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 rec-
     tangular 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  cursor-
     Name)

     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  coor-
     dinate  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_Cur-
     sorFromXPM(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 ar-
     guments.  Since cursors are associated with window or  driver-specific  re-
     sources, AG_MapCursor() will fail if the widget is not attached to any par-
     ent  window.   However,  AG_MapStockCursor() may be called by an unattached
     widget, and as a special case, Agar will defer the operation until the wid-
     get 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.  Oth-
     erwise, 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_Win-
     dow(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  immedi-
     ately 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 coor-
		      dinate  system).	 Widgets  may  modify this rectangle di-
		      rectly.
     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+15.1.quarterly>

home | help