:right-sidebar: True Cursor =================================================================== .. currentmodule:: gi.repository.Gdk .. class:: Cursor(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GdkCursor`` is 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 :obj:`~gi.repository.Gdk.Surface.set_cursor` or :obj:`~gi.repository.Gdk.Surface.set_device_cursor`\. Applications will typically use higher-level GTK functions such as `gtk_widget_set_cursor() <../gtk4/method.Widget.set_cursor.html>`__ instead. Cursors are not bound to a given :obj:`~gi.repository.Gdk.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 :obj:`~gi.repository.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. 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 :obj:`~gi.repository.Gdk.Cursor.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 :obj:`~gi.repository.Gdk.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 ------------ .. rst-class:: interim-class .. class:: Cursor :no-index: .. classmethod:: new_from_callback(callback: ~typing.Callable[[~gi.repository.Gdk.Cursor, int, float, ~typing.Any], ~typing.Tuple[~gi.repository.Gdk.Texture | None, int, int, int, int]], data: ~typing.Any = None, fallback: ~gi.repository.Gdk.Cursor | None = None) -> ~gi.repository.Gdk.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. .. versionadded:: 4.16 :param callback: the ``GdkCursorGetTextureCallback`` :param data: data to pass to ``callback`` :param fallback: the ``GdkCursor`` to fall back to when this one cannot be supported .. classmethod:: new_from_name(name: str, fallback: ~gi.repository.Gdk.Cursor | None = None) -> ~gi.repository.Gdk.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: .. list-table:: :header-rows: 1 * - - - - * - "none" - .. image:: https://docs.gtk.org/gdk4/default_cursor.png "default" - .. image:: https://docs.gtk.org/gdk4/help_cursor.png "help" - .. image:: https://docs.gtk.org/gdk4/pointer_cursor.png "pointer" * - .. image:: https://docs.gtk.org/gdk4/context_menu_cursor.png "context-menu" - .. image:: https://docs.gtk.org/gdk4/progress_cursor.png "progress" - .. image:: https://docs.gtk.org/gdk4/wait_cursor.png "wait" - .. image:: https://docs.gtk.org/gdk4/cell_cursor.png "cell" * - .. image:: https://docs.gtk.org/gdk4/crosshair_cursor.png "crosshair" - .. image:: https://docs.gtk.org/gdk4/text_cursor.png "text" - .. image:: https://docs.gtk.org/gdk4/vertical_text_cursor.png "vertical-text" - .. image:: https://docs.gtk.org/gdk4/alias_cursor.png "alias" * - .. image:: https://docs.gtk.org/gdk4/copy_cursor.png "copy" - .. image:: https://docs.gtk.org/gdk4/no_drop_cursor.png "no-drop" - .. image:: https://docs.gtk.org/gdk4/move_cursor.png "move" - .. image:: https://docs.gtk.org/gdk4/not_allowed_cursor.png "not-allowed" * - .. image:: https://docs.gtk.org/gdk4/grab_cursor.png "grab" - .. image:: https://docs.gtk.org/gdk4/grabbing_cursor.png "grabbing" - .. image:: https://docs.gtk.org/gdk4/all_scroll_cursor.png "all-scroll" - .. image:: https://docs.gtk.org/gdk4/col_resize_cursor.png "col-resize" * - .. image:: https://docs.gtk.org/gdk4/row_resize_cursor.png "row-resize" - .. image:: https://docs.gtk.org/gdk4/n_resize_cursor.png "n-resize" - .. image:: https://docs.gtk.org/gdk4/e_resize_cursor.png "e-resize" - .. image:: https://docs.gtk.org/gdk4/s_resize_cursor.png "s-resize" * - .. image:: https://docs.gtk.org/gdk4/w_resize_cursor.png "w-resize" - .. image:: https://docs.gtk.org/gdk4/ne_resize_cursor.png "ne-resize" - .. image:: https://docs.gtk.org/gdk4/nw_resize_cursor.png "nw-resize" - .. image:: https://docs.gtk.org/gdk4/sw_resize_cursor.png "sw-resize" * - .. image:: https://docs.gtk.org/gdk4/se_resize_cursor.png "se-resize" - .. image:: https://docs.gtk.org/gdk4/ew_resize_cursor.png "ew-resize" - .. image:: https://docs.gtk.org/gdk4/ns_resize_cursor.png "ns-resize" - .. image:: https://docs.gtk.org/gdk4/nesw_resize_cursor.png "nesw-resize" * - .. image:: https://docs.gtk.org/gdk4/nwse_resize_cursor.png "nwse-resize" - .. image:: https://docs.gtk.org/gdk4/zoom_in_cursor.png "zoom-in" - .. image:: https://docs.gtk.org/gdk4/zoom_out_cursor.png "zoom-out" - :param name: the name of the cursor :param fallback: :const:`None` or the ``GdkCursor`` to fall back to when this one cannot be supported .. classmethod:: new_from_texture(texture: ~gi.repository.Gdk.Texture, hotspot_x: int, hotspot_y: int, fallback: ~gi.repository.Gdk.Cursor | None = None) -> ~gi.repository.Gdk.Cursor Creates a new cursor from a ``GdkTexture``\. :param texture: the texture providing the pixel data :param hotspot_x: the horizontal offset of the “hotspot” of the cursor :param hotspot_y: the vertical offset of the “hotspot” of the cursor :param fallback: the ``GdkCursor`` to fall back to when this one cannot be supported Methods ------- .. rst-class:: interim-class .. class:: Cursor :no-index: .. method:: get_fallback() -> ~gi.repository.Gdk.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. .. method:: 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 :obj:`~gi.repository.Gdk.Cursor.new_from_texture`\. .. method:: 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 :obj:`~gi.repository.Gdk.Cursor.new_from_texture`\. .. method:: get_name() -> str | None Returns the name of the cursor. If the cursor is not a named cursor, :const:`None` will be returned. .. method:: get_texture() -> ~gi.repository.Gdk.Texture | None Returns the texture for the cursor. If the cursor is a named cursor, :const:`None` will be returned. Properties ---------- .. rst-class:: interim-class .. class:: Cursor :no-index: .. attribute:: props.fallback :type: ~gi.repository.Gdk.Cursor The type of the None singleton. .. attribute:: props.hotspot_x :type: int The type of the None singleton. .. attribute:: props.hotspot_y :type: int The type of the None singleton. .. attribute:: props.name :type: str The type of the None singleton. .. attribute:: props.texture :type: ~gi.repository.Gdk.Texture The type of the None singleton.