AG_CURSOR(3)

NAME
AG_Cursor - agar cursor operations

SYNOPSIS

    #include <agar/core.h>
    #include <agar/gui.h>
    #include <agar/gui/cursors.h>

DESCRIPTION
The AG_Cursor interface provides Agar widgets with control over the shape of the mouse cursor. Specific cursors can be associated with specific rectangular areas in a widget's local coordinate system.

WIDGET INTERFACE
AG_CursorArea * AG_MapCursor(AG_Widget *wid, AG_Rect r, AG_Cursor *c)

AG_CursorArea * AG_MapStockCursor(AG_Widget *wid, AG_Rect r, int cursorName)

void AG_SetCursor(AG_Widget *wid, AG_CursorArea **cursorArea, AG_Rect r, AG_Cursor *c)

void AG_SetStockCursor(AG_Widget *wid, AG_CursorArea **cursorArea, AG_Rect r, int cursorName)

void AG_UnmapCursor(AG_Widget *wid, AG_CursorArea *cursorArea)

The AG_MapCursor() function configures a new cursor-change area described by the rectangle r (in pixels, relative to the parent window's local coordinate system). When the mouse is moved within this rectangle, Agar will set the specified cursor c. The return value of AG_CursorNew(3) or AG_CursorFromXPM(3) will typically be used. The allocated cursor will be freed automatically by Agar when the window is detached.

AG_MapStockCursor() sets up a cursor-change area associated with a stock Agar cursor. See STOCK CURSORS for the list of acceptable cursorName arguments. Since cursors are associated with window or driver-specific resources, AG_MapCursor() will fail if the widget is not attached to any parent window. However, AG_MapStockCursor() may be called by an unattached widget, and as a special case, Agar will defer the operation until the widget is attached to a window.

AG_MapCursor() and AG_MapStockCursor() both return a pointer to the AG_CursorArea structure describing the cursor-change area, or NULL if an error has occured.

The AG_SetCursor() and AG_SetStockCursor() routines provide an alternate interface to AG_MapCursor() and AG_MapStockCursor(). If the pointer at cursorArea is NULL, a new cursor area is mapped and returned into it. Otherwise, the rectangle of the existing cursor area is updated from r.

AG_UnmapCursor() removes the specified cursor-change area. If the mouse happens to be currently in this area, the cursor will be reverted immediately to the default.

INTERFACE
AG_Cursor * AG_CursorNew(AG_Driver *drv, Uint w, Uint h, const Uint8 *data, const Uint8 *mask, int xHot, int yHot)

AG_Cursor * AG_CursorFromXPM(AG_Driver *drv, char *xpmData[], int xHot, int yHot)

void AG_CursorFree(AG_Driver *drv, AG_Cursor *cursor)

AG_Cursor * AG_GetStockCursor(AG_Driver *drv, int name)

AG_Cursor * AG_GetActiveCursor(AG_Driver *drv)

void AG_ShowCursor(AG_Driver *drv)

void AG_HideCursor(AG_Driver *drv)

int AG_CursorIsVisible(AG_Driver *drv)

AG_CursorNew() registers a new hardware cursor with the underlying graphics driver. The cursor's pixels are determined from bytes in data (1 = black, 0 = white) and mask (1 = opaque, 0 = transparent). The w and h arguments specify the dimensions of the surface in pixels. The tip of the cursor is located at coordinates xHot and yHot.

AG_CursorFromXPM() creates a cursor from the contents of an XPM file.

AG_CursorFree() releases all resources allocated by a cursor.

AG_GetStockCursor() returns a pointer to a built-in cursor (see STOCK CURSORS for a list).

AG_GetActiveCursor() returns a pointer to the currently active cursor.

AG_ShowCursor() and AG_HideCursor() control the visibility of the active cursor. AG_CursorIsVisible() returns 1 if the active cursor is visible, 0 otherwise.

STOCK CURSORS
As of this writing, Agar provides the following built-in cursors:

    enum {
    	AG_FILL_CURSOR,
    	AG_ERASE_CURSOR,
    	AG_PICK_CURSOR,
    	AG_HRESIZE_CURSOR,
    	AG_VRESIZE_CURSOR,
    	AG_LRDIAG_CURSOR,
    	AG_LLDIAG_CURSOR,
    	AG_TEXT_CURSOR,
    	AG_LAST_CURSOR
    };

STRUCTURE DATA
For the AG_CursorArea structure:

AG_Rect r
    The AG_Rect(3) area (relative to the parent window's coordinate system). Widgets may modify this rectangle directly.
AG_Cursor *c
    The associated cursor (read-only).
AG_Widget *wid
    The widget responsible for the cursor (read-only).
int stock
    If set, the cursor is a stock Agar cursor (read-only).

SEE ALSO
AG_Driver(3), AG_Intro(3), AG_Widget(3), AG_Window(3)

HISTORY
An AG_Cursor interface first appeared in Agar 1.0. A more extensive API was introduced in Agar 1.4.