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 [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 [classGdk.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 [methodGdk.Paintable.invalidate_contents] which will emit the [signalGdk.Paintable::invalidate-contents] signal. If a paintable is known to never change its contents, it will set the Gdk.Paintable.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 [signalGdk.Paintable::invalidate-size] signal. And just like for contents, if a paintable is known to never change its size, it will set the Gdk.Paintable.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].
function "+" (W : Gdk_Paintable) return Gdk_Paintable
type Cb_Gdk_Paintable_Void is not null access procedure (Self : Gdk_Paintable);
type Cb_GObject_Void is not null access procedure
(Self : access Glib.Object.GObject_Record'Class);
procedure Compute_Concrete_Size
(Self : Gdk_Paintable;
Specified_Width : Gdouble;
Specified_Height : Gdouble;
Default_Width : Gdouble;
Default_Height : Gdouble;
Concrete_Width : out Gdouble;
Concrete_Height : out Gdouble)
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.
the width Paintable could be drawn into or 0.0 if unknown
the height Paintable could be drawn into or 0.0 if unknown
the width Paintable would be drawn into if no other constraints were given
the height Paintable would be drawn into if no other constraints were given
will be set to the concrete width computed
will be set to the concrete height computed
type Gdk_Paintable is new Glib.Types.GType_Interface;
type Gdk_Paintable_Flags is mod 2 ** Integer'Size;
Flags about a paintable object.
Implementations use these for optimizations such as caching.
package Gdk_Paintable_Flags_Properties is
new Generic_Internal_Flags_Property (Gdk_Paintable_Flags);
Gdk_Paintable_Static_Contents : constant Gdk_Paintable_Flags := 2;
Gdk_Paintable_Static_Size : constant Gdk_Paintable_Flags := 1;
function Get_Current_Image (Self : Gdk_Paintable) return Gdk_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.
An immutable paintable for the current contents of Paintable
function Get_Flags (Self : Gdk_Paintable) return Gdk_Paintable_Flags
Get flags for the paintable. This is oftentimes useful for optimizations. See [flagsGdk.PaintableFlags] for the flags and what they mean.
The GdkPaintableFlags for this paintable
function Get_Intrinsic_Aspect_Ratio (Self : Gdk_Paintable) return Gdouble
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.
the intrinsic aspect ratio of Paintable or 0 if none.
function Get_Intrinsic_Height (Self : Gdk_Paintable) return Glib.Gint
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.
the intrinsic height of Paintable or 0 if none.
function Get_Intrinsic_Width (Self : Gdk_Paintable) return Glib.Gint
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.
the intrinsic width of Paintable or 0 if none.
function Get_Type return Glib.GType
procedure Invalidate_Contents (Self : Gdk_Paintable)
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.Gdk_Paintable_Static_Contents flag, it must not call this function.
procedure Invalidate_Size (Self : Gdk_Paintable)
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.Gdk_Paintable_Static_Size flag, it must not call this function.
function New_Empty
(Intrinsic_Width : Glib.Gint;
Intrinsic_Height : Glib.Gint) return Gdk_Paintable
Returns a paintable that has the given intrinsic size and draws nothing. This is often useful for implementing the [vfuncGdk.Paintable.get_current_image] virtual function when the paintable is in an incomplete state (like a GtkMediaStream before receiving the first frame).
The intrinsic width to report. Can be 0 for no width.
The intrinsic height to report. Can be 0 for no height.
a GdkPaintable
Null_Gdk_Paintable : constant Gdk_Paintable;
procedure On_Invalidate_Contents
(Self : Gdk_Paintable;
Call : Cb_Gdk_Paintable_Void;
After : Boolean := False)
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.
procedure On_Invalidate_Contents
(Self : Gdk_Paintable;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
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.
procedure On_Invalidate_Size
(Self : Gdk_Paintable;
Call : Cb_Gdk_Paintable_Void;
After : Boolean := False)
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.
procedure On_Invalidate_Size
(Self : Gdk_Paintable;
Call : Cb_GObject_Void;
Slot : not null access Glib.Object.GObject_Record'Class;
After : Boolean := False)
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.
subtype Paintable_Interface_Descr is Glib.Object.Interface_Description;
type Property_Gdk_Paintable_Flags is new Gdk_Paintable_Flags_Properties.Property;
procedure Set_Get_Current_Image
(Self : Paintable_Interface_Descr;
Handler : Virtual_Get_Current_Image)
procedure Set_Get_Flags
(Self : Paintable_Interface_Descr;
Handler : Virtual_Get_Flags)
procedure Set_Get_Intrinsic_Aspect_Ratio
(Self : Paintable_Interface_Descr;
Handler : Virtual_Get_Intrinsic_Aspect_Ratio)
procedure Set_Get_Intrinsic_Height
(Self : Paintable_Interface_Descr;
Handler : Virtual_Get_Intrinsic_Height)
procedure Set_Get_Intrinsic_Width
(Self : Paintable_Interface_Descr;
Handler : Virtual_Get_Intrinsic_Width)
procedure Set_Snapshot
(Self : Paintable_Interface_Descr;
Handler : Virtual_Snapshot)
See Glib.Object.Add_Interface
Signal_Invalidate_Contents : constant Glib.Signal_Name := "invalidate-contents";
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.
Signal_Invalidate_Size : constant Glib.Signal_Name := "invalidate-size";
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.
procedure Snapshot
(Self : Gdk_Paintable;
Snapshot : not null access Gdk.Snapshot.Gdk_Snapshot_Record'Class;
Width : Gdouble;
Height : Gdouble)
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.
a GdkSnapshot to snapshot to
width to snapshot in
height to snapshot in
type Virtual_Get_Current_Image is access function (Self : Gdk_Paintable) return Gdk_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.
An immutable paintable for the current contents of Paintable
type Virtual_Get_Flags is access function (Self : Gdk_Paintable) return Gdk_Paintable_Flags;
Get flags for the paintable. This is oftentimes useful for optimizations. See [flagsGdk.PaintableFlags] for the flags and what they mean.
The GdkPaintableFlags for this paintable
type Virtual_Get_Intrinsic_Aspect_Ratio is access function (Self : Gdk_Paintable) return Gdouble;
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.
the intrinsic aspect ratio of Paintable or 0 if none.
type Virtual_Get_Intrinsic_Height is access function (Self : Gdk_Paintable) return Glib.Gint;
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.
the intrinsic height of Paintable or 0 if none.
type Virtual_Get_Intrinsic_Width is access function (Self : Gdk_Paintable) return Glib.Gint;
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.
the intrinsic width of Paintable or 0 if none.
type Virtual_Snapshot is access procedure
(Self : Gdk_Paintable;
Snapshot : System.Address;
Width : Gdouble;
Height : Gdouble);
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.
a GdkSnapshot to snapshot to
width to snapshot in
height to snapshot in