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

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