Gtk.Snapshot¶

class — extends Gdk.Snapshot

Assists in creating Gsk.RenderNodes 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 Snapshot.pop to change the current node.

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

Note that GtkSnapshot applies some optimizations, so the node it produces may not match the API calls 1:1. For example, it will omit clip nodes if the child node is entirely contained within the clip rectangle.

Constructors¶

new¶

@classmethod
def new(cls) -> Snapshot

Creates a new GtkSnapshot.

Methods¶

append_border¶

def append_border(self, outline: Gsk.RoundedRect, border_width: list[float], border_color: list[Gdk.RGBA]) -> None

Appends a stroked border rectangle inside the given outline.

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

Parameters:

outline — the outline of the border
border_width — the stroke width of the border on the top, right, bottom and left side respectively.
border_color — the color used on the top, right, bottom and left side.

append_cairo¶

def append_cairo(self, bounds: Graphene.Rect) -> cairo.Context[cairo.Surface]

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

Parameters:

bounds — the bounds for the new node

append_color¶

def append_color(self, color: Gdk.RGBA, bounds: Graphene.Rect) -> None

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 color to draw
bounds — the bounds for the new node

append_conic_gradient¶

def append_conic_gradient(self, bounds: Graphene.Rect, center: Graphene.Point, rotation: float, stops: list[Gsk.ColorStop]) -> None

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

Parameters:

bounds — the rectangle to render the gradient into
center — the center point of the conic gradient
rotation — the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top.
stops — the color stops defining the gradient

append_fill¶

def append_fill(self, path: Gsk.Path, fill_rule: Gsk.FillRule | int, color: Gdk.RGBA) -> None

A convenience method to fill a path with a color.

See Snapshot.push_fill if you need to fill a path with more complex content than a color.

Parameters:

path — The path describing the area to fill
fill_rule — The fill rule to use
color — the color to fill the path with

append_inset_shadow¶

def append_inset_shadow(self, outline: Gsk.RoundedRect, color: Gdk.RGBA, dx: float, dy: float, spread: float, blur_radius: float) -> None

Appends an inset shadow into the box given by outline.

Parameters:

outline — outline of the region surrounded by shadow
color — color of the shadow
dx — horizontal offset of shadow
dy — vertical offset of shadow
spread — how far the shadow spreads towards the inside
blur_radius — how much blur to apply to the shadow

append_layout¶

def append_layout(self, layout: Pango.Layout, color: Gdk.RGBA) -> None

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. The current theme's foreground color for a widget can be obtained with Widget.get_color.

Note that if the layout does not produce any visible output, then nodes may not be added to the snapshot.

Parameters:

layout — the PangoLayout to render
color — the foreground color to render the layout in

append_linear_gradient¶

def append_linear_gradient(self, bounds: Graphene.Rect, start_point: Graphene.Point, end_point: Graphene.Point, stops: list[Gsk.ColorStop]) -> None

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

Parameters:

bounds — the rectangle to render the linear gradient into
start_point — the point at which the linear gradient will begin
end_point — the point at which the linear gradient will finish
stops — the color stops defining the gradient

append_node¶

def append_node(self, node: Gsk.RenderNode) -> None

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

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

Parameters:

node — a GskRenderNode

append_outset_shadow¶

def append_outset_shadow(self, outline: Gsk.RoundedRect, color: Gdk.RGBA, dx: float, dy: float, spread: float, blur_radius: float) -> None

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

Parameters:

outline — outline of the region surrounded by shadow
color — color of the shadow
dx — horizontal offset of shadow
dy — vertical offset of shadow
spread — how far the shadow spreads towards the outside
blur_radius — how much blur to apply to the shadow

append_paste¶

def append_paste(self, bounds: Graphene.Rect, nth: int) -> None

Creates a new render node that pastes the contents copied by a previous call to Snapshot.push_copy

Parameters:

bounds — the bounds for the new node
nth — the index of the copy, with 0 being the latest copy, 1 being the copy before that, and so on.

append_radial_gradient¶

def append_radial_gradient(self, bounds: Graphene.Rect, center: Graphene.Point, hradius: float, vradius: float, start: float, end: float, stops: list[Gsk.ColorStop]) -> None

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

Parameters:

bounds — the rectangle to render the readial gradient into
center — the center point for the radial gradient
hradius — the horizontal radius
vradius — the vertical radius
start — the start position (on the horizontal axis)
end — the end position (on the horizontal axis)
stops — the color stops defining the gradient

append_repeating_linear_gradient¶

def append_repeating_linear_gradient(self, bounds: Graphene.Rect, start_point: Graphene.Point, end_point: Graphene.Point, stops: list[Gsk.ColorStop]) -> None

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

Parameters:

bounds — the rectangle to render the linear gradient into
start_point — the point at which the linear gradient will begin
end_point — the point at which the linear gradient will finish
stops — the color stops defining the gradient

append_repeating_radial_gradient¶

def append_repeating_radial_gradient(self, bounds: Graphene.Rect, center: Graphene.Point, hradius: float, vradius: float, start: float, end: float, stops: list[Gsk.ColorStop]) -> None

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

Parameters:

bounds — the rectangle to render the readial gradient into
center — the center point for the radial gradient
hradius — the horizontal radius
vradius — the vertical radius
start — the start position (on the horizontal axis)
end — the end position (on the horizontal axis)
stops — the color stops defining the gradient

append_scaled_texture¶

def append_scaled_texture(self, texture: Gdk.Texture, filter: Gsk.ScalingFilter | int, bounds: Graphene.Rect) -> None

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

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

Parameters:

texture — the texture to render
filter — the filter to use
bounds — the bounds for the new node

append_stroke¶

def append_stroke(self, path: Gsk.Path, stroke: Gsk.Stroke, color: Gdk.RGBA) -> None

A convenience method to stroke a path with a color.

See Snapshot.push_stroke if you need to stroke a path with more complex content than a color.

Parameters:

path — The path describing the area to fill
stroke — The stroke attributes
color — the color to fill the path with

append_texture¶

def append_texture(self, texture: Gdk.Texture, bounds: Graphene.Rect) -> None

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

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

Parameters:

texture — the texture to render
bounds — the bounds for the new node

gl_shader_pop_texture¶

def gl_shader_pop_texture(self) -> None

:::warning Deprecated since 4.16 This API is deprecated. :::

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

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

perspective¶

def perspective(self, depth: float) -> None

Applies a perspective projection transform.

See Gsk.Transform.perspective for a discussion on the details.

Parameters:

depth — distance of the z=0 plane

pop¶

def pop(self) -> None

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

push_blend¶

def push_blend(self, blend_mode: Gsk.BlendMode | int) -> None

Blends together two images with the given blend mode.

Until the first call to 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 Snapshot.pop.

Calling this function requires two subsequent calls to Snapshot.pop.

Parameters:

blend_mode — blend mode to use

push_blur¶

def push_blur(self, radius: float) -> None

Blurs an image.

The image is recorded until the next call to Snapshot.pop.

Parameters:

radius — the blur radius to use. Must be positive

push_clip¶

def push_clip(self, bounds: Graphene.Rect) -> None

Clips an image to a rectangle.

The image is recorded until the next call to Snapshot.pop.

Parameters:

bounds — the rectangle to clip to

push_color_matrix¶

def push_color_matrix(self, color_matrix: Graphene.Matrix, color_offset: Graphene.Vec4) -> None

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

Parameters:

color_matrix — the color matrix to use
color_offset — the color offset to use

push_component_transfer¶

def push_component_transfer(self, red: Gsk.ComponentTransfer, green: Gsk.ComponentTransfer, blue: Gsk.ComponentTransfer, alpha: Gsk.ComponentTransfer) -> None

Modifies the colors of an image by applying a transfer function for each component.

The transfer functions operate on unpremultiplied colors.

The image is recorded until the next call to Snapshot.pop.

Parameters:

red — the transfer for the red component
green — the transfer for the green component
blue — the transfer for the blue component
alpha — the transfer for the alpha component

push_composite¶

def push_composite(self, op: Gsk.PorterDuff | int) -> None

Until the first call to Snapshot.pop, the mask image for the mask operation will be recorded.

After that call, the child image will be recorded until the second call to Snapshot.pop.

Calling this function requires 2 subsequent calls to Snapshot.pop.

Parameters:

op — The Porter/Duff compositing operator to use

push_copy¶

def push_copy(self) -> None

Stores the current rendering state for later pasting via Snapshot.append_paste.

Pasting is possible until the matching call to Snapshot.pop.

push_cross_fade¶

def push_cross_fade(self, progress: float) -> None

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

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

Calling this function requires two subsequent calls to Snapshot.pop.

Parameters:

progress — progress between 0.0 and 1.0

push_fill¶

def push_fill(self, path: Gsk.Path, fill_rule: Gsk.FillRule | int) -> None

Fills the area given by path and fill_rule with an image and discards everything outside of it.

The image is recorded until the next call to Snapshot.pop.

If you want to fill the path with a color, Snapshot.append_fill than rendering new ones, use Snapshot.append_fill may be more convenient.

Parameters:

path — The path describing the area to fill
fill_rule — The fill rule to use

push_gl_shader¶

def push_gl_shader(self, shader: Gsk.GLShader, bounds: Graphene.Rect, take_args: bytes) -> None

:::warning Deprecated since 4.16 This API is deprecated. :::

Push a Gsk.GLShaderNode.

The node uses the given Gsk.GLShader and uniform values Additionally this takes a list of n_children other nodes which will be passed to the 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 Gsk.GLShader.format_args or 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 Gsk.GLShader.compile to ensure the shader will work for the renderer before using it.

If the shader requires textures (see Gsk.GLShader.get_n_textures), then it is expected that you call 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 Snapshot.pop.

If you want to use pre-existing textures as input to the shader rather than rendering new ones, use 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 Gsk.GLShader.

Parameters:

shader — The code to run
bounds — the rectangle to render into
take_args — Data block with arguments for the shader.

push_isolation¶

def push_isolation(self, features: Gsk.Isolation | int) -> None

Isolates the following drawing operations from previous ones.

You can express "everything but these flags" in a forward compatible way by using bit math: GSK_ISOLATION_ALL & ~(GSK_ISOLATION_BACKGROUND | GSK_ISOLATION_COPY_PASTE) will isolate everything but background and copy/paste.

For what isolation features exist, see Gsk.Isolation.

Content is isolated until the next call to Snapshot.pop.

Parameters:

features — features that are isolated

push_mask¶

def push_mask(self, mask_mode: Gsk.MaskMode | int) -> None

Until the first call to 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 Snapshot.pop.

Calling this function requires 2 subsequent calls to Snapshot.pop.

Parameters:

mask_mode — mask mode to use

push_opacity¶

def push_opacity(self, opacity: float) -> None

Modifies the opacity of an image.

The image is recorded until the next call to Snapshot.pop.

Parameters:

opacity — the opacity to use

push_repeat¶

def push_repeat(self, bounds: Graphene.Rect, child_bounds: Graphene.Rect | None = ...) -> None

Creates a node that repeats the child node.

The child is recorded until the next call to Snapshot.pop.

Parameters:

bounds — the bounds within which to repeat
child_bounds — the bounds of the child or None to use the full size of the collected child node

push_rounded_clip¶

def push_rounded_clip(self, bounds: Gsk.RoundedRect) -> None

Clips an image to a rounded rectangle.

The image is recorded until the next call to Snapshot.pop.

Parameters:

bounds — the rounded rectangle to clip to

push_shadow¶

def push_shadow(self, shadow: list[Gsk.Shadow]) -> None

Applies a shadow to an image.

The image is recorded until the next call to Snapshot.pop.

Parameters:

shadow — the first shadow specification

push_stroke¶

def push_stroke(self, path: Gsk.Path, stroke: Gsk.Stroke) -> None

Strokes the given path with the attributes given by stroke and an image.

The image is recorded until the next call to Snapshot.pop.

Note that the strokes are subject to the same transformation as everything else, so uneven scaling will cause horizontal and vertical strokes to have different widths.

If you want to stroke the path with a color, Snapshot.append_stroke may be more convenient.

Parameters:

path — The path to stroke
stroke — The stroke attributes

render_background¶

def render_background(self, context: StyleContext, x: float, y: float, width: float, height: float) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 style context that defines the background
x — X origin of the rectangle
y — Y origin of the rectangle
width — rectangle width
height — rectangle height

render_focus¶

def render_focus(self, context: StyleContext, x: float, y: float, width: float, height: float) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 style context that defines the focus ring
x — X origin of the rectangle
y — Y origin of the rectangle
width — rectangle width
height — rectangle height

render_frame¶

def render_frame(self, context: StyleContext, x: float, y: float, width: float, height: float) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 style context that defines the frame
x — X origin of the rectangle
y — Y origin of the rectangle
width — rectangle width
height — rectangle height

render_insertion_cursor¶

def render_insertion_cursor(self, context: StyleContext, x: float, y: float, layout: Pango.Layout, index: int, direction: Pango.Direction | int) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 PangoLayout
direction — the PangoDirection of the text

render_layout¶

def render_layout(self, context: StyleContext, x: float, y: float, layout: Pango.Layout) -> None

:::warning Deprecated since 4.10 This API is deprecated. :::

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 style context that defines the text
x — X origin of the rectangle
y — Y origin of the rectangle
layout — the PangoLayout to render

restore¶

def restore(self) -> None

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

rotate¶

def rotate(self, angle: float) -> None

Rotates @snapshot'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 snapshot's current coordinate system.

To rotate around axes other than the Z axis, use Gsk.Transform.rotate_3d.

Parameters:

angle — the rotation angle, in degrees (clockwise)

rotate_3d¶

def rotate_3d(self, angle: float, axis: Graphene.Vec3) -> None

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

For a rotation in 2D space, use Gsk.Transform.rotate.

Parameters:

angle — the rotation angle, in degrees (clockwise)
axis — The rotation axis

save¶

def save(self) -> None

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

When Snapshot.restore is called, snapshot will be restored to the saved state.

Multiple calls to Snapshot.save and 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¶

def scale(self, factor_x: float, factor_y: float) -> None

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

Use 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_3d¶

def scale_3d(self, factor_x: float, factor_y: float, factor_z: float) -> None

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

to_node¶

def to_node(self) -> Gsk.RenderNode | None

Returns the render node that was constructed by snapshot.

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 snapshot. The only function that should be called after this is GObject.Object.unref.

to_paintable¶

def to_paintable(self, size: Graphene.Size | None = ...) -> Gdk.Paintable | None

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

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

Parameters:

size — The size of the resulting paintable or None to use the bounds of the snapshot

transform¶

def transform(self, transform: Gsk.Transform | None = ...) -> None

Transforms snapshot's coordinate system with the given transform.

Parameters:

transform — the transform to apply

transform_matrix¶

def transform_matrix(self, matrix: Graphene.Matrix) -> None

Transforms snapshot's coordinate system with the given matrix.

Parameters:

matrix — the matrix to multiply the transform with

translate¶

def translate(self, point: Graphene.Point) -> None

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

Parameters:

point — the point to translate the snapshot by

translate_3d¶

def translate_3d(self, point: Graphene.Point3D) -> None

Translates snapshot's coordinate system by point.

Parameters:

point — the point to translate the snapshot by