gtkmm: Gdk::Paintable Class Reference

gtkmm 4.8.0

Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Gdk::Paintable Class Reference

An interface for a paintable region. More...

`#include <gdkmm/paintable.h>`

Inheritance diagram for Gdk::Paintable:
[legend]

## Public Types
enum class | Flags { Flags::STATIC_SIZE = 1 << 0 , Flags::STATIC_CONTENTS = 1 << 1 }
| Flags about a paintable object. More...

## Public Member Functions
| Paintable (Paintable && src) noexcept
Paintable & | operator= (Paintable && src) noexcept
| ~Paintable () noexcept override
GdkPaintable * | gobj ()
| Provides access to the underlying C GObject. More...
const GdkPaintable * | gobj () const
| Provides access to the underlying C GObject. More...
void | snapshot (const Glib::RefPtr< Gdk::Snapshot > & snapshot, double width, double height)
| Snapshots the given paintable with the given width and height. More...
Glib::RefPtr< const Paintable > | get_current_image () const
| Gets an immutable paintable for the current contents displayed by paintable. More...
Flags | get_flags () const
| Get flags for the paintable. More...
int | get_intrinsic_width () const
| Gets the preferred width the paintable would like to be displayed at. More...
int | get_intrinsic_height () const
| Gets the preferred height the paintable would like to be displayed at. More...
double | get_intrinsic_aspect_ratio () const
| Gets the preferred aspect ratio the paintable would like to be displayed at. More...
void | compute_concrete_size (double specified_width, double specified_height, double default_width, double default_height, double & concrete_width, double & concrete_height) const
| Compute a concrete size for the `Gdk::Paintable`. More...
void | invalidate_contents ()
| Called by implementations of `Gdk::Paintable` to invalidate their contents. More...
void | invalidate_size ()
| Called by implementations of `Gdk::Paintable` to invalidate their size. More...
Glib::SignalProxy< void()> | signal_invalidate_contents ()
Glib::SignalProxy< void()> | signal_invalidate_size ()
Public Member Functions inherited from Glib::Interface
| Interface ()
| Interface (Interface &&src) noexcept
Interface & | operator= (Interface &&src) noexcept
| Interface (const Glib::Interface_Class &interface_class)
| Interface (GObject *castitem)
| ~Interface () noexcept override
| Interface (const Interface &)=delete
Interface & | operator= (const Interface &)=delete
GObject * | gobj ()
const GObject * | gobj () const
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
PropertyType | get_property (const Glib::ustring &property_name) const
sigc::connection | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void()> &slot)
sigc::connection | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void()> &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const

## Static Public Member Functions
static void | add_interface (GType gtype_implementer)
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Protected Member Functions
| Paintable ()
| You should derive from this class to use it. More...
virtual void | snapshot_vfunc (const Glib::RefPtr< Gdk::Snapshot > &snapshot, double width, double height)
virtual Glib::RefPtr< Paintable > | get_current_image_vfunc () const
virtual Flags | get_flags_vfunc () const
virtual int | get_intrinsic_width_vfunc () const
virtual int | get_intrinsic_height_vfunc () const
virtual double | get_intrinsic_aspect_ratio_vfunc () const
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gdk::Paintable > | wrap (GdkPaintable * object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Detailed Description

An interface for a paintable region.

Gdk::Paintable is a simple interface used by GDK and GTK 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 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 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 invalidate_contents() which will emit the signal_invalidate_contents() signal.
If a paintable is known to never change its contents, it will set the Flags::STATIC_CONTENTS flag. If a consumer cannot deal with changing contents, it may call 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 the paintable appropriately. Just like the contents, the size of a paintable can change. A paintable will indicate this by calling invalidate_size() which will emit the signal_invalidate_size() signal. And just like for contents, if a paintable is known to never change its size, it will set the Flags::STATIC_SIZE flag.

See also
  Gtk::Image, Gdk::Texture, Gtk::Snapshot

Since gtkmm 3.94:

## Constructor & Destructor Documentation

## ◆ Paintable() [1/2]

Gdk::Paintable::Paintable | ( |  | ) |
| protected

You should derive from this class to use it.

## ◆ Paintable() [2/2]

Gdk::Paintable::Paintable | ( | Paintable && | src | ) |
| noexcept

## ◆ ~Paintable()

Gdk::Paintable::~Paintable | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ add_interface()

static void Gdk::Paintable::add_interface | ( | GType | gtype_implementer | ) |
| static

## ◆ compute_concrete_size()

void Gdk::Paintable::compute_concrete_size | ( | double | specified_width,
|  | double | specified_height,
|  | double | default_width,
|  | double | default_height,
|  | double & | concrete_width,
|  | double & | concrete_height
| ) |  | const

Compute a concrete size for the `Gdk::Paintable`.

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.

Parameters

  specified_width | The width paintable could be drawn into or 0.0 if unknown.
  specified_height | The height paintable could be drawn into or 0.0 if unknown.
  default_width | The width paintable would be drawn into if no other constraints were given.
  default_height | The height paintable would be drawn into if no other constraints were given.
  concrete_width | Will be set to the concrete width computed.
  concrete_height | Will be set to the concrete height computed.

## ◆ get_current_image()

Glib::RefPtr< const Paintable > Gdk::Paintable::get_current_image | ( |  | ) | const

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.

Returns
  An immutable paintable for the current contents of paintable.

## ◆ get_current_image_vfunc()

virtual Glib::RefPtr< Paintable > Gdk::Paintable::get_current_image_vfunc | ( |  | ) | const
| protectedvirtual

## ◆ get_flags()

Flags Gdk::Paintable::get_flags | ( |  | ) | const

Get flags for the paintable.

This is oftentimes useful for optimizations.

See Gdk::PaintableFlags for the flags and what they mean.

Returns
  The `Gdk::PaintableFlags` for this paintable.

## ◆ get_flags_vfunc()

virtual Flags Gdk::Paintable::get_flags_vfunc | ( |  | ) | const
| protectedvirtual

## ◆ get_intrinsic_aspect_ratio()

double Gdk::Paintable::get_intrinsic_aspect_ratio | ( |  | ) | const

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

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

Returns
  The intrinsic aspect ratio of paintable or 0 if none.

## ◆ get_intrinsic_aspect_ratio_vfunc()

virtual double Gdk::Paintable::get_intrinsic_aspect_ratio_vfunc | ( |  | ) | const
| protectedvirtual

## ◆ get_intrinsic_height()

int Gdk::Paintable::get_intrinsic_height | ( |  | ) | const

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

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

Returns
  The intrinsic height of paintable or 0 if none.

## ◆ get_intrinsic_height_vfunc()

virtual int Gdk::Paintable::get_intrinsic_height_vfunc | ( |  | ) | const
| protectedvirtual

## ◆ get_intrinsic_width()

int Gdk::Paintable::get_intrinsic_width | ( |  | ) | const

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

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

Returns
  The intrinsic width of paintable or 0 if none.

## ◆ get_intrinsic_width_vfunc()

virtual int Gdk::Paintable::get_intrinsic_width_vfunc | ( |  | ) | const
| protectedvirtual

## ◆ get_type()

static GType Gdk::Paintable::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ gobj() [1/2]

GdkPaintable * Gdk::Paintable::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GdkPaintable * Gdk::Paintable::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ invalidate_contents()

void Gdk::Paintable::invalidate_contents | ( |  | ) |

Called by implementations of `Gdk::Paintable` to invalidate their contents.

Unless the contents are invalidated, implementations must guarantee that multiple calls of snapshot() produce the same output.

This function will emit the signal_invalidate_contents() signal.

If a paintable reports the Gdk::Paintable::Flags::STATIC_CONTENTS flag, it must not call this function.

## ◆ invalidate_size()

void Gdk::Paintable::invalidate_size | ( |  | ) |

Called by implementations of `Gdk::Paintable` 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 signal_invalidate_size() signal.

If a paintable reports the Gdk::Paintable::Flags::STATIC_SIZE flag, it must not call this function.

## ◆ operator=()

Paintable & Gdk::Paintable::operator= | ( | Paintable && | src | ) |
| noexcept

## ◆ signal_invalidate_contents()

Glib::SignalProxy< void()> Gdk::Paintable::signal_invalidate_contents | ( |  | ) |

Slot Prototype:
  `void on_my_invalidate_contents()`

Flags: Run Last

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

Glib::SignalProxy< void()> Gdk::Paintable::signal_invalidate_size | ( |  | ) |

Slot Prototype:
  `void on_my_invalidate_size()`

Flags: Run Last

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.

## ◆ snapshot()

void Gdk::Paintable::snapshot | ( | const Glib::RefPtr< Gdk::Snapshot > & | snapshot,
|  | double | width,
|  | double | height
| ) |  |

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.

Parameters

  snapshot | A `Gdk::Snapshot` to snapshot to.
  width | Width to snapshot in.
  height | Height to snapshot in.

## ◆ snapshot_vfunc()

virtual void Gdk::Paintable::snapshot_vfunc | ( | const Glib::RefPtr< Gdk::Snapshot > & | snapshot,
|  | double | width,
|  | double | height
| ) |  |
| protectedvirtual

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Gdk::Paintable > wrap | ( | GdkPaintable * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.