Pango Reference Manual
<<< Previous PageHomeUpNext Page >>>

Fonts

Name

Fonts -- Structures representing abstract fonts.

Synopsis



struct      PangoFontDescription;
enum        PangoStyle;
enum        PangoWeight;
enum        PangoVariant;
enum        PangoStretch;
PangoFontDescription* pango_font_description_copy
                                            (const PangoFontDescription *desc);
gboolean    pango_font_description_compare  (const PangoFontDescription *desc1,
                                             const PangoFontDescription *desc2);
void        pango_font_descriptions_free    (PangoFontDescription **descs,
                                             int n_descs);
void        pango_font_description_free     (PangoFontDescription *desc);
PangoFontDescription* pango_font_description_from_string
                                            (const char *str);
char*       pango_font_description_to_string
                                            (const PangoFontDescription *desc);

struct      PangoFont;
struct      PangoFontClass;
struct      PangoFontMetrics;
PangoEngineShape* pango_font_find_shaper    (PangoFont *font,
                                             const char *lang,
                                             guint32 ch);
PangoFontDescription* pango_font_describe   (PangoFont *font);
PangoCoverage* pango_font_get_coverage      (PangoFont *font,
                                             const char *lang);
void        pango_font_get_glyph_extents    (PangoFont *font,
                                             PangoGlyph glyph,
                                             PangoRectangle *ink_rect,
                                             PangoRectangle *logical_rect);
void        pango_font_get_metrics          (PangoFont *font,
                                             const gchar *lang,
                                             PangoFontMetrics *metrics);
#define     PANGO_TYPE_FONT
#define     PANGO_FONT                      (object)
#define     PANGO_IS_FONT                   (object)
#define     PANGO_FONT_CLASS                (klass)
#define     PANGO_IS_FONT_CLASS             (klass)
#define     PANGO_FONT_GET_CLASS            (obj)
GType       pango_font_get_type             (void);

struct      PangoFontMap;
struct      PangoFontMapClass;
PangoFont*  pango_font_map_load_font        (PangoFontMap *fontmap,
                                             const PangoFontDescription *desc);
void        pango_font_map_list_families    (PangoFontMap *fontmap,
                                             gchar ***families,
                                             int *n_families);
void        pango_font_map_free_families    (gchar **families,
                                             int n_families);
void        pango_font_map_list_fonts       (PangoFontMap *fontmap,
                                             const gchar *family,
                                             PangoFontDescription ***descs,
                                             int *n_descs);
#define     PANGO_TYPE_FONT_MAP
#define     PANGO_FONT_MAP                  (object)
#define     PANGO_IS_FONT_MAP               (object)
#define     PANGO_FONT_MAP_CLASS            (klass)
#define     PANGO_IS_FONT_MAP_CLASS         (klass)
#define     PANGO_FONT_MAP_GET_CLASS        (obj)
GType       pango_font_map_get_type         (void);

Description

Pango supports a flexible architecture where a particular rendering architecture can supply an implementation of fonts. The PangoFont structure representn an abstract rendering-system-indepent font. Pango provides routines to list available fonts, and to load a font of a given description.

Details

struct PangoFontDescription

struct PangoFontDescription
{
  char *family_name;

  PangoStyle style;
  PangoVariant variant;
  PangoWeight weight;
  PangoStretch stretch;

  int size;
};

The PangoFontDescription structure represents the description of an ideal font. These structures are used both to list what fonts are available on the system and also for specifying the characteristics of a font to load.

char *family_namethe name of the font family.
PangoStyle stylethe style (slant) of the font.
PangoVariant variantthe variant (normal or small caps) of the font.
PangoWeight weightthe weight (boldness) of the font.
PangoStretch stretchthe relative width of the font.
int size 

enum PangoStyle

typedef enum {
  PANGO_STYLE_NORMAL,
  PANGO_STYLE_OBLIQUE,
  PANGO_STYLE_ITALIC
} PangoStyle;

An enumeration specifying the various slant styles possible for a font.

PANGO_STYLE_NORMAL the font is upright.
PANGO_STYLE_OBLIQUE the font is slanted, but in a roman style.
PANGO_STYLE_ITALIC the font is slanted in an italic style.

enum PangoWeight

typedef enum {
  PANGO_WEIGHT_NORMAL = 400,
  PANGO_WEIGHT_BOLD = 700
} PangoWeight;

An enumeration specifying the weight (boldness) of a font. This is a numerical value ranging from 100 to 900, but there are two predefined values:

PANGO_WEIGHT_NORMALthe default weight (= 400)
PANGO_WEIGHT_BOLDthe bold weight (= 700)

enum PangoVariant

typedef enum {
  PANGO_VARIANT_NORMAL,
  PANGO_VARIANT_SMALL_CAPS
} PangoVariant;

An enumeration specifying capitalization variant of the font.

PANGO_VARIANT_NORMALA normal font.
PANGO_VARIANT_SMALL_CAPSA font with the lower case characters replaced by smaller variants of the capital characters.

enum PangoStretch

typedef enum {
  PANGO_STRETCH_ULTRA_CONDENSED,
  PANGO_STRETCH_EXTRA_CONDENSED,
  PANGO_STRETCH_CONDENSED,
  PANGO_STRETCH_SEMI_CONDENSED,
  PANGO_STRETCH_NORMAL,
  PANGO_STRETCH_SEMI_EXPANDED,
  PANGO_STRETCH_EXPANDED,
  PANGO_STRETCH_EXTRA_EXPANDED,
  PANGO_STRETCH_ULTRA_EXPANDED
} PangoStretch;

An enumeration specifying the width of the font relative to other designs within a family.

PANGO_STRETCH_ULTRA_CONDENSED 
PANGO_STRETCH_EXTRA_CONDENSED 
PANGO_STRETCH_CONDENSED 
PANGO_STRETCH_SEMI_CONDENSED 
PANGO_STRETCH_NORMALthe normal width
PANGO_STRETCH_SEMI_EXPANDED 
PANGO_STRETCH_EXPANDED 
PANGO_STRETCH_EXTRA_EXPANDED 
PANGO_STRETCH_ULTRA_EXPANDED 

pango_font_description_copy ()

PangoFontDescription* pango_font_description_copy
                                            (const PangoFontDescription *desc);

Make a copy of a PangoFontDescription.

desc : a PangoFontDescription
Returns : a newly allocated PangoFontDescription. This value must be freed using pango_font_description_free().

pango_font_description_compare ()

gboolean    pango_font_description_compare  (const PangoFontDescription *desc1,
                                             const PangoFontDescription *desc2);

Compare two font descriptions for equality.

desc1 : a PangoFontDescription
desc2 : another PangoFontDescription
Returns : TRUE if the two font descriptions are proveably identical. (Two font descriptions may result in identical fonts being loaded, but still compare FALSE.)

pango_font_descriptions_free ()

void        pango_font_descriptions_free    (PangoFontDescription **descs,
                                             int n_descs);

Free a list of font descriptions from pango_font_map_list_fonts()

descs : a pointer to an array of PangoFontDescription
n_descs : number of font descriptions in descs

pango_font_description_free ()

void        pango_font_description_free     (PangoFontDescription *desc);

Free a font description returned from pango_font_describe() or pango_font_description_copy().

desc : a PangoFontDescription

pango_font_description_from_string ()

PangoFontDescription* pango_font_description_from_string
                                            (const char *str);

Create a new font description from a string representation in the form "[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). 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.

str : string reprentation of a font description.
Returns : a new PangoFontDescription, or NULL if the string could not be parsed.

pango_font_description_to_string ()

char*       pango_font_description_to_string
                                            (const PangoFontDescription *desc);

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

desc : a PangoFontDescription
Returns : a new string that must be freed with g_free().

struct PangoFont

struct PangoFont
{
  GObject parent_instance;
};

The PangoFont structure is used to represent a font in a rendering-system-independent matter. To create an implementation of a PangoFont, the rendering-system specific code should malloc a larger structure that contains a nested PangoFont, fill in the klass member of the nested PangoFont with a pointer to a appropriate PangoFontClass, then call pango_font_init() on the structure.

The PangoFont structure contains one member which the implementation fills in:

struct PangoFontClass

struct PangoFontClass
{
  GObjectClass parent_class;
  
  PangoFontDescription *(*describe)           (PangoFont      *font);
  PangoCoverage *       (*get_coverage)       (PangoFont      *font,
					      const char      *lang);
  PangoEngineShape *    (*find_shaper)        (PangoFont      *font,
					       const char     *lang,
					       guint32         ch);
  void                  (*get_glyph_extents)  (PangoFont      *font,
					       PangoGlyph      glyph,
					       PangoRectangle *ink_rect,
					       PangoRectangle *logical_rect);
  void                  (*get_metrics)        (PangoFont        *font,
					       const gchar      *lang,
					       PangoFontMetrics *metrics);
};

The PangoFontClass structure contains the virtual functions for an implementation of a a PangoFont. It contains the following members:

void (*destroy) (PangoFont *font);a function to free the font structure and associated resources.

GObjectClass parent_class 
PangoFontDescription* (*describe) (PangoFont *font)a function to describe the characteristics of a font. See pango_font_describe().
PangoCoverage* (*get_coverage) (PangoFont *font, const char *lang)A function to get a coverage map for the font. See pango_font_get_coverage().
PangoEngineShape* (*find_shaper) (PangoFont *font, const char *lang, guint32 ch)A function to find the shaper for a particular character point. See pango_font_find_shaper().
void (*get_glyph_extents) (PangoFont *font, PangoGlyph glyph, PangoRectangle *ink_rect, PangoRectangle *logical_rect)A function called to find out the logical and ink extents of a glyph within the fonts. See pango_font_get_glyph_extents().
void (*get_metrics) (PangoFont *font, const gchar *lang, PangoFontMetrics *metrics)A function called to find the overall metric information for the font or the metric information appropriate to a particular language. See pango_font_get_metrics().

struct PangoFontMetrics

struct PangoFontMetrics
{
  int ascent;
  int descent;
};

The PangoFontMetrics structure represents the overall metrics for a font. It contains the following members:

int ascentthe logical extent of the font upwards from the baseline. The spacing between lines of text should be calculated as ascent + descent. Individual characters may have extents exceeding this value.
int descentthe logical extent of the font beneath the baseline. as ascent + descent. Individual characters may have extents exceeding this value.

pango_font_find_shaper ()

PangoEngineShape* pango_font_find_shaper    (PangoFont *font,
                                             const char *lang,
                                             guint32 ch);

Find the best matching shaper for a font for a particular language tag and character point.

font : a PangoFont
lang : the language tag (in the form of "en_US")
ch : the ISO-10646 character code.
Returns : the best matching shaper.

pango_font_describe ()

PangoFontDescription* pango_font_describe   (PangoFont *font);

font : 
Returns : 

pango_font_get_coverage ()

PangoCoverage* pango_font_get_coverage      (PangoFont *font,
                                             const char *lang);

Compute the coverage map for a given font and language tag.

font : a PangoFont
lang : the language tag (in the form of "en_US")
Returns : a newly allocated PangoContext object.

pango_font_get_glyph_extents ()

void        pango_font_get_glyph_extents    (PangoFont *font,
                                             PangoGlyph glyph,
                                             PangoRectangle *ink_rect,
                                             PangoRectangle *logical_rect);

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

font : a PangoFont
glyph : the glyph index
ink_rect : rectangle used to store the extents of the glyph as drawn or NULL to indicate that the result is not needed.
logical_rect : rectangle used to store the logical extents of the glyph or NULL to indicate that the result is not needed.

pango_font_get_metrics ()

void        pango_font_get_metrics          (PangoFont *font,
                                             const gchar *lang,
                                             PangoFontMetrics *metrics);

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

font : a PangoFont
lang : language tag used to determine which script to get the metrics for, or NULL to indicate to get the metrics for the entire font.
metrics : Structure to fill in with the metrics of the font

PANGO_TYPE_FONT

#define PANGO_TYPE_FONT              (pango_font_get_type ())

PANGO_FONT()

#define PANGO_FONT(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))

object : 

PANGO_IS_FONT()

#define PANGO_IS_FONT(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))

object : 

PANGO_FONT_CLASS()

#define PANGO_FONT_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_FONT, PangoFontClass))

klass : 

PANGO_IS_FONT_CLASS()

#define PANGO_IS_FONT_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONT))

klass : 

PANGO_FONT_GET_CLASS()

#define PANGO_FONT_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONT, PangoFontClass))

obj : 

pango_font_get_type ()

GType       pango_font_get_type             (void);

Returns : 

struct PangoFontMap

struct PangoFontMap
{
  GObject parent_instance;
};

The PangoFontMap represents the set of fonts available for a particular rendering system. This is a virtual object with implementations being specific to particular rendering systems. To create an implementation of a PangoFontMap, the rendering-system specific code should malloc a larger structure that contains a nested PangoFontMap, fill in the klass member of the nested PangoFontMap with a pointer to a appropriate PangoFontMapClass, then call pango_font_map_init() on the structure.

The PangoFont structure contains one member which the implementation fills in:

struct PangoFontMapClass

struct PangoFontMapClass
{
  GObjectClass parent_class;
  
  PangoFont *(*load_font)     (PangoFontMap               *fontmap,
			       const PangoFontDescription *desc);
  void       (*list_fonts)    (PangoFontMap               *fontmap,
			       const gchar                *family,
			       PangoFontDescription     ***descs,
			       int                        *n_descs);
  void       (*list_families) (PangoFontMap               *fontmap,
			       gchar                    ***families,
			       int                        *n_families);
};

The PangoFontMapClass structure holds the virtual functions for a particular PangoFontMap implementation.

GObjectClass parent_class 
PangoFont* (*load_font) (PangoFontMap *fontmap, const PangoFontDescription *desc)a function to load a font with a given description. See pango_font_map_load_font()
void (*list_fonts) (PangoFontMap *fontmap, const gchar *family, PangoFontDescription ***descs, int *n_descs)A function to list available fonts. See pango_font_map_list_fonts()
void (*list_families) (PangoFontMap *fontmap, gchar ***families, int *n_families)A function to list available font families. See pango_font_map_list_families().

pango_font_map_load_font ()

PangoFont*  pango_font_map_load_font        (PangoFontMap *fontmap,
                                             const PangoFontDescription *desc);

Load the font in the fontmap that is the closest match for desc.

fontmap : a PangoFontMap
desc : a PangoFontDescription describing the font to load
Returns :the font loaded, or NULL if no font matched.

pango_font_map_list_families ()

void        pango_font_map_list_families    (PangoFontMap *fontmap,
                                             gchar ***families,
                                             int *n_families);

List all families for a fontmap.

fontmap : a PangoFontMap
families : location to store a pointer to an array of strings. This array should be freed with pango_font_map_free_families().
n_families : location to store the number of elements in descs

pango_font_map_free_families ()

void        pango_font_map_free_families    (gchar **families,
                                             int n_families);

Free a list of families returned from pango_font_map_list_families()

families : a list of families
n_families : number of elements in families

pango_font_map_list_fonts ()

void        pango_font_map_list_fonts       (PangoFontMap *fontmap,
                                             const gchar *family,
                                             PangoFontDescription ***descs,
                                             int *n_descs);

List all fonts in a fontmap, or the fonts in a particular family.

fontmap : a PangoFontMap
family : the family for which to list the fonts, or NULL to list fonts in all families.
descs : location to store a pointer to an array of pointers to PangoFontDescription. This array should be freed with pango_font_descriptions_free().
n_descs : location to store the number of elements in descs

PANGO_TYPE_FONT_MAP

#define PANGO_TYPE_FONT_MAP              (pango_font_map_get_type ())

PANGO_FONT_MAP()

#define PANGO_FONT_MAP(object)           (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP, PangoFontMap))

object : 

PANGO_IS_FONT_MAP()

#define PANGO_IS_FONT_MAP(object)        (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))

object : 

PANGO_FONT_MAP_CLASS()

#define PANGO_FONT_MAP_CLASS(klass)      (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_FONT_MAP, PangoFontMapClass))

klass : 

PANGO_IS_FONT_MAP_CLASS()

#define PANGO_IS_FONT_MAP_CLASS(klass)   (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONT_MAP))

klass : 

PANGO_FONT_MAP_GET_CLASS()

#define PANGO_FONT_MAP_GET_CLASS(obj)    (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONT_MAP, PangoFontMapClass))

obj : 

pango_font_map_get_type ()

GType       pango_font_map_get_type         (void);

Returns : 



<<< Previous PageHomeUpNext Page >>>
Glyph StorageText Attributes