Types and Values

Object Hierarchy

GObject
╰── GdkCursor

Includes

#include <gdk/gdk.h>

Description

These functions are used to create and destroy cursors. Cursors
are immutable objects, so once you created them, there is no way
to modify them later. Create a new cursor, when you want to change
something about it.

Cursors by themselves are not very interesting, they must be
bound to a window for users to see them. This is done with
gdk_surface_set_cursor() or gdk_surface_set_device_cursor().
Applications will typically use higher-level GTK+ functions such
as gtk_widget_set_cursor() instead.

Cursors are not bound to a given GdkDisplay, so they can be shared.
However, the appearance of cursors may vary when used on different
platforms.

There are multiple ways to create cursors. The platform's own cursors
can be created with gdk_cursor_new_from_name(). That function lists
the commonly available names that are shared with the CSS specification.
Other names may be available, depending on the platform in use.
Another option to create a cursor is to use gdk_cursor_new_from_texture()
and provide an image to use for the cursor. Depending on the GdkDisplay
in use, the type of supported images may be limited. See
gdk_display_supports_cursor_alpha(),
gdk_display_supports_cursor_color(),
gdk_display_get_default_cursor_size() and
gdk_display_get_maximal_cursor_size() for the limitations that might apply.

To ease work with unsupported cursors, a fallback cursor can be provided.
If a GdkSurface cannot use a cursor because of the reasons mentioned above,
it will try the fallback cursor. Of course, fallback cursors can themselves
have fallback cursors again, so it is possible to provide a chain of
progressively easier to support cursors. If none of the provided cursors
can be supported, the default cursor will be the ultimate fallback.

Functions

gdk_cursor_new_from_texture ()

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

texture

the texture providing the pixel data

hotspot_x

the horizontal offset of the “hotspot” of the cursor

hotspot_y

the vertical offset of the “hotspot” of the cursor

fallback

NULL or the GdkCursor to fall back to when
this one cannot be supported.

Returns

gdk_cursor_get_fallback ()

Returns the fallback for this cursor
. The fallback will be used if this
cursor is not available on a given GdkDisplay.

For named cursors, this can happen when using nonstandard names or when
using an incomplete cursor theme.
For textured cursors, this can happen when the texture is too large or
when the GdkDisplay it is used on does not support textured cursors.