— Function: cairo-select-font-face (cr <cairo-t>) (family <char>) (slant <cairo-font-slant-t>) (weight <cairo-font-weight-t>)

Selects a family and style of font from a simplified description as a family name, slant and weight. This function is meant to be used only for applications with simple font needs: Cairo doesn't provide for operations such as listing all available fonts on the system, and it is expected that most applications will need to use a more comprehensive font handling and text layout library in addition to cairo.

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

— Function: cairo-set-font-size (cr <cairo-t>) (size <double>)

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

cr

a <cairo-t>

size

the new font size, in user space units

— Function: cairo-set-font-matrix (cr <cairo-t>) (matrix <cairo-matrix-t>)

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

cr

a <cairo-t>

matrix

a <cairo-matrix-t> describing a transform to be applied to the current font.

— Function: cairo-get-font-matrix (cr <cairo-t>) (matrix <cairo-matrix-t>)

Stores the current font matrix into matrix. See cairo-set-font-matrix.

cr

a <cairo-t>

matrix

return value for the matrix

— Function: cairo-set-font-options (cr <cairo-t>) (options <cairo-font-options-t>)

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.

cr

a <cairo-t>

options

font options to use

— Function: cairo-get-font-options (cr <cairo-t>) (options <cairo-font-options-t>)

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.

cr

a <cairo-t>

options

a <cairo-font-options-t> object into which to store the retrieved options. All existing values are overwritten

— Function: cairo-set-font-face (cr <cairo-t>) (font-face <cairo-font-face-t>)

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.

cr

a <cairo-t>

font-face

a <cairo-font-face-t>, or `#f' to restore to the default font

— Function: cairo-get-font-face (cr <cairo-t>) =>  (ret <cairo-font-face-t>)

Gets the current font face for a <cairo-t>.

cr

a <cairo-t>

ret

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 `#f'. 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).

— Function: cairo-set-scaled-font (cr <cairo-t>) (scaled-font <cairo-scaled-font-t>)

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.

cr

a <cairo-t>

scaled-font

a <cairo-scaled-font-t>

Since 1.2

— Function: cairo-get-scaled-font (cr <cairo-t>) =>  (ret <cairo-scaled-font-t>)

Gets the current scaled font for a <cairo-t>.

cr

a <cairo-t>

ret

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 `#f'. 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

— Function: cairo-show-text (cr <cairo-t>) (utf8 <char>)

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.

cr

a cairo context

utf8

a string of text encoded in UTF-8

— Function: cairo-show-glyphs (cr <cairo-t>) (glyphs <cairo-glyph-t>) (num-glyphs <int>)

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.

cr

a cairo context

glyphs

array of glyphs to show

num-glyphs

number of glyphs to show

— Function: cairo-font-extents (cr <cairo-t>) (extents <cairo-font-extents-t>)

Gets the font extents for the currently selected font.

cr

a <cairo-t>

extents

a <cairo-font-extents-t> object into which the results will be stored.

— Function: cairo-text-extents (cr <cairo-t>) (utf8 <char>) (extents <cairo-text-extents-t>)

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.

cr

a <cairo-t>

utf8

a string of text, encoded in UTF-8

extents

a <cairo-text-extents-t> object into which the results will be stored

— Function: cairo-glyph-extents (cr <cairo-t>) (glyphs <cairo-glyph-t>) (num-glyphs <int>) (extents <cairo-text-extents-t>)

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

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