pango.Context
Prev | The pango Class Reference | Next

## pango.Context

pango.Context — stores global information used to control rendering.

## Synopsis

    class pango.Context(gobject.GObject):
        pango.Context()
        def get_font_map()
        def set_font_map(font_map)
        def list_families()
        def load_font(desc)
        def load_fontset(desc, language)
        def get_metrics(desc, language)
        def set_font_description(desc)
        def get_font_description()
        def get_language()
        def set_language(language)
        def set_base_dir(direction)
        def get_base_dir()

## Ancestry

    +-- gobject.GObject
      +-- pango.Context

## Description

A `pango.Context` object contains global information used to control the rendering process. The information accessible using the `pango.Context` methods includes:

- the default `pango.FontDescription`
- the default `pango.Language`
- the base direction of the text

A `pango.Context` can be created with the `gtk.Widget.create_pango_context`() method. The `pango.Context` associated with a `gtk.Widget` is retrieved using the `gtk.Widget.get_pango_context`()) method.

## Constructor

        pango.Context()

Returns : | a new `pango.Context` without an associated font map

### Note

Constructor is available in PyGTK 2.16 and above.

Creates a new PangoContext initialized to default values.

This constructor is not particularly useful as it should always be followed by a call to set_font_map method. Method pango.FontMap.create_context does these two steps together and hence users are recommended to use that.

If you are using Pango as part of a higher-level system, that system may have it's own way of create a pango.Context. For instance, the GTK+ toolkit has, among others, gtk.gdk.pango_context_get_for_screen and gtk.Widget.get_pango_context. Use those instead.

## Methods

### pango.Context.get_font_map

        def get_font_map()

Returns : | the font map for the `pango.Context`.

### pango.Context.get_font_map

        def set_font_map(font_map)

`font_map` : | the `pango.FontMap` to set object

### Note

This method is available in PyGTK 2.16 and above.

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.

### pango.Context.list_families

        def list_families()

Returns : | a tuple containing a set of `pango.FontFamily` objects.

The `list_families`() method returns a tuple containing the list of all the `pango.FontFamily` objects for a context.

### pango.Context.load_font

        def load_font(desc)

`desc` : | a `pango.FontDescription` describing the font to load
Returns : | the `pango.Font` loaded, or `None` if no font matched.

The `load_font`() method loads and returns the `pango.Font` from one of the fontmaps in the context that is the closest match for the `pango.FontDescription` specified by `desc`.

### pango.Context.load_fontset

        def load_fontset(desc, language)

`desc` : | a `pango.FontDescription` describing the fonts to load
`language` : | a `pango.Language` the fonts will be used for
Returns : | the `pango.FontSet`, or `None` if no font matched.

The `load_fontset`() method loads and returns a set of fonts (in a `pango.FontSet`) from the context that can be used to render a font matching the `pango.FontDescription` specified by `desc` with the `pango.Language` specified by `language`.

### pango.Context.get_metrics

        def get_metrics(desc, language)

`desc` : | a `pango.FontDescription` object
`language` : | the `pango.Language` that determines the script to get the metrics for, or `None` to get the metrics for the entire font.
Returns : | a `pango.FontMetrics` object.

The `get_metrics`() method returns the overall metric information for the font described by the `pango.FontDescription` specified by `desc`. Since the metrics may be substantially different for different scripts, a `pango.Language` (specified by `language`) can be provided to indicate that the metrics should correspond to the script(s) used by that language. If the value of `language` is `None`, the returned `pango.FontMetrics` covers the entire font.

The family name in the `pango.FontDescription` may be a comma separated list of families. 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.

### pango.Context.set_font_description

        def set_font_description(desc)

`desc` : | a `pango.FontDescription` object

The `set_font_description`() method sets the default `pango.FontDescription` (specified by `desc`) for the context.

### pango.Context.get_font_description

        def get_font_description()

Returns : | the default font description of the context.

The `get_font_description`() method returns the default `pango.FontDescription` for the context.

### pango.Context.get_language

        def get_language()

Returns : | the global `pango.Language`.

The `get_language`() method returns the global `pango.Language` for the context.

### pango.Context.set_language

        def set_language(language)

`language` : | a `pango.Language`.

The `set_language`() method sets the global `pango.Language` for the context to the value specified by `language`.

### pango.Context.set_base_dir

        def set_base_dir(direction)

`direction` : | the new base direction

The `set_base_dir`() method sets the base text direction for the context to the value specified by `direction`. The value of `direction` must be one of:

`pango.DIRECTION_LTR` | The text is written left-to-right
`pango.DIRECTION_RTL` | The text is written right-to-left
`pango.DIRECTION_TTB_LTR` | The text is written vertically top-to-bottom, with the rows ordered from left to right.
`pango.DIRECTION_TTB_RTL` | The text is written vertically top-to-bottom, with the rows ordered from right to left.

### pango.Context.get_base_dir

        def get_base_dir()

Returns : | the base direction for the context.

The `get_base_dir`() method returns the base text direction for the context. See the `set_base_dir`() method for more information.

Prev | Up | Next
pango.Color | Home | pango.Font