pangomm: Pango::Context Class Reference

pangomm 2.40.1

Public Member Functions | Static Public Member Functions | Protected Member Functions | Related Functions | List of all members
Pango::Context Class Reference

A Pango::Context stores global information used to control the itemization process. More...

`#include <pangomm/context.h>`

Inheritance diagram for Pango::Context:
[legend]

## Public Member Functions
| Context (Context&& src) noexcept
Context& | operator= (Context&& src) noexcept
| ~Context () noexcept override
PangoContext* | gobj ()
| Provides access to the underlying C GObject. More...
const PangoContext* | gobj () const
| Provides access to the underlying C GObject. More...
PangoContext* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs. More...
Glib::ArrayHandle< Glib::RefPtr< FontFamily > > | list_families () const
| List all available font families for a context. More...
void | set_font_map (const Glib::RefPtr< FontMap >& font_map)
| Sets the font map to be searched when fonts are looked-up in this context. More...
Glib::RefPtr< FontMap > | get_font_map ()
| Gets the Pango::FontMap used to look up fonts for this context. More...
Glib::RefPtr< const FontMap > | get_font_map () const
| Gets the Pango::FontMap used to look up fonts for this context. More...
guint | get_serial () const
| Returns the current serial number of context. More...
Glib::RefPtr< Font > | load_font (const FontDescription& desc) const
| Loads the font in one of the fontmaps in the context that is the closest match for desc. More...
Glib::RefPtr< Fontset > | load_fontset (const FontDescription& desc, const Language& language) const
| Load a set of fonts in the context that can be used to render a font matching desc. More...
FontMetrics | get_metrics (const FontDescription& desc) const
| Get overall metric information for a particular font description. More...
FontMetrics | get_metrics (const FontDescription& desc, const Language& language) const
| Get overall metric information for a font particular font description. More...
void | set_font_description (const FontDescription& desc)
| Set the default font description for the context. More...
FontDescription | get_font_description () const
| Retrieve the default font description for the context. More...
Language | get_language () const
| Retrieves the global language tag for the context. More...
void | set_language (const Language& language)
| Sets the global language tag for the context. More...
void | set_base_dir (Direction direction)
| Sets the base direction for the context. More...
Direction | get_base_dir () const
| Retrieves the base direction for the context. More...
void | set_base_gravity (Gravity gravity)
| Sets the base gravity for the context. More...
Gravity | get_base_gravity () const
| Retrieves the base gravity for the context. More...
Gravity | get_gravity () const
| Retrieves the gravity for the context. More...
void | set_gravity_hint (GravityHint hint)
| Sets the gravity hint for the context. More...
GravityHint | get_gravity_hint () const
| Retrieves the gravity hint for the context. More...
void | set_matrix (const Matrix& matrix)
| Sets the transformation matrix that will be applied when rendering with this context. More...
Matrix | get_matrix () const
ListHandle_Item | itemize (const Glib::ustring& text, const AttrList& attrs) const
| Breaks a piece of text into segments with consistent directional level and shaping engine. More...
ListHandle_Item | itemize (const Glib::ustring& text, int start_index, int length, const AttrList& attrs, AttrIter& cached_iter) const
| Breaks a piece of text into segments with consistent directional level and shaping engine. More...
void | update_from_cairo_context (const Cairo::RefPtr< Cairo::Context >& context)
| Updates a Pango Context previously created for use with Cairo to match the current transformation and target surface of a Cairo Context. More...
void | set_cairo_font_options (const Cairo::FontOptions& options)
| Sets the font options used when rendering text with this context. More...
Cairo::FontOptions | get_font_options () const
| Retrieves any font rendering options previously set with pango_cairo_context_set_font_options(). More...
void | set_resolution (double dpi)
| Sets the resolution for the context. More...
double | get_resolution () const
| Gets the resolution for the context. More...
Public Member Functions inherited from Glib::Object
| Object (const Object &)=delete
Object & | operator= (const Object &)=delete
| Object (Object &&src) noexcept
Object & | operator= (Object &&src) noexcept
void * | get_data (const QueryQuark &key)
void | set_data (const Quark &key, void *data)
void | set_data (const Quark &key, void *data, DestroyNotify notify)
void | remove_data (const QueryQuark &quark)
void * | steal_data (const QueryQuark &quark)
Glib::RefPtr< Glib::Object > | wrap (GObject *object, bool take_copy=false)
Public Member Functions inherited from Glib::ObjectBase
| ObjectBase (const ObjectBase &)=delete
ObjectBase & | operator= (const ObjectBase &)=delete
void | set_property_value (const Glib::ustring &property_name, const Glib::ValueBase &value)
void | get_property_value (const Glib::ustring &property_name, Glib::ValueBase &value) const
void | set_property (const Glib::ustring &property_name, const PropertyType &value)
void | get_property (const Glib::ustring &property_name, PropertyType &value) const
void | connect_property_changed (const Glib::ustring &property_name, const sigc::slot< void > &slot)
void | connect_property_changed (const Glib::ustring &property_name, sigc::slot< void > &&slot)
sigc::connection | connect_property_changed_with_return (const Glib::ustring &property_name, const sigc::slot< void > &slot)
sigc::connection | connect_property_changed_with_return (const Glib::ustring &property_name, sigc::slot< void > &&slot)
void | freeze_notify ()
void | thaw_notify ()
virtual void | reference () const
virtual void | unreference () const
GObject * | gobj ()
const GObject * | gobj () const
GObject * | gobj_copy () const
Public Member Functions inherited from sigc::trackable
| trackable () noexcept
| trackable (const trackable &src) noexcept
| trackable (trackable &&src)
| ~trackable ()
void | add_destroy_notify_callback (void *data, func_destroy_notify func) const
void | notify_callbacks ()
trackable & | operator= (const trackable &src)
trackable & | operator= (trackable &&src)
void | remove_destroy_notify_callback (void *data) const

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

## Protected Member Functions
| Context ()
Protected Member Functions inherited from Glib::Object
| Object ()
| Object (const Glib::ConstructParams &construct_params)
| Object (GObject *castitem)
| ~Object () noexcept override
Protected Member Functions inherited from Glib::ObjectBase
| ObjectBase ()
| ObjectBase (const char *custom_type_name)
| ObjectBase (const std::type_info &custom_type_info)
| ObjectBase (ObjectBase &&src) noexcept
ObjectBase & | operator= (ObjectBase &&src) noexcept
virtual | ~ObjectBase () noexcept=0
void | initialize (GObject *castitem)
void | initialize_move (GObject *castitem, Glib::ObjectBase *previous_wrapper)

## Related Functions
(Note that these are not member functions.)
Glib::RefPtr< Pango::Context > | wrap (PangoContext* object, bool take_copy=false)
| A Glib::wrap() method for this object. More...

## Additional Inherited Members
Public Types inherited from Glib::Object
typedef void(*)(gpointer data | DestroyNotify)
Public Types inherited from sigc::trackable
typedef internal::func_destroy_notify | func_destroy_notify

## Detailed Description

A Pango::Context stores global information used to control the itemization process.

You can retrieve a Pango::Context object with Gtk::Widget::create_pango_context() or Gtk::Widget::get_pango_context(). If you don't use gtkmm call some c function of the pango backend you intend to use and create a wrapper for the returned context, e.g. Glib::wrap(pango_x_get_context()).

Creating a Pango::Context object is the starting point of every rendering process. You can either use it to create a high level Pango::Layout object which does all the hard work for you by passing it into Pango::Layout::create() or to generate glyph strings from character strings with the help of itemize() and Pango::Item::shape() subsequently.

Which fonts are used for rendering can be influenced by setting the default font description, language and base direction of the context.

If you want to calculate the space some text will need to be displayed you might find the functions of Pango::FontMetrics useful. Use get_metrics() to obtain the Pango::FontMetrics object for a specific Pango::FontDescription. For more detailed calculations in a rendering-system-independant manner and to determine whether specific characters can be represented by the font that would be used for a specific Pango::FontDescription load a Pango::Fontset with load_fontset() (load_font() returns the Pango::Font that is the closest match for a Pango::FontDescription; however that's not necessarily the font that will be used for rendering).

## Constructor & Destructor Documentation

## ◆ Context() [1/2]

Pango::Context::Context | ( | Context&& | src | ) |
| noexcept

## ◆ ~Context()

Pango::Context::~Context | ( |  | ) |
| overridenoexcept

## ◆ Context() [2/2]

Pango::Context::Context | ( |  | ) |
| protected

## Member Function Documentation

## ◆ get_base_dir()

Direction Pango::Context::get_base_dir | ( |  | ) | const

Retrieves the base direction for the context.

See set_base_dir().

Returns
  The base direction for the context.

## ◆ get_base_gravity()

Gravity Pango::Context::get_base_gravity | ( |  | ) | const

Retrieves the base gravity for the context.

See set_base_gravity().

Since pangomm 1.16:

Returns
  The base gravity for the context.

## ◆ get_font_description()

FontDescription Pango::Context::get_font_description | ( |  | ) | const

Retrieve the default font description for the context.

Returns
  A pointer to the context's default font description. This value must not be modified or freed.

## ◆ get_font_map() [1/2]

Glib::RefPtr<FontMap> Pango::Context::get_font_map | ( |  | ) |

Gets the Pango::FontMap used to look up fonts for this context.

Since pangomm 1.6:

Returns
  The font map for the Pango::Context. This value is owned by Pango and should not be unreferenced.

## ◆ get_font_map() [2/2]

Glib::RefPtr<const FontMap> Pango::Context::get_font_map | ( |  | ) | const

Gets the Pango::FontMap used to look up fonts for this context.

Since pangomm 1.6:

Returns
  The font map for the Pango::Context. This value is owned by Pango and should not be unreferenced.

## ◆ get_font_options()

Cairo::FontOptions Pango::Context::get_font_options | ( |  | ) | const

Retrieves any font rendering options previously set with pango_cairo_context_set_font_options().

This function does not report options that are derived from the target surface by pango_cairo_update_context()

Since pangomm 1.10:

Returns
  The font options previously set on the context, or `nullptr` if no options have been set. This value is owned by the context and must not be modified or freed.

## ◆ get_gravity()

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

Retrieves the gravity for the context.

This is similar to get_base_gravity(), except for when the base gravity is Pango::GRAVITY_AUTO for which pango_gravity_get_for_matrix() is used to return the gravity from the current context matrix.

Since pangomm 1.16:

Returns
  The resolved gravity for the context.

## ◆ get_gravity_hint()

GravityHint Pango::Context::get_gravity_hint | ( |  | ) | const

Retrieves the gravity hint for the context.

See set_gravity_hint() for details.

Since pangomm 1.16:

Returns
  The gravity hint for the context.

## ◆ get_language()

Language Pango::Context::get_language | ( |  | ) | const

Retrieves the global language tag for the context.

Returns
  The global language tag.

## ◆ get_matrix()

Matrix Pango::Context::get_matrix | ( |  | ) | const

## ◆ get_metrics() [1/2]

FontMetrics Pango::Context::get_metrics | ( | const FontDescription& | desc | ) | const

Get overall metric information for a particular font description.

The metrics may be substantially different for different scripts. However this function overload returns the metrics of the entire font.

Parameters

  desc | A Pango::FontDescription object.

Returns
  A Pango::FontMetrics object.

## ◆ get_metrics() [2/2]

FontMetrics Pango::Context::get_metrics | ( | const FontDescription& | desc,
|  | const Language& | language
| ) |  | const

Get overall metric information for a font particular font description.

Since the metrics may be substantially different for different scripts, a language tag can be provided to indicate that the metrics should be retrieved that correspond to the script(s) used by that language.

The Pango::FontDescription is interpreted in the same way as by pango_itemize(), and the family name may be a comma separated list of figures. If characters from multiple of these families would be used to render the string, then the returned fonts would be a composite of the metrics for the fonts loaded for the individual families.

Parameters

  desc | A Pango::FontDescription structure.
  language | Language tag used to determine which script to get the metrics for.

Returns
  A Pango::Metrics object.

## ◆ get_resolution()

double Pango::Context::get_resolution | ( |  | ) | const

Gets the resolution for the context.

See pango_cairo_context_set_resolution()

Since pangomm 1.10:

Returns
  The resolution in "dots per inch". A negative value will be returned if no resolution has previously been set.

## ◆ get_serial()

guint Pango::Context::get_serial | ( |  | ) | const

Returns the current serial number of context.

The serial number is initialized to an small number larger than zero when a new context is created and is increased whenever the context is changed using any of the setter functions, or the Pango::FontMap it uses to find fonts has changed. The serial may wrap, but will never have the value 0. Since it can wrap, never compare it with "less than", always use "not equals".

This can be used to automatically detect changes to a Pango::Context, and is only useful when implementing objects that need update when their Pango::Context changes, like Pango::Layout.

Since pangomm 1.32.4:

Returns
  The current serial number of context.

## ◆ get_type()

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

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

## ◆ gobj() [1/2]

PangoContext* Pango::Context::gobj | ( |  | ) |
| inline

Provides access to the underlying C GObject.

## ◆ gobj() [2/2]

const PangoContext* Pango::Context::gobj | ( |  | ) | const
| inline

Provides access to the underlying C GObject.

## ◆ gobj_copy()

PangoContext* Pango::Context::gobj_copy | ( |  | ) |

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

## ◆ itemize() [1/2]

ListHandle_Item Pango::Context::itemize | ( | const Glib::ustring & | text,
|  | const AttrList& | attrs
| ) |  | const

Breaks a piece of text into segments with consistent directional level and shaping engine.

Each byte of text will be contained in exactly one of the items in the returned list. The generated list of items will be in logical order (the start offsets of the items are ascending).

Parameters

  text | The text to itemize.
  attrs | The set of attributes that apply.

Returns
  A list of Pango::Item objects.

## ◆ itemize() [2/2]

ListHandle_Item Pango::Context::itemize | ( | const Glib::ustring & | text,
|  | int | start_index,
|  | int | length,
|  | const AttrList& | attrs,
|  | AttrIter& | cached_iter
| ) |  | const

Breaks a piece of text into segments with consistent directional level and shaping engine.

Each byte of text will be contained in exactly one of the items in the returned list. The generated list of items will be in logical order (the start offsets of the items are ascending).

cached_iter should be an iterator over attrs currently positioned at a range before or containing start_index. cached_iter will be advanced to the range covering the position just after start_index + length. (i.e. if itemizing in a loop, just keep passing in the same cached_iter).

Parameters

  text | The text to itemize.
  start_index | First byte in text to process.
  length | The number of bytes (not characters) to process after start_index. This must be >= `0`.
  attrs | The set of attributes that apply to text.
  cached_iter | Cached attribute iterator.

Returns
  A list of Pango::Item structures.

## ◆ list_families()

Glib::ArrayHandle< Glib::RefPtr<FontFamily> > Pango::Context::list_families | ( |  | ) | const

List all available font families for a context.

You can specify one of these as your desired font family in the Pango::FontDesciption objects you use, e.g. in the default font description of the context.

Returns
  An array of Pango::FontFamily objects.

## ◆ load_font()

Glib::RefPtr<Font> Pango::Context::load_font | ( | const FontDescription& | desc | ) | const

Loads the font in one of the fontmaps in the context that is the closest match for desc.

Parameters

  desc | A Pango::FontDescription describing the font to load.

Returns
  The newly allocated Pango::Font that was loaded, or `nullptr` if no font matched.

## ◆ load_fontset()

Glib::RefPtr<Fontset> Pango::Context::load_fontset | ( | const FontDescription& | desc,
|  | const Language& | language
| ) |  | const

Load a set of fonts in the context that can be used to render a font matching desc.

Parameters

  desc | A Pango::FontDescription describing the fonts to load.
  language | A Pango::Language the fonts will be used for.

Returns
  The newly allocated Pango::Fontset loaded, or `nullptr` if no font matched.

## ◆ operator=()

Context& Pango::Context::operator= | ( | Context&& | src | ) |
| noexcept

## ◆ set_base_dir()

void Pango::Context::set_base_dir | ( | Direction | direction | ) |

Sets the base direction for the context.

The base direction is used in applying the Unicode bidirectional algorithm; if the direction is Pango::DIRECTION_LTR or Pango::DIRECTION_RTL, then the value will be used as the paragraph direction in the Unicode bidirectional algorithm. A value of Pango::DIRECTION_WEAK_LTR or Pango::DIRECTION_WEAK_RTL is used only for paragraphs that do not contain any strong characters themselves.

Parameters

  direction | The new base direction.

## ◆ set_base_gravity()

void Pango::Context::set_base_gravity | ( | Gravity | gravity | ) |

Sets the base gravity for the context.

The base gravity is used in laying vertical text out.

Since pangomm 1.16:

Parameters

  gravity | The new base gravity.

## ◆ set_cairo_font_options()

void Pango::Context::set_cairo_font_options | ( | const Cairo::FontOptions & | options | ) |

Sets the font options used when rendering text with this context.

These options override any options that pango_cairo_update_context() derives from the target surface.

Since pangomm 1.10:

Parameters

  options | A #cairo_font_options_t, or `nullptr` to unset any previously set options. A copy is made.

## ◆ set_font_description()

void Pango::Context::set_font_description | ( | const FontDescription& | desc | ) |

Set the default font description for the context.

Parameters

  desc | The new pango font description.

## ◆ set_font_map()

void Pango::Context::set_font_map | ( | const Glib::RefPtr< FontMap >& | font_map | ) |

Sets the font map to be searched when fonts are looked-up in this context.

This is only for internal use by Pango backends, a Pango::Context obtained via one of the recommended methods should already have a suitable font map.

Parameters

  font_map | The Pango::FontMap to set.

## ◆ set_gravity_hint()

void Pango::Context::set_gravity_hint | ( | GravityHint | hint | ) |

Sets the gravity hint for the context.

The gravity hint is used in laying vertical text out, and is only relevant if gravity of the context as returned by get_gravity() is set Pango::GRAVITY_EAST or Pango::GRAVITY_WEST.

Since pangomm 1.16:

Parameters

  hint | The new gravity hint.

## ◆ set_language()

void Pango::Context::set_language | ( | const Language& | language | ) |

Sets the global language tag for the context.

The default language for the locale of the running process can be found using Pango::Language::get_default().

Parameters

  language | The new language tag.

## ◆ set_matrix()

void Pango::Context::set_matrix | ( | const Matrix& | matrix | ) |

Sets the transformation matrix that will be applied when rendering with this context.

Note that reported metrics are in the user space coordinates before the application of the matrix, not device-space coordinates after the application of the matrix. So, they don't scale with the matrix, though they may change slightly for different matrices, depending on how the text is fit to the pixel grid.

Since pangomm 1.6:

Parameters

  matrix | A Pango::Matrix, or `nullptr` to unset any existing matrix. (No matrix set is the same as setting the identity matrix.).

## ◆ set_resolution()

void Pango::Context::set_resolution | ( | double | dpi | ) |

Sets the resolution for the context.

This is a scale factor between points specified in a Pango::FontDescription and Cairo units. The default value is 96, meaning that a 10 point font will be 13 units high. (10* 96. / 72. = 13.3).

Since pangomm 1.10:

Parameters

  dpi | The resolution in "dots per inch". (Physical inches aren't actually involved; the terminology is conventional.) A 0 or negative value means to use the resolution from the font map.

## ◆ update_from_cairo_context()

void Pango::Context::update_from_cairo_context | ( | const Cairo::RefPtr< Cairo::Context > & | context | ) |

Updates a Pango Context previously created for use with Cairo to match the current transformation and target surface of a Cairo Context.

If any layouts have been created for the context, it's necessary to call Pango::Layout::context_changed() on those layouts.

Parameters

  context | A Cairo context, from CairoFontMap::create_context().

## Friends And Related Function Documentation

## ◆ wrap()

Glib::RefPtr< Pango::Context > wrap | ( | PangoContext * | 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.