Functions
pango_font_description_new ()
PangoFontDescription *
pango_font_description_new (void);
Creates a new font description structure with all fields unset.
pango_font_description_copy_static ()
PangoFontDescription *
pango_font_description_copy_static (const PangoFontDescription *desc);
Like pango_font_description_copy(), but only a shallow copy is made
of the family name and other allocated fields. The result can only
be used until desc
is modified or freed. This is meant to be used
when the copy is only needed temporarily.
pango_font_description_equal ()
gboolean
pango_font_description_equal (const PangoFontDescription *desc1,
const PangoFontDescription *desc2);
Compares two font descriptions for equality. Two font descriptions
are considered equal if the fonts they describe are provably identical.
This means that their masks do not have to match, as long as other fields
are all the same. (Two font descriptions may result in identical fonts
being loaded, but still compare FALSE.)
Returns
TRUE if the two font descriptions are identical,
FALSE otherwise.
pango_font_description_free ()
void
pango_font_description_free (PangoFontDescription *desc);
Frees a font description.
pango_font_descriptions_free ()
void
pango_font_descriptions_free (PangoFontDescription **descs,
int n_descs);
Frees an array of font descriptions.
pango_font_description_set_family ()
void
pango_font_description_set_family (PangoFontDescription *desc,
const char *family);
Sets the family name field of a font description. The family
name represents a family of related font styles, and will
resolve to a particular PangoFontFamily. In some uses of
PangoFontDescription, it is also possible to use a comma
separated list of family names for this field.
pango_font_description_set_family_static ()
void
pango_font_description_set_family_static
(PangoFontDescription *desc,
const char *family);
Like pango_font_description_set_family(), except that no
copy of family
is made. The caller must make sure that the
string passed in stays around until desc
has been freed
or the name is set again. This function can be used if
family
is a static string such as a C string literal, or
if desc
is only needed temporarily.
pango_font_description_get_family ()
const char *
pango_font_description_get_family (const PangoFontDescription *desc);
Gets the family name field of a font description. See
pango_font_description_set_family().
Returns
the family name field for the font
description, or NULL if not previously set. This
has the same life-time as the font description itself
and should not be freed.
[nullable]
pango_font_description_set_weight ()
void
pango_font_description_set_weight (PangoFontDescription *desc,
PangoWeight weight);
Sets the weight field of a font description. The weight field
specifies how bold or light the font should be. In addition
to the values of the PangoWeight enumeration, other intermediate
numeric values are possible.
pango_font_description_set_stretch ()
void
pango_font_description_set_stretch (PangoFontDescription *desc,
PangoStretch stretch);
Sets the stretch field of a font description. The stretch field
specifies how narrow or wide the font should be.
pango_font_description_set_absolute_size ()
void
pango_font_description_set_absolute_size
(PangoFontDescription *desc,
double size);
Sets the size field of a font description, in device units. This is mutually
exclusive with pango_font_description_set_size() which sets the font size
in points.
Since: 1.8
pango_font_description_set_gravity ()
void
pango_font_description_set_gravity (PangoFontDescription *desc,
PangoGravity gravity);
Sets the gravity field of a font description. The gravity field
specifies how the glyphs should be rotated. If gravity
is
PANGO_GRAVITY_AUTO, this actually unsets the gravity mask on
the font description.
This function is seldom useful to the user. Gravity should normally
be set on a PangoContext.
Since: 1.16
pango_font_description_set_variations ()
void
pango_font_description_set_variations (PangoFontDescription *desc,
const char *variations);
Sets the variations field of a font description. OpenType
font variations allow to select a font instance by specifying
values for a number of axes, such as width or weight.
The format of the variations string is AXIS1=VALUE,AXIS2=VALUE...,
with each AXIS a 4 character tag that identifies a font axis,
and each VALUE a floating point number. Unknown axes are ignored,
and values are clamped to their allowed range.
Pango does not currently have a way to find supported axes of
a font. Both harfbuzz or freetype have API for this.
Since: 1.42
pango_font_description_set_variations_static ()
void
pango_font_description_set_variations_static
(PangoFontDescription *desc,
const char *variations);
Like pango_font_description_set_variations(), except that no
copy of variations
is made. The caller must make sure that the
string passed in stays around until desc
has been freed
or the name is set again. This function can be used if
variations
is a static string such as a C string literal, or
if desc
is only needed temporarily.
Since: 1.42
pango_font_description_get_variations ()
const char *
pango_font_description_get_variations (const PangoFontDescription *desc);
Gets the variations field of a font description. See
pango_font_description_set_variations().
Returns
the varitions field for the font
description, or NULL if not previously set. This
has the same life-time as the font description itself
and should not be freed.
[nullable]
Since: 1.42
pango_font_description_get_set_fields ()
PangoFontMask
pango_font_description_get_set_fields (const PangoFontDescription *desc);
Determines which fields in a font description have been set.
Returns
a bitmask with bits set corresponding to the
fields in desc
that have been set.
pango_font_description_merge ()
void
pango_font_description_merge (PangoFontDescription *desc,
const PangoFontDescription *desc_to_merge,
gboolean replace_existing);
Merges the fields that are set in desc_to_merge
into the fields in
desc
. If replace_existing
is FALSE, only fields in desc
that
are not already set are affected. If TRUE, then fields that are
already set will be replaced as well.
If desc_to_merge
is NULL, this function performs nothing.
pango_font_description_merge_static ()
void
pango_font_description_merge_static (PangoFontDescription *desc,
const PangoFontDescription *desc_to_merge,
gboolean replace_existing);
Like pango_font_description_merge(), but only a shallow copy is made
of the family name and other allocated fields. desc
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_font_description_better_match ()
gboolean
pango_font_description_better_match (const PangoFontDescription *desc,
const PangoFontDescription *old_match,
const PangoFontDescription *new_match);
Determines if the style attributes of new_match
are a closer match
for desc
than those of old_match
are, or if old_match
is NULL,
determines if new_match
is a match at all.
Approximate matching is done for
weight and style; other style attributes must match exactly.
Style attributes are all attributes other than family and size-related
attributes. Approximate matching for style considers PANGO_STYLE_OBLIQUE
and PANGO_STYLE_ITALIC as matches, but not as good a match as when the
styles are equal.
Note that old_match
must match desc
.
Returns
TRUE if new_match
is a better match
pango_font_description_from_string ()
PangoFontDescription *
pango_font_description_from_string (const char *str);
Creates a new font description from a string representation in the
form
"[FAMILY-LIST] [STYLE-OPTIONS] [SIZE] [VARIATIONS]",
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,
stretch, or gravity, and SIZE is a decimal number (size in points)
or optionally followed by the unit modifier "px" for absolute size.
VARIATIONS is a comma-separated list of font variation
specifications of the form "@axis=value" (the = sign is optional).
The following words are understood as styles:
"Normal", "Roman", "Oblique", "Italic".
The following words are understood as variants:
"Small-Caps".
The following words are understood as weights:
"Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light",
"Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold",
"Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black",
"Extra-Black".
The following words are understood as stretch values:
"Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed",
"Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded".
The following words are understood as gravity values:
"Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left",
"East", "Rotated-Right", "West".
Any one of the options may be absent. If FAMILY-LIST is absent, then
the family_name field of the resulting font description will be
initialized to NULL. If STYLE-OPTIONS is missing, then all style
options will be set to the default values. If SIZE is missing, the
size in the resulting font description will be set to 0.
A typical example:
"Cantarell Italic Light 15 @wght=200"
pango_font_description_to_string ()
char *
pango_font_description_to_string (const PangoFontDescription *desc);
Creates a string representation of a font description. See
pango_font_description_from_string() 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.
Returns
a new string that must be freed with g_free().
pango_font_description_to_filename ()
char *
pango_font_description_to_filename (const PangoFontDescription *desc);
Creates a filename representation of a font description. The
filename is identical to the result from calling
pango_font_description_to_string(), but with underscores instead of
characters that are untypical in filenames, and in lower case only.
Returns
a new string that must be freed with g_free().
pango_font_metrics_ref ()
PangoFontMetrics *
pango_font_metrics_ref (PangoFontMetrics *metrics);
Increase the reference count of a font metrics structure by one.
Returns
metrics
.
[nullable]
pango_font_metrics_unref ()
void
pango_font_metrics_unref (PangoFontMetrics *metrics);
Decrease the reference count of a font metrics structure by one. If
the result is zero, frees the structure and any associated
memory.
pango_font_metrics_get_ascent ()
int
pango_font_metrics_get_ascent (PangoFontMetrics *metrics);
Gets the ascent from a font metrics structure. The ascent is
the distance from the baseline to the logical top of a line
of text. (The logical top may be above or below the top of the
actual drawn ink. It is necessary to lay out the text to figure
where the ink will be.)
Returns
the ascent, in Pango units.
pango_font_metrics_get_descent ()
int
pango_font_metrics_get_descent (PangoFontMetrics *metrics);
Gets the descent from a font metrics structure. The descent is
the distance from the baseline to the logical bottom of a line
of text. (The logical bottom may be above or below the bottom of the
actual drawn ink. It is necessary to lay out the text to figure
where the ink will be.)
Returns
the descent, in Pango units.
pango_font_metrics_get_height ()
int
pango_font_metrics_get_height (PangoFontMetrics *metrics);
Gets the line height from a font metrics structure. The
line height is the distance between successive baselines
in wrapped text.
If the line height is not available, 0 is returned.
Returns
the height, in Pango units
Since: 1.44
pango_font_metrics_get_approximate_char_width ()
int
pango_font_metrics_get_approximate_char_width
(PangoFontMetrics *metrics);
Gets the approximate character width for a font metrics structure.
This is merely a representative value useful, for example, for
determining the initial size for a window. Actual characters in
text will be wider and narrower than this.
Returns
the character width, in Pango units.
pango_font_metrics_get_approximate_digit_width ()
int
pango_font_metrics_get_approximate_digit_width
(PangoFontMetrics *metrics);
Gets the approximate digit width for a font metrics structure.
This is merely a representative value useful, for example, for
determining the initial size for a window. Actual digits in
text can be wider or narrower than this, though this value
is generally somewhat more accurate than the result of
pango_font_metrics_get_approximate_char_width() for digits.
Returns
the digit width, in Pango units.
pango_font_metrics_get_underline_thickness ()
int
pango_font_metrics_get_underline_thickness
(PangoFontMetrics *metrics);
Gets the suggested thickness to draw for the underline.
Returns
the suggested underline thickness, in Pango units.
Since: 1.6
pango_font_metrics_get_underline_position ()
int
pango_font_metrics_get_underline_position
(PangoFontMetrics *metrics);
Gets the suggested position to draw the underline.
The value returned is the distance above the
baseline of the top of the underline. Since most fonts have
underline positions beneath the baseline, this value is typically
negative.
Returns
the suggested underline position, in Pango units.
Since: 1.6
pango_font_metrics_get_strikethrough_thickness ()
int
pango_font_metrics_get_strikethrough_thickness
(PangoFontMetrics *metrics);
Gets the suggested thickness to draw for the strikethrough.
Returns
the suggested strikethrough thickness, in Pango units.
Since: 1.6
pango_font_metrics_get_strikethrough_position ()
int
pango_font_metrics_get_strikethrough_position
(PangoFontMetrics *metrics);
Gets the suggested position to draw the strikethrough.
The value returned is the distance above the
baseline of the top of the strikethrough.
Returns
the suggested strikethrough position, in Pango units.
Since: 1.6
pango_font_find_shaper ()
PangoEngineShape *
pango_font_find_shaper (PangoFont *font,
PangoLanguage *language,
guint32 ch);
pango_font_find_shaper is deprecated and should not be used in newly-written code.
Shape engines are no longer used
Finds the best matching shaper for a font for a particular
language tag and character point.
Returns
the best matching shaper.
[transfer none]
pango_font_describe_with_absolute_size ()
PangoFontDescription *
pango_font_describe_with_absolute_size
(PangoFont *font);
Returns a description of the font, with absolute font size set
(in device units). Use pango_font_describe() if you want the font
size in points.
Since: 1.14
pango_font_has_char ()
gboolean
pango_font_has_char (PangoFont *font,
gunichar wc);
Returns whether the font provides a glyph for this character.
Returns TRUE if font
can render wc
Since: 1.44
pango_font_get_glyph_extents ()
void
pango_font_get_glyph_extents (PangoFont *font,
PangoGlyph glyph,
PangoRectangle *ink_rect,
PangoRectangle *logical_rect);
Gets the logical and ink extents of a glyph within a font. The
coordinate system for each rectangle has its origin at the
base line and horizontal origin of the character with increasing
coordinates extending to the right and down. The macros PANGO_ASCENT(),
PANGO_DESCENT(), PANGO_LBEARING(), and PANGO_RBEARING() can be used to convert
from the extents rectangle to more traditional font metrics. The units
of the rectangles are in 1/PANGO_SCALE of a device unit.
If font
is NULL, this function gracefully sets some sane values in the
output variables and returns.
pango_font_get_metrics ()
PangoFontMetrics *
pango_font_get_metrics (PangoFont *font,
PangoLanguage *language);
Gets overall metric information for a font. 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.
If font
is NULL, this function gracefully sets some sane values in the
output variables and returns.
pango_font_get_font_map ()
PangoFontMap *
pango_font_get_font_map (PangoFont *font);
Gets the font map for which the font was created.
Note that the font maintains a weak reference
to the font map, so if all references to font map are dropped, the font
map will be finalized even if there are fonts created with the font
map that are still alive. In that case this function will return NULL.
It is the responsibility of the user to ensure that the font map is kept
alive. In most uses this is not an issue as a PangoContext holds
a reference to the font map.
Since: 1.10
pango_font_get_features ()
void
pango_font_get_features (PangoFont *font,
hb_feature_t *features,
guint len,
guint *num_features);
Obtain the OpenType features that are provided by the font.
These are passed to the rendering system, together with features
that have been explicitly set via attributes.
Note that this does not include OpenType features which the
rendering system enables by default.
Since: 1.44
pango_font_get_hb_font ()
hb_font_t *
pango_font_get_hb_font (PangoFont *font);
Get a hb_font_t object backing this font.
Note that the objects returned by this function
are cached and immutable. If you need to make
changes to the hb_font_t, use hb_font_create_sub_font().
[skip]
Returns
the hb_font_t object backing the
font, or NULL if the font does not have one.
[transfer none][nullable]
Since: 1.44
pango_font_family_get_name ()
const char *
pango_font_family_get_name (PangoFontFamily *family);
Gets the name of the family. The name is unique among all
fonts for the font backend and can be used in a PangoFontDescription
to specify that a face from this family is desired.
Returns
the name of the family. This string is owned
by the family object and must not be modified or freed.
pango_font_family_is_monospace ()
gboolean
pango_font_family_is_monospace (PangoFontFamily *family);
A monospace font is a font designed for text display where the the
characters form a regular grid. For Western languages this would
mean that the advance width of all characters are the same, but
this categorization also includes Asian fonts which include
double-width characters: characters that occupy two grid cells.
g_unichar_iswide() returns a result that indicates whether a
character is typically double-width in a monospace font.
The best way to find out the grid-cell size is to call
pango_font_metrics_get_approximate_digit_width(), since the results
of pango_font_metrics_get_approximate_char_width() may be affected
by double-width characters.
Returns
TRUE if the family is monospace.
Since: 1.4
pango_font_family_is_variable ()
gboolean
pango_font_family_is_variable (PangoFontFamily *family);
A variable font is a font which has axes that can be modified to
produce different faces.
Returns
TRUE if the family is variable
Since: 1.44
pango_font_family_list_faces ()
void
pango_font_family_list_faces (PangoFontFamily *family,
PangoFontFace ***faces,
int *n_faces);
Lists the different font faces that make up family
. The faces
in a family share a common design, but differ in slant, weight,
width and other aspects.
pango_font_face_get_face_name ()
const char *
pango_font_face_get_face_name (PangoFontFace *face);
Gets a name representing the style of this face among the
different faces in the PangoFontFamily for the face. This
name is unique among all faces in the family and is suitable
for displaying to users.
Returns
the face name for the face. This string is
owned by the face object and must not be modified or freed.
pango_font_face_list_sizes ()
void
pango_font_face_list_sizes (PangoFontFace *face,
int **sizes,
int *n_sizes);
List the available sizes for a font. This is only applicable to bitmap
fonts. For scalable fonts, stores NULL at the location pointed to by
sizes
and 0 at the location pointed to by n_sizes
. The sizes returned
are in Pango units and are sorted in ascending order.
Since: 1.4
pango_font_face_describe ()
PangoFontDescription *
pango_font_face_describe (PangoFontFace *face);
Returns the family, style, variant, weight and stretch of
a PangoFontFace. The size field of the resulting font description
will be unset.
pango_font_face_is_synthesized ()
gboolean
pango_font_face_is_synthesized (PangoFontFace *face);
Returns whether a PangoFontFace is synthesized by the underlying
font rendering engine from another face, perhaps by shearing, emboldening,
or lightening it.
Returns
whether face
is synthesized.
Since: 1.18
pango_font_map_list_families ()
void
pango_font_map_list_families (PangoFontMap *fontmap,
PangoFontFamily ***families,
int *n_families);
List all families for a fontmap.
pango_font_map_get_serial ()
guint
pango_font_map_get_serial (PangoFontMap *fontmap);
Returns the current serial number of fontmap
. The serial number is
initialized to an small number larger than zero when a new fontmap
is created and is increased whenever the fontmap is changed. It may
wrap, but will never have the value 0. Since it can wrap, never compare
it with "less than", always use "not equals".
The fontmap can only be changed using backend-specific API, like changing
fontmap resolution.
This can be used to automatically detect changes to a PangoFontMap, like
in PangoContext.
Returns
The current serial number of fontmap
.
Since: 1.32.4
pango_font_map_changed ()
void
pango_font_map_changed (PangoFontMap *fontmap);
Forces a change in the context, which will cause any PangoContext
using this fontmap to change.
This function is only useful when implementing a new backend
for Pango, something applications won't do. Backends should
call this function if they have attached extra data to the context
and such data is changed.
Since: 1.34
pango_fontset_get_font ()
PangoFont *
pango_fontset_get_font (PangoFontset *fontset,
guint wc);
Returns the font in the fontset that contains the best glyph for the
Unicode character wc
.
Returns
a PangoFont. The caller must call
g_object_unref when finished with the font.
[transfer full]
pango_fontset_get_metrics ()
PangoFontMetrics *
pango_fontset_get_metrics (PangoFontset *fontset);
Get overall metric information for the fonts in the fontset.
pango_fontset_foreach ()
void
pango_fontset_foreach (PangoFontset *fontset,
PangoFontsetForeachFunc func,
gpointer data);
Iterates through all the fonts in a fontset, calling func
for
each one. If func
returns TRUE, that stops the iteration.
Since: 1.4