Gtk.Snapshot¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`append_border` (outline, border_width, border_color)
	`append_cairo` (bounds)
	`append_color` (color, bounds)
	`append_conic_gradient` (bounds, center, rotation, stops)
	`append_inset_shadow` (outline, color, dx, dy, spread, blur_radius)
	`append_layout` (layout, color)
	`append_linear_gradient` (bounds, start_point, end_point, stops)
	`append_node` (node)
	`append_outset_shadow` (outline, color, dx, dy, spread, blur_radius)
	`append_radial_gradient` (bounds, center, hradius, vradius, start, end, stops)
	`append_repeating_linear_gradient` (bounds, start_point, end_point, stops)
	`append_repeating_radial_gradient` (bounds, center, hradius, vradius, start, end, stops)
	`append_scaled_texture` (texture, filter, bounds)
	`append_texture` (texture, bounds)
	`gl_shader_pop_texture` ()
	`perspective` (depth)
	`pop` ()
	`push_blend` (blend_mode)
	`push_blur` (radius)
	`push_clip` (bounds)
	`push_color_matrix` (color_matrix, color_offset)
	`push_cross_fade` (progress)
	`push_gl_shader` (shader, bounds, take_args)
	`push_mask` (mask_mode)
	`push_opacity` (opacity)
	`push_repeat` (bounds, child_bounds)
	`push_rounded_clip` (bounds)
	`push_shadow` (shadow)
	`render_background` (context, x, y, width, height)
	`render_focus` (context, x, y, width, height)
	`render_frame` (context, x, y, width, height)
	`render_insertion_cursor` (context, x, y, layout, index, direction)
	`render_layout` (context, x, y, layout)
	`restore` ()
	`rotate` (angle)
	`rotate_3d` (angle, axis)
	`save` ()
	`scale` (factor_x, factor_y)
	`scale_3d` (factor_x, factor_y, factor_z)
	`to_node` ()
	`to_paintable` (size)
	`transform` (transform)
	`transform_matrix` (matrix)
	`translate` (point)
	`translate_3d` (point)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Gtk.Snapshot(**kwargs)¶

Bases:: Gdk.Snapshot
Abstract:: No
Structure:: Gtk.SnapshotClass

GtkSnapshot assists in creating [class`Gsk`.RenderNode]s for widgets.

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 one that gtk_snapshot_append_…() functions operate on. Use the gtk_snapshot_push_…() functions and [method`Snapshot`.pop] to change the current node.

The typical way to obtain a GtkSnapshot object is as an argument to the [vfunc`Gtk`.Widget.snapshot] vfunc. If you need to create your own GtkSnapshot, use [ctor`Gtk`.Snapshot.new].

classmethod new()[source]¶

Returns:: a newly-allocated GtkSnapshot
Return type:: Gtk.Snapshot

Creates a new GtkSnapshot.

append_border(outline, border_width, border_color)[source]¶

Parameters:

outline (Gsk.RoundedRect) – the outline of the border
border_width ([float]) – the stroke width of the border on the top, right, bottom and left side respectively.
border_color ([Gdk.RGBA]) – the color used on the top, right, bottom and left side.

Appends a stroked border rectangle inside the given outline.

The four sides of the border can have different widths and colors.

append_cairo(bounds)[source]¶

Parameters:: bounds (Graphene.Rect) – the bounds for the new node
Returns:: a cairo_t suitable for drawing the contents of the newly created render node
Return type:: cairo.Context

Creates a new [class`Gsk`.CairoNode] and appends it to the current render node of self, without changing the current node.

append_color(color, bounds)[source]¶

Parameters:

color (Gdk.RGBA) – the color to draw
bounds (Graphene.Rect) – the bounds for the new node

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

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

append_conic_gradient(bounds, center, rotation, stops)[source]¶

Parameters:

bounds (Graphene.Rect) – the rectangle to render the gradient into
center (Graphene.Point) – the center point of the conic gradient
rotation (float) – the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top.
stops ([Gsk.ColorStop]) – the color stops defining the gradient

Appends a conic gradient node with the given stops to self.

append_inset_shadow(outline, color, dx, dy, spread, blur_radius)[source]¶

Parameters:

outline (Gsk.RoundedRect) – outline of the region surrounded by shadow
color (Gdk.RGBA) – color of the shadow
dx (float) – horizontal offset of shadow
dy (float) – vertical offset of shadow
spread (float) – how far the shadow spreads towards the inside
blur_radius (float) – how much blur to apply to the shadow

Appends an inset shadow into the box given by outline.

append_layout(layout, color)[source]¶

Parameters:

layout (Pango.Layout) –
color (Gdk.RGBA) –

append_linear_gradient(bounds, start_point, end_point, stops)[source]¶

Parameters:

bounds (Graphene.Rect) – the rectangle to render the linear gradient into
start_point (Graphene.Point) – the point at which the linear gradient will begin
end_point (Graphene.Point) – the point at which the linear gradient will finish
stops ([Gsk.ColorStop]) – the color stops defining the gradient

Appends a linear gradient node with the given stops to self.

append_node(node)[source]¶

Parameters:: node (Gsk.RenderNode) – a GskRenderNode

Appends node to the current render node of self, without changing the current node.

If self does not have a current node yet, node will become the initial node.

append_outset_shadow(outline, color, dx, dy, spread, blur_radius)[source]¶

Parameters:

outline (Gsk.RoundedRect) – outline of the region surrounded by shadow
color (Gdk.RGBA) – color of the shadow
dx (float) – horizontal offset of shadow
dy (float) – vertical offset of shadow
spread (float) – how far the shadow spreads towards the outside
blur_radius (float) – how much blur to apply to the shadow

Appends an outset shadow node around the box given by outline.

append_radial_gradient(bounds, center, hradius, vradius, start, end, stops)[source]¶

Parameters:

bounds (Graphene.Rect) – the rectangle to render the readial gradient into
center (Graphene.Point) – the center point for the radial gradient
hradius (float) – the horizontal radius
vradius (float) – the vertical radius
start (float) – the start position (on the horizontal axis)
end (float) – the end position (on the horizontal axis)
stops ([Gsk.ColorStop]) – the color stops defining the gradient

Appends a radial gradient node with the given stops to self.

append_repeating_linear_gradient(bounds, start_point, end_point, stops)[source]¶

Parameters:

bounds (Graphene.Rect) – the rectangle to render the linear gradient into
start_point (Graphene.Point) – the point at which the linear gradient will begin
end_point (Graphene.Point) – the point at which the linear gradient will finish
stops ([Gsk.ColorStop]) – the color stops defining the gradient

Appends a repeating linear gradient node with the given stops to self.

append_repeating_radial_gradient(bounds, center, hradius, vradius, start, end, stops)[source]¶

Parameters:

bounds (Graphene.Rect) – the rectangle to render the readial gradient into
center (Graphene.Point) – the center point for the radial gradient
hradius (float) – the horizontal radius
vradius (float) – the vertical radius
start (float) – the start position (on the horizontal axis)
end (float) – the end position (on the horizontal axis)
stops ([Gsk.ColorStop]) – the color stops defining the gradient

Appends a repeating radial gradient node with the given stops to self.

append_scaled_texture(texture, filter, bounds)[source]¶

Parameters:

texture (Gdk.Texture) – the texture to render
filter (Gsk.ScalingFilter) – the filter to use
bounds (Graphene.Rect) – the bounds for the new node

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

In contrast to [method`Gtk`.Snapshot.append_texture], this function provides control about how the filter that is used when scaling.

New in version 4.10.

append_texture(texture, bounds)[source]¶

Parameters:

texture (Gdk.Texture) – the texture to render
bounds (Graphene.Rect) – the bounds for the new node

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

If the texture needs to be scaled to fill bounds, linear filtering is used. See [method`Gtk`.Snapshot.append_scaled_texture] if you need other filtering, such as nearest-neighbour.

gl_shader_pop_texture()[source]¶

Removes the top element from the stack of render nodes and adds it to the nearest [class`Gsk`.GLShaderNode] 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].

perspective(depth)[source]¶

Parameters:: depth (float) – distance of the z=0 plane

Applies a perspective projection transform.

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

pop()[source]¶: Removes the top element from the stack of render nodes, and appends it to the node underneath it.

push_blend(blend_mode)[source]¶

Parameters:: blend_mode (Gsk.BlendMode) – blend mode to use

Blends together two images with the given blend mode.

Until the first call to [method`Gtk`.Snapshot.pop], the bottom image for the blend operation will be recorded. After that call, the top image to be blended will be recorded until the second call to [method`Gtk`.Snapshot.pop].

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

push_blur(radius)[source]¶

Parameters:: radius (float) – the blur radius to use. Must be positive

Blurs an image.

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

push_clip(bounds)[source]¶

Parameters:: bounds (Graphene.Rect) – the rectangle to clip to

Clips an image to a rectangle.

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

push_color_matrix(color_matrix, color_offset)[source]¶

Parameters:

color_matrix (Graphene.Matrix) – the color matrix to use
color_offset (Graphene.Vec4) – the color offset to use

Modifies the colors of an image by applying an affine transformation in RGB space.

In particular, the colors will be transformed by applying

pixel = transpose(color_matrix) * pixel + color_offset

for every pixel. The transformation operates on unpremultiplied colors, with color components ordered R, G, B, A.

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

push_cross_fade(progress)[source]¶

Parameters:: progress (float) – progress between 0.0 and 1.0

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

push_gl_shader(shader, bounds, take_args)[source]¶

Parameters:

shader (Gsk.GLShader) – The code to run
bounds (Graphene.Rect) – the rectangle to render into
take_args (GLib.Bytes) – Data block with arguments for the shader.

Push a [class`Gsk`.GLShaderNode].

The node uses the given [class`Gsk`.GLShader] and uniform values Additionally this takes a list of n_children other nodes which will be passed to the [class`Gsk`.GLShaderNode].

The take_args argument is a block of data to use for uniform arguments, as per types and offsets defined by the shader. Normally this is generated by [method`Gsk`.GLShader.format_args] or [struct`Gsk`.ShaderArgsBuilder].

The snapshotter takes ownership of take_args, so the caller should not free it after this.

If the renderer doesn’t support GL shaders, or if there is any problem when compiling the shader, then the node will draw pink. You should use [method`Gsk`.GLShader.compile] to ensure the shader will work for the renderer before using it.

If the shader requires textures (see [method`Gsk`.GLShader.get_n_textures]), then it is expected that you call [method`Gtk`.Snapshot.gl_shader_pop_texture] the number of times that are required. Each of these calls will generate a node that is added as a child to the GskGLShaderNode, which in turn will render these offscreen and pass as a texture to the shader.

Once all textures (if any) are pop:ed, you must call the regular [method`Gtk`.Snapshot.pop].

If you want to use pre-existing textures as input to the shader rather than rendering new ones, use [method`Gtk`.Snapshot.append_texture] to push a texture node. These will be used directly rather than being re-rendered.

For details on how to write shaders, see [class`Gsk`.GLShader].

push_mask(mask_mode)[source]¶

Parameters:: mask_mode (Gsk.MaskMode) – mask mode to use

Until the first call to [method`Gtk`.Snapshot.pop], the mask image for the mask operation will be recorded.

After that call, the source image will be recorded until the second call to [method`Gtk`.Snapshot.pop].

Calling this function requires 2 subsequent calls to Gtk.Snapshot.pop().

New in version 4.10.

push_opacity(opacity)[source]¶

Parameters:: opacity (float) – the opacity to use

Modifies the opacity of an image.

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

push_repeat(bounds, child_bounds)[source]¶

Parameters:

bounds (Graphene.Rect) – the bounds within which to repeat
child_bounds (Graphene.Rect or None) – the bounds of the child or None to use the full size of the collected child node

Creates a node that repeats the child node.

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

push_rounded_clip(bounds)[source]¶

Parameters:: bounds (Gsk.RoundedRect) – the rounded rectangle to clip to

Clips an image to a rounded rectangle.

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

push_shadow(shadow)[source]¶

Parameters:: shadow ([Gsk.Shadow]) – the first shadow specification

Applies a shadow to an image.

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

render_background(context, x, y, width, height)[source]¶

Parameters:

context (Gtk.StyleContext) – the style context that defines the background
x (float) – X origin of the rectangle
y (float) – Y origin of the rectangle
width (float) – rectangle width
height (float) – rectangle height

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

Deprecated since version 4.10.

render_focus(context, x, y, width, height)[source]¶

Parameters:

context (Gtk.StyleContext) – the style context that defines the focus ring
x (float) – X origin of the rectangle
y (float) – Y origin of the rectangle
width (float) – rectangle width
height (float) – rectangle height

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

Deprecated since version 4.10.

render_frame(context, x, y, width, height)[source]¶

Parameters:

context (Gtk.StyleContext) – the style context that defines the frame
x (float) – X origin of the rectangle
y (float) – Y origin of the rectangle
width (float) – rectangle width
height (float) – rectangle height

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

Deprecated since version 4.10.

render_insertion_cursor(context, x, y, layout, index, direction)[source]¶

Parameters:

context (Gtk.StyleContext) – a GtkStyleContext
x (float) – X origin
y (float) – Y origin
layout (Pango.Layout) – the PangoLayout of the text
index (int) – the index in the PangoLayout
direction (Pango.Direction) – the PangoDirection of the text

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

Deprecated since version 4.10.

render_layout(context, x, y, layout)[source]¶

Parameters:

context (Gtk.StyleContext) – the style context that defines the text
x (float) – X origin of the rectangle
y (float) – Y origin of the rectangle
layout (Pango.Layout) – the PangoLayout to render

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

Deprecated since version 4.10.

restore()[source]¶: Restores self to the state saved by a preceding call to [method`Snapshot`.save] and removes that state from the stack of saved states.

rotate(angle)[source]¶

Parameters:: angle (float) – the rotation angle, in degrees (clockwise)

Rotates @`self`'s coordinate system by angle degrees in 2D space - or in 3D speak, rotates around the Z axis. The rotation happens around the origin point of (0, 0) in the self's current coordinate system.

To rotate around axes other than the Z axis, use [method`Gsk`.Transform.rotate_3d].

rotate_3d(angle, axis)[source]¶

Parameters:

angle (float) – the rotation angle, in degrees (clockwise)
axis (Graphene.Vec3) – The rotation axis

Rotates self's coordinate system by angle degrees around axis.

For a rotation in 2D space, use [method`Gsk`.Transform.rotate].

save()[source]¶

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

When [method`Gtk`.Snapshot.restore] is called, self will be restored to the saved state.

Multiple calls to [method`Gtk`.Snapshot.save] and [method`Gtk`.Snapshot.restore] can be nested; each call to gtk_snapshot_restore() restores the state from the matching paired gtk_snapshot_save().

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

scale(factor_x, factor_y)[source]¶

Parameters:

factor_x (float) – scaling factor on the X axis
factor_y (float) – scaling factor on the Y axis

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

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

scale_3d(factor_x, factor_y, factor_z)[source]¶

Parameters:

factor_x (float) – scaling factor on the X axis
factor_y (float) – scaling factor on the Y axis
factor_z (float) – scaling factor on the Z axis

Scales self's coordinate system by the given factors.

to_node()[source]¶

Returns:: the constructed GskRenderNode or None if there are no nodes to render.
Return type:: Gsk.RenderNode or None

Returns the render node that was constructed by self.

Note that this function may return None if nothing has been added to the snapshot or if its content does not produce pixels to be rendered.

After calling this function, it is no longer possible to add more nodes to self. The only function that should be called after this is [method`GObject`.Object.unref].

to_paintable(size)[source]¶

Parameters:: size (Graphene.Size or None) – The size of the resulting paintable or None to use the bounds of the snapshot
Returns:: a new GdkPaintable
Return type:: Gdk.Paintable or None

Returns a paintable encapsulating the render node that was constructed by self.

After calling this function, it is no longer possible to add more nodes to self. The only function that should be called after this is [method`GObject`.Object.unref].

transform(transform)[source]¶

Parameters:: transform (Gsk.Transform or None) – the transform to apply

Transforms self's coordinate system with the given transform.

transform_matrix(matrix)[source]¶

Parameters:: matrix (Graphene.Matrix) – the matrix to multiply the transform with

Transforms self's coordinate system with the given matrix.

translate(point)[source]¶

Parameters:: point (Graphene.Point) – the point to translate the snapshot by

Translates self's coordinate system by point in 2-dimensional space.

translate_3d(point)[source]¶

Parameters:: point (Graphene.Point3D) – the point to translate the snapshot by

Translates self's coordinate system by point.