pangomm: Pango::FontDescription Class Reference

pangomm 2.46.4

Public Member Functions | Static Public Member Functions | Protected Attributes | Related Symbols | List of all members
Pango::FontDescription Class Reference

A Pango::FontDescription represents the description of an ideal font. More...

`#include <pangomm/fontdescription.h>`

## Public Member Functions
| FontDescription ()
| FontDescription (PangoFontDescription * gobject, bool make_a_copy=true)
| FontDescription (const FontDescription & other)
FontDescription & | operator= (const FontDescription & other)
| FontDescription (FontDescription && other) noexcept
FontDescription & | operator= (FontDescription && other) noexcept
| ~FontDescription () noexcept
void | swap (FontDescription & other) noexcept
PangoFontDescription * | gobj ()
| Provides access to the underlying C instance.
const PangoFontDescription * | gobj () const
| Provides access to the underlying C instance.
PangoFontDescription * | gobj_copy () const
| Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.
| FontDescription (const Glib::ustring & font_name)
| Constructs a font description from a string representation.
guint | hash () const
| Computes a hash of a Pango::FontDescription structure suitable to be used, for example, as an argument to Glib::hash_table_new().
void | set_family (const Glib::ustring & family)
| Sets the family name field of a font description.
Glib::ustring | get_family () const
| Gets the family name field of a font description.
void | set_style (Style style)
| Sets the style field of a Pango::FontDescription.
Style | get_style () const
| Gets the style field of a Pango::FontDescription.
void | set_variant (Variant variant)
| Sets the variant field of a font description.
Variant | get_variant () const
| Gets the variant field of a Pango::FontDescription.
void | set_weight (Weight weight)
| Sets the weight field of a font description.
Weight | get_weight () const
| Gets the weight field of a font description.
void | set_stretch (Stretch stretch)
| Sets the stretch field of a font description.
Stretch | get_stretch () const
| Gets the stretch field of a font description.
void | set_size (int size)
| Sets the size field of a font description in fractional points.
int | get_size () const
| Gets the size field of a font description.
void | set_absolute_size (double size)
| Sets the size field of a font description, in device units.
bool | get_size_is_absolute () const
| Determines whether the size of the font is in points (not absolute) or device units (absolute).
void | set_gravity (Gravity gravity)
| Sets the gravity field of a font description.
Gravity | get_gravity () const
| Gets the gravity field of a font description.
void | set_variations (const Glib::ustring & settings)
| Sets the variations field of a font description.
Glib::ustring | get_variations () const
| Gets the variations field of a font description.
FontMask | get_set_fields () const
| Determines which fields in a font description have been set.
void | unset_fields (FontMask to_unset)
| Unsets some of the fields in a Pango::FontDescription.
void | merge (const FontDescription & desc_to_merge, bool replace_existing)
| Merges the fields that are set in desc_to_merge into the fields in desc.
bool | better_match (const FontDescription & old_match, const FontDescription & new_match) const
| Determines if the style attributes of new_match are a closer match for desc than those of old_match are, or if old_match is nullptr, determines if new_match is a match at all.
Glib::ustring | to_string () const
| Creates a string representation of a font description.
Glib::ustring | to_filename () const
| Creates a filename representation of a font description.

## Static Public Member Functions
static GType | get_type ()
| Get the GType for this class, for use with the underlying GObject type system.

## Protected Attributes
PangoFontDescription * | gobject_

## Related Symbols
(Note that these are not member symbols.)
bool | operator== (const FontDescription & lhs, const FontDescription & rhs)
bool | operator!= (const FontDescription & lhs, const FontDescription & rhs)
void | swap (FontDescription & lhs, FontDescription & rhs) noexcept
Pango::FontDescription | wrap (PangoFontDescription * object, bool take_copy=false)
| A Glib::wrap() method for this object.

## Detailed Description

A Pango::FontDescription represents the description of an ideal font.

It is used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

## Constructor & Destructor Documentation

## ◆ FontDescription() [1/5]

Pango::FontDescription::FontDescription | ( |  | ) |

## ◆ FontDescription() [2/5]

Pango::FontDescription::FontDescription | ( | PangoFontDescription * | gobject,
|  | bool | make_a_copy = true )
| explicit

## ◆ FontDescription() [3/5]

Pango::FontDescription::FontDescription | ( | const FontDescription & | other | ) |

## ◆ FontDescription() [4/5]

Pango::FontDescription::FontDescription | ( | FontDescription && | other | ) |
| noexcept

## ◆ ~FontDescription()

Pango::FontDescription::~FontDescription | ( |  | ) |
| noexcept

## ◆ FontDescription() [5/5]

Pango::FontDescription::FontDescription | ( | const Glib::ustring & | font_name | ) |
| explicit

Constructs a font description from a string representation.

font_name must have the form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a comma separated list of families optionally terminated by a comma, STYLE_OPTIONS is a whitespace separated list of words where each WORD describes one of style, variant, weight, or stretch, and SIZE is an decimal number (size in points). Any one of the options may be absent. If FAMILY-LIST is absent, then the family_name field of the resulting font description will be initialized to 0. If STYLE-OPTIONS is missing, then all style options will be set to the default values. If SIZE is missing, the size in the resulting font description will be set to 0.

Parameters

  font_name | String representation of a font description.

## Member Function Documentation

## ◆ better_match()

bool Pango::FontDescription::better_match | ( | const FontDescription & | old_match,
|  | const FontDescription & | new_match ) const

Determines if the style attributes of new_match are a closer match for desc than those of old_match are, or if old_match is nullptr, determines if new_match is a match at all.

Approximate matching is done for weight and style; other style attributes must match exactly. Style attributes are all attributes other than family and size-related attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE and PANGO_STYLE_ITALIC as matches, but not as good a match as when the styles are equal.

Note that old_match must match desc.

Parameters

  old_match | A Pango::FontDescription, or nullptr.
  new_match | A Pango::FontDescription.

Returns
  true if new_match is a better match.

## ◆ get_family()

Glib::ustring Pango::FontDescription::get_family | ( |  | ) | const

Gets the family name field of a font description.

See set_family().

Returns
  The family name field for the font description, or nullptr if not previously set. This has the same life-time as the font description itself and should not be freed.

## ◆ get_gravity()

Gravity Pango::FontDescription::get_gravity | ( |  | ) | const

Gets the gravity field of a font description.

See set_gravity().

Since pangomm 1.16

Returns
  The gravity field for the font description. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ get_set_fields()

FontMask Pango::FontDescription::get_set_fields | ( |  | ) | const

Determines which fields in a font description have been set.

Returns
  A bitmask with bits set corresponding to the fields in desc that have been set.

## ◆ get_size()

int Pango::FontDescription::get_size | ( |  | ) | const

Gets the size field of a font description.

See set_size().

Returns
  The size field for the font description in points or device units. You must call get_size_is_absolute() to find out which is the case. Returns 0 if the size field has not previously been set or it has been set to 0 explicitly. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ get_size_is_absolute()

bool Pango::FontDescription::get_size_is_absolute | ( |  | ) | const

Determines whether the size of the font is in points (not absolute) or device units (absolute).

See set_size() and set_absolute_size().

Since pangomm 1.8

Returns
  Whether the size for the font description is in points or device units. Use get_set_fields() to find out if the size field of the font description was explicitly set or not.

## ◆ get_stretch()

Stretch Pango::FontDescription::get_stretch | ( |  | ) | const

Gets the stretch field of a font description.

See set_stretch().

Returns
  The stretch field for the font description. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ get_style()

Style Pango::FontDescription::get_style | ( |  | ) | const

Gets the style field of a Pango::FontDescription.

See set_style().

Returns
  The style field for the font description. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ get_type()

GType Pango::FontDescription::get_type | ( |  | ) |
| static

Get the GType for this class, for use with the underlying GObject type system.

## ◆ get_variant()

Variant Pango::FontDescription::get_variant | ( |  | ) | const

Gets the variant field of a Pango::FontDescription.

See set_variant().

Returns
  The variant field for the font description. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ get_variations()

Glib::ustring Pango::FontDescription::get_variations | ( |  | ) | const

Gets the variations field of a font description.

See set_variations().

Since pangomm 1.42

Returns
  The varitions field for the font description, or nullptr if not previously set. This has the same life-time as the font description itself and should not be freed.

## ◆ get_weight()

Weight Pango::FontDescription::get_weight | ( |  | ) | const

Gets the weight field of a font description.

See set_weight().

Returns
  The weight field for the font description. Use get_set_fields() to find out if the field was explicitly set or not.

## ◆ gobj() [1/2]

PangoFontDescription * Pango::FontDescription::gobj | ( |  | ) |
| inline

Provides access to the underlying C instance.

## ◆ gobj() [2/2]

const PangoFontDescription * Pango::FontDescription::gobj | ( |  | ) | const
| inline

Provides access to the underlying C instance.

## ◆ gobj_copy()

PangoFontDescription * Pango::FontDescription::gobj_copy | ( |  | ) | const

Provides access to the underlying C instance. The caller is responsible for freeing it. Use when directly setting fields in structs.

## ◆ hash()

guint Pango::FontDescription::hash | ( |  | ) | const

Computes a hash of a Pango::FontDescription structure suitable to be used, for example, as an argument to Glib::hash_table_new().

The hash value is independent of desc->mask.

Returns
  The hash value.

## ◆ merge()

void Pango::FontDescription::merge | ( | const FontDescription & | desc_to_merge,
|  | bool | replace_existing )

Merges the fields that are set in desc_to_merge into the fields in desc.

If replace_existing is false, only fields in desc that are not already set are affected. If true, then fields that are already set will be replaced as well.

If desc_to_merge is nullptr, this function performs nothing.

Parameters

  desc_to_merge | The Pango::FontDescription to merge from, or nullptr.
  replace_existing | If true, replace fields in desc with the corresponding values from desc_to_merge, even if they are already exist.

## ◆ operator=() [1/2]

FontDescription & Pango::FontDescription::operator= | ( | const FontDescription & | other | ) |

## ◆ operator=() [2/2]

FontDescription & Pango::FontDescription::operator= | ( | FontDescription && | other | ) |
| noexcept

## ◆ set_absolute_size()

void Pango::FontDescription::set_absolute_size | ( | double | size | ) |

Sets the size field of a font description, in device units.

This is mutually exclusive with set_size() which sets the font size in points.

Since pangomm 1.8

Parameters

  size | The new size, in Pango units. There are Pango::SCALE Pango units in one device unit. For an output backend where a device unit is a pixel, a size value of 10 * PANGO_SCALE gives a 10 pixel font.

## ◆ set_family()

void Pango::FontDescription::set_family | ( | const Glib::ustring & | family | ) |

Sets the family name field of a font description.

The family name represents a family of related font styles, and will resolve to a particular Pango::FontFamily. In some uses of Pango::FontDescription, it is also possible to use a comma separated list of family names for this field.

Parameters

  family | A string representing the family name.

## ◆ set_gravity()

void Pango::FontDescription::set_gravity | ( | Gravity | gravity | ) |

Sets the gravity field of a font description.

The gravity field specifies how the glyphs should be rotated. If gravity is Pango::GRAVITY_AUTO, this actually unsets the gravity mask on the font description.

This function is seldom useful to the user. Gravity should normally be set on a Pango::Context.

Since pangomm 1.16

Parameters

  gravity | The gravity for the font description.

## ◆ set_size()

void Pango::FontDescription::set_size | ( | int | size | ) |

Sets the size field of a font description in fractional points.

This is mutually exclusive with set_absolute_size().

Parameters

  size | The size of the font in points, scaled by PANGO_SCALE. (That is, a size value of 10 * PANGO_SCALE is a 10 point font. The conversion factor between points and device units depends on system configuration and the output device. For screen display, a logical DPI of 96 is common, in which case a 10 point font corresponds to a 10 * (96 / 72) = 13.3 pixel font. Use set_absolute_size() if you need a particular size in device units.

## ◆ set_stretch()

void Pango::FontDescription::set_stretch | ( | Stretch | stretch | ) |

Sets the stretch field of a font description.

The stretch field specifies how narrow or wide the font should be.

Parameters

  stretch | The stretch for the font description.

## ◆ set_style()

void Pango::FontDescription::set_style | ( | Style | style | ) |

Sets the style field of a Pango::FontDescription.

The Pango::Style enumeration describes whether the font is slanted and the manner in which it is slanted; it can be either Pango::STYLE_NORMAL, Pango::STYLE_ITALIC, or Pango::STYLE_OBLIQUE. Most fonts will either have a italic style or an oblique style, but not both, and font matching in Pango will match italic specifications with oblique fonts and vice-versa if an exact match is not found.

Parameters

  style | The style for the font description.

## ◆ set_variant()

void Pango::FontDescription::set_variant | ( | Variant | variant | ) |

Sets the variant field of a font description.

The Pango::Variant can either be Pango::VARIANT_NORMAL or Pango::VARIANT_SMALL_CAPS.

Parameters

  variant | The variant type for the font description.

## ◆ set_variations()

void Pango::FontDescription::set_variations | ( | const Glib::ustring & | settings | ) |

Sets the variations field of a font description.

OpenType font variations allow to select a font instance by specifying values for a number of axes, such as width or weight.

The format of the variations string is AXIS1=VALUE,AXIS2=VALUE..., with each AXIS a 4 character tag that identifies a font axis, and each VALUE a floating point number. Unknown axes are ignored, and values are clamped to their allowed range.

Pango does not currently have a way to find supported axes of a font. Both harfbuzz or freetype have API for this.

Since pangomm 1.42

Parameters

  settings | A string representing the variations.

## ◆ set_weight()

void Pango::FontDescription::set_weight | ( | Weight | weight | ) |

Sets the weight field of a font description.

The weight field specifies how bold or light the font should be. In addition to the values of the Pango::Weight enumeration, other intermediate numeric values are possible.

Parameters

  weight | The weight for the font description.

## ◆ swap()

void Pango::FontDescription::swap | ( | FontDescription & | other | ) |
| noexcept

## ◆ to_filename()

Glib::ustring Pango::FontDescription::to_filename | ( |  | ) | const

Creates a filename representation of a font description.

The filename is identical to the result from calling to_string(), but with underscores instead of characters that are untypical in filenames, and in lower case only.

Returns
  The filename.

## ◆ to_string()

Glib::ustring Pango::FontDescription::to_string | ( |  | ) | const

Creates a string representation of a font description.

See from_string() for a description of the format of the string representation. The family list in the string description will only have a terminating comma if the last word of the list is a valid style option.

Returns
  The string.

## ◆ unset_fields()

void Pango::FontDescription::unset_fields | ( | FontMask | to_unset | ) |

Unsets some of the fields in a Pango::FontDescription.

The unset fields will get back to their default values.

Parameters

  to_unset | Bitmask of fields in the desc to unset.

## Friends And Related Symbol Documentation

## ◆ operator!=()

bool operator!= | ( | const FontDescription & | lhs,
|  | const FontDescription & | rhs )
| related

Parameters

  lhs | The left-hand side
  rhs | The right-hand side

Returns
  The result

## ◆ operator==()

bool operator== | ( | const FontDescription & | lhs,
|  | const FontDescription & | rhs )
| related

Parameters

  lhs | The left-hand side
  rhs | The right-hand side

Returns
  The result

## ◆ swap()

void swap | ( | FontDescription & | lhs,
|  | FontDescription & | rhs )
| related

Parameters

  lhs | The left-hand side
  rhs | The right-hand side

## ◆ wrap()

Pango::FontDescription wrap | ( | PangoFontDescription * | object,
|  | bool | take_copy = false )
| related

A Glib::wrap() method for this object.

Parameters

  object | The C instance.
  take_copy | False if the result should take ownership of the C instance. True if it should take a new copy or ref.

Returns
  A C++ instance that wraps this C instance.

## Member Data Documentation

## ◆ gobject_

PangoFontDescription* Pango::FontDescription::gobject_
| protected