:right-sidebar: True Snapshot =================================================================== .. currentmodule:: gi.repository.Gtk .. class:: Snapshot(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.Gdk.Snapshot`, :class:`~gi.repository.GObject.Object` ``GtkSnapshot`` assists in creating :obj:`~gi.repository.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 :obj:`~gi.repository.Snapshot.pop` to change the current node. The typical way to obtain a ``GtkSnapshot`` object is as an argument to the :obj:`~gi.repository.Gtk.Widget.snapshot` vfunc. If you need to create your own ``GtkSnapshot``, use :obj:`~gi.repository.Gtk.Snapshot.new`. Constructors ------------ .. rst-class:: interim-class .. class:: Snapshot :no-index: .. classmethod:: new() -> ~gi.repository.Gtk.Snapshot Creates a new ``GtkSnapshot``. Methods ------- .. rst-class:: interim-class .. class:: Snapshot :no-index: .. method:: append_border(outline: ~gi.repository.Gsk.RoundedRect, border_width: ~typing.Sequence[float], border_color: ~typing.Sequence[~gi.repository.Gdk.RGBA]) -> None Appends a stroked border rectangle inside the given ``outline``. The four sides of the border can have different widths and colors. :param outline: the outline of the border :param border_width: the stroke width of the border on the top, right, bottom and left side respectively. :param border_color: the color used on the top, right, bottom and left side. .. method:: append_cairo(bounds: ~gi.repository.Graphene.Rect) -> ~gi.repository.cairo.Context Creates a new :obj:`~gi.repository.Gsk.CairoNode` and appends it to the current render node of ``snapshot``, without changing the current node. :param bounds: the bounds for the new node .. method:: append_color(color: ~gi.repository.Gdk.RGBA, bounds: ~gi.repository.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. :param color: the color to draw :param bounds: the bounds for the new node .. method:: append_conic_gradient(bounds: ~gi.repository.Graphene.Rect, center: ~gi.repository.Graphene.Point, rotation: float, stops: ~typing.Sequence[~gi.repository.Gsk.ColorStop]) -> None Appends a conic gradient node with the given stops to ``snapshot``. :param bounds: the rectangle to render the gradient into :param center: the center point of the conic gradient :param rotation: the clockwise rotation in degrees of the starting angle. 0 means the starting angle is the top. :param stops: the color stops defining the gradient .. method:: append_fill(path: ~gi.repository.Gsk.Path, fill_rule: ~gi.repository.Gsk.FillRule, color: ~gi.repository.Gdk.RGBA) -> None A convenience method to fill a path with a color. See :obj:`~gi.repository.Gtk.Snapshot.push_fill` if you need to fill a path with more complex content than a color. .. versionadded:: 4.14 :param path: The path describing the area to fill :param fill_rule: The fill rule to use :param color: the color to fill the path with .. method:: append_inset_shadow(outline: ~gi.repository.Gsk.RoundedRect, color: ~gi.repository.Gdk.RGBA, dx: float, dy: float, spread: float, blur_radius: float) -> None Appends an inset shadow into the box given by ``outline``. :param outline: outline of the region surrounded by shadow :param color: color of the shadow :param dx: horizontal offset of shadow :param dy: vertical offset of shadow :param spread: how far the shadow spreads towards the inside :param blur_radius: how much blur to apply to the shadow .. method:: append_layout(layout: ~gi.repository.Pango.Layout, color: ~gi.repository.Gdk.RGBA) -> None :param layout: :param color: .. method:: append_linear_gradient(bounds: ~gi.repository.Graphene.Rect, start_point: ~gi.repository.Graphene.Point, end_point: ~gi.repository.Graphene.Point, stops: ~typing.Sequence[~gi.repository.Gsk.ColorStop]) -> None Appends a linear gradient node with the given stops to ``snapshot``. :param bounds: the rectangle to render the linear gradient into :param start_point: the point at which the linear gradient will begin :param end_point: the point at which the linear gradient will finish :param stops: the color stops defining the gradient .. method:: append_node(node: ~gi.repository.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. :param node: a ``GskRenderNode`` .. method:: append_outset_shadow(outline: ~gi.repository.Gsk.RoundedRect, color: ~gi.repository.Gdk.RGBA, dx: float, dy: float, spread: float, blur_radius: float) -> None Appends an outset shadow node around the box given by ``outline``. :param outline: outline of the region surrounded by shadow :param color: color of the shadow :param dx: horizontal offset of shadow :param dy: vertical offset of shadow :param spread: how far the shadow spreads towards the outside :param blur_radius: how much blur to apply to the shadow .. method:: append_radial_gradient(bounds: ~gi.repository.Graphene.Rect, center: ~gi.repository.Graphene.Point, hradius: float, vradius: float, start: float, end: float, stops: ~typing.Sequence[~gi.repository.Gsk.ColorStop]) -> None Appends a radial gradient node with the given stops to ``snapshot``. :param bounds: the rectangle to render the readial gradient into :param center: the center point for the radial gradient :param hradius: the horizontal radius :param vradius: the vertical radius :param start: the start position (on the horizontal axis) :param end: the end position (on the horizontal axis) :param stops: the color stops defining the gradient .. method:: append_repeating_linear_gradient(bounds: ~gi.repository.Graphene.Rect, start_point: ~gi.repository.Graphene.Point, end_point: ~gi.repository.Graphene.Point, stops: ~typing.Sequence[~gi.repository.Gsk.ColorStop]) -> None Appends a repeating linear gradient node with the given stops to ``snapshot``. :param bounds: the rectangle to render the linear gradient into :param start_point: the point at which the linear gradient will begin :param end_point: the point at which the linear gradient will finish :param stops: the color stops defining the gradient .. method:: append_repeating_radial_gradient(bounds: ~gi.repository.Graphene.Rect, center: ~gi.repository.Graphene.Point, hradius: float, vradius: float, start: float, end: float, stops: ~typing.Sequence[~gi.repository.Gsk.ColorStop]) -> None Appends a repeating radial gradient node with the given stops to ``snapshot``. :param bounds: the rectangle to render the readial gradient into :param center: the center point for the radial gradient :param hradius: the horizontal radius :param vradius: the vertical radius :param start: the start position (on the horizontal axis) :param end: the end position (on the horizontal axis) :param stops: the color stops defining the gradient .. method:: append_scaled_texture(texture: ~gi.repository.Gdk.Texture, filter: ~gi.repository.Gsk.ScalingFilter, bounds: ~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.append_texture`, this function provides control about how the filter that is used when scaling. .. versionadded:: 4.10 :param texture: the texture to render :param filter: the filter to use :param bounds: the bounds for the new node .. method:: append_stroke(path: ~gi.repository.Gsk.Path, stroke: ~gi.repository.Gsk.Stroke, color: ~gi.repository.Gdk.RGBA) -> None A convenience method to stroke a path with a color. See :obj:`~gi.repository.Gtk.Snapshot.push_stroke` if you need to stroke a path with more complex content than a color. .. versionadded:: 4.14 :param path: The path describing the area to fill :param stroke: The stroke attributes :param color: the color to fill the path with .. method:: append_texture(texture: ~gi.repository.Gdk.Texture, bounds: ~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.append_scaled_texture` if you need other filtering, such as nearest-neighbour. :param texture: the texture to render :param bounds: the bounds for the new node .. method:: gl_shader_pop_texture() -> None Removes the top element from the stack of render nodes and adds it to the nearest :obj:`~gi.repository.Gsk.GLShaderNode` below it. This must be called the same number of times as the number of textures is needed for the shader in :obj:`~gi.repository.Gtk.Snapshot.push_gl_shader`. .. method:: perspective(depth: float) -> None Applies a perspective projection transform. See :obj:`~gi.repository.Gsk.Transform.perspective` for a discussion on the details. :param depth: distance of the z=0 plane .. method:: pop() -> None Removes the top element from the stack of render nodes, and appends it to the node underneath it. .. method:: push_blend(blend_mode: ~gi.repository.Gsk.BlendMode) -> None Blends together two images with the given blend mode. Until the first call to :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.pop`. Calling this function requires two subsequent calls to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param blend_mode: blend mode to use .. method:: push_blur(radius: float) -> None Blurs an image. The image is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param radius: the blur radius to use. Must be positive .. method:: push_clip(bounds: ~gi.repository.Graphene.Rect) -> None Clips an image to a rectangle. The image is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param bounds: the rectangle to clip to .. method:: push_color_matrix(color_matrix: ~gi.repository.Graphene.Matrix, color_offset: ~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.pop`. :param color_matrix: the color matrix to use :param color_offset: the color offset to use .. method:: push_cross_fade(progress: float) -> None Snapshots a cross-fade operation between two images with the given ``progress``. Until the first call to :obj:`~gi.repository.Gtk.Snapshot.pop`, the start image will be snapshot. After that call, the end image will be recorded until the second call to :obj:`~gi.repository.Gtk.Snapshot.pop`. Calling this function requires two subsequent calls to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param progress: progress between 0.0 and 1.0 .. method:: push_fill(path: ~gi.repository.Gsk.Path, fill_rule: ~gi.repository.Gsk.FillRule) -> 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 :obj:`~gi.repository.Gtk.Snapshot.pop`. If you want to fill the path with a color, :obj:`~gi.repository.Gtk.Snapshot.append_fill` may be more convenient. .. versionadded:: 4.14 :param path: The path describing the area to fill :param fill_rule: The fill rule to use .. method:: push_gl_shader(shader: ~gi.repository.Gsk.GLShader, bounds: ~gi.repository.Graphene.Rect, take_args: ~gi.repository.GLib.Bytes) -> None Push a :obj:`~gi.repository.Gsk.GLShaderNode`. The node uses the given :obj:`~gi.repository.Gsk.GLShader` and uniform values Additionally this takes a list of ``n_children`` other nodes which will be passed to the :obj:`~gi.repository.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 :obj:`~gi.repository.Gsk.GLShader.format_args` or :obj:`~gi.repository.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 :obj:`~gi.repository.Gsk.GLShader.compile` to ensure the ``shader`` will work for the renderer before using it. If the shader requires textures (see :obj:`~gi.repository.Gsk.GLShader.get_n_textures`), then it is expected that you call :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.pop`. If you want to use pre-existing textures as input to the shader rather than rendering new ones, use :obj:`~gi.repository.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 :obj:`~gi.repository.Gsk.GLShader`. :param shader: The code to run :param bounds: the rectangle to render into :param take_args: Data block with arguments for the shader. .. method:: push_mask(mask_mode: ~gi.repository.Gsk.MaskMode) -> None Until the first call to :obj:`~gi.repository.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 :obj:`~gi.repository.Gtk.Snapshot.pop`. Calling this function requires 2 subsequent calls to :func:`~gi.repository.Gtk.Snapshot.pop`. .. versionadded:: 4.10 :param mask_mode: mask mode to use .. method:: push_opacity(opacity: float) -> None Modifies the opacity of an image. The image is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param opacity: the opacity to use .. method:: push_repeat(bounds: ~gi.repository.Graphene.Rect, child_bounds: ~gi.repository.Graphene.Rect | None = None) -> None Creates a node that repeats the child node. The child is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param bounds: the bounds within which to repeat :param child_bounds: the bounds of the child or :const:`None` to use the full size of the collected child node .. method:: push_rounded_clip(bounds: ~gi.repository.Gsk.RoundedRect) -> None Clips an image to a rounded rectangle. The image is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param bounds: the rounded rectangle to clip to .. method:: push_shadow(shadow: ~typing.Sequence[~gi.repository.Gsk.Shadow]) -> None Applies a shadow to an image. The image is recorded until the next call to :obj:`~gi.repository.Gtk.Snapshot.pop`. :param shadow: the first shadow specification .. method:: push_stroke(path: ~gi.repository.Gsk.Path, stroke: ~gi.repository.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 :obj:`~gi.repository.Gtk.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, :obj:`~gi.repository.Gtk.Snapshot.append_stroke` may be more convenient. .. versionadded:: 4.14 :param path: The path to stroke :param stroke: The stroke attributes .. method:: render_background(context: ~gi.repository.Gtk.StyleContext, x: float, y: float, width: float, height: float) -> None 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. .. deprecated:: 4.10 Please do not use it in newly written code :param context: the style context that defines the background :param x: X origin of the rectangle :param y: Y origin of the rectangle :param width: rectangle width :param height: rectangle height .. method:: render_focus(context: ~gi.repository.Gtk.StyleContext, x: float, y: float, width: float, height: float) -> None 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. .. deprecated:: 4.10 Please do not use it in newly written code :param context: the style context that defines the focus ring :param x: X origin of the rectangle :param y: Y origin of the rectangle :param width: rectangle width :param height: rectangle height .. method:: render_frame(context: ~gi.repository.Gtk.StyleContext, x: float, y: float, width: float, height: float) -> None 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. .. deprecated:: 4.10 Please do not use it in newly written code :param context: the style context that defines the frame :param x: X origin of the rectangle :param y: Y origin of the rectangle :param width: rectangle width :param height: rectangle height .. method:: render_insertion_cursor(context: ~gi.repository.Gtk.StyleContext, x: float, y: float, layout: ~gi.repository.Pango.Layout, index: int, direction: ~gi.repository.Pango.Direction) -> None Draws a text caret using ``snapshot`` at the specified index of ``layout``. .. deprecated:: 4.10 Please do not use it in newly written code :param context: a ``GtkStyleContext`` :param x: X origin :param y: Y origin :param layout: the ``PangoLayout`` of the text :param index: the index in the ``PangoLayout`` :param direction: the ``PangoDirection`` of the text .. method:: render_layout(context: ~gi.repository.Gtk.StyleContext, x: float, y: float, layout: ~gi.repository.Pango.Layout) -> None 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. .. deprecated:: 4.10 Please do not use it in newly written code :param context: the style context that defines the text :param x: X origin of the rectangle :param y: Y origin of the rectangle :param layout: the ``PangoLayout`` to render .. method:: restore() -> None Restores ``snapshot`` to the state saved by a preceding call to :obj:`~gi.repository.Snapshot.save` and removes that state from the stack of saved states. .. method:: rotate(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 :obj:`~gi.repository.Gsk.Transform.rotate_3d`. :param angle: the rotation angle, in degrees (clockwise) .. method:: rotate_3d(angle: float, axis: ~gi.repository.Graphene.Vec3) -> None Rotates ``snapshot``'s coordinate system by ``angle`` degrees around ``axis``. For a rotation in 2D space, use :obj:`~gi.repository.Gsk.Transform.rotate`. :param angle: the rotation angle, in degrees (clockwise) :param axis: The rotation axis .. method:: save() -> None Makes a copy of the current state of ``snapshot`` and saves it on an internal stack. When :obj:`~gi.repository.Gtk.Snapshot.restore` is called, ``snapshot`` will be restored to the saved state. Multiple calls to :obj:`~gi.repository.Gtk.Snapshot.save` and :obj:`~gi.repository.Gtk.Snapshot.restore` can be nested; each call to ``:func:`~gi.repository.Gtk.Snapshot.restore``` restores the state from the matching paired ``:func:`~gi.repository.Gtk.Snapshot.save```. It is necessary to clear all saved states with corresponding calls to ``:func:`~gi.repository.Gtk.Snapshot.restore```. .. method:: scale(factor_x: float, factor_y: float) -> None Scales ``snapshot``'s coordinate system in 2-dimensional space by the given factors. Use :obj:`~gi.repository.Gtk.Snapshot.scale_3d` to scale in all 3 dimensions. :param factor_x: scaling factor on the X axis :param factor_y: scaling factor on the Y axis .. method:: scale_3d(factor_x: float, factor_y: float, factor_z: float) -> None Scales ``snapshot``'s coordinate system by the given factors. :param factor_x: scaling factor on the X axis :param factor_y: scaling factor on the Y axis :param factor_z: scaling factor on the Z axis .. method:: to_node() -> ~gi.repository.Gsk.RenderNode | None Returns the render node that was constructed by ``snapshot``. Note that this function may return :const:`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 :obj:`~gi.repository.GObject.Object.unref`. .. method:: to_paintable(size: ~gi.repository.Graphene.Size | None = None) -> ~gi.repository.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 :obj:`~gi.repository.GObject.Object.unref`. :param size: The size of the resulting paintable or :const:`None` to use the bounds of the snapshot .. method:: transform(transform: ~gi.repository.Gsk.Transform | None = None) -> None Transforms ``snapshot``'s coordinate system with the given ``transform``. :param transform: the transform to apply .. method:: transform_matrix(matrix: ~gi.repository.Graphene.Matrix) -> None Transforms ``snapshot``'s coordinate system with the given ``matrix``. :param matrix: the matrix to multiply the transform with .. method:: translate(point: ~gi.repository.Graphene.Point) -> None Translates ``snapshot``'s coordinate system by ``point`` in 2-dimensional space. :param point: the point to translate the snapshot by .. method:: translate_3d(point: ~gi.repository.Graphene.Point3D) -> None Translates ``snapshot``'s coordinate system by ``point``. :param point: the point to translate the snapshot by