gtkmm: Gdk::Cursor Class Reference

gtkmm 4.18.0

Public Types | Public Member Functions | Static Public Member Functions | Related Symbols | List of all members
Gdk::Cursor Class Reference

Gdk::Cursor is used to create and destroy cursors. More...

`#include <gdkmm/cursor.h>`

Inheritance diagram for Gdk::Cursor:
[legend]

## Public Types
using | SlotGetTexture
| Callback used by a dynamic Gdk::Cursor to generate a texture for the cursor image at the given cursor_size and scale.
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)

## Public Member Functions
| Cursor (Cursor && src) noexcept
Cursor & | operator= (Cursor && src) noexcept
| ~Cursor () noexcept override
GdkCursor * | gobj ()
| Provides access to the underlying C GObject.
const GdkCursor * | gobj () const
| Provides access to the underlying C GObject.
GdkCursor * | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::RefPtr< Cursor > | get_fallback ()
| Returns the fallback for this cursor.
Glib::RefPtr< const Cursor > | get_fallback () const
| Returns the fallback for this cursor.
Glib::ustring | get_name () const
| Returns the name of the cursor.
Glib::RefPtr< Texture > | get_texture ()
| Returns the texture for the cursor.
Glib::RefPtr< const Texture > | get_texture () const
| Returns the texture for the cursor.
int | get_hotspot_x () const
| Returns the horizontal offset of the hotspot.
int | get_hotspot_y () const
| Returns the vertical offset of the hotspot.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > | property_fallback () const
| Cursor to fall back to if this cursor cannot be displayed.
Glib::PropertyProxy_ReadOnly< int > | property_hotspot_x () const
| X position of the cursor hotspot in the cursor image.
Glib::PropertyProxy_ReadOnly< int > | property_hotspot_y () const
| Y position of the cursor hotspot in the cursor image.
Glib::PropertyProxy_ReadOnly< Glib::ustring > | property_name () const
| Name of this this cursor.
Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Texture > > | property_texture () const
| The texture displayed by this cursor.
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data_with_c_callback (const Quark &key, void *data, GDestroyNotify notify)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system.
static Glib::RefPtr< Cursor > | create (const Glib::RefPtr< const Texture > & texture, int hotspot_x, int hotspot_y, const Glib::RefPtr< Cursor > & fallback={})
| Creates a new cursor from a `Gdk::Texture`.
static Glib::RefPtr< Cursor > | create (const Glib::ustring & name, const Glib::RefPtr< Cursor > & fallback={})
| Creates a new cursor by looking up name in the current cursor theme.
static Glib::RefPtr< Cursor > | create_from_slot (const SlotGetTexture & slot, const Glib::RefPtr< Cursor > & fallback={})
| Creates a new callback-based cursor object.

## Related Symbols
(Note that these are not member symbols.)
Glib::RefPtr< Gdk::Cursor > | wrap (GdkCursor * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Additional Inherited Members
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Detailed Description

Gdk::Cursor 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 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 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 create(const Glib::ustring& name, const Glib::RefPtr<Cursor>& fallback). 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 create(const Glib::RefPtr<const Texture>& texture, int hotspot_x, int hotspot_y, const Glib::RefPtr<Cursor>& fallback) and provide an image to use for the cursor.

To ease work with unsupported cursors, a fallback cursor can be provided. If a Gdk::Surface cannot use a cursor, 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.

## Member Typedef Documentation

## ◆ SlotGetTexture

using Gdk::Cursor::SlotGetTexture

Initial value:
sigc::slot<Glib::RefPtr<Texture>(int, double,
int&, int&, int&, int&)>

Callback used by a dynamic Gdk::Cursor to generate a texture for the cursor image at the given cursor_size and scale.

The actual cursor size in application pixels may be different from cursor_size x cursor_size, and will be returned in width, height. The returned texture should have a size that corresponds to the actual cursor size, in device pixels (i.e. application pixels, multiplied by scale).

This function may fail and return an empty RefPtr, in which case the fallback cursor will be used.

Parameters

  | cursor_size | The nominal cursor size, in application pixels.
  | scale | The device scale.
  [out] | width | Return location for the actual cursor width, in application pixels.
  [out] | height | Return location for the actual cursor height, in application pixels.
  [out] | hotspot_x | Return location for the hotspot X position, in application pixels.
  [out] | hotspot_y | Return location for the hotspot Y position, in application pixels.

Returns
  The cursor image, or an empty RefPtr if none could be produced..

Since gtkmm 4.16

## Constructor & Destructor Documentation

## ◆ Cursor()

Gdk::Cursor::Cursor | ( | Cursor && | src | ) |
| noexcept

## ◆ ~Cursor()

Gdk::Cursor::~Cursor | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ create() [1/2]

static Glib::RefPtr< Cursor > Gdk::Cursor::create | ( | const Glib::RefPtr< const Texture > & | texture,
|  | int | hotspot_x,
|  | int | hotspot_y,
|  | const Glib::RefPtr< Cursor > & | fallback = {} )
| static

Creates a new cursor from a `Gdk::Texture`.

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 `Gdk::Cursor` to fall back to when this one cannot be supported.

Returns
  A new `Gdk::Cursor`.

## ◆ create() [2/2]

static Glib::RefPtr< Cursor > Gdk::Cursor::create | ( | const Glib::ustring & | name,
|  | const Glib::RefPtr< Cursor > & | fallback = {} )
| static

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
| "default" | The default cursor
| "help" | Help is available
| "pointer" | Indicates a link or interactive element
| "context-menu" | A context menu is available
| "progress" | Progress indicator
| "wait" | Busy cursor
| "cell" | Cell(s) may be selected
| "crosshair" | Simple crosshair
| "text" | Text may be selected
| "vertical-text" | Vertical text may be selected
| "alias" | DND: Something will be linked
| "copy" | DND: Something will be copied
| "move" | DND: Something will be moved
| "dnd-ask" | DND: User can choose action to be carried out
| "no-drop" | DND: Can't drop here
| "not-allowed" | DND: Action will not be carried out
| "grab" | DND: Something can be grabbed
| "grabbing" | DND: Something is being grabbed
| "n-resize" | Resizing: Move north border
| "e-resize" | Resizing: Move east border
| "s-resize" | Resizing: Move south border
| "w-resize" | Resizing: Move west border
| "ne-resize" | Resizing: Move north-east corner
| "nw-resize" | Resizing: Move north-west corner
| "sw-resize" | Resizing: Move south-west corner
| "se-resize" | Resizing: Move south-east corner
| "col-resize" | Resizing: Move an item or border horizontally
| "row-resize" | Resizing: Move an item or border vertically
| "ew-resize" | Moving: Something can be moved horizontally
| "ns-resize" | Moving: Something can be moved vertically
| "nesw-resize" | Moving: Something can be moved diagonally, north-east to south-west
| "nwse-resize" | Moving: something can be moved diagonally, north-west to south-east
| "all-resize" | Moving: Something can be moved in any direction
| "all-scroll" | Can scroll in any direction
| "zoom-in" | Zoom in
| "zoom-out" | Zoom out

Parameters

  name | The name of the cursor.
  fallback | `nullptr` or the `Gdk::Cursor` to fall back to when this one cannot be supported.

Returns
  A new `Gdk::Cursor`, or `nullptr` if there is no cursor with the given name.

## ◆ create_from_slot()

static Glib::RefPtr< Cursor > Gdk::Cursor::create_from_slot | ( | const SlotGetTexture & | slot,
|  | const Glib::RefPtr< Cursor > & | fallback = {} )
| static

Creates a new callback-based cursor object.

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

Since gtkmm 4.16

Parameters

  slot | Callback that lets you create a suitable texture.
  fallback | The Gdk::Cursor to fall back to when this one cannot be supported.

Returns
  A new Gdk::Cursor.

## ◆ get_fallback() [1/2]

Glib::RefPtr< Cursor > Gdk::Cursor::get_fallback | ( |  | ) |

Returns the fallback for this cursor.

The fallback will be used if this cursor is not available on a given `Gdk::Display`. 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 `Gdk::Display` it is used on does not support textured cursors.

Returns
  The fallback of the cursor or `nullptr` to use the default cursor as fallback.

## ◆ get_fallback() [2/2]

Glib::RefPtr< const Cursor > Gdk::Cursor::get_fallback | ( |  | ) | const

Returns the fallback for this cursor.

The fallback will be used if this cursor is not available on a given `Gdk::Display`. 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 `Gdk::Display` it is used on does not support textured cursors.

Returns
  The fallback of the cursor or `nullptr` to use the default cursor as fallback.

## ◆ get_hotspot_x()

int Gdk::Cursor::get_hotspot_x | ( |  | ) | const

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().

Returns
  The horizontal offset of the hotspot or 0 for named cursors.

## ◆ get_hotspot_y()

int Gdk::Cursor::get_hotspot_y | ( |  | ) | const

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().

Returns
  The vertical offset of the hotspot or 0 for named cursors.

## ◆ get_name()

Glib::ustring Gdk::Cursor::get_name | ( |  | ) | const

Returns the name of the cursor.

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

Returns
  The name of the cursor or `nullptr` if it is not a named cursor.

## ◆ get_texture() [1/2]

Glib::RefPtr< Texture > Gdk::Cursor::get_texture | ( |  | ) |

Returns the texture for the cursor.

If the cursor is a named cursor, `nullptr` will be returned.

Returns
  The texture for cursor or `nullptr` if it is a named cursor.

## ◆ get_texture() [2/2]

Glib::RefPtr< const Texture > Gdk::Cursor::get_texture | ( |  | ) | const

Returns the texture for the cursor.

If the cursor is a named cursor, `nullptr` will be returned.

Returns
  The texture for cursor or `nullptr` if it is a named cursor.

## ◆ get_type()

static GType Gdk::Cursor::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GdkCursor * Gdk::Cursor::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GdkCursor * Gdk::Cursor::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GdkCursor * Gdk::Cursor::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ operator=()

Cursor & Gdk::Cursor::operator= | ( | Cursor && | src | ) |
| noexcept

## ◆ property_fallback()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Cursor > > Gdk::Cursor::property_fallback | ( |  | ) | const

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

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_hotspot_x()

Glib::PropertyProxy_ReadOnly< int > Gdk::Cursor::property_hotspot_x | ( |  | ) | const

X position of the cursor hotspot in the cursor image.

Default value: 0

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_hotspot_y()

Glib::PropertyProxy_ReadOnly< int > Gdk::Cursor::property_hotspot_y | ( |  | ) | const

Y position of the cursor hotspot in the cursor image.

Default value: 0

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_name()

Glib::PropertyProxy_ReadOnly< Glib::ustring > Gdk::Cursor::property_name | ( |  | ) | const

Name of this this cursor.

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

Default value: ""

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## ◆ property_texture()

Glib::PropertyProxy_ReadOnly< Glib::RefPtr< Texture > > Gdk::Cursor::property_texture | ( |  | ) | const

The texture displayed by this cursor.

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

Returns
  A PropertyProxy_ReadOnly that allows you to get the value of the property, or receive notification when the value of the property changes.

## Friends And Related Symbol Documentation

## ◆ wrap()

Glib::RefPtr< Gdk::Cursor > wrap | ( | GdkCursor * | object,
|  | bool | take_copy = false )
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.