Text
Cairo has two sets of text rendering capabilities:
The functions with text in their name form cairo’s toy text API. The toy API takes UTF-8 encoded text and is limited in its functionality to rendering simple left-to-right text with no advanced features. That means for example that most complex scripts like Hebrew, Arabic, and Indic scripts are out of question. No kerning or correct positioning of diacritical marks either. The font selection is pretty limited too and doesn’t handle the case that the selected font does not cover the characters in the text. This set of functions are really that, a toy text API, for testing and demonstration purposes. Any serious application should avoid them.
The functions with glyphs in their name form cairo’s low-level text API. The low-level API relies on the user to convert text to a set of glyph indexes and positions. This is a very hard problem and is best handled by external libraries, like the pangocairo that is part of the Pango text layout and rendering library. Pango is available from http://www.pango.org/.
class FontFace()
- class cairo.FontFace
A cairo.FontFace specifies all aspects of a font other than the size or font matrix (a font matrix is used to distort a font by sheering it or scaling it unequally in the two directions). A FontFace can be set on a
Context
by usingContext.set_font_face()
the size and font matrix are set withContext.set_font_size()
andContext.set_font_matrix()
.There are various types of FontFace, depending on the font backend they use.
Note
This class cannot be instantiated directly, it is returned by
Context.get_font_face()
.
class FreeTypeFontFace(FontFace
)
FreeType Fonts - Font support for FreeType.
The FreeType font backend is primarily used to render text on GNU/Linux systems, but can be used on other platforms too.
Note
FreeType Fonts are not implemented in pycairo because there is no open source Python bindings to FreeType (and fontconfig) that provides a C API. This a possible project idea for anyone interested in adding FreeType support to pycairo.
class ToyFontFace(FontFace
)
- class cairo.ToyFontFace(family: str, slant: FontSlant = Ellipsis, weight: FontWeight = Ellipsis)
The cairo.ToyFontFace class can be used instead of
Context.select_font_face()
to create a toy font independently of a context.New in version 1.8.4.
- __init__(family: str, slant: FontSlant = Ellipsis, weight: FontWeight = Ellipsis) None
- Parameters:
family – a font family name
slant – the font slant of the font, defaults to
cairo.FontSlant.NORMAL
.weight – the font weight of the font, defaults to
cairo.FontWeight.NORMAL
.
Creates a ToyFontFace from a triplet of family, slant, and weight. These font faces are used in implementation of the the “toy” font API.
If family is the zero-length string “”, the platform-specific default family is assumed. The default family then can be queried using
get_family()
.The
Context.select_font_face()
method uses this to create font faces. See that function for limitations of toy font faces.
- get_weight() FontWeight
- Returns:
the font weight value
New in version 1.8.4.
class UserFontFace(FontFace
)
The user-font feature allows the cairo user to provide drawings for glyphs in a font. This is most useful in implementing fonts in non-standard formats, like SVG fonts and Flash fonts, but can also be used by games and other application to draw “funky” fonts.
Note
UserFontFace support has not (yet) been added to pycairo. If you need this feature in pycairo register your interest by sending a message to the cairo mailing list, or by opening a pycairo bug report.
class ScaledFont()
- class cairo.ScaledFont(font_face: FontFace, font_matrix: Matrix, ctm: Matrix, options: FontOptions)
A ScaledFont is a font scaled to a particular size and device resolution. A ScaledFont is most useful for low-level font usage where a library or application wants to cache a reference to a scaled font to speed up the computation of metrics.
There are various types of scaled fonts, depending on the font backend they use.
- __init__(font_face: FontFace, font_matrix: Matrix, ctm: Matrix, options: FontOptions) None
- Parameters:
font_face – a
FontFace
instancefont_matrix – font space to user space transformation
Matrix
for the font. In the simplest case of a N point font, this matrix is just a scale by N, but it can also be used to shear the font or stretch it unequally along the two axes. SeeContext.set_font_matrix()
.ctm – user to device transformation
Matrix
with which the font will be used.options – a
FontOptions
instance to use when getting metrics for the font and rendering with it.
Creates a ScaledFont object from a FontFace and matrices that describe the size of the font and the environment in which it will be used.
- get_ctm() Matrix
- Returns:
the CTM
Returns the CTM with which scaled_font was created into ctm. Note that the translation offsets (x0, y0) of the CTM are ignored by
ScaledFont()
. So, the matrix this function returns always has 0, 0 as x0, y0.New in version 1.12.0.
- get_font_face() FontFace
- Returns:
the
FontFace
that this ScaledFont was created for.
New in version 1.2.
- get_font_matrix() Matrix
- Returns:
the matrix
Returns the font matrix with which scaled_font was created.
- get_font_options() FontOptions
- Returns:
font options
Returns the font options with which scaled_font was created.
New in version 1.12.0.
- get_scale_matrix() Matrix
- Returns:
the scale
Matrix
The scale matrix is product of the font matrix and the ctm associated with the scaled font, and hence is the matrix mapping from font space to device space.
New in version 1.8.
- glyph_extents(glyphs: Sequence[Glyph]) TextExtents
- Parameters:
glyphs – glyphs, a sequence of
Glyph
New in version 1.15.
Gets the extents for a list of glyphs. The extents describe a user-space rectangle that encloses the “inked” portion of the glyphs, (as they would be drawn by
Context.show_glyphs()
if the cairo graphics state were set to the same font_face, font_matrix, ctm, and font_options as scaled_font ). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by cairo_show_glyphs().Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).
- text_extents(text: str) TextExtents
- Parameters:
text – text
Gets the extents for a string of text. The extents describe a user-space rectangle that encloses the “inked” portion of the text drawn at the origin (0,0) (as it would be drawn by
Context.show_text()
if the cairo graphics state were set to the same font_face, font_matrix, ctm, and font_options as ScaledFont). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced byContext.show_text()
.Note that whitespace characters do not directly contribute to the size of the rectangle (width and height). They do contribute indirectly by changing the position of non-whitespace characters. In particular, trailing whitespace characters are likely to not affect the size of the rectangle, though they will affect the x_advance and y_advance values.
New in version 1.2.
- text_to_glyphs(x: float, y: float, utf8: str, with_clusters: bool = True) Tuple[List[Glyph], List[TextCluster], TextClusterFlags] | List[Glyph]
- Parameters:
x – X position to place first glyph
y – Y position to place first glyph
utf8 – a string of text
with_clusters – If
False
only the glyph list will computed and returned
- Returns:
a tuple of ([
Glyph
], [TextCluster
],TextClusterFlags
)- Raises:
Error –
New in version 1.15.
Converts UTF-8 text to a list of glyphs, with cluster mapping, that can be used to render later.
For details of how clusters, and cluster_flags map input UTF-8 text to the output glyphs see
Context.show_text_glyphs()
.The output values can be readily passed to
Context.show_text_glyphs()
Context.show_glyphs()
, or related functions, assuming that the exact same scaled font is used for the operation.
class FontOptions()
- class cairo.FontOptions
An opaque structure holding all options that are used when rendering fonts.
Individual features of a FontOptions can be set or accessed using functions named FontOptions.set_<feature_name> and FontOptions.get_<feature_name>, like
FontOptions.set_antialias()
andFontOptions.get_antialias()
.New features may be added to a FontOptions in the future. For this reason,
FontOptions.copy()
,FontOptions.equal()
,FontOptions.merge()
, andFontOptions.hash()
should be used to copy, check for equality, merge, or compute a hash value of FontOptions objects.Implements __eq__ and __ne__ using equal() since 1.12.0.
- __init__() None
Allocates a new FontOptions object with all options initialized to default values.
- get_subpixel_order() SubpixelOrder
- Returns:
the subpixel order for the FontOptions object
- set_antialias(antialias: Antialias) None
- Parameters:
antialias – the antialias mode
This specifies the type of antialiasing to do when rendering text.
- set_hint_metrics(hint_metrics: HintMetrics) None
- Parameters:
hint_metrics – the hint metrics mode
This controls whether metrics are quantized to integer values in device units.
- set_hint_style(hint_style: HintStyle) None
- Parameters:
hint_style – the hint style
This controls whether to fit font outlines to the pixel grid, and if so, whether to optimize for fidelity or contrast.
- merge(other: FontOptions) None
- Parameters:
other (FontOptions) – another
FontOptions
Merges non-default options from other into options , replacing existing values. This operation can be thought of as somewhat similar to compositing other onto options with the operation of
Operator.OVER
.New in version 1.12.0.
- copy() FontOptions
- Returns:
a new
FontOptions
Returns a new font options object copying the option values from original.
New in version 1.12.0.
- hash() int
- Returns:
the hash value for the font options object
Compute a hash for the font options object; this value will be useful when storing an object containing a
FontOptions
in a hash table.New in version 1.12.0.
- equal(other: FontOptions) bool
- Parameters:
other – another
FontOptions
- Returns:
True
if all fields of the two font options objects match. Note that this function will returnFalse
if either object is in error.
Compares two font options objects for equality.
New in version 1.12.0.
- set_variations(variations: str | None) None
- Parameters:
variations – the new font variations, or
None
Sets the OpenType font variations for the font options object. Font variations are specified as a string with a format that is similar to the CSS font-variation-settings. The string contains a comma-separated list of axis assignments, which each assignment consists of a 4-character axis name and a value, separated by whitespace and optional equals sign.
Examples:
wght=200,wdth=140.5
wght 200 , wdth 140.5
New in version 1.18.0: Only available with cairo 1.15.12+
- get_variations() str
- Returns:
the font variations for the font options object. The returned string belongs to the options and must not be modified. It is valid until either the font options object is destroyed or the font variations in this object is modified with
set_variations()
.
Gets the OpenType font variations for the font options object. See
set_variations()
for details about the string format.New in version 1.18.0: Only available with cairo 1.15.12+
- get_hint_metrics() HintMetrics
- Returns:
the hint metrics mode for the FontOptions object
- set_subpixel_order(subpixel_order: SubpixelOrder) None
- Parameters:
subpixel_order – the subpixel order
The subpixel order specifies the order of color elements within each pixel on the display device when rendering with an antialiasing mode of
cairo.Antialias.SUBPIXEL
.
- set_color_mode(color_mode: ColorMode) None
- Parameters:
color_mode – the new color mode
Sets the color mode for the font options object. This controls whether color fonts are to be rendered in color or as outlines. See the documentation for
ColorMode
for full details.New in version 1.25.0: Only available with cairo 1.17.8+
- get_color_mode() ColorMode
- Returns:
the color mode for the font options object
Gets the color mode for the font options object. See the documentation for
ColorMode
for full details.New in version 1.25.0: Only available with cairo 1.17.8+
- set_color_palette(palette_index: int) None
- Parameters:
palette_index – the palette index in the CPAL table
Sets the OpenType font color palette for the font options object. OpenType color fonts with a CPAL table may contain multiple palettes. The default color palette index is
COLOR_PALETTE_DEFAULT
. If palette_index is invalid, the default palette is used.New in version 1.25.0: Only available with cairo 1.17.8+
- get_color_palette() int
- Returns:
the palette index
Gets the OpenType color font palette for the font options object.
New in version 1.25.0: Only available with cairo 1.17.8+
- set_custom_palette_color(index: int, red: float, green: float, blue: float, alpha: float) None
- Parameters:
index – the index of the color to set
red – red component of color
green – green component of color
blue – blue component of color
alpha – alpha component of color
Sets a custom palette color for the font options object. This overrides the palette color at the specified color index. This override is independent of the selected palette index and will remain in place even if
FontOptions.set_color_palette()
is called to change the palette index.It is only possible to override color indexes already in the font palette.
New in version 1.25.0: Only available with cairo 1.17.8+
- get_custom_palette_color(index: int) Tuple[float, float, float, float]
- Parameters:
index – the index of the color to get
- Returns:
a (red, green, blue, alpha) tuple of float
- Raises:
Error – if no custom color exists for the color index.
Gets the custom palette color for the color index for the font options object.
New in version 1.25.0: Only available with cairo 1.17.8+