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