gtkmm: Gtk::Snapshot Class Reference

gtkmm 4.2.0

Public Member Functions | Static Public Member Functions | Related Functions | List of all members
Gtk::Snapshot Class Reference

Auxiliary object for snapshots. More...

`#include <gtkmm/snapshot.h>`

Inheritance diagram for Gtk::Snapshot:
[legend]

## Public Member Functions
| Snapshot (Snapshot&& src) noexcept
Snapshot& | operator= (Snapshot&& src) noexcept
| ~Snapshot () noexcept override
GtkSnapshot* | gobj ()
| Provides access to the underlying C GObject. More...
const GtkSnapshot* | gobj () const
| Provides access to the underlying C GObject. More...
GtkSnapshot* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
void | push_debug (const Glib::ustring& name)
| Creates a new debug node. More...
void | push_opacity (double opacity)
| Modifies the opacity of an image. More...
void | push_blur (double radius)
| Blurs an image. More...
void | push_repeat (const graphene_rect_t* bounds, const graphene_rect_t* child_bounds)
| Creates a node that repeats the child node. More...
void | push_repeat (const Gdk::Rectangle& bounds, const Gdk::Rectangle& child_bounds)
| Creates a node that repeats the child node. More...
void | push_repeat (const Gdk::Rectangle& bounds)
| A push_repeat() convenience overload. More...
void | push_clip (const graphene_rect_t* bounds)
| Clips an image to a rectangle. More...
void | push_clip (const Gdk::Rectangle& bounds)
| Clips an image to a rectangle. More...
void | push_cross_fade (double progress)
| Snapshots a cross-fade operation between two images with the given progress. More...
void | gl_shader_pop_texture ()
| Removes the top element from the stack of render nodes and adds it to the nearest `GskGLShaderNode` below it. More...
void | pop ()
| Removes the top element from the stack of render nodes, and appends it to the node underneath it. More...
void | save ()
| Makes a copy of the current state of snapshot and saves it on an internal stack. More...
void | restore ()
| Restores snapshot to the state saved by a preceding call to save() and removes that state from the stack of saved states. More...
void | rotate (float angle)
| Rotates @ snapshot's coordinate system by angle degrees in 2D space - or in 3D speak, rotates around the Z axis. More...
void | scale (float factor_x, float factor_y)
| Scales snapshot's coordinate system in 2-dimensional space by the given factors. More...
void | scale (float factor_x, float factor_y, float factor_z)
| Scales snapshot's coordinate system by the given factors. More...
void | perspective (float depth)
| Applies a perspective projection transform. More...
Cairo::RefPtr< Cairo::Context > | append_cairo (const graphene_rect_t* bounds)
| Creates a new `GskCairoNode` and appends it to the current render node of snapshot, without changing the current node. More...
Cairo::RefPtr< Cairo::Context > | append_cairo (const Gdk::Rectangle& bounds)
| Creates a new `GskCairoNode` and appends it to the current render node of snapshot, without changing the current node. More...
void | append_texture (const Glib::RefPtr< Gdk::Texture >& texture, const graphene_rect_t* bounds)
| Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot. More...
void | append_texture (const Glib::RefPtr< Gdk::Texture >& texture, const Gdk::Rectangle& bounds)
| Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot. More...
void | append_color (const Gdk::RGBA& color, const graphene_rect_t* bounds)
| Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot. More...
void | append_color (const Gdk::RGBA& color, const Gdk::Rectangle& bounds)
| Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot. More...
void | append_layout (const Glib::RefPtr< Pango::Layout >& layout, const Gdk::RGBA& color)
| Creates render nodes for rendering layout in the given foregound color and appends them to the current node of snapshot without changing the current node. More...
void | render_backgrount (const Glib::RefPtr< StyleContext >& context, double x, double y, double width, double height)
| Creates a render node for the CSS background according to context, and appends it to the current node of snapshot, without changing the current node. More...
void | render_frame (const Glib::RefPtr< StyleContext >& context, double x, double y, double width, double height)
| Creates a render node for the CSS border according to context, and appends it to the current node of snapshot, without changing the current node. More...
void | render_focus (const Glib::RefPtr< StyleContext >& context, double x, double y, double width, double height)
| Creates a render node for the focus outline according to context, and appends it to the current node of snapshot, without changing the current node. More...
void | render_layout (const Glib::RefPtr< StyleContext >& context, double x, double y, const Glib::RefPtr< Pango::Layout >& layout)
| Creates a render node for rendering layout according to the style information in context, and appends it to the current node of snapshot, without changing the current node. More...
void | render_insertion_cursor (const Glib::RefPtr< StyleContext >& context, double x, double y, const Glib::RefPtr< Pango::Layout >& layout, int index, Pango::Direction direction)
| Draws a text caret using snapshot at the specified index of layout. More...
Public Member Functions inherited from Gdk::Snapshot
| Snapshot (Snapshot&& src) noexcept
Snapshot& | operator= (Snapshot&& src) noexcept
| ~Snapshot () noexcept override
GdkSnapshot* | gobj ()
| Provides access to the underlying C GObject. More...
const GdkSnapshot* | gobj () const
| Provides access to the underlying C GObject. More...
GdkSnapshot* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
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 GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...
static Glib::RefPtr< Snapshot > | create ()
| Creates a new `GtkSnapshot`. More...
Static Public Member Functions inherited from Gdk::Snapshot
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system. More...

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Gtk::Snapshot > | wrap_gtk_snapshot (GtkSnapshot* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...
Related Functions inherited from Gdk::Snapshot
Glib::RefPtr< Gdk::Snapshot > | wrap (GdkSnapshot* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
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)

## Detailed Description

Auxiliary object for snapshots.

Snapshot is an auxiliary object that assists in creating GskRenderNodes in Gtk::Widget::snapshot_vfunc(). It functions in a similar way to a cairo context, and maintains a stack of render nodes and their associated transformations.

The node at the top of the stack is the the one that append_node() operates on. Use the push() and pop() functions to change the current node.

The typical way to obtain a Snapshot object is as an argument to Gtk::Widget::snapshot_vfunc(). If you need to create your own Snapshot, use create().

Since gtkmm 3.90:

## Constructor & Destructor Documentation

## ◆ Snapshot()

Gtk::Snapshot::Snapshot | ( | Snapshot&& | src | ) |
| noexcept

## ◆ ~Snapshot()

Gtk::Snapshot::~Snapshot | ( |  | ) |
| overridenoexcept

## Member Function Documentation

## ◆ append_cairo() [1/2]

Cairo::RefPtr<Cairo::Context> Gtk::Snapshot::append_cairo | ( | const Gdk::Rectangle& | bounds | ) |

Creates a new `GskCairoNode` and appends it to the current render node of snapshot, without changing the current node.

Parameters

  bounds | The bounds for the new node.

Returns
  A `cairo_t` suitable for drawing the contents of the newly created render node.

## ◆ append_cairo() [2/2]

Cairo::RefPtr<Cairo::Context> Gtk::Snapshot::append_cairo | ( | const graphene_rect_t * | bounds | ) |

Creates a new `GskCairoNode` and appends it to the current render node of snapshot, without changing the current node.

Parameters

  bounds | The bounds for the new node.

Returns
  A `cairo_t` suitable for drawing the contents of the newly created render node.

## ◆ append_color() [1/2]

void Gtk::Snapshot::append_color | ( | const Gdk::RGBA& | color,
|  | const Gdk::Rectangle& | bounds
| ) |  |

Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot.

You should try to avoid calling this function if color is transparent.

Parameters

  color | The `GdkRGBA` to draw.
  bounds | The bounds for the new node.

## ◆ append_color() [2/2]

void Gtk::Snapshot::append_color | ( | const Gdk::RGBA& | color,
|  | const graphene_rect_t * | bounds
| ) |  |

Creates a new render node drawing the color into the given bounds and appends it to the current render node of snapshot.

You should try to avoid calling this function if color is transparent.

Parameters

  color | The `GdkRGBA` to draw.
  bounds | The bounds for the new node.

## ◆ append_layout()

void Gtk::Snapshot::append_layout | ( | const Glib::RefPtr< Pango::Layout > & | layout,
|  | const Gdk::RGBA& | color
| ) |  |

Creates render nodes for rendering layout in the given foregound color and appends them to the current node of snapshot without changing the current node.

Parameters

  layout | The Pango::Layout to render.
  color | The foreground color to render the layout in.

## ◆ append_texture() [1/2]

void Gtk::Snapshot::append_texture | ( | const Glib::RefPtr< Gdk::Texture >& | texture,
|  | const Gdk::Rectangle& | bounds
| ) |  |

Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot.

Parameters

  texture | The `GdkTexture` to render.
  bounds | The bounds for the new node.

## ◆ append_texture() [2/2]

void Gtk::Snapshot::append_texture | ( | const Glib::RefPtr< Gdk::Texture >& | texture,
|  | const graphene_rect_t * | bounds
| ) |  |

Creates a new render node drawing the texture into the given bounds and appends it to the current render node of snapshot.

Parameters

  texture | The `GdkTexture` to render.
  bounds | The bounds for the new node.

## ◆ create()

static Glib::RefPtr<Snapshot> Gtk::Snapshot::create | ( |  | ) |
| static

Creates a new `GtkSnapshot`.

Returns
  A newly-allocated `GtkSnapshot`.

## ◆ get_type()

static GType Gtk::Snapshot::get_type | ( |  | ) |
| static

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

## ◆ gl_shader_pop_texture()

void Gtk::Snapshot::gl_shader_pop_texture | ( |  | ) |

Removes the top element from the stack of render nodes and adds it to the nearest `GskGLShaderNode` below it.

This must be called the same number of times as the number of textures is needed for the shader in [method Gtk.Snapshot.push_gl_shader].

## ◆ gobj() [1/2]

GtkSnapshot* Gtk::Snapshot::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const GtkSnapshot* Gtk::Snapshot::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

GtkSnapshot* Gtk::Snapshot::gobj_copy | ( |  | ) |

Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.

## ◆ operator=()

Snapshot& Gtk::Snapshot::operator= | ( | Snapshot&& | src | ) |
| noexcept

## ◆ perspective()

void Gtk::Snapshot::perspective | ( | float | depth | ) |

Applies a perspective projection transform.

See [method Gsk.Transform.perspective] for a discussion on the details.

Parameters

  depth | Distance of the z=0 plane.

## ◆ pop()

void Gtk::Snapshot::pop | ( |  | ) |

Removes the top element from the stack of render nodes, and appends it to the node underneath it.

## ◆ push_blur()

void Gtk::Snapshot::push_blur | ( | double | radius | ) |

Blurs an image.

The image is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  radius | The blur radius to use.

## ◆ push_clip() [1/2]

void Gtk::Snapshot::push_clip | ( | const Gdk::Rectangle& | bounds | ) |

Clips an image to a rectangle.

The image is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  bounds | The rectangle to clip to.

## ◆ push_clip() [2/2]

void Gtk::Snapshot::push_clip | ( | const graphene_rect_t * | bounds | ) |

Clips an image to a rectangle.

The image is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  bounds | The rectangle to clip to.

## ◆ push_cross_fade()

void Gtk::Snapshot::push_cross_fade | ( | double | progress | ) |

Snapshots a cross-fade operation between two images with the given progress.

Until the first call to [method Gtk.Snapshot.pop], the start image will be snapshot. After that call, the end image will be recorded until the second call to [method Gtk.Snapshot.pop].

Calling this function requires two subsequent calls to [method Gtk.Snapshot.pop].

Parameters

  progress | Progress between 0.0 and 1.0.

## ◆ push_debug()

void Gtk::Snapshot::push_debug | ( | const Glib::ustring & | name | ) |

Creates a new debug node.

Since gtkmm 3.94:

Parameters

  name | The name for the new node, or an empty string for no name.

## ◆ push_opacity()

void Gtk::Snapshot::push_opacity | ( | double | opacity | ) |

Modifies the opacity of an image.

The image is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  opacity | The opacity to use.

## ◆ push_repeat() [1/3]

void Gtk::Snapshot::push_repeat | ( | const Gdk::Rectangle& | bounds | ) |

A push_repeat() convenience overload.

## ◆ push_repeat() [2/3]

void Gtk::Snapshot::push_repeat | ( | const Gdk::Rectangle& | bounds,
|  | const Gdk::Rectangle& | child_bounds
| ) |  |

Creates a node that repeats the child node.

The child is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  bounds | The bounds within which to repeat.
  child_bounds | The bounds of the child or `nullptr` to use the full size of the collected child node.

## ◆ push_repeat() [3/3]

void Gtk::Snapshot::push_repeat | ( | const graphene_rect_t * | bounds,
|  | const graphene_rect_t * | child_bounds
| ) |  |

Creates a node that repeats the child node.

The child is recorded until the next call to [method Gtk.Snapshot.pop].

Parameters

  bounds | The bounds within which to repeat.
  child_bounds | The bounds of the child or `nullptr` to use the full size of the collected child node.

## ◆ render_backgrount()

void Gtk::Snapshot::render_backgrount | ( | const Glib::RefPtr< StyleContext >& | context,
|  | double | x,
|  | double | y,
|  | double | width,
|  | double | height
| ) |  |

Creates a render node for the CSS background according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters

  context | The `GtkStyleContext` to use.
  x | X origin of the rectangle.
  y | Y origin of the rectangle.
  width | Rectangle width.
  height | Rectangle height.

## ◆ render_focus()

void Gtk::Snapshot::render_focus | ( | const Glib::RefPtr< StyleContext >& | context,
|  | double | x,
|  | double | y,
|  | double | width,
|  | double | height
| ) |  |

Creates a render node for the focus outline according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters

  context | The `GtkStyleContext` to use.
  x | X origin of the rectangle.
  y | Y origin of the rectangle.
  width | Rectangle width.
  height | Rectangle height.

## ◆ render_frame()

void Gtk::Snapshot::render_frame | ( | const Glib::RefPtr< StyleContext >& | context,
|  | double | x,
|  | double | y,
|  | double | width,
|  | double | height
| ) |  |

Creates a render node for the CSS border according to context, and appends it to the current node of snapshot, without changing the current node.

Parameters

  context | The `GtkStyleContext` to use.
  x | X origin of the rectangle.
  y | Y origin of the rectangle.
  width | Rectangle width.
  height | Rectangle height.

## ◆ render_insertion_cursor()

void Gtk::Snapshot::render_insertion_cursor | ( | const Glib::RefPtr< StyleContext >& | context,
|  | double | x,
|  | double | y,
|  | const Glib::RefPtr< Pango::Layout > & | layout,
|  | int | index,
|  | Pango::Direction | direction
| ) |  |

Draws a text caret using snapshot at the specified index of layout.

Parameters

  context | A `GtkStyleContext`.
  x | X origin.
  y | Y origin.
  layout | The `PangoLayout` of the text.
  index | The index in the Pango::Layout.
  direction | The Pango::Direction of the text.

## ◆ render_layout()

void Gtk::Snapshot::render_layout | ( | const Glib::RefPtr< StyleContext >& | context,
|  | double | x,
|  | double | y,
|  | const Glib::RefPtr< Pango::Layout > & | layout
| ) |  |

Creates a render node for rendering layout according to the style information in context, and appends it to the current node of snapshot, without changing the current node.

Parameters

  context | The `GtkStyleContext` to use.
  x | X origin of the rectangle.
  y | Y origin of the rectangle.
  layout | The Pango::Layout to render.

## ◆ restore()

void Gtk::Snapshot::restore | ( |  | ) |

Restores snapshot to the state saved by a preceding call to save() and removes that state from the stack of saved states.

## ◆ rotate()

void Gtk::Snapshot::rotate | ( | float | angle | ) |

Rotates @ snapshot's coordinate system by angle degrees in 2D space - or in 3D speak, rotates around the Z axis.

To rotate around other axes, use [method Gsk.Transform.rotate_3d].

Parameters

  angle | The rotation angle, in degrees (clockwise).

## ◆ save()

void Gtk::Snapshot::save | ( |  | ) |

Makes a copy of the current state of snapshot and saves it on an internal stack.

When [method Gtk.Snapshot.restore] is called, snapshot will be restored to the saved state. Multiple calls to save() and restore() can be nested; each call to restore() restores the state from the matching paired save().

It is necessary to clear all saved states with corresponding calls to restore().

## ◆ scale() [1/2]

void Gtk::Snapshot::scale | ( | float | factor_x,
|  | float | factor_y
| ) |  |

Scales snapshot's coordinate system in 2-dimensional space by the given factors.

Use [method Gtk.Snapshot.scale_3d] to scale in all 3 dimensions.

Parameters

  factor_x | Scaling factor on the X axis.
  factor_y | Scaling factor on the Y axis.

## ◆ scale() [2/2]

void Gtk::Snapshot::scale | ( | float | factor_x,
|  | float | factor_y,
|  | float | factor_z
| ) |  |

Scales snapshot's coordinate system by the given factors.

Parameters

  factor_x | Scaling factor on the X axis.
  factor_y | Scaling factor on the Y axis.
  factor_z | Scaling factor on the Z axis.

## Friends And Related Function Documentation

## ◆ wrap_gtk_snapshot()

Glib::RefPtr< Gtk::Snapshot > wrap_gtk_snapshot | ( | GtkSnapshot * | object,
|  | bool | take_copy = `false`
| ) |  |
| related

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

It's not called wrap() because GtkSnapshot is a typedef of GdkSnapshot.

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.