text: Cairo: A Vector Graphics Library

+ + +

text

text — Rendering text and glyphs

Functions

++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

+void +	+cairo_select_font_face () +
+void +	+cairo_set_font_size () +
+void +	+cairo_set_font_matrix () +
+void +	+cairo_get_font_matrix () +
+void +	+cairo_set_font_options () +
+void +	+cairo_get_font_options () +
+void +	+cairo_set_font_face () +
+cairo_font_face_t * +	+cairo_get_font_face () +
+void +	+cairo_set_scaled_font () +
+cairo_scaled_font_t * +	+cairo_get_scaled_font () +
+void +	+cairo_show_text () +
+void +	+cairo_show_glyphs () +
+void +	+cairo_show_text_glyphs () +
+void +	+cairo_font_extents () +
+void +	+cairo_text_extents () +
+void +	+cairo_glyph_extents () +
+cairo_font_face_t * +	+cairo_toy_font_face_create () +
const char * +	+cairo_toy_font_face_get_family () +
+cairo_font_slant_t +	+cairo_toy_font_face_get_slant () +
+cairo_font_weight_t +	+cairo_toy_font_face_get_weight () +
+cairo_glyph_t * +	+cairo_glyph_allocate () +
+void +	+cairo_glyph_free () +
+cairo_text_cluster_t * +	+cairo_text_cluster_allocate () +
+void +	+cairo_text_cluster_free () +

Types and Values

++++ + + + + + + + + + + + + + + + + + + + + + + +

	cairo_glyph_t
enum	cairo_font_slant_t
enum	cairo_font_weight_t
	cairo_text_cluster_t
enum	cairo_text_cluster_flags_t

Description

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/.

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().

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo_t
family	a font family name, encoded in UTF-8
slant	the slant for the font
weight	the weight for the font

Since: 1.0

cairo_set_font_size ()

void
+cairo_set_font_size (cairo_t *cr,
+                     double size);

Sets the current font matrix to a scale by a factor of size +, replacing +any font matrix previously set with cairo_set_font_size() or +cairo_set_font_matrix(). This results in a font size of size + user space +units. (More precisely, this matrix will result in the font's +em-square being a size + by size + square in user space.)

If text is drawn without a call to cairo_set_font_size(), (nor +cairo_set_font_matrix() nor cairo_set_scaled_font()), the default +font size is 10.0.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
size	the new font size, in user space units

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

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
matrix	a cairo_matrix_t describing a transform to be applied to +the current font.

Since: 1.0

cairo_get_font_matrix ()

void
+cairo_get_font_matrix (cairo_t *cr,
+                       cairo_matrix_t *matrix);

Stores the current font matrix into matrix +. See +cairo_set_font_matrix().

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
matrix	return value for the matrix

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.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
options	font options to use

Since: 1.0

cairo_get_font_options ()

void
+cairo_get_font_options (cairo_t *cr,
+                        cairo_font_options_t *options);

Retrieves font rendering options set via cairo_set_font_options. +Note that the returned options do not include any options derived +from the underlying surface; they are literally the options +passed to cairo_set_font_options().

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
options	a cairo_font_options_t object into which to store +the retrieved options. All existing values are overwritten

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.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
font_face	a cairo_font_face_t, or `NULL` to restore to the default font

Since: 1.0

cairo_get_font_face ()

cairo_font_face_t *
+cairo_get_font_face (cairo_t *cr);

Gets the current font face for a cairo_t.

Parameters

+++++ + + + + + +

a cairo_t

Returns

the current font face. This object is owned by +cairo. To keep a reference to it, you must call +cairo_font_face_reference().

This function never returns NULL. If memory cannot be allocated, a +special "nil" cairo_font_face_t object will be returned on which +cairo_font_face_status() returns CAIRO_STATUS_NO_MEMORY. Using +this nil object will cause its error state to propagate to other +objects it is passed to, (for example, calling +cairo_set_font_face() with a nil font will trigger an error that +will shutdown the cairo_t object).

Since: 1.0

cairo_set_scaled_font ()

void
+cairo_set_scaled_font (cairo_t *cr,
+                       const cairo_scaled_font_t *scaled_font);

Replaces the current font face, font matrix, and font options in +the cairo_t with those of the cairo_scaled_font_t. Except for +some translation, the current CTM of the cairo_t should be the +same as that of the cairo_scaled_font_t, which can be accessed +using cairo_scaled_font_get_ctm().

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
scaled_font	a cairo_scaled_font_t

Since: 1.2

cairo_get_scaled_font ()

cairo_scaled_font_t *
+cairo_get_scaled_font (cairo_t *cr);

Gets the current scaled font for a cairo_t.

Parameters

+++++ + + + + + +

a cairo_t

Returns

the current scaled font. This object is owned by +cairo. To keep a reference to it, you must call +cairo_scaled_font_reference().

This function never returns NULL. If memory cannot be allocated, a +special "nil" cairo_scaled_font_t object will be returned on which +cairo_scaled_font_status() returns CAIRO_STATUS_NO_MEMORY. Using +this nil object will cause its error state to propagate to other +objects it is passed to, (for example, calling +cairo_set_scaled_font() with a nil font will trigger an error that +will shutdown the cairo_t object).

Since: 1.4

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.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo context
utf8	a NUL-terminated string of text encoded in UTF-8, or `NULL`

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo context
glyphs	array of glyphs to show
num_glyphs	number of glyphs to show

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo context
utf8	a string of text encoded in UTF-8
utf8_len	length of `utf8` +in bytes, or -1 if it is NUL-terminated
glyphs	array of glyphs to show
num_glyphs	number of glyphs to show
clusters	array of cluster mapping information
num_clusters	number of clusters in the mapping
cluster_flags	cluster mapping flags

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.

Parameters

+++++ + + + + + + + + + + + + +

cr	a cairo_t
extents	a cairo_font_extents_t object into which the results +will be stored.

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

cr	a cairo_t
utf8	a NUL-terminated string of text encoded in UTF-8, or `NULL`
extents	a cairo_text_extents_t object into which the results +will be stored

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).

Parameters

+++++ + + + + + + + + + + + + + + + + + + + + + + +

cr	a cairo_t
glyphs	an array of cairo_glyph_t objects
num_glyphs	the number of elements in `glyphs` +
extents	a cairo_text_extents_t object into which the results +will be stored

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.

Parameters

+++++ + + + + + + + + + + + + + + + + + +

family	a font family name, encoded in UTF-8
slant	the slant for the font
weight	the weight for the font

Returns

a newly created cairo_font_face_t. Free with +cairo_font_face_destroy() when you are done using it.

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.

Parameters

+++++ + + + + + +

font_face

A toy font face

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_toy_font_face_get_slant ()

cairo_font_slant_t
+cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);

Gets the slant a toy font.

Parameters

+++++ + + + + + +

font_face

A toy font face

Returns

The slant value

Since: 1.8

cairo_toy_font_face_get_weight ()

cairo_font_weight_t
+cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);

Gets the weight a toy font.

Parameters

+++++ + + + + + +

font_face

A toy font face

Returns

The weight value

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.

Parameters

+++++ + + + + + +

num_glyphs

number of glyphs to allocate

Returns

the newly allocated array of glyphs that should be +freed using cairo_glyph_free()

Since: 1.8

cairo_glyph_free ()

void
+cairo_glyph_free (cairo_glyph_t *glyphs);

Frees an array of cairo_glyph_t's allocated using cairo_glyph_allocate(). +This function is only useful to free glyph array returned +by cairo_scaled_font_text_to_glyphs() where cairo returns +an array of glyphs that the user will free. +For all other uses, user can use their own allocation method +for glyphs.

Parameters

+++++ + + + + + +

glyphs

array of glyphs to free, or NULL

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.

Parameters

+++++ + + + + + +

num_clusters

number of text_clusters to allocate

Returns

the newly allocated array of text clusters that should be +freed using cairo_text_cluster_free()

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.

Parameters

+++++ + + + + + +

clusters

array of text clusters to free, or NULL

Since: 1.8

Types and Values

cairo_glyph_t

typedef struct {
+    unsigned long        index;
+    double               x;
+    double               y;
+} cairo_glyph_t;
+

The cairo_glyph_t structure holds information about a single glyph +when drawing or measuring text. A font is (in simple terms) a +collection of shapes used to draw text. A glyph is one of these +shapes. There can be multiple glyphs for a single character +(alternates to be used in different contexts, for example), or a +glyph can be a ligature of multiple +characters. Cairo doesn't expose any way of converting input text +into glyphs, so in order to use the Cairo interfaces that take +arrays of glyphs, you must directly access the appropriate +underlying font system.

Note that the offsets given by x + and y + are not cumulative. When +drawing or measuring text, each glyph is individually positioned +with respect to the overall origin

Members

+++++ + + + + + + + + + + + + + + + + + +

unsigned long `index`;	glyph index in the font. The exact interpretation of the +glyph index depends on the font technology being used.
double `x`;	the offset in the X direction between the origin used for +drawing or measuring the string and the origin of this glyph.
double `y`;	the offset in the Y direction between the origin used for +drawing or measuring the string and the origin of this glyph.

Since: 1.0

enum cairo_font_slant_t

Specifies variants of a font face based on their slant.

Members

+++++ + + + + + + + + + + + + + + + + + +

CAIRO_FONT_SLANT_NORMAL	+ Upright font style, since 1.0 +
CAIRO_FONT_SLANT_ITALIC	+ Italic font style, since 1.0 +
CAIRO_FONT_SLANT_OBLIQUE	+ Oblique font style, since 1.0 +

Since: 1.0

enum cairo_font_weight_t

Specifies variants of a font face based on their weight.

Members

+++++ + + + + + + + + + + + + +

CAIRO_FONT_WEIGHT_NORMAL	+ Normal font weight, since 1.0 +
CAIRO_FONT_WEIGHT_BOLD	+ Bold font weight, since 1.0 +

Since: 1.0

cairo_text_cluster_t

typedef struct {
+    int        num_bytes;
+    int        num_glyphs;
+} cairo_text_cluster_t;
+

The cairo_text_cluster_t structure holds information about a single +text cluster. A text cluster is a minimal +mapping of some glyphs corresponding to some UTF-8 text.

For a cluster to be valid, both num_bytes + and num_glyphs + should +be non-negative, and at least one should be non-zero. +Note that clusters with zero glyphs are not as well supported as +normal clusters. For example, PDF rendering applications typically +ignore those clusters when PDF text is being selected.

See cairo_show_text_glyphs() for how clusters are used in advanced +text operations.

Members

+++++ + + + + + + + + + + + + +

int `num_bytes`;	the number of bytes of UTF-8 text covered by cluster
int `num_glyphs`;	the number of glyphs covered by cluster

Since: 1.8

enum cairo_text_cluster_flags_t

Specifies properties of a text cluster mapping.

Members

+++++ + + + + + +

CAIRO_TEXT_CLUSTER_FLAG_BACKWARD

The clusters in the cluster array +map to glyphs in the glyph array from end to start. (Since 1.8)

Since: 1.8

text

Functions

Types and Values

Description

Functions

cairo_select_font_face ()

Parameters

cairo_set_font_size ()

Parameters

cairo_set_font_matrix ()

Parameters

cairo_get_font_matrix ()

Parameters

cairo_set_font_options ()

Parameters

cairo_get_font_options ()

Parameters

cairo_set_font_face ()

Parameters

cairo_get_font_face ()

Parameters

Returns

cairo_set_scaled_font ()

Parameters

cairo_get_scaled_font ()

Parameters

Returns

cairo_show_text ()

Parameters

cairo_show_glyphs ()

Parameters

cairo_show_text_glyphs ()

Parameters

cairo_font_extents ()

Parameters

cairo_text_extents ()

Parameters

cairo_glyph_extents ()

Parameters

cairo_toy_font_face_create ()

Parameters

Returns

cairo_toy_font_face_get_family ()

Parameters

Returns

cairo_toy_font_face_get_slant ()

Parameters

Returns

cairo_toy_font_face_get_weight ()

Parameters

Returns

cairo_glyph_allocate ()

Parameters

Returns

cairo_glyph_free ()

Parameters

cairo_text_cluster_allocate ()

Parameters

Returns

cairo_text_cluster_free ()

Parameters

Types and Values

cairo_glyph_t

Members

enum cairo_font_slant_t

Members

enum cairo_font_weight_t

Members

cairo_text_cluster_t

Members

enum cairo_text_cluster_flags_t

Members

See Also