Note: The Agar manual pages follow certain conventions, notably concerning function return values. Please read AG_Intro(3) first.

SYNOPSIS

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

DESCRIPTION

The AG_Cursor interface provides Agar applications control over the shape of the mouse cursor; usually the hardware cursor.

WIDGET INTERFACE

Agar widgets may configure alternate mouse cursors, for those platforms where hardware cursors are configurable. To prevent conflicts where multiple widgets may try to set different cursors, AG_Cursor associates specific window regions with specific cursors. Internally, Agar will change cursors accordingly as the mouse is moved into those regions.

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_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 (typically obtained through AG_CursorNew(3) or AG_CursorFromXPM(3)). Note that this cursor will be freed automatically when the window is detached (do not pass a stock cursor as the c argument).

The AG_MapStockCursor() variant configures a cursor-change area, associated with a stock Agar cursor. See AG_Cursor(3) for the list of acceptable cursorName arguments.

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.

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. Acceptable values for name include:

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
};

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.

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

HISTORY

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