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.Interfaces.Paintable

Contents

- Exported types
- Methods
  - computeConcreteSize
  - getCurrentImage
  - getFlags
  - getIntrinsicAspectRatio
  - getIntrinsicHeight
  - getIntrinsicWidth
  - invalidateContents
  - invalidateSize
  - newEmpty
  - snapshot
- Signals
  - invalidateContents
  - invalidateSize

Description

An interface for content that can be painted.

The content of a `GdkPaintable` can be painted anywhere at any size without requiring any sort of layout. The interface is inspired by similar concepts elsewhere, such as ClutterContent, HTML/CSS Paint Sources, or SVG Paint Servers.

A `GdkPaintable` can be snapshot at any time and size using `paintableSnapshot`. How the paintable interprets that size and if it scales or centers itself into the given rectangle is implementation defined, though if you are implementing a `GdkPaintable` and don't know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

The contents that a `GdkPaintable` produces may depend on the `Snapshot` passed to it. For example, paintables may decide to use more detailed images on higher resolution screens or when OpenGL is available. A `GdkPaintable` will however always produce the same output for the same snapshot.

A `GdkPaintable` may change its contents, meaning that it will now produce a different output with the same snapshot. Once that happens, it will call `paintableInvalidateContents` which will emit the Paintable::invalidateContents signal. If a paintable is known to never change its contents, it will set the `PaintableFlagsStaticContents` flag. If a consumer cannot deal with changing contents, it may call `paintableGetCurrentImage` which will return a static paintable and use that.

A paintable can report an intrinsic (or preferred) size or aspect ratio it wishes to be rendered at, though it doesn't have to. Consumers of the interface can use this information to layout thepaintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling `paintableInvalidateSize` which will emit the Paintable::invalidateSize signal. And just like for contents, if a paintable is known to never change its size, it will set the `PaintableFlagsStaticSize` flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: `paintableInvalidateContents`, `paintableInvalidateSize`, `paintableNewEmpty`.

Synopsis

- newtype Paintable = Paintable (ManagedPtr Paintable)
- class (GObject o, IsDescendantOf Paintable o) => IsPaintable o
- toPaintable :: (MonadIO m, IsPaintable o) => o -> m Paintable
- paintableComputeConcreteSize :: (HasCallStack, MonadIO m, IsPaintable a) => a -> Double -> Double -> Double -> Double -> m (Double, Double)
- paintableGetCurrentImage :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m Paintable
- paintableGetFlags :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m [PaintableFlags]
- paintableGetIntrinsicAspectRatio :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m Double
- paintableGetIntrinsicHeight :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m Int32
- paintableGetIntrinsicWidth :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m Int32
- paintableInvalidateContents :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m ()
- paintableInvalidateSize :: (HasCallStack, MonadIO m, IsPaintable a) => a -> m ()
- paintableNewEmpty :: (HasCallStack, MonadIO m) => Int32 -> Int32 -> m Paintable
- paintableSnapshot :: (HasCallStack, MonadIO m, IsPaintable a, IsSnapshot b) => a -> b -> Double -> Double -> m ()
- type PaintableInvalidateContentsCallback = IO ()
- afterPaintableInvalidateContents :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateContentsCallback) -> m SignalHandlerId
- onPaintableInvalidateContents :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateContentsCallback) -> m SignalHandlerId
- type PaintableInvalidateSizeCallback = IO ()
- afterPaintableInvalidateSize :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateSizeCallback) -> m SignalHandlerId
- onPaintableInvalidateSize :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateSizeCallback) -> m SignalHandlerId

# Exported types

newtype Paintable Source #

Memory-managed wrapper type.

Constructors

Paintable (ManagedPtr Paintable) |

#### Instances

Instances details

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

class (GObject o, IsDescendantOf Paintable o) => IsPaintable o Source #

Type class for types which can be safely cast to `Paintable`, for instance with `toPaintable`.

#### Instances

Instances details

(GObject o, IsDescendantOf Paintable o) => IsPaintable o Source # |
Instance details Defined in GI.Gdk.Interfaces.Paintable

toPaintable :: (MonadIO m, IsPaintable o) => o -> m Paintable Source #

Cast to `Paintable`, 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, computeConcreteSize, forceFloating, freezeNotify, getv, invalidateContents, invalidateSize, isFloating, notify, notifyByPspec, ref, refSink, runDispose, snapshot, stealData, stealQdata, thawNotify, unref, watchClosure.

#### Getters

getCurrentImage, getData, getFlags, getIntrinsicAspectRatio, getIntrinsicHeight, getIntrinsicWidth, getProperty, getQdata.

#### Setters

setData, setDataFull, setProperty.

## computeConcreteSize

paintableComputeConcreteSize Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> Double | `specifiedWidth`: the width `paintable` could be drawn into or 0.0 if unknown
-> Double | `specifiedHeight`: the height `paintable` could be drawn into or 0.0 if unknown
-> Double | `defaultWidth`: the width `paintable` would be drawn into if no other constraints were given
-> Double | `defaultHeight`: the height `paintable` would be drawn into if no other constraints were given
-> m (Double, Double) |

Compute a concrete size for the `GdkPaintable`.

Applies the sizing algorithm outlined in the CSS Image spec to the given `paintable`. See that link for more details.

It is not necessary to call this function when both `specifiedWidth` and `specifiedHeight` are known, but it is useful to call this function in GtkWidget:measure implementations to compute the other dimension when only one dimension is given.

## getCurrentImage

paintableGetCurrentImage Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m Paintable | Returns: An immutable paintable for the current contents of `paintable`

Gets an immutable paintable for the current contents displayed by `paintable`.

This is useful when you want to retain the current state of an animation, for example to take a screenshot of a running animation.

If the `paintable` is already immutable, it will return itself.

## getFlags

paintableGetFlags Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m [PaintableFlags] | Returns: The `GdkPaintableFlags` for this paintable

Get flags for the paintable.

This is oftentimes useful for optimizations.

See [flags`gdk`.PaintableFlags] for the flags and what they mean.

## getIntrinsicAspectRatio

paintableGetIntrinsicAspectRatio Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m Double | Returns: the intrinsic aspect ratio of `paintable` or 0 if none.

Gets the preferred aspect ratio the `paintable` would like to be displayed at.

The aspect ratio is the width divided by the height, so a value of 0.5 means that the `paintable` prefers to be displayed twice as high as it is wide. Consumers of this interface can use this to preserve aspect ratio when displaying the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to `paintableSnapshot`.

Usually when a `paintable` returns nonzero values from `paintableGetIntrinsicWidth` and `paintableGetIntrinsicHeight` the aspect ratio should conform to those values, though that is not required.

If the `paintable` does not have a preferred aspect ratio, it returns 0. Negative values are never returned.

## getIntrinsicHeight

paintableGetIntrinsicHeight Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m Int32 | Returns: the intrinsic height of `paintable` or 0 if none.

Gets the preferred height the `paintable` would like to be displayed at.

Consumers of this interface can use this to reserve enough space to draw the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to `paintableSnapshot`.

If the `paintable` does not have a preferred height, it returns 0. Negative values are never returned.

## getIntrinsicWidth

paintableGetIntrinsicWidth Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m Int32 | Returns: the intrinsic width of `paintable` or 0 if none.

Gets the preferred width the `paintable` would like to be displayed at.

Consumers of this interface can use this to reserve enough space to draw the paintable.

This is a purely informational value and does not in any way limit the values that may be passed to `paintableSnapshot`.

If the `paintable` does not have a preferred width, it returns 0. Negative values are never returned.

## invalidateContents

paintableInvalidateContents Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m () |

Called by implementations of `GdkPaintable` to invalidate their contents.

Unless the contents are invalidated, implementations must guarantee that multiple calls of `paintableSnapshot` produce the same output.

This function will emit the Paintable::invalidateContents signal.

If a `paintable` reports the `PaintableFlagsStaticContents` flag, it must not call this function.

## invalidateSize

paintableInvalidateSize Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a) |
=> a | `paintable`: a `GdkPaintable`
-> m () |

Called by implementations of `GdkPaintable` to invalidate their size.

As long as the size is not invalidated, `paintable` must return the same values for its intrinsic width, height and aspect ratio.

This function will emit the Paintable::invalidateSize signal.

If a `paintable` reports the `PaintableFlagsStaticSize` flag, it must not call this function.

## newEmpty

paintableNewEmpty Source #

Arguments

:: (HasCallStack, MonadIO m) |
=> Int32 | `intrinsicWidth`: The intrinsic width to report. Can be 0 for no width.
-> Int32 | `intrinsicHeight`: The intrinsic height to report. Can be 0 for no height.
-> m Paintable | Returns: a `GdkPaintable`

Returns a paintable that has the given intrinsic size and draws nothing.

This is often useful for implementing the `Paintable`.`get_current_image`() virtual function when the paintable is in an incomplete state (like a GtkMediaStream before receiving the first frame).

## snapshot

paintableSnapshot Source #

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a, IsSnapshot b) |
=> a | `paintable`: a `GdkPaintable`
-> b | `snapshot`: a `GdkSnapshot` to snapshot to
-> Double | `width`: width to snapshot in
-> Double | `height`: height to snapshot in
-> m () |

Snapshots the given paintable with the given `width` and `height`.

The paintable is drawn at the current (0,0) offset of the `snapshot`. If `width` and `height` are not larger than zero, this function will do nothing.

# Signals

## invalidateContents

type PaintableInvalidateContentsCallback = IO () Source #

Emitted when the contents of the `paintable` change.

Examples for such an event would be videos changing to the next frame or the icon theme for an icon changing.

afterPaintableInvalidateContents :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateContentsCallback) -> m SignalHandlerId Source #

Connect a signal handler for the invalidateContents signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after paintable #invalidateContents callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onPaintableInvalidateContents :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateContentsCallback) -> m SignalHandlerId Source #

Connect a signal handler for the invalidateContents signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on paintable #invalidateContents callback

## invalidateSize

type PaintableInvalidateSizeCallback = IO () Source #

Emitted when the intrinsic size of the `paintable` changes.

This means the values reported by at least one of `paintableGetIntrinsicWidth`, `paintableGetIntrinsicHeight` or `paintableGetIntrinsicAspectRatio` has changed.

Examples for such an event would be a paintable displaying the contents of a toplevel surface being resized.

afterPaintableInvalidateSize :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateSizeCallback) -> m SignalHandlerId Source #

Connect a signal handler for the invalidateSize signal, to be run after the default handler. When overloading is enabled, this is equivalent to

    after paintable #invalidateSize callback

By default the object invoking the signal is not passed to the callback. If you need to access it, you can use the implit `?self` parameter. Note that this requires activating the `ImplicitParams` GHC extension.

onPaintableInvalidateSize :: (IsPaintable a, MonadIO m) => a -> ((?self :: a) => PaintableInvalidateSizeCallback) -> m SignalHandlerId Source #

Connect a signal handler for the invalidateSize signal, to be run before the default handler. When overloading is enabled, this is equivalent to

    on paintable #invalidateSize callback