gdk_paintable_get_current_image ()

GdkPaintable *
gdk_paintable_get_current_image (GdkPaintable *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.

gdk_paintable_snapshot ()

void
gdk_paintable_snapshot (GdkPaintable *paintable,
                        GdkSnapshot *snapshot,
                        double width,
                        double height);

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.

gdk_paintable_get_flags ()

GdkPaintableFlags
gdk_paintable_get_flags (GdkPaintable *paintable);

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

See GdkPaintableFlags for the flags and what they mean.

gdk_paintable_get_intrinsic_width ()

int
gdk_paintable_get_intrinsic_width (GdkPaintable *paintable);

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 gdk_paintable_snapshot().

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

gdk_paintable_get_intrinsic_height ()

int
gdk_paintable_get_intrinsic_height (GdkPaintable *paintable);

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 gdk_paintable_snapshot().

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

gdk_paintable_get_intrinsic_aspect_ratio ()

double
gdk_paintable_get_intrinsic_aspect_ratio
                               (GdkPaintable *paintable);

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 gdk_paintable_snapshot().

Usually when a paintable returns nonzero values from gdk_paintable_get_intrinsic_width() and gdk_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.

gdk_paintable_compute_concrete_size ()

void
gdk_paintable_compute_concrete_size (GdkPaintable *paintable,
                                     double specified_width,
                                     double specified_height,
                                     double default_width,
                                     double default_height,
                                     double *concrete_width,
                                     double *concrete_height);

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

gdk_paintable_invalidate_contents ()

void
gdk_paintable_invalidate_contents (GdkPaintable *paintable);

Called by implementations of GdkPaintable to invalidate their contents. Unless the contents are invalidated, implementations must guarantee that multiple calls of gdk_paintable_snapshot() produce the same output.

This function will emit the “invalidate-contents” signal.

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

gdk_paintable_invalidate_size ()

void
gdk_paintable_invalidate_size (GdkPaintable *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 “invalidate-size” signal.

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

gdk_paintable_new_empty ()

GdkPaintable *
gdk_paintable_new_empty (int intrinsic_width,
                         int intrinsic_height);

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

GdkPaintable

typedef struct _GdkPaintable GdkPaintable;

Interface for paintable objects.

struct GdkPaintableInterface

struct GdkPaintableInterface {
  /* draw to 0,0 with the given width and height */
  void                  (* snapshot)                    (GdkPaintable           *paintable,
                                                         GdkSnapshot            *snapshot,
                                                         double                  width,
                                                         double                  height);
  /* get the current contents in an immutable form (optional) */
  GdkPaintable *        (* get_current_image)           (GdkPaintable           *paintable);

  /* get flags for potential optimizations (optional) */
  GdkPaintableFlags     (* get_flags)                   (GdkPaintable           *paintable);
  /* preferred width of paintable or 0 if it has no width (optional) */
  int                   (* get_intrinsic_width)         (GdkPaintable           *paintable);
  /* preferred height of paintable or 0 if it has no height (optional) */
  int                   (* get_intrinsic_height)        (GdkPaintable           *paintable);
  /* aspect ratio (width / height) of paintable or 0 if it has no aspect ratio (optional) */
  double                (* get_intrinsic_aspect_ratio)  (GdkPaintable           *paintable);
};

The list of functions that can be implemented for the GdkPaintable interface.

Note that apart from the GdkPaintableInterface.snapshot() function, no virtual function of this interface is mandatory to implement, though it is a good idea to implement GdkPaintableInterface.get_current_image() for non-static paintables and GdkPaintableInterface.get_flags() if the image is not dynamic as the default implementation returns no flags and that will make the implementation likely quite slow.

enum GdkPaintableFlags

Flags about this object. Implementations use these for optimizations such as caching.

GdkSnapshot

typedef struct _GdkSnapshot GdkSnapshot;

Base type for snapshot operations.

The “invalidate-contents” signal

void
user_function (GdkPaintable *paintable,
               gpointer      user_data)

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.

Flags: Run Last

The “invalidate-size” signal

void
user_function (GdkPaintable *paintable,
               gpointer      user_data)

Emitted when the intrinsic size of the paintable changes. This means the values reported by at least one of gdk_paintable_get_intrinsic_width(), gdk_paintable_get_intrinsic_height() or gdk_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.

Flags: Run Last