| jpayne@68: Top jpayne@68: | jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68: |
jpayne@68:
jpayne@68: textjpayne@68:text — Rendering text and glyphs jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_select_font_face () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_set_font_size () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_set_font_matrix () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_get_font_matrix () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_set_font_options () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_get_font_options () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_set_font_face () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_face_t * jpayne@68: | jpayne@68:jpayne@68: cairo_get_font_face () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_set_scaled_font () jpayne@68: | jpayne@68:
| jpayne@68: cairo_scaled_font_t * jpayne@68: | jpayne@68:jpayne@68: cairo_get_scaled_font () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_show_text () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_show_glyphs () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_show_text_glyphs () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_font_extents () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_text_extents () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_glyph_extents () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_face_t * jpayne@68: | jpayne@68:jpayne@68: cairo_toy_font_face_create () jpayne@68: | jpayne@68:
| const char * jpayne@68: | jpayne@68:jpayne@68: cairo_toy_font_face_get_family () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_slant_t jpayne@68: | jpayne@68:jpayne@68: cairo_toy_font_face_get_slant () jpayne@68: | jpayne@68:
| jpayne@68: cairo_font_weight_t jpayne@68: | jpayne@68:jpayne@68: cairo_toy_font_face_get_weight () jpayne@68: | jpayne@68:
| jpayne@68: cairo_glyph_t * jpayne@68: | jpayne@68:jpayne@68: cairo_glyph_allocate () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_glyph_free () jpayne@68: | jpayne@68:
| jpayne@68: cairo_text_cluster_t * jpayne@68: | jpayne@68:jpayne@68: cairo_text_cluster_allocate () jpayne@68: | jpayne@68:
| jpayne@68: void jpayne@68: | jpayne@68:jpayne@68: cairo_text_cluster_free () jpayne@68: | jpayne@68:
| jpayne@68: | cairo_glyph_t | jpayne@68:
| enum | jpayne@68:cairo_font_slant_t | jpayne@68:
| enum | jpayne@68:cairo_font_weight_t | jpayne@68:
| jpayne@68: | cairo_text_cluster_t | jpayne@68:
| enum | jpayne@68:cairo_text_cluster_flags_t | jpayne@68:
The functions with text in their name form cairo's jpayne@68: toy text API. The toy API takes UTF-8 encoded jpayne@68: text and is limited in its functionality to rendering simple jpayne@68: left-to-right text with no advanced features. That means for example jpayne@68: that most complex scripts like Hebrew, Arabic, and Indic scripts are jpayne@68: out of question. No kerning or correct positioning of diacritical marks jpayne@68: either. The font selection is pretty limited too and doesn't handle the jpayne@68: case that the selected font does not cover the characters in the text. jpayne@68: This set of functions are really that, a toy text API, for testing and jpayne@68: demonstration purposes. Any serious application should avoid them.
jpayne@68:The functions with glyphs in their name form cairo's jpayne@68: low-level text API. The low-level API relies on jpayne@68: the user to convert text to a set of glyph indexes and positions. This jpayne@68: is a very hard problem and is best handled by external libraries, like jpayne@68: the pangocairo that is part of the Pango text layout and rendering library. jpayne@68: Pango is available from http://www.pango.org/.
jpayne@68:void jpayne@68: cairo_select_font_face (jpayne@68:cairo_t *cr, jpayne@68:const char *family, jpayne@68:cairo_font_slant_t slant, jpayne@68:cairo_font_weight_t weight);
Note: The cairo_select_font_face() function call is part of what
jpayne@68: the cairo designers call the "toy" text API. It is convenient for
jpayne@68: short demos and simple programs, but it is not expected to be
jpayne@68: adequate for serious text-using applications.
Selects a family and style of font from a simplified description as jpayne@68: a family name, slant and weight. Cairo provides no operation to jpayne@68: list available family names on the system (this is a "toy", jpayne@68: remember), but the standard CSS2 generic family names, ("serif", jpayne@68: "sans-serif", "cursive", "fantasy", "monospace"), are likely to jpayne@68: work as expected.
jpayne@68:If family
jpayne@68: starts with the string "cairo
jpayne@68: :", or if no native font
jpayne@68: backends are compiled in, cairo will use an internal font family.
jpayne@68: The internal font family recognizes many modifiers in the family
jpayne@68:
jpayne@68: string, most notably, it recognizes the string "monospace". That is,
jpayne@68: the family name "cairo
jpayne@68: :monospace" will use the monospace version of
jpayne@68: the internal font family.
For "real" font selection, see the font-backend-specific
jpayne@68: font_face_create functions for the font backend you are using. (For
jpayne@68: example, if you are using the freetype-based cairo-ft font backend,
jpayne@68: see cairo_ft_font_face_create_for_ft_face() or
jpayne@68: cairo_ft_font_face_create_for_pattern().) The resulting font face
jpayne@68: could then be used with cairo_scaled_font_create() and
jpayne@68: cairo_set_scaled_font().
Similarly, when using the "real" font support, you can call jpayne@68: directly into the underlying font system, (such as fontconfig or jpayne@68: freetype), for operations such as listing available fonts, etc.
jpayne@68:It is expected that most applications will need to use a more jpayne@68: comprehensive font handling and text layout library, (for example, jpayne@68: pango), in conjunction with cairo.
jpayne@68:If text is drawn without a call to cairo_select_font_face(), (nor
jpayne@68: cairo_set_font_face() nor cairo_set_scaled_font()), the default
jpayne@68: family is platform-specific, but is essentially "sans-serif".
jpayne@68: Default slant is CAIRO_FONT_SLANT_NORMAL, and default weight is
jpayne@68: CAIRO_FONT_WEIGHT_NORMAL.
This function is equivalent to a call to cairo_toy_font_face_create()
jpayne@68: followed by cairo_set_font_face().
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
family |
jpayne@68: a font family name, encoded in UTF-8 |
jpayne@68: jpayne@68: |
slant |
jpayne@68: the slant for the font |
jpayne@68: jpayne@68: |
weight |
jpayne@68: the weight for the font |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_set_font_size (jpayne@68:cairo_t *cr, jpayne@68:double size);
Sets the current font matrix to a scale by a factor of size
jpayne@68: , replacing
jpayne@68: any font matrix previously set with cairo_set_font_size() or
jpayne@68: cairo_set_font_matrix(). This results in a font size of size
jpayne@68: user space
jpayne@68: units. (More precisely, this matrix will result in the font's
jpayne@68: em-square being a size
jpayne@68: by size
jpayne@68: square in user space.)
If text is drawn without a call to cairo_set_font_size(), (nor
jpayne@68: cairo_set_font_matrix() nor cairo_set_scaled_font()), the default
jpayne@68: font size is 10.0.
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
size |
jpayne@68: the new font size, in user space units |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_set_font_matrix (jpayne@68:cairo_t *cr, jpayne@68:const cairo_matrix_t *matrix);
Sets the current font matrix to matrix
jpayne@68: . The font matrix gives a
jpayne@68: transformation from the design space of the font (in this space,
jpayne@68: the em-square is 1 unit by 1 unit) to user space. Normally, a
jpayne@68: simple scale is used (see cairo_set_font_size()), but a more
jpayne@68: complex font matrix can be used to shear the font
jpayne@68: or stretch it unequally along the two axes
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
matrix |
jpayne@68: a cairo_matrix_t describing a transform to be applied to jpayne@68: the current font. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_get_font_matrix (jpayne@68:cairo_t *cr, jpayne@68:cairo_matrix_t *matrix);
Stores the current font matrix into matrix
jpayne@68: . See
jpayne@68: cairo_set_font_matrix().
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
matrix |
jpayne@68: return value for the matrix |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_set_font_options (jpayne@68:cairo_t *cr, jpayne@68:const cairo_font_options_t *options);
Sets a set of custom font rendering options for the cairo_t.
jpayne@68: Rendering options are derived by merging these options with the
jpayne@68: options derived from underlying surface; if the value in options
jpayne@68:
jpayne@68: has a default value (like CAIRO_ANTIALIAS_DEFAULT), then the value
jpayne@68: from the surface is used.
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
options |
jpayne@68: font options to use |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_get_font_options (jpayne@68:cairo_t *cr, jpayne@68:cairo_font_options_t *options);
Retrieves font rendering options set via cairo_set_font_options.
jpayne@68: Note that the returned options do not include any options derived
jpayne@68: from the underlying surface; they are literally the options
jpayne@68: passed to cairo_set_font_options().
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
options |
jpayne@68: a cairo_font_options_t object into which to store jpayne@68: the retrieved options. All existing values are overwritten |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_set_font_face (jpayne@68:cairo_t *cr, jpayne@68:cairo_font_face_t *font_face);
Replaces the current cairo_font_face_t object in the cairo_t with
jpayne@68: font_face
jpayne@68: . The replaced font face in the cairo_t will be
jpayne@68: destroyed if there are no other references to it.
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
font_face |
jpayne@68: a cairo_font_face_t, or |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_font_face_t *
jpayne@68: cairo_get_font_face (cairo_t *cr);
jpayne@68: Gets the current font face for a cairo_t.
jpayne@68:cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
the current font face. This object is owned by
jpayne@68: cairo. To keep a reference to it, you must call
jpayne@68: cairo_font_face_reference().
This function never returns NULL. If memory cannot be allocated, a
jpayne@68: special "nil" cairo_font_face_t object will be returned on which
jpayne@68: cairo_font_face_status() returns CAIRO_STATUS_NO_MEMORY. Using
jpayne@68: this nil object will cause its error state to propagate to other
jpayne@68: objects it is passed to, (for example, calling
jpayne@68: cairo_set_font_face() with a nil font will trigger an error that
jpayne@68: will shutdown the cairo_t object).
Since: 1.0
jpayne@68:void jpayne@68: cairo_set_scaled_font (jpayne@68:cairo_t *cr, jpayne@68:const cairo_scaled_font_t *scaled_font);
Replaces the current font face, font matrix, and font options in
jpayne@68: the cairo_t with those of the cairo_scaled_font_t. Except for
jpayne@68: some translation, the current CTM of the cairo_t should be the
jpayne@68: same as that of the cairo_scaled_font_t, which can be accessed
jpayne@68: using cairo_scaled_font_get_ctm().
cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
scaled_font |
jpayne@68: jpayne@68: | jpayne@68: |
Since: 1.2
jpayne@68:cairo_scaled_font_t *
jpayne@68: cairo_get_scaled_font (cairo_t *cr);
jpayne@68: Gets the current scaled font for a cairo_t.
jpayne@68:cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
the current scaled font. This object is owned by
jpayne@68: cairo. To keep a reference to it, you must call
jpayne@68: cairo_scaled_font_reference().
This function never returns NULL. If memory cannot be allocated, a
jpayne@68: special "nil" cairo_scaled_font_t object will be returned on which
jpayne@68: cairo_scaled_font_status() returns CAIRO_STATUS_NO_MEMORY. Using
jpayne@68: this nil object will cause its error state to propagate to other
jpayne@68: objects it is passed to, (for example, calling
jpayne@68: cairo_set_scaled_font() with a nil font will trigger an error that
jpayne@68: will shutdown the cairo_t object).
Since: 1.4
jpayne@68:void jpayne@68: cairo_show_text (jpayne@68:cairo_t *cr, jpayne@68:const char *utf8);
A drawing operator that generates the shape from a string of UTF-8 jpayne@68: characters, rendered according to the current font_face, font_size jpayne@68: (font_matrix), and font_options.
jpayne@68:This function first computes a set of glyphs for the string of jpayne@68: text. The first glyph is placed so that its origin is at the jpayne@68: current point. The origin of each subsequent glyph is offset from jpayne@68: that of the previous glyph by the advance values of the previous jpayne@68: glyph.
jpayne@68:After this call the current point is moved to the origin of where
jpayne@68: the next glyph would be placed in this same progression. That is,
jpayne@68: the current point will be at the origin of the final glyph offset
jpayne@68: by its advance values. This allows for easy display of a single
jpayne@68: logical string with multiple calls to cairo_show_text().
Note: The cairo_show_text() function call is part of what the cairo
jpayne@68: designers call the "toy" text API. It is convenient for short demos
jpayne@68: and simple programs, but it is not expected to be adequate for
jpayne@68: serious text-using applications. See cairo_show_glyphs() for the
jpayne@68: "real" text display API in cairo.
cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: a NUL-terminated string of text encoded in UTF-8, or |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_show_glyphs (jpayne@68:cairo_t *cr, jpayne@68:const cairo_glyph_t *glyphs, jpayne@68:int num_glyphs);
A drawing operator that generates the shape from an array of glyphs, jpayne@68: rendered according to the current font face, font size jpayne@68: (font matrix), and font options.
jpayne@68:cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
glyphs |
jpayne@68: array of glyphs to show |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: number of glyphs to show |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_show_text_glyphs (jpayne@68:cairo_t *cr, jpayne@68:const char *utf8, jpayne@68:int utf8_len, jpayne@68:const cairo_glyph_t *glyphs, jpayne@68:int num_glyphs, jpayne@68:const cairo_text_cluster_t *clusters, jpayne@68:int num_clusters, jpayne@68:cairo_text_cluster_flags_t cluster_flags);
This operation has rendering effects similar to cairo_show_glyphs()
jpayne@68: but, if the target surface supports it, uses the provided text and
jpayne@68: cluster mapping to embed the text for the glyphs shown in the output.
jpayne@68: If the target does not support the extended attributes, this function
jpayne@68: acts like the basic cairo_show_glyphs() as if it had been passed
jpayne@68: glyphs
jpayne@68: and num_glyphs
jpayne@68: .
The mapping between utf8
jpayne@68: and glyphs
jpayne@68: is provided by an array of
jpayne@68: clusters. Each cluster covers a number of
jpayne@68: text bytes and glyphs, and neighboring clusters cover neighboring
jpayne@68: areas of utf8
jpayne@68: and glyphs
jpayne@68: . The clusters should collectively cover utf8
jpayne@68:
jpayne@68: and glyphs
jpayne@68: in entirety.
The first cluster always covers bytes from the beginning of utf8
jpayne@68: .
jpayne@68: If cluster_flags
jpayne@68: do not have the CAIRO_TEXT_CLUSTER_FLAG_BACKWARD
jpayne@68: set, the first cluster also covers the beginning
jpayne@68: of glyphs
jpayne@68: , otherwise it covers the end of the glyphs
jpayne@68: array and
jpayne@68: following clusters move backward.
See cairo_text_cluster_t for constraints on valid clusters.
jpayne@68:cr |
jpayne@68: a cairo context |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: a string of text encoded in UTF-8 |
jpayne@68: jpayne@68: |
utf8_len |
jpayne@68: length of |
jpayne@68: jpayne@68: |
glyphs |
jpayne@68: array of glyphs to show |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: number of glyphs to show |
jpayne@68: jpayne@68: |
clusters |
jpayne@68: array of cluster mapping information |
jpayne@68: jpayne@68: |
num_clusters |
jpayne@68: number of clusters in the mapping |
jpayne@68: jpayne@68: |
cluster_flags |
jpayne@68: cluster mapping flags |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:void jpayne@68: cairo_font_extents (jpayne@68:cairo_t *cr, jpayne@68:cairo_font_extents_t *extents);
Gets the font extents for the currently selected font.
jpayne@68:cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
extents |
jpayne@68: a cairo_font_extents_t object into which the results jpayne@68: will be stored. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_text_extents (jpayne@68:cairo_t *cr, jpayne@68:const char *utf8, jpayne@68:cairo_text_extents_t *extents);
Gets the extents for a string of text. The extents describe a
jpayne@68: user-space rectangle that encloses the "inked" portion of the text,
jpayne@68: (as it would be drawn by cairo_show_text()). Additionally, the
jpayne@68: x_advance and y_advance values indicate the amount by which the
jpayne@68: current point would be advanced by cairo_show_text().
Note that whitespace characters do not directly contribute to the jpayne@68: size of the rectangle (extents.width and extents.height). They do jpayne@68: contribute indirectly by changing the position of non-whitespace jpayne@68: characters. In particular, trailing whitespace characters are jpayne@68: likely to not affect the size of the rectangle, though they will jpayne@68: affect the x_advance and y_advance values.
jpayne@68:cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
utf8 |
jpayne@68: a NUL-terminated string of text encoded in UTF-8, or |
jpayne@68: jpayne@68: |
extents |
jpayne@68: a cairo_text_extents_t object into which the results jpayne@68: will be stored |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:void jpayne@68: cairo_glyph_extents (jpayne@68:cairo_t *cr, jpayne@68:const cairo_glyph_t *glyphs, jpayne@68:int num_glyphs, jpayne@68:cairo_text_extents_t *extents);
Gets the extents for an array of glyphs. The extents describe a
jpayne@68: user-space rectangle that encloses the "inked" portion of the
jpayne@68: glyphs, (as they would be drawn by cairo_show_glyphs()).
jpayne@68: Additionally, the x_advance and y_advance values indicate the
jpayne@68: amount by which the current point would be advanced by
jpayne@68: cairo_show_glyphs().
Note that whitespace glyphs do not contribute to the size of the jpayne@68: rectangle (extents.width and extents.height).
jpayne@68:cr |
jpayne@68: a cairo_t |
jpayne@68: jpayne@68: |
glyphs |
jpayne@68: an array of cairo_glyph_t objects |
jpayne@68: jpayne@68: |
num_glyphs |
jpayne@68: the number of elements in |
jpayne@68: jpayne@68: |
extents |
jpayne@68: a cairo_text_extents_t object into which the results jpayne@68: will be stored |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:cairo_font_face_t * jpayne@68: cairo_toy_font_face_create (jpayne@68:const char *family, jpayne@68:cairo_font_slant_t slant, jpayne@68:cairo_font_weight_t weight);
Creates a font face from a triplet of family, slant, and weight. jpayne@68: These font faces are used in implementation of the the cairo_t "toy" jpayne@68: font API.
jpayne@68:If family
jpayne@68: is the zero-length string "", the platform-specific default
jpayne@68: family is assumed. The default family then can be queried using
jpayne@68: cairo_toy_font_face_get_family().
The cairo_select_font_face() function uses this to create font faces.
jpayne@68: See that function for limitations and other details of toy font faces.
family |
jpayne@68: a font family name, encoded in UTF-8 |
jpayne@68: jpayne@68: |
slant |
jpayne@68: the slant for the font |
jpayne@68: jpayne@68: |
weight |
jpayne@68: the weight for the font |
jpayne@68: jpayne@68: |
a newly created cairo_font_face_t. Free with
jpayne@68: cairo_font_face_destroy() when you are done using it.
Since: 1.8
jpayne@68:const char *
jpayne@68: cairo_toy_font_face_get_family (cairo_font_face_t *font_face);
jpayne@68: Gets the familly name of a toy font.
jpayne@68:font_face |
jpayne@68: A toy font face |
jpayne@68: jpayne@68: |
The family name. This string is owned by the font face jpayne@68: and remains valid as long as the font face is alive (referenced).
jpayne@68:Since: 1.8
jpayne@68:cairo_font_slant_t
jpayne@68: cairo_toy_font_face_get_slant (cairo_font_face_t *font_face);
jpayne@68: Gets the slant a toy font.
jpayne@68:font_face |
jpayne@68: A toy font face |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_font_weight_t
jpayne@68: cairo_toy_font_face_get_weight (cairo_font_face_t *font_face);
jpayne@68: Gets the weight a toy font.
jpayne@68:font_face |
jpayne@68: A toy font face |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_glyph_t *
jpayne@68: cairo_glyph_allocate (int num_glyphs);
jpayne@68: Allocates an array of cairo_glyph_t's. jpayne@68: This function is only useful in implementations of jpayne@68: cairo_user_scaled_font_text_to_glyphs_func_t where the user jpayne@68: needs to allocate an array of glyphs that cairo will free. jpayne@68: For all other uses, user can use their own allocation method jpayne@68: for glyphs.
jpayne@68:This function returns NULL if num_glyphs
jpayne@68: is not positive,
jpayne@68: or if out of memory. That means, the NULL return value
jpayne@68: signals out-of-memory only if num_glyphs
jpayne@68: was positive.
num_glyphs |
jpayne@68: number of glyphs to allocate |
jpayne@68: jpayne@68: |
the newly allocated array of glyphs that should be
jpayne@68: freed using cairo_glyph_free()
Since: 1.8
jpayne@68:void
jpayne@68: cairo_glyph_free (cairo_glyph_t *glyphs);
jpayne@68: Frees an array of cairo_glyph_t's allocated using cairo_glyph_allocate().
jpayne@68: This function is only useful to free glyph array returned
jpayne@68: by cairo_scaled_font_text_to_glyphs() where cairo returns
jpayne@68: an array of glyphs that the user will free.
jpayne@68: For all other uses, user can use their own allocation method
jpayne@68: for glyphs.
glyphs |
jpayne@68: array of glyphs to free, or |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_text_cluster_t *
jpayne@68: cairo_text_cluster_allocate (int num_clusters);
jpayne@68: Allocates an array of cairo_text_cluster_t's. jpayne@68: This function is only useful in implementations of jpayne@68: cairo_user_scaled_font_text_to_glyphs_func_t where the user jpayne@68: needs to allocate an array of text clusters that cairo will free. jpayne@68: For all other uses, user can use their own allocation method jpayne@68: for text clusters.
jpayne@68:This function returns NULL if num_clusters
jpayne@68: is not positive,
jpayne@68: or if out of memory. That means, the NULL return value
jpayne@68: signals out-of-memory only if num_clusters
jpayne@68: was positive.
num_clusters |
jpayne@68: number of text_clusters to allocate |
jpayne@68: jpayne@68: |
the newly allocated array of text clusters that should be
jpayne@68: freed using cairo_text_cluster_free()
Since: 1.8
jpayne@68:void
jpayne@68: cairo_text_cluster_free (cairo_text_cluster_t *clusters);
jpayne@68: Frees an array of cairo_text_cluster's allocated using cairo_text_cluster_allocate().
jpayne@68: This function is only useful to free text cluster array returned
jpayne@68: by cairo_scaled_font_text_to_glyphs() where cairo returns
jpayne@68: an array of text clusters that the user will free.
jpayne@68: For all other uses, user can use their own allocation method
jpayne@68: for text clusters.
clusters |
jpayne@68: array of text clusters to free, or |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:typedef struct {
jpayne@68: unsigned long index;
jpayne@68: double x;
jpayne@68: double y;
jpayne@68: } cairo_glyph_t;
jpayne@68:
jpayne@68: The cairo_glyph_t structure holds information about a single glyph jpayne@68: when drawing or measuring text. A font is (in simple terms) a jpayne@68: collection of shapes used to draw text. A glyph is one of these jpayne@68: shapes. There can be multiple glyphs for a single character jpayne@68: (alternates to be used in different contexts, for example), or a jpayne@68: glyph can be a ligature of multiple jpayne@68: characters. Cairo doesn't expose any way of converting input text jpayne@68: into glyphs, so in order to use the Cairo interfaces that take jpayne@68: arrays of glyphs, you must directly access the appropriate jpayne@68: underlying font system.
jpayne@68:Note that the offsets given by x
jpayne@68: and y
jpayne@68: are not cumulative. When
jpayne@68: drawing or measuring text, each glyph is individually positioned
jpayne@68: with respect to the overall origin
| jpayne@68: | glyph index in the font. The exact interpretation of the jpayne@68: glyph index depends on the font technology being used. |
jpayne@68: jpayne@68: |
| jpayne@68: | the offset in the X direction between the origin used for jpayne@68: drawing or measuring the string and the origin of this glyph. |
jpayne@68: jpayne@68: |
| jpayne@68: | the offset in the Y direction between the origin used for jpayne@68: drawing or measuring the string and the origin of this glyph. |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:Specifies variants of a font face based on their slant.
jpayne@68:| jpayne@68: |
jpayne@68: Upright font style, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: Italic font style, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: Oblique font style, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:Specifies variants of a font face based on their weight.
jpayne@68:| jpayne@68: |
jpayne@68: Normal font weight, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
| jpayne@68: |
jpayne@68: Bold font weight, since 1.0 jpayne@68: |
jpayne@68: jpayne@68: |
Since: 1.0
jpayne@68:typedef struct {
jpayne@68: int num_bytes;
jpayne@68: int num_glyphs;
jpayne@68: } cairo_text_cluster_t;
jpayne@68:
jpayne@68: The cairo_text_cluster_t structure holds information about a single jpayne@68: text cluster. A text cluster is a minimal jpayne@68: mapping of some glyphs corresponding to some UTF-8 text.
jpayne@68:For a cluster to be valid, both num_bytes
jpayne@68: and num_glyphs
jpayne@68: should
jpayne@68: be non-negative, and at least one should be non-zero.
jpayne@68: Note that clusters with zero glyphs are not as well supported as
jpayne@68: normal clusters. For example, PDF rendering applications typically
jpayne@68: ignore those clusters when PDF text is being selected.
See cairo_show_text_glyphs() for how clusters are used in advanced
jpayne@68: text operations.
| jpayne@68: | the number of bytes of UTF-8 text covered by cluster |
jpayne@68: jpayne@68: |
| jpayne@68: | the number of glyphs covered by cluster |
jpayne@68: jpayne@68: |
Since: 1.8
jpayne@68:cairo_font_face_t, cairo_scaled_font_t, cairo_text_path(),
jpayne@68: cairo_glyph_path()