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