PaintableProtocol

public protocol PaintableProtocol

The PaintableProtocol protocol exposes the methods and properties of an underlying GdkPaintable instance. The default implementation of these can be found in the protocol extension below. For a concrete class that implements these methods and properties, see Paintable. Alternatively, use PaintableRef as a lighweight, unowned reference if you already have an instance you just want to use.

GdkPaintable is a simple interface used by GTK to represent 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 [methodGdk.Paintable.snapshot]. 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 [classGdkSnapshot] 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 [methodGdk.Paintable.invalidate_contents] which will emit the [signalGdkPaintable::invalidate-contents] signal. If a paintable is known to never change its contents, it will set the GDK_PAINTABLE_STATIC_CONTENTS flag. If a consumer cannot deal with changing contents, it may call [methodGdk.Paintable.get_current_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 [methodGdk.Paintable.invalidate_size] which will emit the [signalGdkPaintable::invalidate-size] signal. And just like for contents, if a paintable is known to never change its size, it will set the GDK_PAINTABLE_STATIC_SIZE flag.

Besides API for applications, there are some functions that are only useful for implementing subclasses and should not be used by applications: [methodGdk.Paintable.invalidate_contents], [methodGdk.Paintable.invalidate_size], [funcGdk.Paintable.new_empty].

Show on GitHub
  • ptr

    Untyped pointer to the underlying GdkPaintable instance.

    Declaration

    Swift

    var ptr: UnsafeMutableRawPointer! { get }
    Show on GitHub
  • paintable_ptr Default implementation

    Typed pointer to the underlying GdkPaintable instance.

    Default Implementation

    Return the stored, untyped pointer as a typed pointer to the GdkPaintable instance.

    Declaration

    Swift

    var paintable_ptr: UnsafeMutablePointer<GdkPaintable>! { get }
    Show on GitHub

  • Required Initialiser for types conforming to PaintableProtocol

    Declaration

    Swift

    init(raw: UnsafeMutableRawPointer)
    Show on GitHub

Paintable signals

  • Connect a Swift signal handler to the given, typed PaintableSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: PaintableSignalName, flags f: ConnectFlags = ConnectFlags(0), handler h: @escaping SignalHandler) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    handler

    The Swift signal handler (function or callback) to invoke on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

  • Connect a C signal handler to the given, typed PaintableSignalName signal

    Declaration

    Swift

    @discardableResult
@inlinable
func connect(signal s: PaintableSignalName, flags f: ConnectFlags = ConnectFlags(0), data userData: gpointer!, destroyData destructor: GClosureNotify? = nil, signalHandler h: @escaping GCallback) -> Int

    Parameters

    signal

    The signal to connect
    flags

    The connection flags to use
    data

    A pointer to user data to provide to the callback
    destroyData

    A GClosureNotify C function to destroy the data pointed to by userData
    signalHandler

    The C function to be called on the given signal

    Return Value

    The signal handler ID (always greater than 0 for successful connections)

    Show on GitHub

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

    Note

    This represents the underlying invalidate-contents signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onInvalidateContents(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: PaintableRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the invalidateContents signal is emitted
    Show on GitHub
  • invalidateContentsSignal Extension method

    Typed invalidate-contents signal for using the connect(signal:) methods

    Declaration

    Swift

    static var invalidateContentsSignal: PaintableSignalName { get }
    Show on GitHub

  • Emitted when the intrinsic size of the paintable changes.

    This means the values reported by at least one of [methodGdk.Paintable.get_intrinsic_width], [methodGdk.Paintable.get_intrinsic_height] or [methodGdk.Paintable.get_intrinsic_aspect_ratio] has changed.

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

    Note

    This represents the underlying invalidate-size signal

    Declaration

    Swift

    @discardableResult
@inlinable
func onInvalidateSize(flags: ConnectFlags = ConnectFlags(0), handler: @escaping (_ unownedSelf: PaintableRef) -> Void) -> Int

    Parameters

    flags

    Flags
    unownedSelf

    Reference to instance of self
    handler

    The signal handler to call Run the given callback whenever the invalidateSize signal is emitted
    Show on GitHub
  • invalidateSizeSignal Extension method

    Typed invalidate-size signal for using the connect(signal:) methods

    Declaration

    Swift

    static var invalidateSizeSignal: PaintableSignalName { get }
    Show on GitHub

Paintable Interface: PaintableProtocol extension (methods and fields)

  • 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 specified_width and specified_height 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.

    Declaration

    Swift

    @inlinable
func computeConcreteSize(specifiedWidth: CDouble, specifiedHeight: CDouble, defaultWidth: CDouble, defaultHeight: CDouble, concreteWidth: UnsafeMutablePointer<CDouble>!, concreteHeight: UnsafeMutablePointer<CDouble>!)
    Show on GitHub
  • getCurrentImage() Extension method

    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.

    Declaration

    Swift

    @inlinable
func getCurrentImage() -> PaintableRef!
    Show on GitHub
  • getFlags() Extension method

    Get flags for the paintable.

    This is oftentimes useful for optimizations.

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

    Declaration

    Swift

    @inlinable
func getFlags() -> PaintableFlags
    Show on GitHub
  • getIntrinsicAspectRatio() Extension method

    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 [methodGdk.Paintable.snapshot].

    Usually when a paintable returns nonzero values from [methodGdk.Paintable.get_intrinsic_width] and [methodGdk.Paintable.get_intrinsic_height] 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.

    Declaration

    Swift

    @inlinable
func getIntrinsicAspectRatio() -> CDouble
    Show on GitHub
  • getIntrinsicHeight() Extension method

    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 [methodGdk.Paintable.snapshot].

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

    Declaration

    Swift

    @inlinable
func getIntrinsicHeight() -> Int
    Show on GitHub
  • getIntrinsicWidth() Extension method

    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 [methodGdk.Paintable.snapshot].

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

    Declaration

    Swift

    @inlinable
func getIntrinsicWidth() -> Int
    Show on GitHub
  • invalidateContents() Extension method

    Called by implementations of GdkPaintable to invalidate their contents.

    Unless the contents are invalidated, implementations must guarantee that multiple calls of [methodGdk.Paintable.snapshot] produce the same output.

    This function will emit the [signalGdk.Paintable::invalidate-contents] signal.

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

    Declaration

    Swift

    @inlinable
func invalidateContents()
    Show on GitHub
  • invalidateSize() Extension method

    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 [signalGdk.Paintable::invalidate-size] signal.

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

    Declaration

    Swift

    @inlinable
func invalidateSize()
    Show on GitHub

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

    Declaration

    Swift

    @inlinable
func snapshot<SnapshotT>(snapshot: SnapshotT, width: CDouble, height: CDouble) where SnapshotT : SnapshotProtocol
    Show on GitHub
  • currentImage Extension method

    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.

    Declaration

    Swift

    @inlinable
var currentImage: PaintableRef! { get }
    Show on GitHub
  • flags Extension method

    Get flags for the paintable.

    This is oftentimes useful for optimizations.

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

    Declaration

    Swift

    @inlinable
var flags: PaintableFlags { get }
    Show on GitHub
  • intrinsicAspectRatio Extension method

    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 [methodGdk.Paintable.snapshot].

    Usually when a paintable returns nonzero values from [methodGdk.Paintable.get_intrinsic_width] and [methodGdk.Paintable.get_intrinsic_height] 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.

    Declaration

    Swift

    @inlinable
var intrinsicAspectRatio: CDouble { get }
    Show on GitHub
  • intrinsicHeight Extension method

    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 [methodGdk.Paintable.snapshot].

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

    Declaration

    Swift

    @inlinable
var intrinsicHeight: Int { get }
    Show on GitHub
  • intrinsicWidth Extension method

    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 [methodGdk.Paintable.snapshot].

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

    Declaration

    Swift

    @inlinable
var intrinsicWidth: Int { get }
    Show on GitHub