Cursor#

class Cursor(**properties: Any)#

Superclasses: Object

Used to create and destroy cursors.

Cursors are immutable objects, so once you created them, there is no way to modify them later. You should 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 set_cursor or 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 Display, so they can be shared. However, the appearance of cursors may vary when used on different platforms.

Named and texture cursors#

There are multiple ways to create cursors. The platform’s own cursors can be created with 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. On some platforms, what images are used for named cursors may be influenced by the cursor theme.

Another option to create a cursor is to use new_from_texture and provide an image to use for the cursor.

To ease work with unsupported cursors, a fallback cursor can be provided. If a Surface cannot use a cursor because of the reasons mentioned above, it will try the fallback cursor. 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.

Constructors#

class Cursor
classmethod new_from_callback(callback: Callable[[Cursor, int, float, Any], tuple[Texture | None, int, int, int, int]], data: Any = None, fallback: Cursor | None = None) → Cursor | None#

Creates a new callback-based cursor object.

Cursors of this kind produce textures for the cursor image on demand, when the callback is called.

Added in version 4.16.

Parameters:

  • callback – the GdkCursorGetTextureCallback

  • data – data to pass to callback

  • fallback – the GdkCursor to fall back to when this one cannot be supported

classmethod new_from_name(name: str, fallback: Cursor | None = None) → Cursor | None#

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”

No cursor
https://docs.gtk.org/gdk4/default_cursor.png

“default”

The default cursor
https://docs.gtk.org/gdk4/help_cursor.png

“help”

Help is available
https://docs.gtk.org/gdk4/pointer_cursor.png

“pointer”

Indicates a link or interactive element
https://docs.gtk.org/gdk4/context_menu_cursor.png

“context-menu”

A context menu is available
https://docs.gtk.org/gdk4/progress_cursor.png

“progress”

Progress indicator
https://docs.gtk.org/gdk4/wait_cursor.png

“wait”

Busy cursor
https://docs.gtk.org/gdk4/cell_cursor.png

“cell”

Cell(s) may be selected
https://docs.gtk.org/gdk4/crosshair_cursor.png

“crosshair”

Simple crosshair
https://docs.gtk.org/gdk4/text_cursor.png

“text”

Text may be selected
https://docs.gtk.org/gdk4/vertical_text_cursor.png

“vertical-text”

Vertical text may be selected
https://docs.gtk.org/gdk4/alias_cursor.png

“alias”

DND: Something will be linked
https://docs.gtk.org/gdk4/copy_cursor.png

“copy”

DND: Something will be copied
https://docs.gtk.org/gdk4/move_cursor.png

“move”

DND: Something will be moved
https://docs.gtk.org/gdk4/dnd_ask_cursor.png

“dnd-ask”

DND: User can choose action to be carried out
https://docs.gtk.org/gdk4/no_drop_cursor.png

“no-drop”

DND: Can’t drop here
https://docs.gtk.org/gdk4/not_allowed_cursor.png

“not-allowed”

DND: Action will not be carried out
https://docs.gtk.org/gdk4/grab_cursor.png

“grab”

DND: Something can be grabbed
https://docs.gtk.org/gdk4/grabbing_cursor.png

“grabbing”

DND: Something is being grabbed
https://docs.gtk.org/gdk4/n_resize_cursor.png

“n-resize”

Resizing: Move north border
https://docs.gtk.org/gdk4/e_resize_cursor.png

“e-resize”

Resizing: Move east border
https://docs.gtk.org/gdk4/s_resize_cursor.png

“s-resize”

Resizing: Move south border
https://docs.gtk.org/gdk4/w_resize_cursor.png

“w-resize”

Resizing: Move west border
https://docs.gtk.org/gdk4/ne_resize_cursor.png

“ne-resize”

Resizing: Move north-east corner
https://docs.gtk.org/gdk4/nw_resize_cursor.png

“nw-resize”

Resizing: Move north-west corner
https://docs.gtk.org/gdk4/sw_resize_cursor.png

“sw-resize”

Resizing: Move south-west corner
https://docs.gtk.org/gdk4/se_resize_cursor.png

“se-resize”

Resizing: Move south-east corner
https://docs.gtk.org/gdk4/col_resize_cursor.png

“col-resize”

Resizing: Move an item or border horizontally
https://docs.gtk.org/gdk4/row_resize_cursor.png

“row-resize”

Resizing: Move an item or border vertically
https://docs.gtk.org/gdk4/ew_resize_cursor.png

“ew-resize”

Moving: Something can be moved horizontally
https://docs.gtk.org/gdk4/ns_resize_cursor.png

“ns-resize”

Moving: Something can be moved vertically
https://docs.gtk.org/gdk4/nesw_resize_cursor.png

“nesw-resize”

Moving: Something can be moved diagonally, north-east to south-west
https://docs.gtk.org/gdk4/nwse_resize_cursor.png

“nwse-resize”

Moving: something can be moved diagonally, north-west to south-east
https://docs.gtk.org/gdk4/all_resize_cursor.png

“all-resize”

Moving: Something can be moved in any direction
https://docs.gtk.org/gdk4/all_scroll_cursor.png

“all-scroll”

Can scroll in any direction
https://docs.gtk.org/gdk4/zoom_in_cursor.png

“zoom-in”

Zoom in
https://docs.gtk.org/gdk4/zoom_out_cursor.png

“zoom-out”

Zoom out
Parameters:

  • name – the name of the cursor

  • fallback – None or the GdkCursor to fall back to when this one cannot be supported

classmethod new_from_texture(texture: Texture, hotspot_x: int, hotspot_y: int, fallback: Cursor | None = None) → Cursor#

Creates a new cursor from a GdkTexture.

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 – the GdkCursor to fall back to when this one cannot be supported

Methods#

class Cursor
get_fallback() → Cursor | None#

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.

get_hotspot_x() → int#

Returns the horizontal offset of the hotspot.

The hotspot indicates the pixel that will be directly above the cursor.

Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with new_from_texture.

get_hotspot_y() → int#

Returns the vertical offset of the hotspot.

The hotspot indicates the pixel that will be directly above the cursor.

Note that named cursors may have a nonzero hotspot, but this function will only return the hotspot position for cursors created with new_from_texture.

get_name() → str | None#

Returns the name of the cursor.

If the cursor is not a named cursor, None will be returned.

get_texture() → Texture | None#

Returns the texture for the cursor.

If the cursor is a named cursor, None will be returned.

Properties#

class Cursor
props.fallback: Cursor#

Cursor to fall back to if this cursor cannot be displayed.

props.hotspot_x: int#

X position of the cursor hotspot in the cursor image.

props.hotspot_y: int#

Y position of the cursor hotspot in the cursor image.

props.name: str#

Name of this this cursor.

The name will be None if the cursor was created from a texture.

props.texture: Texture#

The texture displayed by this cursor.

The texture will be None if the cursor was created from a name.