Functions
cairo_select_font_face ()
void
cairo_select_font_face (cairo_t *cr,
const char *family,
cairo_font_slant_t slant,
cairo_font_weight_t weight);
Note: The cairo_select_font_face() function call is part of what
the cairo designers call the "toy" text API. It is convenient for
short demos and simple programs, but it is not expected to be
adequate for serious text-using applications.
Selects a family and style of font from a simplified description as
a family name, slant and weight. Cairo provides no operation to
list available family names on the system (this is a "toy",
remember), but the standard CSS2 generic family names, ("serif",
"sans-serif", "cursive", "fantasy", "monospace"), are likely to
work as expected.
If family
starts with the string "cairo
:", or if no native font
backends are compiled in, cairo will use an internal font family.
The internal font family recognizes many modifiers in the family
string, most notably, it recognizes the string "monospace". That is,
the family name "cairo
:monospace" will use the monospace version of
the internal font family.
For "real" font selection, see the font-backend-specific
font_face_create functions for the font backend you are using. (For
example, if you are using the freetype-based cairo-ft font backend,
see cairo_ft_font_face_create_for_ft_face() or
cairo_ft_font_face_create_for_pattern().) The resulting font face
could then be used with cairo_scaled_font_create() and
cairo_set_scaled_font().
Similarly, when using the "real" font support, you can call
directly into the underlying font system, (such as fontconfig or
freetype), for operations such as listing available fonts, etc.
It is expected that most applications will need to use a more
comprehensive font handling and text layout library, (for example,
pango), in conjunction with cairo.
If text is drawn without a call to cairo_select_font_face(), (nor
cairo_set_font_face() nor cairo_set_scaled_font()), the default
family is platform-specific, but is essentially "sans-serif".
Default slant is CAIRO_FONT_SLANT_NORMAL, and default weight is
CAIRO_FONT_WEIGHT_NORMAL.
This function is equivalent to a call to cairo_toy_font_face_create()
followed by cairo_set_font_face().
Since: 1.0
cairo_set_font_matrix ()
void
cairo_set_font_matrix (cairo_t *cr,
const cairo_matrix_t *matrix);
Sets the current font matrix to matrix
. The font matrix gives a
transformation from the design space of the font (in this space,
the em-square is 1 unit by 1 unit) to user space. Normally, a
simple scale is used (see cairo_set_font_size()), but a more
complex font matrix can be used to shear the font
or stretch it unequally along the two axes
Since: 1.0
cairo_set_font_options ()
void
cairo_set_font_options (cairo_t *cr,
const cairo_font_options_t *options);
Sets a set of custom font rendering options for the cairo_t.
Rendering options are derived by merging these options with the
options derived from underlying surface; if the value in options
has a default value (like CAIRO_ANTIALIAS_DEFAULT), then the value
from the surface is used.
Since: 1.0
cairo_set_font_face ()
void
cairo_set_font_face (cairo_t *cr,
cairo_font_face_t *font_face);
Replaces the current cairo_font_face_t object in the cairo_t with
font_face
. The replaced font face in the cairo_t will be
destroyed if there are no other references to it.
Since: 1.0
cairo_show_text ()
void
cairo_show_text (cairo_t *cr,
const char *utf8);
A drawing operator that generates the shape from a string of UTF-8
characters, rendered according to the current font_face, font_size
(font_matrix), and font_options.
This function first computes a set of glyphs for the string of
text. The first glyph is placed so that its origin is at the
current point. The origin of each subsequent glyph is offset from
that of the previous glyph by the advance values of the previous
glyph.
After this call the current point is moved to the origin of where
the next glyph would be placed in this same progression. That is,
the current point will be at the origin of the final glyph offset
by its advance values. This allows for easy display of a single
logical string with multiple calls to cairo_show_text().
Note: The cairo_show_text() function call is part of what the cairo
designers call the "toy" text API. It is convenient for short demos
and simple programs, but it is not expected to be adequate for
serious text-using applications. See cairo_show_glyphs() for the
"real" text display API in cairo.
Since: 1.0
cairo_show_glyphs ()
void
cairo_show_glyphs (cairo_t *cr,
const cairo_glyph_t *glyphs,
int num_glyphs);
A drawing operator that generates the shape from an array of glyphs,
rendered according to the current font face, font size
(font matrix), and font options.
Since: 1.0
cairo_show_text_glyphs ()
void
cairo_show_text_glyphs (cairo_t *cr,
const char *utf8,
int utf8_len,
const cairo_glyph_t *glyphs,
int num_glyphs,
const cairo_text_cluster_t *clusters,
int num_clusters,
cairo_text_cluster_flags_t cluster_flags);
This operation has rendering effects similar to cairo_show_glyphs()
but, if the target surface supports it, uses the provided text and
cluster mapping to embed the text for the glyphs shown in the output.
If the target does not support the extended attributes, this function
acts like the basic cairo_show_glyphs() as if it had been passed
glyphs
and num_glyphs
.
The mapping between utf8
and glyphs
is provided by an array of
clusters. Each cluster covers a number of
text bytes and glyphs, and neighboring clusters cover neighboring
areas of utf8
and glyphs
. The clusters should collectively cover utf8
and glyphs
in entirety.
The first cluster always covers bytes from the beginning of utf8
.
If cluster_flags
do not have the CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
set, the first cluster also covers the beginning
of glyphs
, otherwise it covers the end of the glyphs
array and
following clusters move backward.
See cairo_text_cluster_t for constraints on valid clusters.
Since: 1.8
cairo_font_extents ()
void
cairo_font_extents (cairo_t *cr,
cairo_font_extents_t *extents);
Gets the font extents for the currently selected font.
Since: 1.0
cairo_text_extents ()
void
cairo_text_extents (cairo_t *cr,
const char *utf8,
cairo_text_extents_t *extents);
Gets the extents for a string of text. The extents describe a
user-space rectangle that encloses the "inked" portion of the text,
(as it would be drawn by cairo_show_text()). Additionally, the
x_advance and y_advance values indicate the amount by which the
current point would be advanced by cairo_show_text().
Note that whitespace characters do not directly contribute to the
size of the rectangle (extents.width and extents.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.
Since: 1.0
cairo_glyph_extents ()
void
cairo_glyph_extents (cairo_t *cr,
const cairo_glyph_t *glyphs,
int num_glyphs,
cairo_text_extents_t *extents);
Gets the extents for an array of glyphs. The extents describe a
user-space rectangle that encloses the "inked" portion of the
glyphs, (as they would be drawn by cairo_show_glyphs()).
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).
Since: 1.0
cairo_toy_font_face_create ()
cairo_font_face_t *
cairo_toy_font_face_create (const char *family,
cairo_font_slant_t slant,
cairo_font_weight_t weight);
Creates a font face from a triplet of family, slant, and weight.
These font faces are used in implementation of the the cairo_t "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
cairo_toy_font_face_get_family().
The cairo_select_font_face() function uses this to create font faces.
See that function for limitations and other details of toy font faces.
Since: 1.8
cairo_toy_font_face_get_family ()
const char *
cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
Gets the familly name of a toy font.
Returns
The family name. This string is owned by the font face
and remains valid as long as the font face is alive (referenced).
Since: 1.8
cairo_glyph_allocate ()
cairo_glyph_t *
cairo_glyph_allocate (int num_glyphs);
Allocates an array of cairo_glyph_t's.
This function is only useful in implementations of
cairo_user_scaled_font_text_to_glyphs_func_t where the user
needs to allocate an array of glyphs that cairo will free.
For all other uses, user can use their own allocation method
for glyphs.
This function returns NULL if num_glyphs
is not positive,
or if out of memory. That means, the NULL return value
signals out-of-memory only if num_glyphs
was positive.
Since: 1.8
cairo_text_cluster_allocate ()
cairo_text_cluster_t *
cairo_text_cluster_allocate (int num_clusters);
Allocates an array of cairo_text_cluster_t's.
This function is only useful in implementations of
cairo_user_scaled_font_text_to_glyphs_func_t where the user
needs to allocate an array of text clusters that cairo will free.
For all other uses, user can use their own allocation method
for text clusters.
This function returns NULL if num_clusters
is not positive,
or if out of memory. That means, the NULL return value
signals out-of-memory only if num_clusters
was positive.
Since: 1.8
cairo_text_cluster_free ()
void
cairo_text_cluster_free (cairo_text_cluster_t *clusters);
Frees an array of cairo_text_cluster's allocated using cairo_text_cluster_allocate().
This function is only useful to free text cluster array returned
by cairo_scaled_font_text_to_glyphs() where cairo returns
an array of text clusters that the user will free.
For all other uses, user can use their own allocation method
for text clusters.
Since: 1.8