Cursors

Cursors — Standard and pixmap cursors

Functions

Properties

GdkCursorType cursor-type Read / Write / Construct Only
GdkDisplay * display Read / Write / Construct Only

Types and Values

Object Hierarchy

    GObject
    ╰── GdkCursor

Includes

#include <gdk/gdk.h>

Description

These functions are used to create and destroy cursors. There is a number of standard cursors, but it is also possible to construct new cursors from pixbufs. There may be limitations as to what kinds of cursors can be constructed on a given display, see gdk_display_supports_cursor_alpha(), gdk_display_supports_cursor_color(), gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size().

Cursors by themselves are not very interesting, they must be be bound to a window for users to see them. This is done with gdk_window_set_cursor() or by setting the cursor member of the GdkWindowAttr passed to gdk_window_new().

Functions

gdk_cursor_new ()

GdkCursor *
gdk_cursor_new (GdkCursorType cursor_type);

gdk_cursor_new has been deprecated since version 3.16 and should not be used in newly-written code.

Use gdk_cursor_new_for_display() instead.

Creates a new cursor from the set of builtin cursors for the default display. See gdk_cursor_new_for_display().

To make the cursor invisible, use GDK_BLANK_CURSOR.

Parameters

cursor_type

cursor to create

 

Returns

a new GdkCursor


gdk_cursor_new_from_pixbuf ()

GdkCursor *
gdk_cursor_new_from_pixbuf (GdkDisplay *display,
                            GdkPixbuf *pixbuf,
                            gint x,
                            gint y);

Creates a new cursor from a pixbuf.

Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions gdk_display_supports_cursor_alpha() and gdk_display_supports_cursor_color() can be used to determine whether RGBA cursors are supported; gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size() give information about cursor sizes.

If x or y are -1, the pixbuf must have options named “x_hot” and “y_hot”, resp., containing integer values between 0 and the width resp. height of the pixbuf. (Since: 3.0)

On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension.

Parameters

display

the GdkDisplay for which the cursor will be created

 

pixbuf

the GdkPixbuf containing the cursor image

 

x

the horizontal offset of the “hotspot” of the cursor.

 

y

the vertical offset of the “hotspot” of the cursor.

 

Returns

a new GdkCursor.

Since: 2.4


gdk_cursor_new_from_surface ()

GdkCursor *
gdk_cursor_new_from_surface (GdkDisplay *display,
                             cairo_surface_t *surface,
                             gdouble x,
                             gdouble y);

Creates a new cursor from a cairo image surface.

Not all GDK backends support RGBA cursors. If they are not supported, a monochrome approximation will be displayed. The functions gdk_display_supports_cursor_alpha() and gdk_display_supports_cursor_color() can be used to determine whether RGBA cursors are supported; gdk_display_get_default_cursor_size() and gdk_display_get_maximal_cursor_size() give information about cursor sizes.

On the X backend, support for RGBA cursors requires a sufficently new version of the X Render extension.

Parameters

display

the GdkDisplay for which the cursor will be created

 

surface

the cairo image surface containing the cursor pixel data

 

x

the horizontal offset of the “hotspot” of the cursor

 

y

the vertical offset of the “hotspot” of the cursor

 

Returns

a new GdkCursor.

Since: 3.10


gdk_cursor_new_from_name ()

GdkCursor *
gdk_cursor_new_from_name (GdkDisplay *display,
                          const gchar *name);

Creates a new cursor by looking up name in the current cursor theme.

A recommended set of cursor names that will work across different platforms can be found in the CSS specification:

  • "none"

  • "default"

  • "help"

  • "pointer"

  • "context-menu"

  • "progress"

  • "wait"

  • "cell"

  • "crosshair"

  • "text"

  • "vertical-text"

  • "alias"

  • "copy"

  • "no-drop"

  • "move"

  • "not-allowed"

  • "grab"

  • "grabbing"

  • "all-scroll"

  • "col-resize"

  • "row-resize"

  • "n-resize"

  • "e-resize"

  • "s-resize"

  • "w-resize"

  • "ne-resize"

  • "nw-resize"

  • "sw-resize"

  • "se-resize"

  • "ew-resize"

  • "ns-resize"

  • "nesw-resize"

  • "nwse-resize"

  • "zoom-in"

  • "zoom-out"

Parameters

display

the GdkDisplay for which the cursor will be created

 

name

the name of the cursor

 

Returns

a new GdkCursor, or NULL if there is no cursor with the given name.

[nullable]

Since: 2.8


gdk_cursor_new_for_display ()

GdkCursor *
gdk_cursor_new_for_display (GdkDisplay *display,
                            GdkCursorType cursor_type);

Creates a new cursor from the set of builtin cursors.

Parameters

display

the GdkDisplay for which the cursor will be created

 

cursor_type

cursor to create

 

Returns

a new GdkCursor, or NULL on failure.

[nullable][transfer full]

Since: 2.2


gdk_cursor_get_display ()

GdkDisplay *
gdk_cursor_get_display (GdkCursor *cursor);

Returns the display on which the GdkCursor is defined.

Parameters

cursor

a GdkCursor.

 

Returns

the GdkDisplay associated to cursor .

[transfer none]

Since: 2.2


gdk_cursor_get_image ()

GdkPixbuf *
gdk_cursor_get_image (GdkCursor *cursor);

Returns a GdkPixbuf with the image used to display the cursor.

Note that depending on the capabilities of the windowing system and on the cursor, GDK may not be able to obtain the image data. In this case, NULL is returned.

Parameters

cursor

a GdkCursor

 

Returns

a GdkPixbuf representing cursor , or NULL.

[nullable][transfer full]

Since: 2.8


gdk_cursor_get_surface ()

cairo_surface_t *
gdk_cursor_get_surface (GdkCursor *cursor,
                        gdouble *x_hot,
                        gdouble *y_hot);

Returns a cairo image surface with the image used to display the cursor.

Note that depending on the capabilities of the windowing system and on the cursor, GDK may not be able to obtain the image data. In this case, NULL is returned.

Parameters

cursor

a GdkCursor

 

x_hot

Location to store the hotspot x position, or NULL.

[optional][out]

y_hot

Location to store the hotspot y position, or NULL.

[optional][out]

Returns

a cairo_surface_t representing cursor , or NULL.

[nullable][transfer full]

Since: 3.10


gdk_cursor_get_cursor_type ()

GdkCursorType
gdk_cursor_get_cursor_type (GdkCursor *cursor);

Returns the cursor type for this cursor.

Parameters

cursor

a GdkCursor

 

Returns

a GdkCursorType

Since: 2.22


gdk_cursor_ref ()

GdkCursor *
gdk_cursor_ref (GdkCursor *cursor);

gdk_cursor_ref has been deprecated since version 3.0 and should not be used in newly-written code.

Use g_object_ref() instead

Adds a reference to cursor .

Parameters

cursor

a GdkCursor

 

Returns

Same cursor that was passed in.

[transfer full]


gdk_cursor_unref ()

void
gdk_cursor_unref (GdkCursor *cursor);

gdk_cursor_unref has been deprecated since version 3.0 and should not be used in newly-written code.

Use g_object_unref() instead

Removes a reference from cursor , deallocating the cursor if no references remain.

Parameters

cursor

a GdkCursor

 

Types and Values

GdkCursor

typedef struct _GdkCursor GdkCursor;

A GdkCursor represents a cursor. Its contents are private.


enum GdkCursorType

Predefined cursors.

Note that these IDs are directly taken from the X cursor font, and many of these cursors are either not useful, or are not available on other platforms.

The recommended way to create cursors is to use gdk_cursor_new_from_name().

Members

GDK_X_CURSOR

 

GDK_ARROW

 

GDK_BASED_ARROW_DOWN

 

GDK_BASED_ARROW_UP

 

GDK_BOAT

 

GDK_BOGOSITY

 

GDK_BOTTOM_LEFT_CORNER

 

GDK_BOTTOM_RIGHT_CORNER

 

GDK_BOTTOM_SIDE

 

GDK_BOTTOM_TEE

 

GDK_BOX_SPIRAL

 

GDK_CENTER_PTR

 

GDK_CIRCLE

 

GDK_CLOCK

 

GDK_COFFEE_MUG

 

GDK_CROSS

 

GDK_CROSS_REVERSE

 

GDK_CROSSHAIR

 

GDK_DIAMOND_CROSS

 

GDK_DOT

 

GDK_DOTBOX

 

GDK_DOUBLE_ARROW

 

GDK_DRAFT_LARGE

 

GDK_DRAFT_SMALL

 

GDK_DRAPED_BOX

 

GDK_EXCHANGE

 

GDK_FLEUR

 

GDK_GOBBLER

 

GDK_GUMBY

 

GDK_HAND1

 

GDK_HAND2

 

GDK_HEART

 

GDK_ICON

 

GDK_IRON_CROSS

 

GDK_LEFT_PTR

 

GDK_LEFT_SIDE

 

GDK_LEFT_TEE

 

GDK_LEFTBUTTON

 

GDK_LL_ANGLE

 

GDK_LR_ANGLE

 

GDK_MAN

 

GDK_MIDDLEBUTTON

 

GDK_MOUSE

 

GDK_PENCIL

 

GDK_PIRATE

 

GDK_PLUS

 

GDK_QUESTION_ARROW

 

GDK_RIGHT_PTR

 

GDK_RIGHT_SIDE

 

GDK_RIGHT_TEE

 

GDK_RIGHTBUTTON

 

GDK_RTL_LOGO

 

GDK_SAILBOAT

 

GDK_SB_DOWN_ARROW

 

GDK_SB_H_DOUBLE_ARROW

 

GDK_SB_LEFT_ARROW

 

GDK_SB_RIGHT_ARROW

 

GDK_SB_UP_ARROW

 

GDK_SB_V_DOUBLE_ARROW

 

GDK_SHUTTLE

 

GDK_SIZING

 

GDK_SPIDER

 

GDK_SPRAYCAN

 

GDK_STAR

 

GDK_TARGET

 

GDK_TCROSS

 

GDK_TOP_LEFT_ARROW

 

GDK_TOP_LEFT_CORNER

 

GDK_TOP_RIGHT_CORNER

 

GDK_TOP_SIDE

 

GDK_TOP_TEE

 

GDK_TREK

 

GDK_UL_ANGLE

 

GDK_UMBRELLA

 

GDK_UR_ANGLE

 

GDK_WATCH

 

GDK_XTERM

 

GDK_LAST_CURSOR

last cursor type

 

GDK_BLANK_CURSOR

Blank cursor. Since 2.16

 

GDK_CURSOR_IS_PIXMAP

type of cursors constructed with gdk_cursor_new_from_pixbuf()

 

Property Details

The “cursor-type” property

  “cursor-type”              GdkCursorType

Standard cursor type.

Owner: GdkCursor

Flags: Read / Write / Construct Only

Default value: GDK_X_CURSOR


The “display” property

  “display”                  GdkDisplay *

Display of this cursor.

Owner: GdkCursor

Flags: Read / Write / Construct Only