Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help 
AG_CURSOR(3)		    Library Functions Manual		  AG_CURSOR(3)

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  de-
       scribed	by the rectangle r (in pixels, relative	to the parent window's
       local coordinate	system).  When the mouse is moved within this  rectan-
       gle,  Agar  will	 set  the  specified  cursor  c.   The return value of
       AG_CursorNew(3) or AG_CursorFromXPM(3) will typically be	used.  The al-
       located 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 dri-
       ver-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	alter-
       nate  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  up-
       dated 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 re-
       turned 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 ac-
       tive 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.

Agar 1.7		       December	21, 2022		  AG_CURSOR(3)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=AG_Cursor&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>

home | help