<-- Back to AG_Intro.3


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


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.


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 occurred.

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.


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.


As of this writing, Agar provides the following built-in cursors:
enum {


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).


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


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