GI.Gdk.Interfaces.Paintable

Paintable is a simple interface used by GDK and GDK to represent objects that 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 Paintable 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 Paintable and don't know what to do, it is suggested that you scale your paintable ignoring any potential aspect ratio.

The contents that a Paintable 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 Paintable will however always produce the same output for the same snapshot.

A Paintable may change its contents, meaning that it will now produce a different output with the same snpashot. Once that happens, it will call paintableInvalidateContents which will emit the invalidateContents signal. If a paintable is known to never change its contents, it will set the GDK_PAINTABLE_STATIC_CONTENT flag. If a consumer cannot deal with changing contents, it may call gdk_paintable_get_static_image() 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 invalidateSize signal. And just like for contents, if a paintable is known to never change its size, it will set the PaintableFlagsSize 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.

Exported types

newtype Paintable

Memory-managed wrapper type.

Constructors

Paintable (ManagedPtr Paintable)

Instances

Eq Paintable

Defined in GI.Gdk.Interfaces.Paintable

Methods

(==) :: Paintable -> Paintable -> Bool

(/=) :: Paintable -> Paintable -> Bool

GObject Paintable

Defined in GI.Gdk.Interfaces.Paintable

Methods

gobjectType :: IO GType

IsGValue Paintable

Convert Paintable to and from GValue with toGValue and fromGValue.

Defined in GI.Gdk.Interfaces.Paintable

Methods

toGValue :: Paintable -> IO GValue

fromGValue :: GValue -> IO Paintable

HasParentTypes Paintable

Defined in GI.Gdk.Interfaces.Paintable

type ParentTypes Paintable

Defined in GI.Gdk.Interfaces.Paintable

type ParentTypes Paintable = '[Object]

noPaintable :: Maybe Paintable

A convenience alias for Nothing :: Maybe Paintable.

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

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

Instances

(GObject o, IsDescendantOf Paintable o) => IsPaintable o

Defined in GI.Gdk.Interfaces.Paintable

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

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

Methods

Overloaded methods

computeConcreteSize

paintableComputeConcreteSize

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

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

Applies the sizing algorithm outlined in https://drafts.csswg.org/css-images-3/default-sizing 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

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> 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

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> m [PaintableFlags]

Returns: The PaintableFlags for this paintable.

Get flags for the paintable. This is oftentimes useful for optimizations.

See PaintableFlags for the flags and what they mean.

getIntrinsicAspectRatio

paintableGetIntrinsicAspectRatio

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> m Double

Returns: the intrinsic aspect ratio of paintable or 0.0 if none.

Gets the preferred aspect ratio the paintable would like to be displayed at. The aspect ration 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 this 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 non-0 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.0. Negative values are never returned.

getIntrinsicHeight

paintableGetIntrinsicHeight

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> 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

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> 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

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> m ()

Called by implementations of Paintable to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls to GdkPaintable[snapshot](#signal:snapshot) produce the same output.

This function will emit the GdkPaintable[invalidateContents](#signal:invalidateContents) signal.

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

invalidateSize

paintableInvalidateSize

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a)

=> a

paintable: a Paintable

-> m ()

Called by implementations of Paintable to invalidate their size. As long as the size is not invalidated, paintable must return the same values for its width, height and intrinsic height.

This function will emit the GdkPaintable[invalidateSize](#signal:invalidateSize) signal.

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

newEmpty

paintableNewEmpty

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 Paintable

Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the GdkPaintableClass:get_current_image() virtual function when the paintable is in an incomplete state (like a GtkMediaStream before receiving the first frame).

snapshot

paintableSnapshot

Arguments

:: (HasCallStack, MonadIO m, IsPaintable a, IsSnapshot b)

=> a

paintable: a Paintable

-> b

snapshot: a Snapshot 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 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 C_PaintableInvalidateContentsCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type PaintableInvalidateContentsCallback = IO ()

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 -> PaintableInvalidateContentsCallback -> m SignalHandlerId

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

genClosure_PaintableInvalidateContents :: MonadIO m => PaintableInvalidateContentsCallback -> m (GClosure C_PaintableInvalidateContentsCallback)

Wrap the callback into a GClosure.

mk_PaintableInvalidateContentsCallback :: C_PaintableInvalidateContentsCallback -> IO (FunPtr C_PaintableInvalidateContentsCallback)

Generate a function pointer callable from C code, from a C_PaintableInvalidateContentsCallback.

noPaintableInvalidateContentsCallback :: Maybe PaintableInvalidateContentsCallback

A convenience synonym for Nothing :: Maybe PaintableInvalidateContentsCallback.

onPaintableInvalidateContents :: (IsPaintable a, MonadIO m) => a -> PaintableInvalidateContentsCallback -> m SignalHandlerId

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

wrap_PaintableInvalidateContentsCallback :: PaintableInvalidateContentsCallback -> C_PaintableInvalidateContentsCallback

Wrap a PaintableInvalidateContentsCallback into a C_PaintableInvalidateContentsCallback.

invalidateSize

type C_PaintableInvalidateSizeCallback = Ptr () -> Ptr () -> IO ()

Type for the callback on the (unwrapped) C side.

type PaintableInvalidateSizeCallback = IO ()

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 -> PaintableInvalidateSizeCallback -> m SignalHandlerId

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

genClosure_PaintableInvalidateSize :: MonadIO m => PaintableInvalidateSizeCallback -> m (GClosure C_PaintableInvalidateSizeCallback)

Wrap the callback into a GClosure.

mk_PaintableInvalidateSizeCallback :: C_PaintableInvalidateSizeCallback -> IO (FunPtr C_PaintableInvalidateSizeCallback)

Generate a function pointer callable from C code, from a C_PaintableInvalidateSizeCallback.

noPaintableInvalidateSizeCallback :: Maybe PaintableInvalidateSizeCallback

A convenience synonym for Nothing :: Maybe PaintableInvalidateSizeCallback.

onPaintableInvalidateSize :: (IsPaintable a, MonadIO m) => a -> PaintableInvalidateSizeCallback -> m SignalHandlerId

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

wrap_PaintableInvalidateSizeCallback :: PaintableInvalidateSizeCallback -> C_PaintableInvalidateSizeCallback

Wrap a PaintableInvalidateSizeCallback into a C_PaintableInvalidateSizeCallback.