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.

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 (without setting an error message).

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. If the given cursor doesn't exist (or doesn't exist yet, as for an AG_Window(3) in the process of being setup), then NULL is returned into cursorArea.

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_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:

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