Main Page Widgets Namespaces Book

# Pango::Context Class Reference

Inheritance diagram for Pango::Context:

[legend]
List of all members.

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

## Public Member Functions

virtual | ~Context ()
PangoContext* | gobj ()
| Provides access to the underlying C GObject.
const PangoContext* | gobj () const
| Provides access to the underlying C GObject.
PangoContext* | gobj_copy ()
| Provides access to the underlying C instance. The caller is responsible for unrefing it. Use when directly setting fields in structs.
Glib::ArrayHandle< Glib::RefPtr< FontFamily > > | list_families () const
| List all available font families for a context.
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 .
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 .
FontMetrics | get_metrics (const FontDescription& desc) const
| Get overall metric information for a particular font description.
FontMetrics | get_metrics (const FontDescription& desc, const Language& language) const
| Get overall metric information for a font particular font description.
void | set_font_description (const FontDescription& desc)
| Set the default font description for the context.
FontDescription | get_font_description () const
| Retrieve the default font description for the context.
Language | get_language () const
| Retrieves the global language tag for the context.
void | set_language (const Language& language)
| Sets the global language tag for the context.
void | set_base_dir (Direction direction)
| Sets the base direction for the context.
Direction | get_base_dir () const
| Retrieves the base direction for the context.
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.
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.

## Protected Member Functions

| Context ()

## Related Functions

(Note that these are not member functions.)
Glib::RefPtr<Pango::Context> | wrap (PangoContext* object, bool take_copy=false)

## Constructor & Destructor Documentation

virtual Pango::Context::~Context | ( |  | ) | `[virtual]`

Pango::Context::Context | ( |  | ) | `[protected]`

## Member Function Documentation

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

Retrieves the base direction for the context.

See pango_context_set_base_dir().

Returns:
  The base direction for the context.

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.

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

Retrieves the global language tag for the context.

Returns:
  The global language tag.

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.

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.

const PangoContext* Pango::Context::gobj | ( |  | ) | const`[inline]`

| Provides access to the underlying C GObject. Reimplemented from Glib::ObjectBase.

PangoContext* Pango::Context::gobj | ( |  | ) | `[inline]`

| Provides access to the underlying C GObject. Reimplemented from Glib::ObjectBase.

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.

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.

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.

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.

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 font loaded, or `0` if no font matched.

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 fontset, or `0` if no font matched.

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.

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

Set the default font description for the context.

Parameters:

  | desc | The new pango font description.

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

Sets the global language tag for the context.

Parameters:

  | language | The new language tag.

## Friends And Related Function Documentation

Glib::RefPtr<Pango::Context> wrap | ( | PangoContext* | object,
|  | bool | take_copy = `false`
| ) | `[related]`

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.

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

- context.h