Graphics cursors: Grx Reference Manual

Functions

GrxCursor *	grx_cursor_new ()
GrxCursor *	grx_cursor_ref ()
void	grx_cursor_unref ()
void	grx_cursor_show ()
void	grx_cursor_hide ()
void	grx_cursor_move ()
GrxCursor *	grx_mouse_get_cursor ()
void	grx_mouse_set_cursor ()
void	grx_mouse_set_cursor_default ()
void	grx_mouse_set_cursor_mode ()
gboolean	grx_mouse_is_cursor_shown ()
guint	grx_mouse_block ()
void	grx_mouse_unblock ()

Types and Values

enum	GrxCursorMode
	GrxCursor

Object Hierarchy

    GBoxed
    ╰── GrxCursor

Includes

#include <grx-3.0.h>

Description

The library provides support for the creation and usage of an unlimited number of graphics cursors. An application can use these cursors for any purpose, e.g. mouse cursor, animation sprites. Cursors always save the area they occupy before they are drawn. When moved or erased they restore this area. As a general rule of thumb, an application should erase a cursor before making changes to an area it occupies and redraw the cursor after finishing the drawing.

A devault mouse cursor is created during mode setting and it will be automatically shown if and only if there is a pointing device attached.

Functions

grx_cursor_new ()

GrxCursor *
grx_cursor_new (guint8 *pixels,
                gint pitch,
                gint width,
                gint height,
                gint x0,
                gint y0,
                const GArray *colors);

Create a new cursor using the data provided.

Pixel data values of 0 are treated as transparent, 1 is the first color in colors and so on.

The hot point x0 , y0 is relative to the top left of the cursor.

Parameters

pixels	cursor bitmap data
pitch	width of pixel data rows in bytes
width	width of cursor in pixels
height	height of cursor in pixels
x0	hot point of cursor x coordinate
y0	hot point of cursor y coordinate
colors	color table for pixel data.	[element-type GrxColor]

Returns

the new cursor or NULL if creating the cursor failed.

[transfer full][nullable]

grx_cursor_ref ()

GrxCursor *
grx_cursor_ref (GrxCursor *cursor);

Increase the reference count by 1.

Parameters

cursor

the cursor

Returns

the cursor.

[transfer none]

grx_cursor_unref ()

void
grx_cursor_unref (GrxCursor *cursor);

Decrease the reference count by 1. If there are no more references, the cursor is freed.

Parameters

cursor

the cursor

grx_cursor_show ()

void
grx_cursor_show (GrxCursor *cursor);

Draws the cursor at it's current position.

Parameters

cursor

the cursor

grx_cursor_hide ()

void
grx_cursor_hide (GrxCursor *cursor);

Erase the cursor. The saved data is restored.

Parameters

cursor

the cursor

grx_cursor_move ()

void
grx_cursor_move (GrxCursor *cursor,
                 gint x,
                 gint y);

Move the cursor to a new position.

Parameters

cursor	the cursor
x	the new x coordinate
y	the new y coordinate

grx_mouse_get_cursor ()

GrxCursor *
grx_mouse_get_cursor (void);

Gets the current mouse cursor.

Returns

the cursor or NULL if the cursor has not been set.

[transfer none][nullable]

grx_mouse_set_cursor ()

void
grx_mouse_set_cursor (GrxCursor *cursor);

Sets the mouse cursor to the specified cursor.

Parameters

cursor

the cursor.

[nullable]

grx_mouse_set_cursor_default ()

void
grx_mouse_set_cursor_default (GrxColor fill_color,
                              GrxColor border_color);

Sets the mouse cursor to a default pointer shape.

Parameters

fill_color	the cursor fill color
border_color	the cursor border color

grx_mouse_set_cursor_mode ()

void
grx_mouse_set_cursor_mode (int mode,
                           ...);

Sets the mouse cursor mode.

[skip]

Parameters

mode	the mode
...	mode specific arguments

grx_mouse_is_cursor_shown ()

gboolean
grx_mouse_is_cursor_shown (void);

Gets the mouse cursor visibility.

Returns

TRUE if the mouse cursor is shown on the screen.

grx_mouse_block ()

guint
grx_mouse_block (GrxContext *context,
                 gint x1,
                 gint y1,
                 gint x2,
                 gint y2);

Erase the cursor before drawing. Must call grx_mouse_unblock() when finished.

Normally, you don't need to call this function manually, but it can be more efficient to do so if there is a long sequence of drawing functions.

Parameters

context	the target content for `NULL` for the global context.	[nullable]
x1	the left x coordinate
y1	the top y coordinate
x2	the right x coordinate
y2	the bottom y coordinate

Returns

state flags that need to be passed to grx_mouse_unblock()

grx_mouse_unblock ()

void
grx_mouse_unblock (guint flags);

Restore the mouse cursor after a call to grx_mouse_block().

Parameters

flags

flags returned by grx_mouse_block()

Types and Values

enum GrxCursorMode

Mouse cursor modes.

Members

GRX_CURSOR_MODE_NORMAL	just the cursor
GRX_CURSOR_MODE_RUBBER	rectangular rubber band (XOR-d to the screen)
GRX_CURSOR_MODE_LINE	line attached to the cursor
GRX_CURSOR_MODE_BOX	rectangular box dragged by the cursor

GrxCursor

typedef struct _GrxCursor GrxCursor;

Structure to hold cursor state.