diff options
| -rw-r--r-- | docs/meson.build | 1 | ||||
| -rw-r--r-- | docs/pango.toml.in | 1 | ||||
| -rw-r--r-- | docs/pango_fonts.md | 65 | ||||
| -rw-r--r-- | pango/fonts.c | 13 |
4 files changed, 67 insertions, 13 deletions
diff --git a/docs/meson.build b/docs/meson.build index 4e2c06e8..fdf49162 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -3,6 +3,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) pango_content_files = [ 'pango_rendering.md', 'pango_markup.md', + 'pango_fonts.md', 'pango-name.png', 'layout.png', 'pipeline.png', diff --git a/docs/pango.toml.in b/docs/pango.toml.in index 1e8c0048..eca52ea2 100644 --- a/docs/pango.toml.in +++ b/docs/pango.toml.in @@ -57,6 +57,7 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/" content_files = [ "pango_rendering.md", "pango_markup.md", + "pango_fonts.md", ] content_images = [ diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md new file mode 100644 index 00000000..6e28e8f7 --- /dev/null +++ b/docs/pango_fonts.md @@ -0,0 +1,65 @@ +--- +Title: Fonts and Glyphs +--- + +# Fonts + +Pango supports a flexible architecture where a particular rendering architecture +can supply an implementation of fonts. The `PangoFont` structure represents an +abstract rendering-system-independent font. Pango provides routines to list +available fonts, and to load a font matching a given description. + +Conceptually, Pango groups fonts into faces and families which are identified +by a name. A *font face* provides the different sizes of a single font style. +A *font family* provides the available styles of a font. + +As an example, "Helvetica" is a family, "Helvetica Bold" is a face of this +family, and "Helvetica Bold 12pt" is a concrete font of this face. + +# Font Enumeration + +The central object for dealing with the available fonts on a system and caching +loaded fonts is a [class@Pango.FontMap]. An application typically uses a single +font map. + +Since the font map depends on the rendering architecture in use, you'll need to +use the backend function pango_cairo_font_map_get_default() to obtain the default +fontmap. Depending on the platform, it will return a `PangoCairoFcFontMap`, a +`PangoCairoWin32FontMap` or a `PangoCairoCoreTextFontMap`. + +Once you have a fontmap, you can enumerate the available font families with +[method@Pango.FontMap.list_families]. To enumerate the faces of a font family, +use [method@Pango.FontFamily.list_faces]. + +# Font Descriptions + +Since loading fonts uses system resources, Pango provides a way to describe +a font without loading it. A [struct@Pango.FontDescription] is a struct that +contains enough information to load a concrete font with +[method@Pango.FontMap.load_font] or [method@Pango.Context.load_font]. You can +obtain a font description from a font face using [method@Pango.FontFace.describe], +or by parsing a string such as + + Helvetica Bold 12pt + +with [method@Pango.FontDescription.from_string]. + +# Glyphs + +A font provides information about glyphs and how to position and render them. +The Pango rendering pipeline uses this information to create a +[struct@Pango.GlyphString], which contains the glyphs corresponding to the +characters in the text and related information such as glyph positions and sizes, +and clustering information (i.e. which glyphs correspond to which characters). + + + +A glyph is identified by a [alias@Pango.Glyph], which is a numeric ID. Note that +glyph IDs are font-specific: the same character can be represented by diffferent +glyph IDs in different fonts. + +The mapping between characters and glyphs is in general neither 1-1 nor a map: +a single glyph may represent multiple characters (as is the case with ligatures), +a single character may be represented by multiple glyphs (for example, when +combining accents and base character), and in complex scripts, multiple characters +may form clusters that get rearranged and represented by multiple glyphs. diff --git a/pango/fonts.c b/pango/fonts.c index a778facd..3ee21b0c 100644 --- a/pango/fonts.c +++ b/pango/fonts.c @@ -19,19 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:pangofont - * @short_description:Structures representing abstract fonts - * @title: Fonts - * - * Pango supports a flexible architecture where a - * particular rendering architecture can supply an - * implementation of fonts. The #PangoFont structure - * represents an abstract rendering-system-independent font. - * Pango provides routines to list available fonts, and - * to load a font matching a given description. - */ - #include "config.h" #include <stdlib.h> #include <math.h> |