pango.FontDescription
Prev | The pango Class Reference | Next

## pango.FontDescription

pango.FontDescription — an object representing a description of a font.

## Synopsis

    class pango.FontDescription(gobject.GBoxed):
        pango.FontDescription(str=None)
        def copy()
        def copy_static()
        def hash()
        def set_family(family)
        def set_family_static(family)
        def get_family()
        def set_style(style)
        def get_style()
        def set_variant(variant)
        def get_variant()
        def set_weight(weight)
        def get_weight()
        def set_stretch(stretch)
        def get_stretch()
        def set_size(size)
        def get_size()
        def get_set_fields()
        def unset_fields(to_unset)
        def merge(desc_to_merge, replace_existing)
        def merge_static(desc_to_merge, replace_existing)
        def better_match(old_match, new_match)
        def to_string()
        def to_filename()
        def set_absolute_size(size)
        def get_size_is_absolute()

## Description

A `pango.FontDescription` represents the description of an ideal font. They are used to both specify the characteristics of a font to load and to list the available fonts on the system.

## Constructor

        pango.FontDescription()

Returns : | a `pango.FontDescription` object.

Creates a new `pango.FontDescription` object from the representation in the string specified by `str`. The format of the string representation is:

      "[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). For example the following are all valid string representations:

      "sans bold 12"
      "serif,monospace bold italic condensed 16"
      "normal 10"

The commonly available font families are: Normal, Sans, Serif and Monospace. The available styles are:

Normal | the font is upright.
Oblique | the font is slanted, but in a roman style.
Italic | the font is slanted in an italic style.

The available weights are:

Ultra-Light | the ultralight weight (= 200)
Light | the light weight (=300)
Normal | the default weight (= 400)
Bold | the bold weight (= 700)
Ultra-Bold | the ultra-bold weight (= 800)
Heavy | the heavy weight (= 900)

The available variants are:

Normal |
Small-Caps |

The available stretch styles are:

Ultra-Condensed | the smallest width
Extra-Condensed |
Condensed |
Semi-Condensed |
Normal | the normal width
Semi-Expanded |
Expanded |
Extra-Expanded |
Ultra-Expanded | the widest width

## Methods

### pango.FontDescription.copy

        def copy()

Returns : | a new `pango.FontDescription`

The `copy`() method returns a new copy of this font description.

### pango.FontDescription.copy_static

        def copy_static()

Returns : | a new `pango.FontDescription`..

The `copy_static`() method is like the `copy`() method, but only a shallow copy is made of the family name and other allocated attribute fields. The result can only be used until the original font description is modified or freed. This is meant to be used when the copy is only needed temporarily.

### pango.FontDescription.hash

        def hash()

Returns : | the hash value.

The `hash`() method computes and returns a hash of the `pango.FontDescription`.

### pango.FontDescription.set_family

        def set_family(family)

`family` : | a string representing the family name.

The `set_family`() method sets the family name attribute field of the font description to the value specified by `family`. 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.

### pango.FontDescription.set_family_static

        def set_family_static(family)

`family` : | a string representing the family name.

The set_family_static() method is like the `set_family`(), except that no copy of `family` is made. The caller must make sure that the string passed in stays around until the font description is no longer needed or the family name is set again. This method can be used if `family` is only needed temporarily.

### pango.FontDescription.get_family

        def get_family()

Returns : | the family name or `None` if not previously set.

The `get_family`() method returns the family name attribute field of the font description. See the `set_family`() method for more information.

### pango.FontDescription.set_style

        def set_style(style)

`style` : | the style for the font description

The `set_style`() method sets the slant style attribute field of the `pango.FontDescription` to the value specified by `style`. The value of `style` must 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.

### pango.FontDescription.get_style

        def get_style()

Returns : | the slant style for the font description.

The `get_style`() method returns the slant style attribute field of the `pango.FontDescription`. See the `set_style`() method for more details. Use the `get_set_fields`() method to find out if the field was explicitly set.

### pango.FontDescription.set_variant

        def set_variant(variant)

`variant` : | the variant type for the font description.

The `set_variant`() method sets the variant attribute field of a font description to the value specified by `variant`. The value of `variant` must be either `pango.VARIANT_NORMAL` or `pango.VARIANT_SMALL_CAPS`.

### pango.FontDescription.get_variant

        def get_variant()

Returns : | the variant style of the font description.

The `get_variant`() method returns the variant style of a `pango.FontDescription`. See the `set_variant`() method for more information. Use the `get_set_fields`() method to find out if the field was explicitly set.

### pango.FontDescription.set_weight

        def set_weight(weight)

`weight` : | the weight for the font description.

The `set_weight`() method sets the weight attribute field of a font description to the value specified by `weight`. The value of `weight` specifies how bold or light the font should be in a range from 100 to 900. The predefined values of weight are:

`pango.WEIGHT_ULTRALIGHT` | the ultralight weight (= 200)
`pango.WEIGHT_LIGHT` | the light weight (=300)
`pango.WEIGHT_NORMAL` | the default weight (= 400)
`pango.WEIGHT_BOLD` | the bold weight (= 700)
`pango.WEIGHT_ULTRABOLD` | the ultrabold weight (= 800)
`pango.WEIGHT_HEAVY` | the heavy weight (= 900)

### pango.FontDescription.get_weight

        def get_weight()

Returns : | the weight field for the font description.

The `get_weight`() method returns the value of the weight attribute of a font description. See the `set_weight`() method for more information. Use the `get_set_fields`() method to determine if the attribute was explicitly set.

### pango.FontDescription.set_stretch

        def set_stretch(stretch)

`stretch` : | the stretch for the font description

The `set_stretch`() method sets the stretch attribute field of a font description to the value specified by `stretch`. The value of `stretch` specifies how narrow or wide the font should be relative to the base width of the font family:

`pango.STRETCH_ULTRA_CONDENSED` | the narrowest width
`pango.STRETCH_EXTRA_CONDENSED` |
`pango.STRETCH_CONDENSED` |
`pango.STRETCH_SEMI_CONDENSED` |
`pango.STRETCH_NORMAL` | the normal (base) width
`pango.STRETCH_SEMI_EXPANDED` |
`pango.STRETCH_EXPANDED` |
`pango.STRETCH_EXTRA_EXPANDED` |
`pango.STRETCH_ULTRA_EXPANDED` | the widest width

### pango.FontDescription.get_stretch

        def get_stretch()

Returns : | the stretch field for the font description

The `get_stretch`() method returns the stretch attribute field of a font description. See the `set_stretch`() method for more details. Use the `get_set_fields`() method to determine if the field was explicitly set.

### pango.FontDescription.set_size

        def set_size(size)

`size` : | the size for the font description in pango units.

The `set_size`() method sets the size attribute field of a font description to the value specified by `size`. The value of `size` is specified in pango units. There are `pango.SCALE` (1024) pango units in one device unit (the device unit is a point for font sizes).

### pango.FontDescription.get_size

        def get_size()

Returns : | the size for the font description in pango units.

The `get_size`() method returns the value of the size attribute field of a font description. See the `get_size`() method for more information. There are `pango.SCALE` pango units in one device unit (point). If the stretch attribute field has not previously been set, 0 is returned. Use the `get_set_fields`() method to determine if the field was explicitly set.

### pango.FontDescription.get_set_fields

        def get_set_fields()

Returns : | a bitmask with bits set corresponding to the font description attribute fields that have been set.

The `get_set_fields`() method returns a value that indicates which attribute fields in a font description have been set. The value returned is a combination of:

`pango.FONT_MASK_FAMILY` | the font family has been set.
`pango.FONT_MASK_STYLE` | the font slant style has been set.
`pango.FONT_MASK_VARIANT` | the font variant has been set.
`pango.FONT_MASK_WEIGHT` | the font weight has been set.
`pango.FONT_MASK_STRETCH` | the font stretch has been set.
`pango.FONT_MASK_SIZE` | the font size has been set.

### pango.FontDescription.unset_fields

        def unset_fields(to_unset)

`to_unset` : | a bitmask of attribute fields in the font description to unset.

The `unset_fields`() method unsets the attribute fields (specified by `to_unset`) in the `pango.FontDescription`. Note that this merely marks the attribute fields cleared, it does not clear the settings.

### pango.FontDescription.merge

        def merge(desc_to_merge, replace_existing)

`desc_to_merge` : | the `pango.FontDescription` to merge into the font description
`replace_existing` : | if `True`, replace attribute fields in the font description with the corresponding values from `desc_to_merge`, even if they are already exist.

The `merge`() method merges the attribute fields that are set in the `pango.FontDescription` specified by `desc_to_merge` into the attribute fields in the font description. If `replace_existing` is `False`, only fields in the font description that are not already set are affected. If `replace_existing` is `True`, attribute fields that are already set will also be replaced.

### pango.FontDescription.merge_static

        def merge_static(desc_to_merge, replace_existing)

`desc_to_merge` : | the `pango.FontDescription` to merge from
`replace_existing` : | if `True`, replace attribute fields in the font description with the corresponding values from `desc_to_merge`, even if they are already exist.

The `merge_static`() method is similar to the `merge`() method, but only a shallow copy is made of the family name and other allocated fields. The font description can only be used until `desc_to_merge` is modified or freed. This is meant to be used when the merged font description is only needed temporarily.

### pango.FontDescription.better_match

        def better_match(old_match, new_match)

`old_match` : | a `pango.FontDescription`, or `None`
`new_match` : | a `pango.FontDescription`
Returns : | `True` if `new_match` is a better match

The `better_match`() method determines if the attributes of the `pango.FontDescription` specified by `new_match` are a closer match for the font description than the `pango.FontDescription` specified by `old_match`. If `old_match` is `None`, determines if `new_match` is a match at all. The weight and style attribute need only match approximately but the other attributes must match exactly.

### pango.FontDescription.to_string

        def to_string()

Returns : | a string representation of the font description.

The `to_string`() method returns a string representation of the font description. See the pango.FontDescription() constructor 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.

### pango.FontDescription.to_filename

        def to_filename()

Returns : | a string representation of the font description as a filename.

The `to_filename`() method returns a filename representation of a font description. The filename is identical to the result from calling the `to_string`() method, but underscores replace characters that are not typically used in filenames, and it is in lower case only.

### pango.FontDescription.set_absolute_size

        def set_absolute_size(size)

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

### Note

This method is available in PyGTK 2.10 and above.

Sets the size field of a font description, in device units. This is mutually exclusive with `pango.FontDescription.set_size()`.

### pango.FontDescription.get_size_is_absolute

        def get_size_is_absolute()

Returns : | whether the size for the font description is in points or device units. Use `pango.FontDescription.get_set_fields()` to find out if the size field of the font description was explicitly set or not.

### Note

This method is available in PyGTK 2.10 and above.

Determines whether the size of the font is in points or device units. See `pango.FontDescription.set_size()` and `pango.FontDescription.set_absolute_size()`.

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