.\" Copyright (c) 2008-2022 Julien Nadeau Carriere .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, .\" INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES .\" (INCLUDING BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGE. .\" .Dd December 21, 2022 .Dt AG_CURSOR 3 .Os Agar 1.7 .Sh NAME .Nm AG_Cursor .Nd agar cursor operations .Sh SYNOPSIS .Bd -literal #include #include #include .Ed .Sh DESCRIPTION The .Nm 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. .Sh WIDGET INTERFACE .nr nS 1 .Ft "AG_CursorArea *" .Fn AG_MapCursor "AG_Widget *wid" "AG_Rect r" "AG_Cursor *c" .Pp .Ft "AG_CursorArea *" .Fn AG_MapStockCursor "AG_Widget *wid" "AG_Rect r" "int cursorName" .Pp .Ft "void" .Fn AG_SetCursor "AG_Widget *wid" "AG_CursorArea **cursorArea" "AG_Rect r" "AG_Cursor *c" .Pp .Ft "void" .Fn AG_SetStockCursor "AG_Widget *wid" "AG_CursorArea **cursorArea" "AG_Rect r" "int cursorName" .Pp .Ft "void" .Fn AG_UnmapCursor "AG_Widget *wid" "AG_CursorArea *cursorArea" .Pp .nr nS 0 The .Fn AG_MapCursor function configures a new cursor-change area described by the rectangle .Fa 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 .Fa c . The return value of .Xr AG_CursorNew 3 or .Xr AG_CursorFromXPM 3 will typically be used. The allocated cursor will be freed automatically by Agar when the window is detached. .Pp .Fn AG_MapStockCursor sets up a cursor-change area associated with a stock Agar cursor. See .Sx STOCK CURSORS for the list of acceptable .Fa cursorName arguments. Since cursors are associated with window or driver-specific resources, .Fn AG_MapCursor will fail if the widget is not attached to any parent window. However, .Fn 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. .Pp .Fn AG_MapCursor and .Fn AG_MapStockCursor both return a pointer to the .Ft AG_CursorArea structure describing the cursor-change area, or NULL if an error has occurred (without setting an error message). .Pp The .Fn AG_SetCursor and .Fn AG_SetStockCursor routines provide an alternate interface to .Fn AG_MapCursor and .Fn AG_MapStockCursor . If the pointer at .Fa cursorArea is NULL, a new cursor area is mapped and returned into it. Otherwise, the rectangle of the existing cursor area is updated from .Fa r . If the given cursor doesn't exist (or doesn't exist yet, as for an .Xr AG_Window 3 in the process of being setup), then NULL is returned into .Fa cursorArea . .Pp .Fn 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. .Sh INTERFACE .nr nS 1 .Ft "AG_Cursor *" .Fn AG_CursorNew "AG_Driver *drv" "Uint w" "Uint h" "const Uint8 *data" "const Uint8 *mask" "int xHot" "int yHot" .Pp .Ft "AG_Cursor *" .Fn AG_CursorFromXPM "AG_Driver *drv" "char *xpmData[]" "int xHot" "int yHot" .Pp .Ft void .Fn AG_CursorFree "AG_Driver *drv" "AG_Cursor *cursor" .Pp .Ft "AG_Cursor *" .Fn AG_GetStockCursor "AG_Driver *drv" "int name" .Pp .Ft "AG_Cursor *" .Fn AG_GetActiveCursor "AG_Driver *drv" .Pp .Ft void .Fn AG_ShowCursor "AG_Driver *drv" .Pp .Ft void .Fn AG_HideCursor "AG_Driver *drv" .Pp .Ft int .Fn AG_CursorIsVisible "AG_Driver *drv" .Pp .nr nS 0 .Fn AG_CursorNew registers a new hardware cursor with the underlying graphics driver. The cursor's pixels are determined from bytes in .Fa data (1 = black, 0 = white) and .Fa mask (1 = opaque, 0 = transparent). The .Fa w and .Fa h arguments specify the dimensions of the surface in pixels. The tip of the cursor is located at coordinates .Fa xHot and .Fa yHot . .Pp .Fn AG_CursorFromXPM creates a cursor from the contents of an XPM file. .Pp .Fn AG_CursorFree releases all resources allocated by a cursor. .Pp .Fn AG_GetStockCursor returns a pointer to a built-in cursor (see .Sx STOCK CURSORS for a list). .Pp .Fn AG_GetActiveCursor returns a pointer to the currently active cursor. .Pp .Fn AG_ShowCursor and .Fn AG_HideCursor control the visibility of the active cursor. .Fn AG_CursorIsVisible returns 1 if the active cursor is visible, 0 otherwise. .Sh STOCK CURSORS As of this writing, Agar provides the following built-in cursors: .Bd -literal .\" SYNTAX(c) 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 }; .Ed .Sh STRUCTURE DATA For the .Ft AG_CursorArea structure: .Pp .Bl -tag -compact -width "AG_Widget *wid " .It Ft AG_Rect r The .Xr AG_Rect 3 area (relative to the parent window's coordinate system). Widgets may modify this rectangle directly. .It Ft AG_Cursor *c The associated cursor (read-only). .It Ft AG_Widget *wid The widget responsible for the cursor (read-only). .It Ft int stock If set, the cursor is a stock Agar cursor (read-only). .El .Sh SEE ALSO .Xr AG_Driver 3 , .Xr AG_Intro 3 , .Xr AG_Widget 3 , .Xr AG_Window 3 .Sh HISTORY An .Nm interface first appeared in Agar 1.0. A more extensive API was introduced in Agar 1.4.0.