# Cairo::ScaledFont Class Reference

A ScaledFont is a font scaled to a particular size and device resolution. More...

Inheritance diagram for Cairo::ScaledFont:
[legend]

List of all members.

## Public Types

typedef cairo_scaled_font_t | cobject
| The underlying C cairo object type.

## Public Member Functions

cobject* | cobj ()
| Provides acces to the underlying C cairo object.
const cobject* | cobj () const
| Provides acces to the underlying C cairo object.
| ScaledFont (cobject* cobj, bool has_reference=false)
| Create a C++ wrapper object from the C instance.
virtual | ~ScaledFont ()
void | get_extents (FontExtents& extents) const
| Gets the metrics for a ScaledFont.
void | extents (FontExtents& extents) const
void | get_text_extents (const std::string& utf8, TextExtents& extents) const
| Gets the extents for a string of text.
void | text_extents (const std::string& utf8, TextExtents& extents) const
void | get_glyph_extents (const std::vector< Glyph >& glyphs, TextExtents& extents)
| Gets the extents for an array of glyphs.
void | glyph_extents (const std::vector< Glyph >& glyphs, TextExtents& extents)
RefPtr< FontFace > | get_font_face () const
| The FontFace with which this ScaledFont was created.
void | get_font_options (FontOptions& options) const
| Gets the FontOptions with which the ScaledFont was created.
void | get_font_matrix (Matrix& font_matrix) const
| Gets the font matrix with which the ScaledFont was created.
void | get_font_matrix (cairo_matrix_t& font_matrix) const
void | get_ctm (Matrix& ctm) const
| Gets the CTM with which the ScaledFont was created.
void | get_ctm (cairo_matrix_t& ctm) const
FontType | get_type () const
| Gets the type of scaled Font.
void | text_to_glyphs (double x, double y, const std::string& utf8, std::vector< Glyph >& glyphs, std::vector< TextCluster >& clusters, TextClusterFlags& cluster_flags)
void | get_scale_matrix (Matrix& scale_matrix) const
| Stores the scale matrix of this scaled font into matrix.

## Static Public Member Functions

static RefPtr< ScaledFont > | create (const RefPtr< FontFace >& font_face, const Matrix& font_matrix, const Matrix& ctm, const FontOptions& options=FontOptions())
| Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.
static RefPtr< ScaledFont > | create (const RefPtr< FontFace >& font_face, const cairo_matrix_t& font_matrix, const cairo_matrix_t& ctm, const FontOptions& options=FontOptions())

## Protected Member Functions

| ScaledFont (const RefPtr< FontFace >& font_face, const cairo_matrix_t& font_matrix, const cairo_matrix_t& ctm, const FontOptions& options=FontOptions())

## Protected Attributes

cobject* | m_cobject
| The underlying C cairo object that is wrapped by this ScaledFont.

## Detailed Description

A ScaledFont is a font scaled to a particular size and device resolution.

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

## Member Typedef Documentation

typedef cairo_scaled_font_t Cairo::ScaledFont::cobject

The underlying C cairo object type.

## Constructor & Destructor Documentation

Cairo::ScaledFont::ScaledFont | ( | cobject* | cobj,
|  | bool | has_reference = `false`
| ) |  | `[explicit]`

Create a C++ wrapper object from the C instance.

This C++ object should then be given to a RefPtr.

virtual Cairo::ScaledFont::~ScaledFont | ( |  | ) | `[virtual]`

Cairo::ScaledFont::ScaledFont | ( | const RefPtr< FontFace >& | font_face,
|  | const cairo_matrix_t& | font_matrix,
|  | const cairo_matrix_t& | ctm,
|  | const FontOptions& | options = `FontOptions()`
| ) |  | `[protected]`

## Member Function Documentation

cobject* Cairo::ScaledFont::cobj | ( |  | ) | `[inline]`

Provides acces to the underlying C cairo object.

const cobject* Cairo::ScaledFont::cobj | ( |  | ) | const`[inline]`

Provides acces to the underlying C cairo object.

static RefPtr<ScaledFont> Cairo::ScaledFont::create | ( | const RefPtr< FontFace >& | font_face,
|  | const cairo_matrix_t& | font_matrix,
|  | const cairo_matrix_t& | ctm,
|  | const FontOptions& | options = `FontOptions()`
| ) |  | `[static]`

static RefPtr<ScaledFont> Cairo::ScaledFont::create | ( | const RefPtr< FontFace >& | font_face,
|  | const Matrix& | font_matrix,
|  | const Matrix& | ctm,
|  | const FontOptions& | options = `FontOptions()`
| ) |  | `[static]`

Creates a ScaledFont object from a font face and matrices that describe the size of the font and the environment in which it will be used.

Parameters:

  font_face | A font face.
  font_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. See Context::set_font_matrix().
  ctm | user to device transformation matrix with which the font will be used.
  options | options to use when getting metrics for the font and rendering with it.

void Cairo::ScaledFont::extents | ( | FontExtents& | extents | ) | const

Deprecated:
  Use get_extents() instead

Since:
  1.2

void Cairo::ScaledFont::get_ctm | ( | cairo_matrix_t& | ctm | ) | const

void Cairo::ScaledFont::get_ctm | ( | Matrix& | ctm | ) | const

Gets the CTM with which the ScaledFont was created.

Since:
  1.2

void Cairo::ScaledFont::get_extents | ( | FontExtents& | extents | ) | const

Gets the metrics for a ScaledFont.

Since:
  1.8

RefPtr<FontFace> Cairo::ScaledFont::get_font_face | ( |  | ) | const

The FontFace with which this ScaledFont was created.

Since:
  1.2

void Cairo::ScaledFont::get_font_matrix | ( | Matrix& | font_matrix | ) | const

Gets the font matrix with which the ScaledFont was created.

Since:
  1.2

void Cairo::ScaledFont::get_font_matrix | ( | cairo_matrix_t& | font_matrix | ) | const

void Cairo::ScaledFont::get_font_options | ( | FontOptions& | options | ) | const

Gets the FontOptions with which the ScaledFont was created.

Since:
  1.2

void Cairo::ScaledFont::get_glyph_extents | ( | const std::vector< Glyph >& | glyphs,
|  | TextExtents& | 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 Context::show_glyphs() if the cairo graphics state were set to the same font_face, font_matrix, ctm, and font_options as the ScaledFont object). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context::show_glyphs().

Note that whitespace glyphs do not contribute to the size of the rectangle (extents.width and extents.height).

Parameters:

  glyphs | A vector of glyphs to calculate the extents of.
  extents | Returns the extents for the array of glyphs.

Since:
  1.8

void Cairo::ScaledFont::get_scale_matrix | ( | Matrix& | scale_matrix | ) | const

Stores the scale matrix of this scaled font into 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.

Parameters:

  scale_matrix | return value for the matrix.

Since:
  1.8

void Cairo::ScaledFont::get_text_extents | ( | const std::string & | utf8,
|  | TextExtents& | extents
| ) |  | const

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 the ScaledFont object). Additionally, the x_advance and y_advance values indicate the amount by which the current point would be advanced by Context::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:

  utf8 | a string of text, encoded in UTF-8.
  extents | Returns the extents of the given string.

Since:
  1.8

FontType Cairo::ScaledFont::get_type | ( |  | ) | const

Gets the type of scaled Font.

Since:
  1.2

void Cairo::ScaledFont::glyph_extents | ( | const std::vector< Glyph >& | glyphs,
|  | TextExtents& | extents
| ) |  |

Deprecated:
  Use get_glyph_extents() instead

Since:
  1.2

void Cairo::ScaledFont::text_extents | ( | const std::string & | utf8,
|  | TextExtents& | extents
| ) |  | const

Deprecated:
  Use get_text_extents() instead

Since:
  1.2

void Cairo::ScaledFont::text_to_glyphs | ( | double | x,
|  | double | y,
|  | const std::string & | utf8,
|  | std::vector< Glyph >& | glyphs,
|  | std::vector< TextCluster >& | clusters,
|  | TextClusterFlags& | cluster_flags
| ) |  |

Parameters:

  x | X position to place first glyph.
  y | Y position to place first glyph.
  utf8 | a string of text encoded in UTF-8.
  glyphs | pointer to array of glyphs to fill.
  clusters | pointer to array of cluster mapping information to fill. cluster mapping flags

Converts UTF-8 text to an array 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.

Since:
  1.8

## Member Data Documentation

cobject* Cairo::ScaledFont::m_cobject `[protected]`

The underlying C cairo object that is wrapped by this ScaledFont.

The documentation for this class was generated from the following file:

- cairomm/scaledfont.h