pango.FontDescription — an object representing a description of a font.
class pango.FontDescription(gobject.GBoxed): |
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.
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 |
def copy()
Returns : | a new pango.FontDescription |
The copy
() method returns a new copy of
this font description.
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.
def hash()
Returns : | the hash value. |
The hash
() method computes and returns
a hash of the pango.FontDescription
.
def set_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.
def set_family_static(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.
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.
def set_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.
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.
def set_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
.
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.
def set_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:
| the ultralight weight (= 200) |
| the light weight (=300) |
| the default weight (= 400) |
| the bold weight (= 700) |
| the ultrabold weight (= 800) |
| the heavy weight (= 900) |
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.
def set_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:
| the narrowest width |
| |
| |
| |
| the normal (base) width |
| |
| |
| |
| the widest width |
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.
def set_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).
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.
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:
| the font family has been set. |
| the font slant style has been set. |
| the font variant has been set. |
| the font weight has been set. |
| the font stretch has been set. |
| the font size has been set. |
def unset_fields(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.
def merge(desc_to_merge
, replace_existing
)
| the pango.FontDescription
to merge into the font description |
| 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.
def merge_static(desc_to_merge
, replace_existing
)
| the pango.FontDescription
to merge from |
| 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.
def better_match(old_match
, new_match
)
| a pango.FontDescription ,
or None |
| 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.
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.
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.
def set_absolute_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. |
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()
.
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. |
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()
.