Renderer#
Added in version 1.8.
Superclasses: 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#
- class Renderer
- activate() None #
Does initial setup before rendering operations on
renderer
.deactivate
should be called when done drawing. Calls such asdraw_layout
automatically activate the layout before drawing on it.Calls to
activate
anddeactivate
can be nested and the renderer will only be initialized and deinitialized once.Added in version 1.8.
- deactivate() None #
Cleans up after rendering operations on
renderer
.See docs for
activate
.Added in version 1.8.
- do_draw_error_underline(self, x: int, y: int, width: int, height: int) None #
- Parameters:
x
y
width
height
- do_draw_glyph_item(self, text: str | None, glyph_item: GlyphItem, x: int, y: int) None #
- Parameters:
text
glyph_item
x
y
- do_draw_glyphs(self, font: Font, glyphs: GlyphString, x: int, y: int) None #
- Parameters:
font
glyphs
x
y
- do_draw_rectangle(self, part: RenderPart, x: int, y: int, width: int, height: int) None #
- Parameters:
part
x
y
width
height
- do_draw_trapezoid(self, part: RenderPart, y1_: float, x11: float, x21: float, y2: float, x12: float, x22: float) None #
- Parameters:
part
y1
x11
x21
y2
x12
x22
- do_part_changed(self, part: RenderPart) None #
- Parameters:
part
- 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. Useactivate
to activate a renderer.Added in version 1.8.
- Parameters:
x – X coordinate of underline, in Pango units in user coordinate system
y – Y coordinate of underline, in Pango units in user coordinate system
width – width of underline, in Pango units in user coordinate system
height – height of underline, in Pango units in user coordinate system
- draw_glyph(font: Font, glyph: int, x: float, y: float) None #
Draws a single glyph with coordinates in device space.
Added in version 1.8.
- Parameters:
font – a
PangoFont
glyph – the glyph index of a single glyph
x – X coordinate of left edge of baseline of glyph
y – Y coordinate of left edge of baseline of glyph
- draw_glyph_item(text: str | None, glyph_item: GlyphItem, x: int, y: int) None #
Draws the glyphs in
glyph_item
with the specifiedPangoRenderer
, 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 usedraw_layout_line()
ordraw_layout()
.Note that
text
is the start of the text for layout, which is then indexed byglyph_item->item->offset
.If
text
isNone
, this simply callsdraw_glyphs
.The default implementation of this method simply falls back to
draw_glyphs
.Added in version 1.22.
- Parameters:
text – the UTF-8 text that
glyph_item
refers toglyph_item – a
PangoGlyphItem
x – X position of left edge of baseline, in user space coordinates in Pango units
y – Y position of left edge of baseline, in user space coordinates in Pango units
- draw_glyphs(font: Font, glyphs: GlyphString, x: int, y: int) None #
Draws the glyphs in
glyphs
with the specifiedPangoRenderer
.Added in version 1.8.
- Parameters:
font – a
PangoFont
glyphs – a
PangoGlyphString
x – X position of left edge of baseline, in user space coordinates in Pango units.
y – Y position of left edge of baseline, in user space coordinates in Pango units.
- draw_layout(layout: Layout, x: int, y: int) None #
Draws
layout
with the specifiedPangoRenderer
.This is equivalent to drawing the lines of the layout, at their respective positions relative to
x
,y
.Added in version 1.8.
- Parameters:
layout – a
PangoLayout
x – X position of left edge of baseline, in user space coordinates in Pango units.
y – Y position of left edge of baseline, in user space coordinates in Pango units.
- draw_layout_line(line: LayoutLine, x: int, y: int) None #
Draws
line
with the specifiedPangoRenderer
.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.
Added in version 1.8.
- Parameters:
line – a
PangoLayoutLine
x – X position of left edge of baseline, in user space coordinates in Pango units.
y – Y position of left edge of baseline, in user space coordinates in Pango units.
- draw_rectangle(part: 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. Useactivate
to activate a renderer.Added in version 1.8.
- Parameters:
part – type of object this rectangle is part of
x – X position at which to draw rectangle, in user space coordinates in Pango units
y – Y position at which to draw rectangle, in user space coordinates in Pango units
width – width of rectangle in Pango units
height – height of rectangle in Pango units
- draw_trapezoid(part: 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.Added in version 1.8.
- Parameters:
part – type of object this trapezoid is part of
y1 – Y coordinate of top of trapezoid
x11 – X coordinate of left end of top of trapezoid
x21 – X coordinate of right end of top of trapezoid
y2 – Y coordinate of bottom of trapezoid
x12 – X coordinate of left end of bottom of trapezoid
x22 – X coordinate of right end of bottom of trapezoid
- get_alpha(part: RenderPart) int #
Gets the current alpha for the specified part.
Added in version 1.38.
- Parameters:
part – the part to get the alpha for
- get_color(part: RenderPart) Color | None #
Gets the current rendering color for the specified part.
Added in version 1.8.
- Parameters:
part – the part to get the color for
- get_layout() 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.
Added in version 1.20.
- get_layout_line() 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.
Added in version 1.20.
- get_matrix() Matrix | None #
Gets the transformation matrix that will be applied when rendering.
See
set_matrix
.Added in version 1.8.
- part_changed(part: 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 callpango_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
set_color
)Added in version 1.8.
- Parameters:
part – the part for which rendering has changed.
- set_alpha(part: 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.Added in version 1.38.
- Parameters:
part – the part to set the alpha for
alpha – an alpha value between 1 and 65536, or 0 to unset the alpha
Virtual Methods#
- class Renderer
-
- do_draw_error_underline(type, self, 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. Useactivate
to activate a renderer.Added in version 1.8.
- Parameters:
type
self
x – X coordinate of underline, in Pango units in user coordinate system
y – Y coordinate of underline, in Pango units in user coordinate system
width – width of underline, in Pango units in user coordinate system
height – height of underline, in Pango units in user coordinate system
- do_draw_glyph(type, self, font: Font, glyph: int, x: float, y: float) None #
Draws a single glyph with coordinates in device space.
Added in version 1.8.
- Parameters:
type
self
font – a
PangoFont
glyph – the glyph index of a single glyph
x – X coordinate of left edge of baseline of glyph
y – Y coordinate of left edge of baseline of glyph
- do_draw_glyph_item(type, self, text: str | None, glyph_item: GlyphItem, x: int, y: int) None #
Draws the glyphs in
glyph_item
with the specifiedPangoRenderer
, 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 usedraw_layout_line()
ordraw_layout()
.Note that
text
is the start of the text for layout, which is then indexed byglyph_item->item->offset
.If
text
isNone
, this simply callsdraw_glyphs
.The default implementation of this method simply falls back to
draw_glyphs
.Added in version 1.22.
- Parameters:
type
self
text – the UTF-8 text that
glyph_item
refers toglyph_item – a
PangoGlyphItem
x – X position of left edge of baseline, in user space coordinates in Pango units
y – Y position of left edge of baseline, in user space coordinates in Pango units
- do_draw_glyphs(type, self, font: Font, glyphs: GlyphString, x: int, y: int) None #
Draws the glyphs in
glyphs
with the specifiedPangoRenderer
.Added in version 1.8.
- Parameters:
type
self
font – a
PangoFont
glyphs – a
PangoGlyphString
x – X position of left edge of baseline, in user space coordinates in Pango units.
y – Y position of left edge of baseline, in user space coordinates in Pango units.
- do_draw_rectangle(type, self, part: 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. Useactivate
to activate a renderer.Added in version 1.8.
- Parameters:
type
self
part – type of object this rectangle is part of
x – X position at which to draw rectangle, in user space coordinates in Pango units
y – Y position at which to draw rectangle, in user space coordinates in Pango units
width – width of rectangle in Pango units
height – height of rectangle in Pango units
- do_draw_shape(type, self, attr: AttrShape, x: int, y: int) None #
The type of the None singleton.
- Parameters:
type
self
attr
x
y
- do_draw_trapezoid(type, self, part: 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.Added in version 1.8.
- Parameters:
type
self
part – type of object this trapezoid is part of
y1 – Y coordinate of top of trapezoid
x11 – X coordinate of left end of top of trapezoid
x21 – X coordinate of right end of top of trapezoid
y2 – Y coordinate of bottom of trapezoid
x12 – X coordinate of left end of bottom of trapezoid
x22 – X coordinate of right end of bottom of trapezoid
- do_part_changed(type, self, part: 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 callpango_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
set_color
)Added in version 1.8.
- Parameters:
type
self
part – the part for which rendering has changed.