gi-gdk4-4.0.10: Gdk bindings

Copyright | Will Thompson and Iñaki García Etxebarria
License | LGPL-2.1
Maintainer | Iñaki García Etxebarria
Safe Haskell | None
Language | Haskell2010

GI.Gdk.Objects.Cursor

Contents

- Exported types
- Methods
  - getFallback
  - getHotspotX
  - getHotspotY
  - getName
  - getTexture
  - newFromCallback
  - newFromName
  - newFromTexture
- Properties
  - fallback
  - hotspotX
  - hotspotY
  - name
  - texture

Description

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 `surfaceSetCursor` or `surfaceSetDeviceCursor`. 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 `cursorNewFromName`. 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 `cursorNewFromTexture` 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.

Synopsis

- newtype Cursor = Cursor (ManagedPtr Cursor)
- class (GObject o, IsDescendantOf Cursor o) => IsCursor o
- toCursor :: (MonadIO m, IsCursor o) => o -> m Cursor
- cursorGetFallback :: (HasCallStack, MonadIO m, IsCursor a) => a -> m (Maybe Cursor)
- cursorGetHotspotX :: (HasCallStack, MonadIO m, IsCursor a) => a -> m Int32
- cursorGetHotspotY :: (HasCallStack, MonadIO m, IsCursor a) => a -> m Int32
- cursorGetName :: (HasCallStack, MonadIO m, IsCursor a) => a -> m (Maybe Text)
- cursorGetTexture :: (HasCallStack, MonadIO m, IsCursor a) => a -> m (Maybe Texture)
- cursorNewFromCallback :: (HasCallStack, MonadIO m, IsCursor a) => CursorGetTextureCallback -> Maybe a -> m (Maybe Cursor)
- cursorNewFromName :: (HasCallStack, MonadIO m, IsCursor a) => Text -> Maybe a -> m (Maybe Cursor)
- cursorNewFromTexture :: (HasCallStack, MonadIO m, IsTexture a, IsCursor b) => a -> Int32 -> Int32 -> Maybe b -> m Cursor
- constructCursorFallback :: (IsCursor o, MonadIO m, IsCursor a) => a -> m (GValueConstruct o)
- getCursorFallback :: (MonadIO m, IsCursor o) => o -> m (Maybe Cursor)
- constructCursorHotspotX :: (IsCursor o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getCursorHotspotX :: (MonadIO m, IsCursor o) => o -> m Int32
- constructCursorHotspotY :: (IsCursor o, MonadIO m) => Int32 -> m (GValueConstruct o)
- getCursorHotspotY :: (MonadIO m, IsCursor o) => o -> m Int32
- constructCursorName :: (IsCursor o, MonadIO m) => Text -> m (GValueConstruct o)
- getCursorName :: (MonadIO m, IsCursor o) => o -> m (Maybe Text)
- constructCursorTexture :: (IsCursor o, MonadIO m, IsTexture a) => a -> m (GValueConstruct o)
- getCursorTexture :: (MonadIO m, IsCursor o) => o -> m (Maybe Texture)

# Exported types

newtype Cursor Source #

Memory-managed wrapper type.

Constructors

Cursor (ManagedPtr Cursor) |

#### Instances

Instances details

Eq Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor Methods (==) :: Cursor -> Cursor -> Bool Source # (/=) :: Cursor -> Cursor -> Bool Source #
GObject Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor
ManagedPtrNewtype Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor Methods toManagedPtr :: Cursor -> ManagedPtr Cursor Source #
TypedObject Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor Methods glibType :: IO GType Source #
HasParentTypes Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor
IsGValue (Maybe Cursor) Source # | Convert `Cursor` to and from `GValue`. See `toGValue` and `fromGValue`.
Instance details Defined in GI.Gdk.Objects.Cursor Methods gvalueGType_ :: IO GType Source # gvalueSet_ :: Ptr GValue -> Maybe Cursor -> IO () Source # gvalueGet_ :: Ptr GValue -> IO (Maybe Cursor) Source #
type ParentTypes Cursor Source # |
Instance details Defined in GI.Gdk.Objects.Cursor type ParentTypes Cursor = '[Object]

class (GObject o, IsDescendantOf Cursor o) => IsCursor o Source #

Type class for types which can be safely cast to `Cursor`, for instance with `toCursor`.

#### Instances

Instances details

(GObject o, IsDescendantOf Cursor o) => IsCursor o Source # |
Instance details Defined in GI.Gdk.Objects.Cursor

toCursor :: (MonadIO m, IsCursor o) => o -> m Cursor Source #

Cast to `Cursor`, for types for which this is known to be safe. For general casts, use `castTo`.

# Methods

### Click to display all available methods, including inherited ones

Expand

#### Methods

bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getData, getFallback, getHotspotX, getHotspotY, getName, getProperty, getQdata, getTexture.

#### Setters

setData, setDataFull, setProperty.

## getFallback

cursorGetFallback Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> a | `cursor`: a `GdkCursor`
-> m (Maybe Cursor) | Returns: the fallback of the cursor or `Nothing` to use the default cursor as 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.

## getHotspotX

cursorGetHotspotX Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> a | `cursor`: a `GdkCursor`
-> m Int32 | Returns: the horizontal offset of the hotspot or 0 for named cursors

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 `cursorNewFromTexture`.

## getHotspotY

cursorGetHotspotY Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> a | `cursor`: a `GdkCursor`
-> m Int32 | Returns: the vertical offset of the hotspot or 0 for named cursors

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 `cursorNewFromTexture`.

## getName

cursorGetName Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> a | `cursor`: a `GdkCursor`
-> m (Maybe Text) | Returns: the name of the cursor or `Nothing` if it is not a named cursor

Returns the name of the cursor.

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

## getTexture

cursorGetTexture Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> a | `cursor`: a `GdkCursor`
-> m (Maybe Texture) | Returns: the texture for cursor or `Nothing` if it is a named cursor

Returns the texture for the cursor.

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

## newFromCallback

cursorNewFromCallback Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> CursorGetTextureCallback | `callback`: the `GdkCursorGetTextureCallback`
-> Maybe a | `fallback`: the `GdkCursor` to fall back to when this one cannot be supported
-> m (Maybe Cursor) | Returns: a new `GdkCursor`

Creates a new callback-based cursor object.

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

Since: 4.16

## newFromName

cursorNewFromName Source #

Arguments

:: (HasCallStack, MonadIO m, IsCursor a) |
=> Text | `name`: the name of the cursor
-> Maybe a | `fallback`: `Nothing` or the `GdkCursor` to fall back to when this one cannot be supported
-> m (Maybe Cursor) | Returns: a new `GdkCursor`, or `Nothing` if there is no cursor with the given 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" | 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 |

## newFromTexture

cursorNewFromTexture Source #

Arguments

:: (HasCallStack, MonadIO m, IsTexture a, IsCursor b) |
=> a | `texture`: the texture providing the pixel data
-> Int32 | `hotspotX`: the horizontal offset of the “hotspot” of the cursor
-> Int32 | `hotspotY`: the vertical offset of the “hotspot” of the cursor
-> Maybe b | `fallback`: the `GdkCursor` to fall back to when this one cannot be supported
-> m Cursor | Returns: a new `GdkCursor`

Creates a new cursor from a `GdkTexture`.

# Properties

## fallback

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

constructCursorFallback :: (IsCursor o, MonadIO m, IsCursor a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`fallback`” property. This is rarely needed directly, but it is used by `new`.

getCursorFallback :: (MonadIO m, IsCursor o) => o -> m (Maybe Cursor) Source #

Get the value of the “`fallback`” property. When overloading is enabled, this is equivalent to

    get cursor #fallback

## hotspotX

X position of the cursor hotspot in the cursor image.

constructCursorHotspotX :: (IsCursor o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`hotspot-x`” property. This is rarely needed directly, but it is used by `new`.

getCursorHotspotX :: (MonadIO m, IsCursor o) => o -> m Int32 Source #

Get the value of the “`hotspot-x`” property. When overloading is enabled, this is equivalent to

    get cursor #hotspotX

## hotspotY

Y position of the cursor hotspot in the cursor image.

constructCursorHotspotY :: (IsCursor o, MonadIO m) => Int32 -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`hotspot-y`” property. This is rarely needed directly, but it is used by `new`.

getCursorHotspotY :: (MonadIO m, IsCursor o) => o -> m Int32 Source #

Get the value of the “`hotspot-y`” property. When overloading is enabled, this is equivalent to

    get cursor #hotspotY

## name

Name of this this cursor.

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

constructCursorName :: (IsCursor o, MonadIO m) => Text -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`name`” property. This is rarely needed directly, but it is used by `new`.

getCursorName :: (MonadIO m, IsCursor o) => o -> m (Maybe Text) Source #

Get the value of the “`name`” property. When overloading is enabled, this is equivalent to

    get cursor #name

## texture

The texture displayed by this cursor.

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

constructCursorTexture :: (IsCursor o, MonadIO m, IsTexture a) => a -> m (GValueConstruct o) Source #

Construct a `GValueConstruct` with valid value for the “`texture`” property. This is rarely needed directly, but it is used by `new`.

getCursorTexture :: (MonadIO m, IsCursor o) => o -> m (Maybe Texture) Source #

Get the value of the “`texture`” property. When overloading is enabled, this is equivalent to

    get cursor #texture