:right-sidebar: True Renderer =================================================================== .. currentmodule:: gi.repository.Pango .. versionadded:: 1.8 .. class:: Renderer(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``PangoRenderer`` is a base class for objects that can render text provided as ``PangoGlyphString`` or ``PangoLayout``\. By subclassing ``PangoRenderer`` and overriding operations such as ``draw_glyphs`` and ``draw_rectangle``\, renderers for particular font backends and destinations can be created. Methods ------- .. rst-class:: interim-class .. class:: Renderer :no-index: .. method:: activate() -> None Does initial setup before rendering operations on ``renderer``\. :obj:`~gi.repository.Pango.Renderer.deactivate` should be called when done drawing. Calls such as :obj:`~gi.repository.Pango.Renderer.draw_layout` automatically activate the layout before drawing on it. Calls to :obj:`~gi.repository.Pango.Renderer.activate` and :obj:`~gi.repository.Pango.Renderer.deactivate` can be nested and the renderer will only be initialized and deinitialized once. .. versionadded:: 1.8 .. method:: deactivate() -> None Cleans up after rendering operations on ``renderer``\. See docs for :obj:`~gi.repository.Pango.Renderer.activate`\. .. versionadded:: 1.8 .. method:: do_begin(self) -> None .. method:: do_draw_error_underline(self, x: int, y: int, width: int, height: int) -> None :param x: :param y: :param width: :param height: .. method:: do_draw_glyph(self, font: ~gi.repository.Pango.Font, glyph: int, x: float, y: float) -> None :param font: :param glyph: :param x: :param y: .. method:: do_draw_glyph_item(self, text: str | None, glyph_item: ~gi.repository.Pango.GlyphItem, x: int, y: int) -> None :param text: :param glyph_item: :param x: :param y: .. method:: do_draw_glyphs(self, font: ~gi.repository.Pango.Font, glyphs: ~gi.repository.Pango.GlyphString, x: int, y: int) -> None :param font: :param glyphs: :param x: :param y: .. method:: do_draw_rectangle(self, part: ~gi.repository.Pango.RenderPart, x: int, y: int, width: int, height: int) -> None :param part: :param x: :param y: :param width: :param height: .. method:: do_draw_shape(self, attr: ~gi.repository.Pango.AttrShape, x: int, y: int) -> None :param attr: :param x: :param y: .. method:: do_draw_trapezoid(self, part: ~gi.repository.Pango.RenderPart, y1_: float, x11: float, x21: float, y2: float, x12: float, x22: float) -> None :param part: :param y1_: :param x11: :param x21: :param y2: :param x12: :param x22: .. method:: do_end(self) -> None .. method:: do_part_changed(self, part: ~gi.repository.Pango.RenderPart) -> None :param part: .. method:: do_prepare_run(self, run: ~gi.repository.Pango.GlyphItem) -> None :param run: .. method:: draw_error_underline(x: int, y: int, width: int, height: int) -> None Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. This should be called while ``renderer`` is already active. Use :obj:`~gi.repository.Pango.Renderer.activate` to activate a renderer. .. versionadded:: 1.8 :param x: X coordinate of underline, in Pango units in user coordinate system :param y: Y coordinate of underline, in Pango units in user coordinate system :param width: width of underline, in Pango units in user coordinate system :param height: height of underline, in Pango units in user coordinate system .. method:: draw_glyph(font: ~gi.repository.Pango.Font, glyph: int, x: float, y: float) -> None Draws a single glyph with coordinates in device space. .. versionadded:: 1.8 :param font: a ``PangoFont`` :param glyph: the glyph index of a single glyph :param x: X coordinate of left edge of baseline of glyph :param y: Y coordinate of left edge of baseline of glyph .. method:: draw_glyph_item(text: str | None, glyph_item: ~gi.repository.Pango.GlyphItem, x: int, y: int) -> None Draws the glyphs in ``glyph_item`` with the specified ``PangoRenderer``\, embedding the text associated with the glyphs in the output if the output format supports it. This is useful for rendering text in PDF. Note that this method does not handle attributes in ``glyph_item``\. If you want colors, shapes and lines handled automatically according to those attributes, you need to use :func:`~gi.repository.Pango.Renderer.draw_layout_line` or :func:`~gi.repository.Pango.Renderer.draw_layout`. Note that ``text`` is the start of the text for layout, which is then indexed by ``glyph_item->item->offset``\. If ``text`` is :const:`None`, this simply calls :obj:`~gi.repository.Pango.Renderer.draw_glyphs`\. The default implementation of this method simply falls back to :obj:`~gi.repository.Pango.Renderer.draw_glyphs`\. .. versionadded:: 1.22 :param text: the UTF-8 text that ``glyph_item`` refers to :param glyph_item: a ``PangoGlyphItem`` :param x: X position of left edge of baseline, in user space coordinates in Pango units :param y: Y position of left edge of baseline, in user space coordinates in Pango units .. method:: draw_glyphs(font: ~gi.repository.Pango.Font, glyphs: ~gi.repository.Pango.GlyphString, x: int, y: int) -> None Draws the glyphs in ``glyphs`` with the specified ``PangoRenderer``\. .. versionadded:: 1.8 :param font: a ``PangoFont`` :param glyphs: a ``PangoGlyphString`` :param x: X position of left edge of baseline, in user space coordinates in Pango units. :param y: Y position of left edge of baseline, in user space coordinates in Pango units. .. method:: draw_layout(layout: ~gi.repository.Pango.Layout, x: int, y: int) -> None Draws ``layout`` with the specified ``PangoRenderer``\. This is equivalent to drawing the lines of the layout, at their respective positions relative to ``x``\, ``y``\. .. versionadded:: 1.8 :param layout: a ``PangoLayout`` :param x: X position of left edge of baseline, in user space coordinates in Pango units. :param y: Y position of left edge of baseline, in user space coordinates in Pango units. .. method:: draw_layout_line(line: ~gi.repository.Pango.LayoutLine, x: int, y: int) -> None Draws ``line`` with the specified ``PangoRenderer``\. This draws the glyph items that make up the line, as well as shapes, backgrounds and lines that are specified by the attributes of those items. .. versionadded:: 1.8 :param line: a ``PangoLayoutLine`` :param x: X position of left edge of baseline, in user space coordinates in Pango units. :param y: Y position of left edge of baseline, in user space coordinates in Pango units. .. method:: draw_rectangle(part: ~gi.repository.Pango.RenderPart, x: int, y: int, width: int, height: int) -> None Draws an axis-aligned rectangle in user space coordinates with the specified ``PangoRenderer``\. This should be called while ``renderer`` is already active. Use :obj:`~gi.repository.Pango.Renderer.activate` to activate a renderer. .. versionadded:: 1.8 :param part: type of object this rectangle is part of :param x: X position at which to draw rectangle, in user space coordinates in Pango units :param y: Y position at which to draw rectangle, in user space coordinates in Pango units :param width: width of rectangle in Pango units :param height: height of rectangle in Pango units .. method:: draw_trapezoid(part: ~gi.repository.Pango.RenderPart, y1_: float, x11: float, x21: float, y2: float, x12: float, x22: float) -> None Draws a trapezoid with the parallel sides aligned with the X axis using the given ``PangoRenderer``\; coordinates are in device space. .. versionadded:: 1.8 :param part: type of object this trapezoid is part of :param y1_: Y coordinate of top of trapezoid :param x11: X coordinate of left end of top of trapezoid :param x21: X coordinate of right end of top of trapezoid :param y2: Y coordinate of bottom of trapezoid :param x12: X coordinate of left end of bottom of trapezoid :param x22: X coordinate of right end of bottom of trapezoid .. method:: get_alpha(part: ~gi.repository.Pango.RenderPart) -> int Gets the current alpha for the specified part. .. versionadded:: 1.38 :param part: the part to get the alpha for .. method:: get_color(part: ~gi.repository.Pango.RenderPart) -> ~gi.repository.Pango.Color | None Gets the current rendering color for the specified part. .. versionadded:: 1.8 :param part: the part to get the color for .. method:: get_layout() -> ~gi.repository.Pango.Layout | None Gets the layout currently being rendered using ``renderer``\. Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. The returned layout should not be modified while still being rendered. .. versionadded:: 1.20 .. method:: get_layout_line() -> ~gi.repository.Pango.LayoutLine | None Gets the layout line currently being rendered using ``renderer``\. Calling this function only makes sense from inside a subclass's methods, like in its draw_shape vfunc, for example. The returned layout line should not be modified while still being rendered. .. versionadded:: 1.20 .. method:: get_matrix() -> ~gi.repository.Pango.Matrix | None Gets the transformation matrix that will be applied when rendering. See :obj:`~gi.repository.Pango.Renderer.set_matrix`\. .. versionadded:: 1.8 .. method:: part_changed(part: ~gi.repository.Pango.RenderPart) -> None Informs Pango that the way that the rendering is done for ``part`` has changed. This should be called if the rendering changes in a way that would prevent multiple pieces being joined together into one drawing call. For instance, if a subclass of ``PangoRenderer`` was to add a stipple option for drawing underlines, it needs to call .. code-block:: :dedent: pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for changes to colors. (See :obj:`~gi.repository.Pango.Renderer.set_color`\) .. versionadded:: 1.8 :param part: the part for which rendering has changed. .. method:: set_alpha(part: ~gi.repository.Pango.RenderPart, alpha: int) -> None Sets the alpha for part of the rendering. Note that the alpha may only be used if a color is specified for ``part`` as well. .. versionadded:: 1.38 :param part: the part to set the alpha for :param alpha: an alpha value between 1 and 65536, or 0 to unset the alpha .. method:: set_color(part: ~gi.repository.Pango.RenderPart, color: ~gi.repository.Pango.Color | None = None) -> None Sets the color for part of the rendering. Also see :obj:`~gi.repository.Pango.Renderer.set_alpha`\. .. versionadded:: 1.8 :param part: the part to change the color of :param color: the new color or :const:`None` to unset the current color .. method:: set_matrix(matrix: ~gi.repository.Pango.Matrix | None = None) -> None Sets the transformation matrix that will be applied when rendering. .. versionadded:: 1.8 :param matrix: a ``PangoMatrix``\, or :const:`None` to unset any existing matrix (No matrix set is the same as setting the identity matrix.) Virtual Methods --------------- .. rst-class:: interim-class .. class:: Renderer :no-index: .. method:: do_begin() -> None The type of the None singleton. .. method:: do_draw_error_underline(x: int, y: int, width: int, height: int) -> None Draw a squiggly line that approximately covers the given rectangle in the style of an underline used to indicate a spelling error. The width of the underline is rounded to an integer number of up/down segments and the resulting rectangle is centered in the original rectangle. This should be called while ``renderer`` is already active. Use :obj:`~gi.repository.Pango.Renderer.activate` to activate a renderer. .. versionadded:: 1.8 :param x: X coordinate of underline, in Pango units in user coordinate system :param y: Y coordinate of underline, in Pango units in user coordinate system :param width: width of underline, in Pango units in user coordinate system :param height: height of underline, in Pango units in user coordinate system .. method:: do_draw_glyph(font: ~gi.repository.Pango.Font, glyph: int, x: float, y: float) -> None Draws a single glyph with coordinates in device space. .. versionadded:: 1.8 :param font: a ``PangoFont`` :param glyph: the glyph index of a single glyph :param x: X coordinate of left edge of baseline of glyph :param y: Y coordinate of left edge of baseline of glyph .. method:: do_draw_glyph_item(text: str | None, glyph_item: ~gi.repository.Pango.GlyphItem, x: int, y: int) -> None Draws the glyphs in ``glyph_item`` with the specified ``PangoRenderer``\, embedding the text associated with the glyphs in the output if the output format supports it. This is useful for rendering text in PDF. Note that this method does not handle attributes in ``glyph_item``\. If you want colors, shapes and lines handled automatically according to those attributes, you need to use :func:`~gi.repository.Pango.Renderer.draw_layout_line` or :func:`~gi.repository.Pango.Renderer.draw_layout`. Note that ``text`` is the start of the text for layout, which is then indexed by ``glyph_item->item->offset``\. If ``text`` is :const:`None`, this simply calls :obj:`~gi.repository.Pango.Renderer.draw_glyphs`\. The default implementation of this method simply falls back to :obj:`~gi.repository.Pango.Renderer.draw_glyphs`\. .. versionadded:: 1.22 :param text: the UTF-8 text that ``glyph_item`` refers to :param glyph_item: a ``PangoGlyphItem`` :param x: X position of left edge of baseline, in user space coordinates in Pango units :param y: Y position of left edge of baseline, in user space coordinates in Pango units .. method:: do_draw_glyphs(font: ~gi.repository.Pango.Font, glyphs: ~gi.repository.Pango.GlyphString, x: int, y: int) -> None Draws the glyphs in ``glyphs`` with the specified ``PangoRenderer``\. .. versionadded:: 1.8 :param font: a ``PangoFont`` :param glyphs: a ``PangoGlyphString`` :param x: X position of left edge of baseline, in user space coordinates in Pango units. :param y: Y position of left edge of baseline, in user space coordinates in Pango units. .. method:: do_draw_rectangle(part: ~gi.repository.Pango.RenderPart, x: int, y: int, width: int, height: int) -> None Draws an axis-aligned rectangle in user space coordinates with the specified ``PangoRenderer``\. This should be called while ``renderer`` is already active. Use :obj:`~gi.repository.Pango.Renderer.activate` to activate a renderer. .. versionadded:: 1.8 :param part: type of object this rectangle is part of :param x: X position at which to draw rectangle, in user space coordinates in Pango units :param y: Y position at which to draw rectangle, in user space coordinates in Pango units :param width: width of rectangle in Pango units :param height: height of rectangle in Pango units .. method:: do_draw_shape(attr: ~gi.repository.Pango.AttrShape, x: int, y: int) -> None The type of the None singleton. :param attr: :param x: :param y: .. method:: do_draw_trapezoid(part: ~gi.repository.Pango.RenderPart, y1_: float, x11: float, x21: float, y2: float, x12: float, x22: float) -> None Draws a trapezoid with the parallel sides aligned with the X axis using the given ``PangoRenderer``\; coordinates are in device space. .. versionadded:: 1.8 :param part: type of object this trapezoid is part of :param y1_: Y coordinate of top of trapezoid :param x11: X coordinate of left end of top of trapezoid :param x21: X coordinate of right end of top of trapezoid :param y2: Y coordinate of bottom of trapezoid :param x12: X coordinate of left end of bottom of trapezoid :param x22: X coordinate of right end of bottom of trapezoid .. method:: do_end() -> None The type of the None singleton. .. method:: do_part_changed(part: ~gi.repository.Pango.RenderPart) -> None Informs Pango that the way that the rendering is done for ``part`` has changed. This should be called if the rendering changes in a way that would prevent multiple pieces being joined together into one drawing call. For instance, if a subclass of ``PangoRenderer`` was to add a stipple option for drawing underlines, it needs to call .. code-block:: :dedent: pango_renderer_part_changed (render, PANGO_RENDER_PART_UNDERLINE); When the stipple changes or underlines with different stipples might be joined together. Pango automatically calls this for changes to colors. (See :obj:`~gi.repository.Pango.Renderer.set_color`\) .. versionadded:: 1.8 :param part: the part for which rendering has changed. .. method:: do_prepare_run(run: ~gi.repository.Pango.GlyphItem) -> None The type of the None singleton. :param run: Fields ------ .. rst-class:: interim-class .. class:: Renderer :no-index: .. attribute:: active_count .. attribute:: matrix The current transformation matrix for the Renderer; may be :const:`None`, which should be treated the same as the identity matrix. .. attribute:: parent_instance .. attribute:: priv .. attribute:: strikethrough .. attribute:: underline