[pango] Bug 685167 - migrate docs to no-tmpl flavour
- From: Behdad Esfahbod <behdad src gnome org>
- To: commits-list gnome org
- Cc:
- Subject: [pango] Bug 685167 - migrate docs to no-tmpl flavour
- Date: Fri, 27 Sep 2013 18:39:29 +0000 (UTC)
commit 6d08bcab0d2821365a2ffd955cbbb07270565664
Author: Behdad Esfahbod <behdad behdad org>
Date: Fri Sep 27 14:36:51 2013 -0400
Bug 685167 - migrate docs to no-tmpl flavour
Patch from Rafał Mużyło.
configure.ac | 2 +-
docs/pango-docs.sgml | 4 -
docs/pango-sections.txt | 1 +
docs/tmpl/bidi.sgml | 108 ----
docs/tmpl/coretext-fonts.sgml | 40 --
docs/tmpl/coverage-maps.sgml | 140 -----
docs/tmpl/engines.sgml | 120 -----
docs/tmpl/fonts.sgml | 1036 -------------------------------------
docs/tmpl/freetype-fonts.sgml | 228 --------
docs/tmpl/glyphs.sgml | 694 -------------------------
docs/tmpl/layout.sgml | 938 ---------------------------------
docs/tmpl/main.sgml | 478 -----------------
docs/tmpl/modules.sgml | 90 ----
docs/tmpl/opentype.sgml | 554 --------------------
docs/tmpl/pango-engine-lang.sgml | 56 --
docs/tmpl/pango-engine-shape.sgml | 57 --
docs/tmpl/pango-renderer.sgml | 246 ---------
docs/tmpl/pango-version.sgml | 115 ----
docs/tmpl/pangocairo.sgml | 441 ----------------
docs/tmpl/pangofc-decoder.sgml | 58 --
docs/tmpl/pangofc-font.sgml | 130 -----
docs/tmpl/pangofc-fontmap.sgml | 241 ---------
docs/tmpl/scripts.sgml | 280 ----------
docs/tmpl/tab-stops.sgml | 150 ------
docs/tmpl/text-attributes.sgml | 833 -----------------------------
docs/tmpl/utils.sgml | 222 --------
docs/tmpl/vertical.sgml | 155 ------
docs/tmpl/win32-fonts.sgml | 267 ----------
docs/tmpl/xft-fonts.sgml | 311 -----------
pango/fonts.c | 13 +
pango/modules.c | 21 +
pango/pango-attributes.c | 13 +-
pango/pango-attributes.h | 217 ++++++++-
pango/pango-bidi-type.c | 22 +-
pango/pango-break.h | 53 ++
pango/pango-context.c | 18 +-
pango/pango-coverage.c | 12 +-
pango/pango-coverage.h | 21 +
pango/pango-engine.c | 39 ++
pango/pango-engine.h | 46 ++
pango/pango-font.h | 234 +++++++++
pango/pango-fontmap.h | 68 +++
pango/pango-fontset.h | 42 ++
pango/pango-glyph-item.h | 64 +++
pango/pango-glyph.h | 55 ++
pango/pango-gravity.c | 60 +++-
pango/pango-item.h | 28 +
pango/pango-language.c | 9 +
pango/pango-language.h | 5 +
pango/pango-layout.c | 50 ++-
pango/pango-layout.h | 43 ++
pango/pango-modules.h | 11 +
pango/pango-ot-buffer.c | 2 +-
pango/pango-ot-info.c | 10 +
pango/pango-ot-private.h | 18 +
pango/pango-ot-ruleset.c | 12 +
pango/pango-ot.h | 149 ++++++
pango/pango-script.c | 11 +-
pango/pango-script.h | 102 ++++
pango/pango-tabs.c | 14 +
pango/pango-tabs.h | 11 +
pango/pango-types.h | 104 ++++-
pango/pango-utils.c | 18 +
pango/pango-utils.h | 44 ++
pango/pangocairo-context.c | 2 +-
pango/pangocairo-render.c | 133 +++++
pango/pangocairo.h | 14 +
pango/pangocoretext.c | 8 +
pango/pangocoretext.h | 6 +
pango/pangofc-decoder.c | 8 +
pango/pangofc-font.c | 18 +
pango/pangofc-fontmap.c | 21 +
pango/pangofc-fontmap.h | 4 +-
pango/pangoft2-fontmap.c | 21 +-
pango/pangoft2-render.c | 11 +
pango/pangoft2.c | 15 +-
pango/pangoft2.h | 13 +
pango/pangowin32-fontcache.c | 5 +
pango/pangowin32-fontmap.c | 4 +-
pango/pangowin32.c | 8 +
pango/pangowin32.h | 6 +
pango/pangoxft-font.c | 30 ++
pango/pangoxft-fontmap.c | 4 +-
pango/pangoxft.h | 26 +
pango/shape.c | 10 +
85 files changed, 1975 insertions(+), 8026 deletions(-)
---
diff --git a/configure.ac b/configure.ac
index 5e97e02..fd64d95 100644
--- a/configure.ac
+++ b/configure.ac
@@ -592,7 +592,7 @@ if $have_cairo ; then : ; else
fi
fi
-GTK_DOC_CHECK([1.0])
+GTK_DOC_CHECK([1.15], [--flavour no-tmpl])
AC_ARG_ENABLE(man,
AC_HELP_STRING([--enable-man],
diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index fe7d018..56cb6f6 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -123,10 +123,6 @@
<title>Index of new symbols in 1.26</title>
<xi:include href="xml/api-index-1.26.xml"><xi:fallback /></xi:include>
</index>
- <index id="api-index-1-28" role="1.28">
- <title>Index of new symbols in 1.28</title>
- <xi:include href="xml/api-index-1.28.xml"><xi:fallback /></xi:include>
- </index>
<index id="api-index-1-30" role="1.30">
<title>Index of new symbols in 1.30</title>
<xi:include href="xml/api-index-1.30.xml"><xi:fallback /></xi:include>
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index 02eba9d..41db64d 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -262,6 +262,7 @@ pango_font_map_load_fontset
pango_font_map_list_families
pango_font_map_get_shape_engine_type
pango_font_map_get_serial
+pango_font_map_changed
<SUBSECTION>
PangoFontset
PANGO_TYPE_FONTSET
diff --git a/pango/fonts.c b/pango/fonts.c
index f3fa235..4a72d32 100644
--- a/pango/fonts.c
+++ b/pango/fonts.c
@@ -19,6 +19,19 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:fonts
+ * @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 of a given description.
+ */
+
#include "config.h"
#include <stdlib.h>
#include <math.h>
diff --git a/pango/modules.c b/pango/modules.c
index ca8d488..73935bd 100644
--- a/pango/modules.c
+++ b/pango/modules.c
@@ -19,6 +19,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:modules
+ * @short_description:Support for loadable modules
+ * @title:Modules
+ *
+ * Functions and macros in this section are used to support loading dynamic
+ * modules that add engines to Pango at run time.
+ */
#include "config.h"
#include <string.h>
@@ -44,11 +52,24 @@ typedef struct _PangoMapInfo PangoMapInfo;
typedef struct _PangoEnginePair PangoEnginePair;
typedef struct _PangoSubmap PangoSubmap;
+/**
+ * PangoMap:
+ *
+ * A #PangoMap structure can be used to determine the engine to
+ * use for each character.
+ */
struct _PangoMap
{
GArray *entries;
};
+/**
+ * PangoMapEntry:
+ *
+ * A #PangoMapEntry contains information about the engine that should be used
+ * for the codepoint to which this entry belongs and also whether the engine
+ * matches the language tag for this entry's map exactly or just approximately.
+ */
struct _PangoMapEntry
{
GSList *exact;
diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c
index 9551eb6..9059b1d 100644
--- a/pango/pango-attributes.c
+++ b/pango/pango-attributes.c
@@ -19,6 +19,17 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:text-attributes
+ * @short_description:Font and other attributes for annotating text
+ * @title:Text Attributes
+ *
+ * Attributed text is used in a number of places in Pango. It
+ * is used as the input to the itemization process and also when
+ * creating a #PangoLayout. The data types and functions in
+ * this section are used to represent and manipulate sets
+ * of attributes applied to a portion of text.
+ */
#include "config.h"
#include <string.h>
@@ -122,7 +133,7 @@ pango_attr_type_get_name (PangoAttrType type)
/**
* pango_attribute_init:
* @attr: a #PangoAttribute
- * @klass: a #PangoAttributeClass
+ * @klass: a #PangoAttrClass
*
* Initializes @attr's klass to @klass,
* it's start_index to %PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING
diff --git a/pango/pango-attributes.h b/pango/pango-attributes.h
index 897d07d..1e0feb7 100644
--- a/pango/pango-attributes.h
+++ b/pango/pango-attributes.h
@@ -31,6 +31,15 @@ G_BEGIN_DECLS
typedef struct _PangoColor PangoColor;
+/**
+ * PangoColor:
+ * @red: value of red component
+ * @green: value of green component
+ * @blue: value of blue component
+ *
+ * The #PangoColor structure is used to
+ * represent a color in an uncalibrated RGB color-space.
+ */
struct _PangoColor
{
guint16 red;
@@ -38,6 +47,11 @@ struct _PangoColor
guint16 blue;
};
+/**
+ * PANGO_TYPE_COLOR:
+ *
+ * The #GObject type for #PangoColor.
+ */
#define PANGO_TYPE_COLOR pango_color_get_type ()
GType pango_color_get_type (void) G_GNUC_CONST;
@@ -62,10 +76,73 @@ typedef struct _PangoAttrColor PangoAttrColor;
typedef struct _PangoAttrFontDesc PangoAttrFontDesc;
typedef struct _PangoAttrShape PangoAttrShape;
+/**
+ * PANGO_TYPE_ATTR_LIST:
+ *
+ * The #GObject type for #PangoAttrList.
+ */
#define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()
+/**
+ * PangoAttrIterator:
+ *
+ * The #PangoAttrIterator structure is used to represent an
+ * iterator through a #PangoAttrList. A new iterator is created
+ * with pango_attr_list_get_iterator(). Once the iterator
+ * is created, it can be advanced through the style changes
+ * in the text using pango_attr_iterator_next(). At each
+ * style change, the range of the current style segment and the
+ * attributes currently in effect can be queried.
+ */
+/**
+ * PangoAttrList:
+ *
+ * The #PangoAttrList structure represents a list of attributes
+ * that apply to a section of text. The attributes are, in general,
+ * allowed to overlap in an arbitrary fashion, however, if the
+ * attributes are manipulated only through pango_attr_list_change(),
+ * the overlap between properties will meet stricter criteria.
+ *
+ * Since the #PangoAttrList structure is stored as a linear list,
+ * it is not suitable for storing attributes for large amounts
+ * of text. In general, you should not use a single #PangoAttrList
+ * for more than one paragraph of text.
+ */
typedef struct _PangoAttrList PangoAttrList;
typedef struct _PangoAttrIterator PangoAttrIterator;
+/**
+ * PangoAttrType:
+ * @PANGO_ATTR_INVALID: does not happen
+ * @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
+ * @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
+ * @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
+ * @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
+ * @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
+ * @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
+ * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
+ * @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
+ * @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
+ * @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
+ * @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
+ * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
+ * @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
+ * @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
+ * @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
+ * @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
+ * @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
+ * @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
+ * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
+ * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
+ * @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt)
+ * @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt)
+ *
+ * The #PangoAttrType
+ * distinguishes between different types of attributes. Along with the
+ * predefined values, it is possible to allocate additional values
+ * for custom attributes using pango_attr_type_register(). The predefined
+ * values are given below. The type of structure used to store the
+ * attribute is listed in parentheses after the description.
+ */
typedef enum
{
PANGO_ATTR_INVALID, /* 0 is an invalid attribute type */
@@ -93,6 +170,27 @@ typedef enum
PANGO_ATTR_GRAVITY_HINT /* PangoAttrInt */
} PangoAttrType;
+/**
+ * PangoUnderline:
+ * @PANGO_UNDERLINE_NONE: no underline should be drawn
+ * @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
+ * @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
+ * @PANGO_UNDERLINE_LOW: a single underline should be drawn at a position
+ * beneath the ink extents of the text being
+ * underlined. This should be used only for underlining
+ * single characters, such as for keyboard
+ * accelerators. %PANGO_UNDERLINE_SINGLE should
+ * be used for extended portions of text.
+ * @PANGO_UNDERLINE_ERROR: a wavy underline should be drawn below.
+ * This underline is typically used to indicate
+ * an error such as a possilble mispelling; in some
+ * cases a contrasting color may automatically
+ * be used. This type of underlining is available since Pango 1.4.
+ *
+ * The #PangoUnderline enumeration is used to specify
+ * whether text should be underlined, and if so, the type
+ * of underlining.
+ */
typedef enum {
PANGO_UNDERLINE_NONE,
PANGO_UNDERLINE_SINGLE,
@@ -101,9 +199,39 @@ typedef enum {
PANGO_UNDERLINE_ERROR
} PangoUnderline;
+/**
+ * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING:
+ *
+ * This value can be used to set the start_index member of a #PangoAttribute
+ * such that the attribute covers from the beginning of the text.
+ *
+ * Since: 1.24
+ */
+/**
+ * PANGO_ATTR_INDEX_TO_TEXT_END:
+ *
+ * This value can be used to set the end_index member of a #PangoAttribute
+ * such that the attribute covers to the end of the text.
+ *
+ * Since: 1.24
+ */
#define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING 0
#define PANGO_ATTR_INDEX_TO_TEXT_END G_MAXUINT
+/**
+ * PangoAttribute:
+ * @klass: the class structure holding information about the type of the attribute
+ * @start_index: the start index of the range (in bytes).
+ * @end_index: end index of the range (in bytes). The character at this index
+ * is not included in the range.
+ *
+ * The #PangoAttribute structure represents the common portions of all
+ * attributes. Particular types of attributes include this structure
+ * as their initial portion. The common portion of the attribute holds
+ * the range to which the value in the type-specific part of the attribute
+ * applies and should be initialized using pango_attribute_init().
+ * By default an attribute will have an all-inclusive range of [0,%G_MAXUINT].
+ */
struct _PangoAttribute
{
const PangoAttrClass *klass;
@@ -134,6 +262,18 @@ typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
**/
typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
+/**
+ * PangoAttrClass:
+ * @type: the type ID for this attribute
+ * @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
+ * @destroy: function to free an attribute of this type (see pango_attribute_destroy())
+ * @equal: function to check two attributes of this type for equality (see pango_attribute_equal())
+ *
+ * The #PangoAttrClass structure stores the type and operations for
+ * a particular type of attribute. The functions in this structure should
+ * not be called directly. Instead, one should use the wrapper functions
+ * provided for #PangoAttribute.
+ */
struct _PangoAttrClass
{
/*< public >*/
@@ -143,36 +283,85 @@ struct _PangoAttrClass
gboolean (*equal) (const PangoAttribute *attr1, const PangoAttribute *attr2);
};
+/**
+ * PangoAttrString:
+ * @attr: the common portion of the attribute
+ * @value: the string which is the value of the attribute
+ *
+ * The #PangoAttrString structure is used to represent attributes with
+ * a string value.
+ */
struct _PangoAttrString
{
PangoAttribute attr;
char *value;
};
-
+/**
+ * PangoAttrLanguage:
+ * @attr: the common portion of the attribute
+ * @value: the #PangoLanguage which is the value of the attribute
+ *
+ * The #PangoAttrLanguage structure is used to represent attributes that
+ * are languages.
+ */
struct _PangoAttrLanguage
{
PangoAttribute attr;
PangoLanguage *value;
};
-
+/**
+ * PangoAttrInt:
+ * @attr: the common portion of the attribute
+ * @value: the value of the attribute
+ *
+ * The #PangoAttrInt structure is used to represent attributes with
+ * an integer or enumeration value.
+ */
struct _PangoAttrInt
{
PangoAttribute attr;
int value;
};
-
+/**
+ * PangoAttrFloat:
+ * @attr: the common portion of the attribute
+ * @value: the value of the attribute
+ *
+ * The #PangoAttrFloat structure is used to represent attributes with
+ * a float or double value.
+ */
struct _PangoAttrFloat
{
PangoAttribute attr;
double value;
};
-
+/**
+ * PangoAttrColor:
+ * @attr: the common portion of the attribute
+ * @color: the #PangoColor which is the value of the attribute
+ *
+ * The #PangoAttrColor structure is used to represent attributes that
+ * are colors.
+ */
struct _PangoAttrColor
{
PangoAttribute attr;
PangoColor color;
};
+/**
+ * PangoAttrSize:
+ * @attr: the common portion of the attribute
+ * @size: size of font, in units of 1/%PANGO_SCALE of a point (for
+ * %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE)
+ * @absolute: whether the font size is in device units or points.
+ * This field is only present for compatibility with Pango-1.8.0
+ * (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
+ * be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
+ *
+ * The #PangoAttrSize structure is used to represent attributes which
+ * set font size.
+ */
struct _PangoAttrSize
{
PangoAttribute attr;
@@ -180,6 +369,18 @@ struct _PangoAttrSize
guint absolute : 1;
};
+/**
+ * PangoAttrShape:
+ * @attr: the common portion of the attribute
+ * @ink_rect: the ink rectangle to restrict to
+ * @logical_rect: the logical rectangle to restrict to
+ * @data: user data set (see pango_attr_shape_new_with_data())
+ * @copy_func: copy function for the user data
+ * @destroy_func: destroy function for the user data
+ *
+ * The #PangoAttrShape structure is used to represent attributes which
+ * impose shape restrictions.
+ */
struct _PangoAttrShape
{
PangoAttribute attr;
@@ -191,6 +392,14 @@ struct _PangoAttrShape
GDestroyNotify destroy_func;
};
+/**
+ * PangoAttrFontDesc:
+ * @attr: the common portion of the attribute
+ * @desc: the font description which is the value of this attribute
+ *
+ * The #PangoAttrFontDesc structure is used to store an attribute that
+ * sets all aspects of the font description at once.
+ */
struct _PangoAttrFontDesc
{
PangoAttribute attr;
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index a61e255..462e7b0 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -19,6 +19,24 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:bidi
+ * @short_description:Types and functions to help with handling bidirectional text
+ * @title:Bidirectional Text
+ * @see_also:
+ * pango_context_get_base_dir(),
+ * pango_context_set_base_dir(),
+ * pango_itemize_with_base_dir()
+ *
+ * Pango supports bidirectional text (like Arabic and Hebrew) automatically.
+ * Some applications however, need some help to correctly handle bidirectional text.
+ *
+ * The #PangoDirection type can be used with pango_context_set_base_dir() to
+ * instruct Pango about direction of text, though in most cases Pango detects
+ * that correctly and automatically. The rest of the facilities in this section
+ * are used internally by Pango already, and are provided to help applications
+ * that need more direct control over bidirectional setting of text.
+ */
#include "config.h"
#include <string.h>
@@ -38,7 +56,7 @@
* character, as specified in the Unicode Character Database.
*
* A simplified version of this function is available as
- * pango_unichar_get_direction().
+ * pango_unichar_direction().
*
* Return value: the bidirectional character type, as used in the
* Unicode bidirectional algorithm.
@@ -162,7 +180,7 @@ pango_log2vis_get_embedding_levels (const gchar *text,
* This function is useful to categorize characters into left-to-right
* letters, right-to-left letters, and everything else. If full
* Unicode bidirectional type of a character is needed,
- * pango_bidi_type_for_gunichar() can be used instead.
+ * pango_bidi_type_for_unichar() can be used instead.
*
* Return value: the direction of the character.
*/
diff --git a/pango/pango-break.h b/pango/pango-break.h
index 5c326dd..70f8aed 100644
--- a/pango/pango-break.h
+++ b/pango/pango-break.h
@@ -30,6 +30,59 @@ G_BEGIN_DECLS
/* Logical attributes of a character.
*/
+/**
+ * PangoLogAttr:
+ * @is_line_break: if set, can break line in front of character
+ * @is_mandatory_break: if set, must break line in front of character
+ * @is_char_break: if set, can break here when doing character wrapping
+ * @is_white: is whitespace character
+ * @is_cursor_position: if set, cursor can appear in front of character.
+ * i.e. this is a grapheme boundary, or the first character
+ * in the text.
+ * This flag implements Unicode's
+ * <ulink url="http://www.unicode.org/reports/tr29/";>Grapheme
+ * Cluster Boundaries</ulink> semantics.
+ * @is_word_start: is first character in a word
+ * @is_word_end: is first non-word char after a word
+ * Note that in degenerate cases, you could have both @is_word_start
+ * and @is_word_end set for some character.
+ * @is_sentence_boundary: is a sentence boundary.
+ * There are two ways to divide sentences. The first assigns all
+ * inter-sentence whitespace/control/format chars to some sentence,
+ * so all chars are in some sentence; @is_sentence_boundary denotes
+ * the boundaries there. The second way doesn't assign
+ * between-sentence spaces, etc. to any sentence, so
+ * @is_sentence_start/@is_sentence_end mark the boundaries of those sentences.
+ * @is_sentence_start: is first character in a sentence
+ * @is_sentence_end: is first char after a sentence.
+ * Note that in degenerate cases, you could have both @is_sentence_start
+ * and @is_sentence_end set for some character. (e.g. no space after a
+ * period, so the next sentence starts right away)
+ * @backspace_deletes_character: if set, backspace deletes one character
+ * rather than the entire grapheme cluster. This
+ * field is only meaningful on grapheme
+ * boundaries (where @is_cursor_position is
+ * set). In some languages, the full grapheme
+ * (e.g. letter + diacritics) is considered a
+ * unit, while in others, each decomposed
+ * character in the grapheme is a unit. In the
+ * default implementation of pango_break(), this
+ * bit is set on all grapheme boundaries except
+ * those following Latin, Cyrillic or Greek base characters.
+ * @is_expandable_space: is a whitespace character that can possibly be
+ * expanded for justification purposes. (Since: 1.18)
+ * @is_word_boundary: is a word boundary.
+ * More specifically, means that this is not a position in the middle
+ * of a word. For example, both sides of a punctuation mark are
+ * considered word boundaries. This flag is particularly useful when
+ * selecting text word-by-word.
+ * This flag implements Unicode's
+ * <ulink url="http://www.unicode.org/reports/tr29/";>Word
+ * Boundaries</ulink> semantics. (Since: 1.22)
+ *
+ * The #PangoLogAttr structure stores information
+ * about the attributes of a single character.
+ */
struct _PangoLogAttr
{
guint is_line_break : 1; /* Can break line in front of character */
diff --git a/pango/pango-context.c b/pango/pango-context.c
index 8bb6a86..4e1fb1f 100644
--- a/pango/pango-context.c
+++ b/pango/pango-context.c
@@ -19,6 +19,16 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:main
+ * @title:Rendering
+ * @short_description:Functions to run the rendering pipeline
+ *
+ * The Pango rendering pipeline takes a string of
+ * Unicode characters and converts it into glyphs.
+ * The functions described in this section accomplish
+ * various steps of this process.
+ */
#include "config.h"
#include <string.h>
#include <stdlib.h>
@@ -31,6 +41,12 @@
#include "pango-modules.h"
#include "pango-script-private.h"
+/**
+ * PangoContext:
+ *
+ * The #PangoContext structure stores global information
+ * used to control the itemization process.
+ */
struct _PangoContext
{
GObject parent_instance;
@@ -237,7 +253,7 @@ pango_context_set_font_map (PangoContext *context,
* pango_context_get_font_map:
* @context: a #PangoContext
*
- * Gets the #PangoFontmap used to look up fonts for this context.
+ * Gets the #PangoFontMap used to look up fonts for this context.
*
* Return value: (transfer none): the font map for the #PangoContext.
* This value is owned by Pango and should not be unreferenced.
diff --git a/pango/pango-coverage.c b/pango/pango-coverage.c
index d84a5cd..eccd4f9 100644
--- a/pango/pango-coverage.c
+++ b/pango/pango-coverage.c
@@ -19,6 +19,16 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:coverage-maps
+ * @short_description:Unicode character range coverage storage
+ * @title:Coverage Maps
+ *
+ * It is often necessary in Pango to determine if a particular font can
+ * represent a particular character, and also how well it can represent
+ * that character. The #PangoCoverage is a data structure that is used
+ * to represent that information.
+ */
#include "config.h"
#include <string.h>
@@ -444,7 +454,7 @@ pango_coverage_get_uint32 (guchar **ptr)
* representing a #PangoCoverage
* @n_bytes: the size of @bytes in bytes
*
- * Convert data generated from pango_converage_to_bytes() back
+ * Convert data generated from pango_coverage_to_bytes() back
* to a #PangoCoverage
*
* Return value: (transfer full): a newly allocated #PangoCoverage, or
diff --git a/pango/pango-coverage.h b/pango/pango-coverage.h
index e1e8d13..592d2b1 100644
--- a/pango/pango-coverage.h
+++ b/pango/pango-coverage.h
@@ -26,8 +26,29 @@
G_BEGIN_DECLS
+/**
+ * PangoCoverage:
+ *
+ * The #PangoCoverage structure represents a map from Unicode characters
+ * to #PangoCoverageLevel. It is an opaque structure with no public fields.
+ */
typedef struct _PangoCoverage PangoCoverage;
+/**
+ * PangoCoverageLevel:
+ * @PANGO_COVERAGE_NONE: The character is not representable with the font.
+ * @PANGO_COVERAGE_FALLBACK: The character is represented in a way that may be
+ * comprehensible but is not the correct graphical form.
+ * For instance, a Hangul character represented as a
+ * a sequence of Jamos, or a Latin transliteration of a Cyrillic word.
+ * @PANGO_COVERAGE_APPROXIMATE: The character is represented as basically the correct
+ * graphical form, but with a stylistic variant inappropriate for
+ * the current script.
+ * @PANGO_COVERAGE_EXACT: The character is represented as the correct graphical form.
+ *
+ * Used to indicate how well a font can represent a particular Unicode
+ * character point for a particular script.
+ */
typedef enum {
PANGO_COVERAGE_NONE,
PANGO_COVERAGE_FALLBACK,
diff --git a/pango/pango-engine.c b/pango/pango-engine.c
index 04de3df..6634ff0 100644
--- a/pango/pango-engine.c
+++ b/pango/pango-engine.c
@@ -19,6 +19,45 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:engines
+ * @short_description:Language-specific and rendering-system-specific processing
+ * @title:Engines
+ *
+ * Pango utilizes a module architecture in which the language-specific
+ * and render-system-specific components are provided by loadable
+ * modules. Each loadable module supplies one or more
+ * <firstterm>engines</firstterm>. Each <firstterm>engine</firstterm>
+ * has an associated <firstterm>engine type</firstterm> and
+ * <firstterm>render type</firstterm>. These two types are represented by strings.
+ *
+ * Each dynamically-loaded module exports several functions which provide
+ * the public API. These functions are script_engine_list(),
+ * script_engine_init() and script_engine_exit, and
+ * script_engine_create(). The latter three functions are used when
+ * creating engines from the module at run time, while the first
+ * function is used when building a catalog of all available modules.
+ */
+/**
+ * SECTION:pango-engine-lang
+ * @short_description:Rendering-system independent script engines
+ * @title:PangoEngineLang
+ * @stability:Unstable
+ *
+ * The <firstterm>language engines</firstterm> are rendering-system independent
+ * engines that determine line, word, and character breaks for character strings.
+ * These engines are used in pango_break().
+ */
+/**
+ * SECTION:pango-engine-shape
+ * @short_description:Rendering-system dependent script engines
+ * @title:PangoEngineShape
+ * @stability:Unstable
+ *
+ * The <firstterm>shape engines</firstterm> are rendering-system dependent
+ * engines that convert character strings into glyph strings.
+ * These engines are used in pango_shape().
+ */
#include "config.h"
#include "pango-engine.h"
diff --git a/pango/pango-engine.h b/pango/pango-engine.h
index 51ac8c2..0b8abbe 100644
--- a/pango/pango-engine.h
+++ b/pango/pango-engine.h
@@ -36,6 +36,12 @@ G_BEGIN_DECLS
#include <gmodule.h>
+/**
+ * PANGO_RENDER_TYPE_NONE:
+ *
+ * A string constant defining the render type
+ * for engines that are not rendering-system specific.
+ */
#define PANGO_RENDER_TYPE_NONE "PangoRenderNone"
#define PANGO_TYPE_ENGINE (pango_engine_get_type ())
@@ -73,6 +79,12 @@ struct _PangoEngineClass
GType pango_engine_get_type (void) G_GNUC_CONST;
+/**
+ * PANGO_ENGINE_TYPE_LANG:
+ *
+ * A string constant defining the engine type for language engines.
+ * These engines derive from #PangoEngineLang.
+ */
#define PANGO_ENGINE_TYPE_LANG "PangoEngineLang"
#define PANGO_TYPE_ENGINE_LANG (pango_engine_lang_get_type ())
@@ -127,6 +139,12 @@ struct _PangoEngineLangClass
GType pango_engine_lang_get_type (void) G_GNUC_CONST;
+/**
+ * PANGO_ENGINE_TYPE_SHAPE:
+ *
+ * A string constant defining the engine type for shaping engines.
+ * These engines derive from #PangoEngineShape.
+ */
#define PANGO_ENGINE_TYPE_SHAPE "PangoEngineShape"
#define PANGO_TYPE_ENGINE_SHAPE (pango_engine_shape_get_type ())
@@ -205,12 +223,40 @@ GType pango_engine_shape_get_type (void) G_GNUC_CONST;
typedef struct _PangoEngineInfo PangoEngineInfo;
typedef struct _PangoEngineScriptInfo PangoEngineScriptInfo;
+/**
+ * PangoEngineScriptInfo
+ * @script: a #PangoScript. The value %PANGO_SCRIPT_COMMON has
+ * the special meaning here of "all scripts"
+ * @langs: a semicolon separated list of languages that this
+ * engine handles for this script. This may be empty,
+ * in which case the engine is saying that it is a
+ * fallback choice for all languages for this range,
+ * but should not be used if another engine
+ * indicates that it is specific for the language for
+ * a given code point. An entry in this list of "*"
+ * indicates that this engine is specific to all
+ * languages for this range.
+ *
+ * The #PangoEngineScriptInfo structure contains
+ * information about how the shaper covers a particular script.
+ */
struct _PangoEngineScriptInfo
{
PangoScript script;
const gchar *langs;
};
+/**
+ * PangoEngineInfo:
+ * @id: a unique string ID for the engine.
+ * @engine_type: a string identifying the engine type.
+ * @render_type: a string identifying the render type.
+ * @scripts: array of scripts this engine supports.
+ * @n_scripts: number of items in @scripts.
+ *
+ * The #PangoEngineInfo structure contains information about a particular
+ * engine. It contains the following fields:
+ */
struct _PangoEngineInfo
{
const gchar *id;
diff --git a/pango/pango-font.h b/pango/pango-font.h
index eea27b4..e4ed4e0 100644
--- a/pango/pango-font.h
+++ b/pango/pango-font.h
@@ -29,7 +29,24 @@
G_BEGIN_DECLS
+/**
+ * PangoFontDescription:
+ *
+ * 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.
+ */
typedef struct _PangoFontDescription PangoFontDescription;
+/**
+ * PangoFontMetrics:
+ *
+ * A #PangoFontMetrics structure holds the overall metric information
+ * for a font (possibly restricted to a script). The fields of this
+ * structure are private to implementations of a font backend. See
+ * the documentation of the corresponding getters for documentation
+ * of their meaning.
+ */
typedef struct _PangoFontMetrics PangoFontMetrics;
/**
@@ -46,11 +63,36 @@ typedef enum {
PANGO_STYLE_ITALIC
} PangoStyle;
+/**
+ * PangoVariant:
+ * @PANGO_VARIANT_NORMAL: A normal font.
+ * @PANGO_VARIANT_SMALL_CAPS: A font with the lower case characters
+ * replaced by smaller variants of the capital characters.
+ *
+ * An enumeration specifying capitalization variant of the font.
+ */
typedef enum {
PANGO_VARIANT_NORMAL,
PANGO_VARIANT_SMALL_CAPS
} PangoVariant;
+/**
+ * PangoWeight:
+ * @PANGO_WEIGHT_THIN: the thin weight (= 100; Since: 1.24)
+ * @PANGO_WEIGHT_ULTRALIGHT: the ultralight weight (= 200)
+ * @PANGO_WEIGHT_LIGHT: the light weight (= 300)
+ * @PANGO_WEIGHT_BOOK: the book weight (= 380; Since: 1.24)
+ * @PANGO_WEIGHT_NORMAL: the default weight (= 400)
+ * @PANGO_WEIGHT_MEDIUM: the normal weight (= 500; Since: 1.24)
+ * @PANGO_WEIGHT_SEMIBOLD: the semibold weight (= 600)
+ * @PANGO_WEIGHT_BOLD: the bold weight (= 700)
+ * @PANGO_WEIGHT_ULTRABOLD: the ultrabold weight (= 800)
+ * @PANGO_WEIGHT_HEAVY: the heavy weight (= 900)
+ * @PANGO_WEIGHT_ULTRAHEAVY: the ultraheavy weight (= 1000; Since: 1.24)
+ *
+ * An enumeration specifying the weight (boldness) of a font. This is a numerical
+ * value ranging from 100 to 900, but there are some predefined values:
+ */
typedef enum {
PANGO_WEIGHT_THIN = 100,
PANGO_WEIGHT_ULTRALIGHT = 200,
@@ -65,6 +107,21 @@ typedef enum {
PANGO_WEIGHT_ULTRAHEAVY = 1000
} PangoWeight;
+/**
+ * PangoStretch:
+ * @PANGO_STRETCH_ULTRA_CONDENSED: ultra condensed width
+ * @PANGO_STRETCH_EXTRA_CONDENSED: extra condensed width
+ * @PANGO_STRETCH_CONDENSED: condensed width
+ * @PANGO_STRETCH_SEMI_CONDENSED: semi condensed width
+ * @PANGO_STRETCH_NORMAL: the normal width
+ * @PANGO_STRETCH_SEMI_EXPANDED: semi expanded width
+ * @PANGO_STRETCH_EXPANDED: expanded width
+ * @PANGO_STRETCH_EXTRA_EXPANDED: extra expanded width
+ * @PANGO_STRETCH_ULTRA_EXPANDED: ultra expanded width
+ *
+ * An enumeration specifying the width of the font relative to other designs
+ * within a family.
+ */
typedef enum {
PANGO_STRETCH_ULTRA_CONDENSED,
PANGO_STRETCH_EXTRA_CONDENSED,
@@ -77,6 +134,19 @@ typedef enum {
PANGO_STRETCH_ULTRA_EXPANDED
} PangoStretch;
+/**
+ * PangoFontMask:
+ * @PANGO_FONT_MASK_FAMILY: the font family is specified.
+ * @PANGO_FONT_MASK_STYLE: the font style is specified.
+ * @PANGO_FONT_MASK_VARIANT: the font variant is specified.
+ * @PANGO_FONT_MASK_WEIGHT: the font weight is specified.
+ * @PANGO_FONT_MASK_STRETCH: the font stretch is specified.
+ * @PANGO_FONT_MASK_SIZE: the font size is specified.
+ * @PANGO_FONT_MASK_GRAVITY: the font gravity is specified (Since: 1.16.)
+ *
+ * The bits in a #PangoFontMask correspond to fields in a
+ * #PangoFontDescription that have been set.
+ */
typedef enum {
PANGO_FONT_MASK_FAMILY = 1 << 0,
PANGO_FONT_MASK_STYLE = 1 << 1,
@@ -88,6 +158,41 @@ typedef enum {
} PangoFontMask;
/* CSS scale factors (1.2 factor between each size) */
+/**
+ * PANGO_SCALE_XX_SMALL:
+ *
+ * The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).
+ */
+/**
+ * PANGO_SCALE_X_SMALL:
+ *
+ * The scale factor for two shrinking steps (1 / (1.2 * 1.2)).
+ */
+/**
+ * PANGO_SCALE_SMALL:
+ *
+ * The scale factor for one shrinking step (1 / 1.2).
+ */
+/**
+ * PANGO_SCALE_MEDIUM:
+ *
+ * The scale factor for normal size (1.0).
+ */
+/**
+ * PANGO_SCALE_LARGE:
+ *
+ * The scale factor for one magnification step (1.2).
+ */
+/**
+ * PANGO_SCALE_X_LARGE:
+ *
+ * The scale factor for two magnification steps (1.2 * 1.2).
+ */
+/**
+ * PANGO_SCALE_XX_LARGE:
+ *
+ * The scale factor for three magnification steps (1.2 * 1.2 * 1.2).
+ */
#define PANGO_SCALE_XX_SMALL ((double)0.5787037037037)
#define PANGO_SCALE_X_SMALL ((double)0.6444444444444)
#define PANGO_SCALE_SMALL ((double)0.8333333333333)
@@ -100,6 +205,11 @@ typedef enum {
* PangoFontDescription
*/
+/**
+ * PANGO_TYPE_FONT_DESCRIPTION:
+ *
+ * The #GObject type for #PangoFontDescription.
+ */
#define PANGO_TYPE_FONT_DESCRIPTION (pango_font_description_get_type ())
GType pango_font_description_get_type (void) G_GNUC_CONST;
@@ -163,6 +273,11 @@ char * pango_font_description_to_filename (const PangoFontDescrip
* PangoFontMetrics
*/
+/**
+ * PANGO_TYPE_FONT_METRICS:
+ *
+ * The #GObject type for #PangoFontMetrics.
+ */
#define PANGO_TYPE_FONT_METRICS (pango_font_metrics_get_type ())
GType pango_font_metrics_get_type (void) G_GNUC_CONST;
PangoFontMetrics *pango_font_metrics_ref (PangoFontMetrics *metrics);
@@ -200,6 +315,23 @@ struct _PangoFontMetrics
* PangoFontFamily
*/
+/**
+ * PANGO_TYPE_FONT_FAMILY:
+ *
+ * The #GObject type for #PangoFontFamily.
+ */
+/**
+ * PANGO_FONT_FAMILY:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontFamily.
+ */
+/**
+ * PANGO_IS_FONT_FAMILY:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontFamily.
+ */
#define PANGO_TYPE_FONT_FAMILY (pango_font_family_get_type ())
#define PANGO_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FAMILY,
PangoFontFamily))
#define PANGO_IS_FONT_FAMILY(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FAMILY))
@@ -223,6 +355,14 @@ gboolean pango_font_family_is_monospace (PangoFontFamily *family) G_G
typedef struct _PangoFontFamilyClass PangoFontFamilyClass;
+
+/**
+ * PangoFontFamily:
+ *
+ * The #PangoFontFamily structure is used to represent a family of related
+ * font faces. The faces in a family share a common design, but differ in
+ * slant, weight, width and other aspects.
+ */
struct _PangoFontFamily
{
GObject parent_instance;
@@ -254,6 +394,23 @@ struct _PangoFontFamilyClass
* PangoFontFace
*/
+/**
+ * PANGO_TYPE_FONT_FACE:
+ *
+ * The #GObject type for #PangoFontFace.
+ */
+/**
+ * PANGO_FONT_FACE:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontFace.
+ */
+/**
+ * PANGO_IS_FONT_FACE:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontFace.
+ */
#define PANGO_TYPE_FONT_FACE (pango_font_face_get_type ())
#define PANGO_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_FACE,
PangoFontFace))
#define PANGO_IS_FONT_FACE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_FACE))
@@ -275,6 +432,12 @@ gboolean pango_font_face_is_synthesized (PangoFontFace *face) G_GN
typedef struct _PangoFontFaceClass PangoFontFaceClass;
+/**
+ * PangoFontFace:
+ *
+ * The #PangoFontFace structure is used to represent a group of fonts with
+ * the same family, slant, weight, width, but varying sizes.
+ */
struct _PangoFontFace
{
GObject parent_instance;
@@ -306,6 +469,23 @@ struct _PangoFontFaceClass
* PangoFont
*/
+/**
+ * PANGO_TYPE_FONT:
+ *
+ * The #GObject type for #PangoFont.
+ */
+/**
+ * PANGO_FONT:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFont.
+ */
+/**
+ * PANGO_IS_FONT:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFont.
+ */
#define PANGO_TYPE_FONT (pango_font_get_type ())
#define PANGO_FONT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT, PangoFont))
#define PANGO_IS_FONT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT))
@@ -335,6 +515,22 @@ PangoFontMap *pango_font_get_font_map (PangoFont *font);
typedef struct _PangoFontClass PangoFontClass;
+/**
+ * PangoFont:
+ *
+ * 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 allocate
+ * a larger structure that contains a nested
+ * #PangoFont, fill in the <structfield>klass</structfield> 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 _PangoFont
{
GObject parent_instance;
@@ -375,6 +571,44 @@ struct _PangoFontClass
#endif /* PANGO_ENABLE_BACKEND */
+/**
+ * PANGO_GLYPH_EMPTY:
+ *
+ * The %PANGO_GLYPH_EMPTY macro represents a #PangoGlyph value that has a
+ * special meaning, which is a zero-width empty glyph. This is useful for
+ * example in shaper modules, to use as the glyph for various zero-width
+ * Unicode characters (those passing pango_is_zero_width()).
+ */
+/**
+ * PANGO_GLYPH_INVALID_INPUT:
+ *
+ * The %PANGO_GLYPH_INVALID_INPUT macro represents a #PangoGlyph value that has a
+ * special meaning of invalid input. #PangoLayout produces one such glyph
+ * per invalid input UTF-8 byte and such a glyph is rendered as a crossed
+ * box.
+ *
+ * Note that this value is defined such that it has the %PANGO_GLYPH_UNKNOWN_FLAG
+ * on.
+ *
+ * Since: 1.20
+ */
+/**
+ * PANGO_GLYPH_UNKNOWN_FLAG:
+ *
+ * The %PANGO_GLYPH_UNKNOWN_FLAG macro is a flag value that can be added to
+ * a #gunichar value of a valid Unicode character, to produce a #PangoGlyph
+ * value, representing an unknown-character glyph for the respective #gunichar.
+ */
+/**
+ * PANGO_GET_UNKNOWN_GLYPH:
+ * @wc: a Unicode character
+ *
+ * The way this unknown glyphs are rendered is backend specific. For example,
+ * a box with the hexadecimal Unicode code-point of the character written in it
+ * is what is done in the most common backends.
+ *
+ * Returns: a #PangoGlyph value that means no glyph was found for @wc.
+ */
#define PANGO_GLYPH_EMPTY ((PangoGlyph)0x0FFFFFFF)
#define PANGO_GLYPH_INVALID_INPUT ((PangoGlyph)0xFFFFFFFF)
#define PANGO_GLYPH_UNKNOWN_FLAG ((PangoGlyph)0x10000000)
diff --git a/pango/pango-fontmap.h b/pango/pango-fontmap.h
index 9f31801..207bac7 100644
--- a/pango/pango-fontmap.h
+++ b/pango/pango-fontmap.h
@@ -27,6 +27,23 @@
G_BEGIN_DECLS
+/**
+ * PANGO_TYPE_FONT_MAP:
+ *
+ * The #GObject type for #PangoFontMap.
+ */
+/**
+ * PANGO_FONT_MAP:
+ * @object: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontMap.
+ */
+/**
+ * PANGO_IS_FONT_MAP:
+ * @object: a #GObject.
+ *
+ * Returns: %TRUE if @object is a #PangoFontMap.
+ */
#define PANGO_TYPE_FONT_MAP (pango_font_map_get_type ())
#define PANGO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONT_MAP,
PangoFontMap))
#define PANGO_IS_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONT_MAP))
@@ -50,17 +67,68 @@ void pango_font_map_changed (PangoFontMap *fontma
#ifdef PANGO_ENABLE_BACKEND
+/**
+ * PANGO_FONT_MAP_CLASS:
+ * @klass: a #GObject.
+ *
+ * Casts a #GObject to a #PangoFontMapClass.
+ */
+/**
+ * PANGO_IS_FONT_MAP_CLASS:
+ * @klass: a #GObject.
+ *
+ * Returns: %TRUE if @klass is a subtype of #PangoFontMapClass.
+ */
+/**
+ * PANGO_FONT_MAP_GET_CLASS:
+ * @obj: a #PangoFontMap.
+ *
+ * Returns: class of @obj
+ */
#define PANGO_FONT_MAP_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_FONT_MAP,
PangoFontMapClass))
#define PANGO_IS_FONT_MAP_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONT_MAP))
#define PANGO_FONT_MAP_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONT_MAP,
PangoFontMapClass))
typedef struct _PangoFontMapClass PangoFontMapClass;
+/**
+ * PangoFontMap:
+ *
+ * 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 allocate a larger structure that contains a nested
+ * #PangoFontMap, fill in the <structfield>klass</structfield> member of the nested #PangoFontMap with a
+ * pointer to a appropriate #PangoFontMapClass, then call
+ * pango_font_map_init() on the structure.
+ *
+ * The #PangoFontMap structure contains one member which the implementation
+ * fills in.
+ */
struct _PangoFontMap
{
GObject parent_instance;
};
+/**
+ * PangoFontMapClass:
+ * @parent_class: parent #GObjectClass.
+ * @load_font: a function to load a font with a given description. See
+ * pango_font_map_load_font().
+ * @list_families: A function to list available font families. See
+ * pango_font_map_list_families().
+ * @load_fontset: a function to load a fontset with a given given description
+ * suitable for a particular language. See pango_font_map_load_fontset().
+ * @shape_engine_type: the type of rendering-system-dependent engines that
+ * can handle fonts of this fonts loaded with this fontmap.
+ * @get_serial: a function to get the serial number of the fontmap.
+ * See pango_font_map_get_serial().
+ * @changed: See pango_font_map_changed()
+ *
+ * The #PangoFontMapClass structure holds the virtual functions for
+ * a particular #PangoFontMap implementation.
+ */
struct _PangoFontMapClass
{
GObjectClass parent_class;
diff --git a/pango/pango-fontset.h b/pango/pango-fontset.h
index 282c2cd..7aa7d30 100644
--- a/pango/pango-fontset.h
+++ b/pango/pango-fontset.h
@@ -33,6 +33,11 @@ G_BEGIN_DECLS
* PangoFontset
*/
+/**
+ * PANGO_TYPE_FONTSET:
+ *
+ * The #GObject type for #PangoFontset.
+ */
#define PANGO_TYPE_FONTSET (pango_fontset_get_type ())
#define PANGO_FONTSET(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET,
PangoFontset))
#define PANGO_IS_FONTSET(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET))
@@ -73,11 +78,35 @@ typedef struct _PangoFontsetClass PangoFontsetClass;
#define PANGO_IS_FONTSET_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_FONTSET))
#define PANGO_FONTSET_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_FONTSET,
PangoFontsetClass))
+/**
+ * PangoFontset:
+ *
+ * A #PangoFontset represents a set of #PangoFont to use
+ * when rendering text. It is the result of resolving a
+ * #PangoFontDescription against a particular #PangoContext.
+ * It has operations for finding the component font for
+ * a particular Unicode character, and for finding a composite
+ * set of metrics for the entire fontset.
+ */
struct _PangoFontset
{
GObject parent_instance;
};
+/**
+ * PangoFontsetClass:
+ * @parent_class: parent #GObjectClass.
+ * @get_font: a function to get the font in the fontset that contains the
+ * best glyph for the given Unicode character; see pango_fontset_get_font().
+ * @get_metrics: a function to get overall metric information for the fonts
+ * in the fontset; see pango_fontset_get_metrics().
+ * @get_language: a function to get the language of the fontset.
+ * @foreach: a function to loop over the fonts in the fontset. See
+ * pango_fontset_foreach().
+ *
+ * The #PangoFontsetClass structure holds the virtual functions for
+ * a particular #PangoFontset implementation.
+ */
struct _PangoFontsetClass
{
GObjectClass parent_class;
@@ -106,6 +135,19 @@ struct _PangoFontsetClass
* PangoFontsetSimple
*/
+/**
+ * PANGO_TYPE_FONTSET_SIMPLE:
+ *
+ * The #GObject type for #PangoFontsetSimple.
+ */
+/**
+ * PangoFontsetSimple:
+ *
+ * #PangoFontsetSimple is a implementation of the abstract
+ * #PangoFontset base class in terms of an array of fonts,
+ * which the creator provides when constructing the
+ * #PangoFontsetSimple.
+ */
#define PANGO_TYPE_FONTSET_SIMPLE (pango_fontset_simple_get_type ())
#define PANGO_FONTSET_SIMPLE(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_FONTSET_SIMPLE,
PangoFontsetSimple))
#define PANGO_IS_FONTSET_SIMPLE(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_FONTSET_SIMPLE))
diff --git a/pango/pango-glyph-item.h b/pango/pango-glyph-item.h
index 71c4ab3..61b5ec4 100644
--- a/pango/pango-glyph-item.h
+++ b/pango/pango-glyph-item.h
@@ -29,6 +29,15 @@
G_BEGIN_DECLS
+/**
+ * PangoGlyphItem:
+ *
+ * A #PangoGlyphItem is a pair of a #PangoItem and the glyphs
+ * resulting from shaping the text corresponding to an item.
+ * As an example of the usage of #PangoGlyphItem, the results
+ * of shaping text with #PangoLayout is a list of #PangoLayoutLine,
+ * each of which contains a list of #PangoGlyphItem.
+ */
typedef struct _PangoGlyphItem PangoGlyphItem;
struct _PangoGlyphItem
@@ -37,6 +46,11 @@ struct _PangoGlyphItem
PangoGlyphString *glyphs;
};
+/**
+ * PANGO_TYPE_GLYPH_ITEM:
+ *
+ * The #GObject type for #PangoGlyphItem.
+ */
#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
GType pango_glyph_item_get_type (void) G_GNUC_CONST;
@@ -58,6 +72,49 @@ void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
int *logical_widths);
+/**
+ * PangoGlyphItemIter:
+ *
+ * A #PangoGlyphItemIter is an iterator over the clusters in a
+ * #PangoGlyphItem. The <firstterm>forward direction</firstterm> of the
+ * iterator is the logical direction of text. That is, with increasing
+ * @start_index and @start_char values. If @glyph_item is right-to-left
+ * (that is, if <literal>@glyph_item->item->analysis.level</literal> is odd),
+ * then @start_glyph decreases as the iterator moves forward. Moreover,
+ * in right-to-left cases, @start_glyph is greater than @end_glyph.
+ *
+ * An iterator should be initialized using either of
+ * pango_glyph_item_iter_init_start() and
+ * pango_glyph_item_iter_init_end(), for forward and backward iteration
+ * respectively, and walked over using any desired mixture of
+ * pango_glyph_item_iter_next_cluster() and
+ * pango_glyph_item_iter_prev_cluster(). A common idiom for doing a
+ * forward iteration over the clusters is:
+ * <programlisting>
+ * PangoGlyphItemIter cluster_iter;
+ * gboolean have_cluster;
+ *
+ * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
+ * glyph_item, text);
+ * have_cluster;
+ * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
+ * {
+ * ...
+ * }
+ * </programlisting>
+ *
+ * Note that @text is the start of the text for layout, which is then
+ * indexed by <literal>@glyph_item->item->offset</literal> to get to the
+ * text of @glyph_item. The @start_index and @end_index values can directly
+ * index into @text. The @start_glyph, @end_glyph, @start_char, and @end_char
+ * values however are zero-based for the @glyph_item. For each cluster, the
+ * item pointed at by the start variables is included in the cluster while
+ * the one pointed at by end variables is not.
+ *
+ * None of the members of a #PangoGlyphItemIter should be modified manually.
+ *
+ * Since: 1.22
+ */
typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
struct _PangoGlyphItemIter
@@ -74,6 +131,13 @@ struct _PangoGlyphItemIter
int end_char;
};
+/**
+ * PANGO_TYPE_GLYPH_ITEM_ITER:
+ *
+ * The #GObject type for #PangoGlyphItemIter.
+ *
+ * Since: 1.22
+ */
#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
GType pango_glyph_item_iter_get_type (void) G_GNUC_CONST;
diff --git a/pango/pango-glyph.h b/pango/pango-glyph.h
index 91bae32..4b25d08 100644
--- a/pango/pango-glyph.h
+++ b/pango/pango-glyph.h
@@ -33,10 +33,30 @@ typedef struct _PangoGlyphInfo PangoGlyphInfo;
typedef struct _PangoGlyphString PangoGlyphString;
/* 1024ths of a device unit */
+/**
+ * PangoGlyphUnit:
+ *
+ * The #PangoGlyphUnit type is used to store dimensions within
+ * Pango. Dimensions are stored in 1/%PANGO_SCALE of a device unit.
+ * (A device unit might be a pixel for screen display, or
+ * a point on a printer.) %PANGO_SCALE is currently 1024, and
+ * may change in the future (unlikely though), but you should not
+ * depend on its exact value. The PANGO_PIXELS() macro can be used
+ * to convert from glyph units into device units with correct rounding.
+ */
typedef gint32 PangoGlyphUnit;
/* Positioning information about a glyph
*/
+/**
+ * PangoGlyphGeometry:
+ * @width: the logical width to use for the the character.
+ * @x_offset: horizontal offset from nominal character position.
+ * @y_offset: vertical offset from nominal character position.
+ *
+ * The #PangoGlyphGeometry structure contains width and positioning
+ * information for a single glyph.
+ */
struct _PangoGlyphGeometry
{
PangoGlyphUnit width;
@@ -46,6 +66,18 @@ struct _PangoGlyphGeometry
/* Visual attributes of a glyph
*/
+/**
+ * PangoGlyphVisAttr:
+ * @is_cluster_start: set for the first logical glyph in each cluster. (Clusters
+ * are stored in visual order, within the cluster, glyphs
+ * are always ordered in logical order, since visual
+ * order is meaningless; that is, in Arabic text, accent glyphs
+ * follow the glyphs for the base character.)
+ *
+ * The PangoGlyphVisAttr is used to communicate information between
+ * the shaping phase and the rendering phase. More attributes may be
+ * added in the future.
+ */
struct _PangoGlyphVisAttr
{
guint is_cluster_start : 1;
@@ -53,6 +85,16 @@ struct _PangoGlyphVisAttr
/* A single glyph
*/
+/**
+ * PangoGlyphInfo:
+ * @glyph: the glyph itself.
+ * @geometry: the positional information about the glyph.
+ * @attr: the visual attributes of the glyph.
+ *
+ * The #PangoGlyphInfo structure represents a single glyph together with
+ * positioning information and visual attributes.
+ * It contains the following fields.
+ */
struct _PangoGlyphInfo
{
PangoGlyph glyph;
@@ -63,6 +105,14 @@ struct _PangoGlyphInfo
/* A string of glyphs with positional information and visual attributes -
* ready for drawing
*/
+/**
+ * PangoGlyphString:
+ *
+ * The #PangoGlyphString structure is used to store strings
+ * of glyphs with geometry and visual attribute information.
+ * The storage for the glyph information is owned
+ * by the structure which simplifies memory management.
+ */
struct _PangoGlyphString {
gint num_glyphs;
@@ -79,6 +129,11 @@ struct _PangoGlyphString {
gint space;
};
+/**
+ * PANGO_TYPE_GLYPH_STRING:
+ *
+ * The #GObject type for #PangoGlyphString.
+ */
#define PANGO_TYPE_GLYPH_STRING (pango_glyph_string_get_type ())
PangoGlyphString *pango_glyph_string_new (void);
diff --git a/pango/pango-gravity.c b/pango/pango-gravity.c
index 603c377..a72b67b 100644
--- a/pango/pango-gravity.c
+++ b/pango/pango-gravity.c
@@ -19,6 +19,64 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:vertical
+ * @short_description:Laying text out in vertical directions
+ * @title:Vertical Text
+ * @see_also: pango_context_get_base_gravity(),
+ * pango_context_set_base_gravity(),
+ * pango_context_get_gravity(),
+ * pango_context_get_gravity_hint(),
+ * pango_context_set_gravity_hint(),
+ * pango_font_description_set_gravity(),
+ * pango_font_description_get_gravity(),
+ * pango_attr_gravity_new(),
+ * pango_attr_gravity_hint_new()
+ *
+ * Since 1.16, Pango is able to correctly lay vertical text out. In fact, it can
+ * set layouts of mixed vertical and non-vertical text. This section describes
+ * the types used for setting vertical text parameters.
+ *
+ * The way this is implemented is through the concept of
+ * <firstterm>gravity</firstterm>. Gravity of normal Latin text is south. A
+ * gravity value of east means that glyphs will be rotated ninety degrees
+ * counterclockwise. So, to render vertical text one needs to set the gravity
+ * and rotate the layout using the matrix machinery already in place. This has
+ * the huge advantage that most algorithms working on a #PangoLayout do not need
+ * any change as the assumption that lines run in the X direction and stack in
+ * the Y direction holds even for vertical text layouts.
+ *
+ * Applications should only need to set base gravity on #PangoContext in use, and
+ * let Pango decide the gravity assigned to each run of text. This automatically
+ * handles text with mixed scripts. A very common use is to set the context base
+ * gravity to auto using pango_context_set_base_gravity()
+ * and rotate the layout normally. Pango will make sure that
+ * Asian languages take the right form, while other scripts are rotated normally.
+ *
+ * The correct way to set gravity on a layout is to set it on the context
+ * associated with it using pango_context_set_base_gravity(). The context
+ * of a layout can be accessed using pango_layout_get_context(). The currently
+ * set base gravity of the context can be accessed using
+ * pango_context_get_base_gravity() and the <firstterm>resolved</firstterm>
+ * gravity of it using pango_context_get_gravity(). The resolved gravity is
+ * the same as the base gravity for the most part, except that if the base
+ * gravity is set to %PANGO_GRAVITY_AUTO, the resolved gravity will depend
+ * on the current matrix set on context, and is derived using
+ * pango_gravity_get_for_matrix().
+ *
+ * The next thing an application may want to set on the context is the
+ * <firstterm>gravity hint</firstterm>. A #PangoGravityHint instructs how
+ * different scripts should react to the set base gravity.
+ *
+ * Font descriptions have a gravity property too, that can be set using
+ * pango_font_description_set_gravity() and accessed using
+ * pango_font_description_get_gravity(). However, those are rarely useful
+ * from application code and are mainly used by #PangoLayout internally.
+ *
+ * Last but not least, one can create #PangoAttribute<!---->s for gravity
+ * and gravity hint using pango_attr_gravity_new() and
+ * pango_attr_gravity_hint_new().
+ */
#include "config.h"
#include "pango-gravity.h"
@@ -278,7 +336,7 @@ pango_gravity_get_for_script (PangoScript script,
* This function is similar to pango_gravity_get_for_script() except
* that this function makes a distinction between narrow/half-width and
* wide/full-width characters also. Wide/full-width characters always
- * stand <emph>upright</emph>, that is, they always take the base gravity,
+ * stand <emphasis>upright</emphasis>, that is, they always take the base gravity,
* whereas narrow/full-width characters are always rotated in vertical
* context.
*
diff --git a/pango/pango-item.h b/pango/pango-item.h
index 0775003..b8e8ab6 100644
--- a/pango/pango-item.h
+++ b/pango/pango-item.h
@@ -30,8 +30,31 @@ typedef struct _PangoAnalysis PangoAnalysis;
typedef struct _PangoItem PangoItem;
/* TODO: if more flags are needed, turn this into a real PangoAnalysisFlags enum */
+/**
+ * PANGO_ANALYSIS_FLAG_CENTERED_BASELINE:
+ *
+ * Whether the segment should be shifted to center around the baseline.
+ * Used in vertical writing directions mostly.
+ *
+ * Since: 1.16
+ */
#define PANGO_ANALYSIS_FLAG_CENTERED_BASELINE (1 << 0)
+/**
+ * PangoAnalysis:
+ * @shape_engine: the engine for doing rendering-system-dependent processing.
+ * @lang_engine: the engine for doing rendering-system-independent processing.
+ * @font: the font for this segment.
+ * @level: the bidirectional level for this segment.
+ * @gravity: the glyph orientation for this segment (A #PangoGravity).
+ * @flags: boolean flags for this segment (currently only one) (Since: 1.16).
+ * @script: the detected script for this segment (A #PangoScript) (Since: 1.18).
+ * @language: the detected language for this segment.
+ * @extra_attrs: extra attributes for this segment.
+ *
+ * The #PangoAnalysis structure stores information about
+ * the properties of a segment of text.
+ */
struct _PangoAnalysis
{
PangoEngineShape *shape_engine;
@@ -48,6 +71,11 @@ struct _PangoAnalysis
GSList *extra_attrs;
};
+/**
+ * PangoItem:
+ *
+ * The #PangoItem structure stores information abouta segment of text.
+ */
struct _PangoItem
{
gint offset;
diff --git a/pango/pango-language.c b/pango/pango-language.c
index 7fc7078..15d5fb6 100644
--- a/pango/pango-language.c
+++ b/pango/pango-language.c
@@ -133,6 +133,15 @@ pango_language_free (PangoLanguage *language G_GNUC_UNUSED)
return; /* nothing */
}
+/**
+ * PangoLanguage:
+ *
+ * The #PangoLanguage structure is used to
+ * represent a language.
+ *
+ * #PangoLanguage pointers can be efficiently
+ * copied and compared with each other.
+ */
G_DEFINE_BOXED_TYPE (PangoLanguage, pango_language,
pango_language_copy,
pango_language_free);
diff --git a/pango/pango-language.h b/pango/pango-language.h
index 31660ca..8648a3a 100644
--- a/pango/pango-language.h
+++ b/pango/pango-language.h
@@ -29,6 +29,11 @@ G_BEGIN_DECLS
typedef struct _PangoLanguage PangoLanguage;
+/**
+ * PANGO_TYPE_LANGUAGE:
+ *
+ * The #GObject type for #PangoLanguage.
+ */
#define PANGO_TYPE_LANGUAGE (pango_language_get_type ())
GType pango_language_get_type (void) G_GNUC_CONST;
diff --git a/pango/pango-layout.c b/pango/pango-layout.c
index 82a3283..a024d11 100644
--- a/pango/pango-layout.c
+++ b/pango/pango-layout.c
@@ -19,6 +19,54 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:layout
+ * @short_description:High-level layout driver objects
+ * @title:Layout Objects
+ *
+ * While complete access to the layout capabilities of Pango is provided
+ * using the detailed interfaces for itemization and shaping, using
+ * that functionality directly involves writing a fairly large amount
+ * of code. The objects and functions in this section provide a
+ * high-level driver for formatting entire paragraphs of text
+ * at once.
+ */
+
+/**
+ * PangoLayout:
+ *
+ * The #PangoLayout structure represents an entire paragraph
+ * of text. It is initialized with a #PangoContext, UTF-8 string
+ * and set of attributes for that string. Once that is done, the
+ * set of formatted lines can be extracted from the object,
+ * the layout can be rendered, and conversion between logical
+ * character positions within the layout's text, and the physical
+ * position of the resulting glyphs can be made.
+ *
+ * There are also a number of parameters to adjust the formatting
+ * of a #PangoLayout, which are illustrated in <xref linkend="parameters"/>.
+ * It is possible, as well, to ignore the 2-D setup, and simply
+ * treat the results of a #PangoLayout as a list of lines.
+ *
+ * <figure id="parameters">
+ * <title>Adjustable parameters for a PangoLayout</title>
+ * <graphic fileref="layout.gif" format="GIF"></graphic>
+ * </figure>
+ *
+ * The #PangoLayout structure is opaque, and has no user-visible
+ * fields.
+ */
+
+/**
+ * PangoLayoutIter:
+ *
+ * A #PangoLayoutIter structure can be used to
+ * iterate over the visual extents of a #PangoLayout.
+ *
+ * The #PangoLayoutIter structure is opaque, and
+ * has no user-visible fields.
+ */
+
#include "config.h"
#include "pango-glyph.h" /* For pango_shape() */
#include "pango-break.h"
@@ -1967,7 +2015,7 @@ pango_layout_move_cursor_visually (PangoLayout *layout,
* Y position is not inside the layout, the closest position is chosen
* (the position will be clamped inside the layout). If the
* X position is not within the layout, then the start or the
- * end of the line is chosen as described for pango_layout_x_to_index().
+ * end of the line is chosen as described for pango_layout_xy_to_index().
* If either the X or Y positions were not inside the layout, then the
* function returns %FALSE; on an exact hit, it returns %TRUE.
*
diff --git a/pango/pango-layout.h b/pango/pango-layout.h
index 8177612..25ce9cf 100644
--- a/pango/pango-layout.h
+++ b/pango/pango-layout.h
@@ -33,14 +33,41 @@ typedef struct _PangoLayout PangoLayout;
typedef struct _PangoLayoutClass PangoLayoutClass;
typedef struct _PangoLayoutLine PangoLayoutLine;
+/**
+ * PangoLayoutRun:
+ *
+ * The #PangoLayoutRun structure represents a single run within
+ * a #PangoLayoutLine; it is simply an alternate name for
+ * #PangoGlyphItem.
+ * See the #PangoGlyphItem docs for details on the fields.
+ */
typedef PangoGlyphItem PangoLayoutRun;
+/**
+ * PangoAlignment:
+ * @PANGO_ALIGN_LEFT: Put all available space on the right
+ * @PANGO_ALIGN_CENTER: Center the line within the available space
+ * @PANGO_ALIGN_RIGHT: Put all available space on the left
+ *
+ * A #PangoAlignment describes how to align the lines of a #PangoLayout within the
+ * available space. If the #PangoLayout is set to justify
+ * using pango_layout_set_justify(), this only has effect for partial lines.
+ */
typedef enum {
PANGO_ALIGN_LEFT,
PANGO_ALIGN_CENTER,
PANGO_ALIGN_RIGHT
} PangoAlignment;
+/**
+ * PangoWrapMode:
+ * @PANGO_WRAP_WORD: wrap lines at word boundaries.
+ * @PANGO_WRAP_CHAR: wrap lines at character boundaries.
+ * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is
not
+ * enough space for a full word.
+ *
+ * A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
+ */
typedef enum {
PANGO_WRAP_WORD,
PANGO_WRAP_CHAR,
@@ -67,6 +94,22 @@ typedef enum {
PANGO_ELLIPSIZE_END
} PangoEllipsizeMode;
+/**
+ * PangoLayoutLine:
+ * @start_index: start of line as byte index into layout->text
+ * @length: length of line in bytes
+ * @is_paragraph_start: #TRUE if this is the first line of the paragraph
+ * @resolved_dir: #Resolved PangoDirection of line
+ *
+ * The #PangoLayoutLine structure represents one of the lines resulting
+ * from laying out a paragraph via #PangoLayout. #PangoLayoutLine
+ * structures are obtained by calling pango_layout_get_line() and
+ * are only valid until the text, attributes, or settings of the
+ * parent #PangoLayout are modified.
+ *
+ * Routines for rendering PangoLayout objects are provided in
+ * code specific to each rendering system.
+ */
struct _PangoLayoutLine
{
PangoLayout *layout;
diff --git a/pango/pango-modules.h b/pango/pango-modules.h
index 5dbcfe9..aec79e7 100644
--- a/pango/pango-modules.h
+++ b/pango/pango-modules.h
@@ -33,6 +33,17 @@ typedef struct _PangoMapEntry PangoMapEntry;
typedef struct _PangoIncludedModule PangoIncludedModule;
+/**
+ * PangoIncludedModule:
+ * @list: a function that lists the engines defined in this module.
+ * @init: a function to initialize the module.
+ * @exit: a function to finalize the module.
+ * @create: a function to create an engine, given the engine name.
+ *
+ * The #PangoIncludedModule structure for a statically linked module
+ * contains the functions that would otherwise be loaded from a dynamically
+ * loaded module.
+ */
struct _PangoIncludedModule
{
void (*list) (PangoEngineInfo **engines,
diff --git a/pango/pango-ot-buffer.c b/pango/pango-ot-buffer.c
index 1163730..35d66bc 100644
--- a/pango/pango-ot-buffer.c
+++ b/pango/pango-ot-buffer.c
@@ -82,7 +82,7 @@ pango_ot_buffer_clear (PangoOTBuffer *buffer)
* @cluster: the cluster that this glyph belongs to
*
* Appends a glyph to a #PangoOTBuffer, with @properties identifying which
- * features should be applied on this glyph. See pango_ruleset_add_feature().
+ * features should be applied on this glyph. See pango_ot_ruleset_add_feature().
*
* Since: 1.4
**/
diff --git a/pango/pango-ot-info.c b/pango/pango-ot-info.c
index cd1778d..f6dc1ac 100644
--- a/pango/pango-ot-info.c
+++ b/pango/pango-ot-info.c
@@ -19,6 +19,16 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:opentype
+ * @short_description:Obtaining information from OpenType tables
+ * @title:OpenType Font Handling
+ * @stability:Unstable
+ *
+ * Functions and macros in this section are used to implement the OpenType Layout
+ * features and algorithms. These are mostly useful when writing Fontconfig-based
+ * shaping engines
+ */
#include "config.h"
#include "pango-ot-private.h"
diff --git a/pango/pango-ot-private.h b/pango/pango-ot-private.h
index 81ae7e8..0d803ec 100644
--- a/pango/pango-ot-private.h
+++ b/pango/pango-ot-private.h
@@ -35,6 +35,15 @@ G_BEGIN_DECLS
typedef struct _PangoOTInfoClass PangoOTInfoClass;
+/**
+ * PangoOTInfo:
+ *
+ * The #PangoOTInfo struct contains the various
+ * tables associated with an OpenType font. It contains only private fields and
+ * should only be accessed via the <function>pango_ot_info_*</function> functions
+ * which are documented below. To obtain a #PangoOTInfo,
+ * use pango_ot_info_get().
+ */
struct _PangoOTInfo
{
GObject parent_instance;
@@ -61,6 +70,15 @@ struct _PangoOTRulesetClass
GObjectClass parent_class;
};
+/**
+ * PangoOTBuffer:
+ *
+ * The #PangoOTBuffer structure is used to store strings of glyphs associated
+ * with a #PangoFcFont, suitable for OpenType layout processing. It contains
+ * only private fields and should only be accessed via the
+ * <function>pango_ot_buffer_*</function> functions which are documented below.
+ * To obtain a #PangoOTBuffer, use pango_ot_buffer_new().
+ */
struct _PangoOTBuffer
{
hb_buffer_t *buffer;
diff --git a/pango/pango-ot-ruleset.c b/pango/pango-ot-ruleset.c
index 93ba617..2d8f150 100644
--- a/pango/pango-ot-ruleset.c
+++ b/pango/pango-ot-ruleset.c
@@ -25,6 +25,18 @@
static void pango_ot_ruleset_finalize (GObject *object);
+/**
+ * PangoOTRuleset:
+ *
+ * The #PangoOTRuleset structure holds a
+ * set of features selected from the tables in an OpenType font.
+ * (A feature is an operation such as adjusting glyph positioning
+ * that should be applied to a text feature such as a certain
+ * type of accent.) A #PangoOTRuleset
+ * is created with pango_ot_ruleset_new(), features are added
+ * to it with pango_ot_ruleset_add_feature(), then it is
+ * applied to a #PangoGlyphString with pango_ot_ruleset_shape().
+ */
G_DEFINE_TYPE (PangoOTRuleset, pango_ot_ruleset, G_TYPE_OBJECT);
static void
diff --git a/pango/pango-ot.h b/pango/pango-ot.h
index cca5ef5..a27ed20 100644
--- a/pango/pango-ot.h
+++ b/pango/pango-ot.h
@@ -34,8 +34,35 @@ G_BEGIN_DECLS
#ifdef PANGO_ENABLE_ENGINE
+/**
+ * PangoOTTag:
+ *
+ * The #PangoOTTag typedef is used to represent TrueType and OpenType
+ * four letter tags inside Pango. Use PANGO_OT_TAG_MAKE()
+ * or PANGO_OT_TAG_MAKE_FROM_STRING() macros to create <type>PangoOTTag</type>s manually.
+ */
typedef guint32 PangoOTTag;
+/**
+ * PANGO_OT_TAG_MAKE:
+ * @c1: First character.
+ * @c2: Second character.
+ * @c3: Third character.
+ * @c4: Fourth character.
+ *
+ * Creates a #PangoOTTag from four characters. This is similar and
+ * compatible with the <function>FT_MAKE_TAG()</function> macro from FreeType.
+ */
+/**
+ * PANGO_OT_TAG_MAKE_FROM_STRING:
+ * @s: The string representation of the tag.
+ *
+ * Creates a #PangoOTTag from a string. The string should be at least
+ * four characters long (pad with space characters if needed), and need
+ * not be nul-terminated. This is a convenience wrapper around
+ * PANGO_OT_TAG_MAKE(), but cannot be used in certain situations, for
+ * example, as a switch expression, as it dereferences pointers.
+ */
#define PANGO_OT_TAG_MAKE(c1,c2,c3,c4) ((PangoOTTag) FT_MAKE_TAG (c1, c2, c3, c4))
#define PANGO_OT_TAG_MAKE_FROM_STRING(s) (PANGO_OT_TAG_MAKE(((const char *) s)[0], \
((const char *) s)[1], \
@@ -49,21 +76,109 @@ typedef struct _PangoOTRuleset PangoOTRuleset;
typedef struct _PangoOTFeatureMap PangoOTFeatureMap;
typedef struct _PangoOTRulesetDescription PangoOTRulesetDescription;
+/**
+ * PangoOTTableType:
+ * @PANGO_OT_TABLE_GSUB: The GSUB table.
+ * @PANGO_OT_TABLE_GPOS: The GPOS table.
+ *
+ * The <type>PangoOTTableType</type> enumeration values are used to
+ * identify the various OpenType tables in the
+ * <function>pango_ot_info_*</function> functions.
+ */
typedef enum
{
PANGO_OT_TABLE_GSUB,
PANGO_OT_TABLE_GPOS
} PangoOTTableType;
+/**
+ * PANGO_OT_ALL_GLYPHS:
+ *
+ * This is used as the property bit in pango_ot_ruleset_add_feature() when a
+ * feature should be applied to all glyphs.
+ *
+ * Since: 1.16
+ */
+/**
+ * PANGO_OT_NO_FEATURE:
+ *
+ * This is used as a feature index that represent no feature, that is, should be
+ * skipped. It may be returned as feature index by pango_ot_info_find_feature()
+ * if the feature is not found, and pango_ot_ruleset_add_feature() function
+ * automatically skips this value, so no special handling is required by the user.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_NO_SCRIPT:
+ *
+ * This is used as a script index that represent no script, that is, when the
+ * requested script was not found, and a default ('DFLT') script was not found
+ * either. It may be returned as script index by pango_ot_info_find_script()
+ * if the script or a default script are not found, all other functions
+ * taking a script index essentially return if the input script index is
+ * this value, so no special handling is required by the user.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_DEFAULT_LANGUAGE:
+ *
+ * This is used as the language index in pango_ot_info_find_feature() when
+ * the default language system of the script is desired.
+ *
+ * It is also returned by pango_ot_info_find_language() if the requested language
+ * is not found, or the requested language tag was PANGO_OT_TAG_DEFAULT_LANGUAGE.
+ * The end result is that one can always call pango_ot_tag_from_language()
+ * followed by pango_ot_info_find_language() and pass the result to
+ * pango_ot_info_find_feature() without having to worry about falling back to
+ * default language system explicitly.
+ *
+ * Since: 1.16
+ */
#define PANGO_OT_ALL_GLYPHS ((guint) 0xFFFF)
#define PANGO_OT_NO_FEATURE ((guint) 0xFFFF)
#define PANGO_OT_NO_SCRIPT ((guint) 0xFFFF)
#define PANGO_OT_DEFAULT_LANGUAGE ((guint) 0xFFFF)
+/**
+ * PANGO_OT_TAG_DEFAULT_SCRIPT:
+ *
+ * This is a #PangoOTTag representing the special script tag 'DFLT'. It is
+ * returned as script tag by pango_ot_tag_from_script() if the requested script
+ * is not found.
+ *
+ * Since: 1.18
+ */
+/**
+ * PANGO_OT_TAG_DEFAULT_LANGUAGE:
+ *
+ * This is a #PangoOTTag representing a special language tag 'dflt'. It is
+ * returned as language tag by pango_ot_tag_from_language() if the requested
+ * language is not found. It is safe to pass this value to
+ * pango_ot_info_find_language() as that function falls back to returning default
+ * language-system if the requested language tag is not found.
+ *
+ * Since: 1.18
+ */
#define PANGO_OT_TAG_DEFAULT_SCRIPT PANGO_OT_TAG_MAKE ('D', 'F', 'L', 'T')
#define PANGO_OT_TAG_DEFAULT_LANGUAGE PANGO_OT_TAG_MAKE ('d', 'f', 'l', 't')
/* Note that this must match hb_glyph_info_t */
+/**
+ * PangoOTGlyph:
+ * @glyph: the glyph itself.
+ * @properties: the properties value, identifying which features should be
+ * applied on this glyph. See pango_ot_ruleset_add_feature().
+ * @cluster: the cluster that this glyph belongs to.
+ * @component: a component value, set by the OpenType layout engine.
+ * @ligID: a ligature index value, set by the OpenType layout engine.
+ * @internal: for Pango internal use
+ *
+ * The #PangoOTGlyph structure represents a single glyph together with
+ * information used for OpenType layout processing of the glyph.
+ * It contains the following fields.
+ */
struct _PangoOTGlyph
{
guint32 glyph;
@@ -75,12 +190,46 @@ struct _PangoOTGlyph
guint internal;
};
+/**
+ * PangoOTFeatureMap:
+ * @feature_name: feature tag in represented as four-letter ASCII string.
+ * @property_bit: the property bit to use for this feature. See
+ * pango_ot_ruleset_add_feature() for details.
+ *
+ * The #PangoOTFeatureMap typedef is used to represent an OpenType
+ * feature with the property bit associated with it. The feature tag is
+ * represented as a char array instead of a #PangoOTTag for convenience.
+ *
+ * Since: 1.18
+ */
struct _PangoOTFeatureMap
{
char feature_name[5];
gulong property_bit;
};
+/**
+ * PangoOTRulesetDescription:
+ * @script: a #PangoScript.
+ * @language: a #PangoLanguage.
+ * @static_gsub_features: static map of GSUB features, or %NULL.
+ * @n_static_gsub_features: length of @static_gsub_features, or 0.
+ * @static_gpos_features: static map of GPOS features, or %NULL.
+ * @n_static_gpos_features: length of @static_gpos_features, or 0.
+ * @other_features: map of extra features to add to both GSUB and GPOS, or %NULL.
+ * Unlike the static maps, this pointer need not live beyond
+ * the life of function calls taking this struct.
+ * @n_other_features: length of @other_features, or 0.
+ *
+ * The #PangoOTRuleset structure holds all the information needed
+ * to build a complete #PangoOTRuleset from an OpenType font.
+ * The main use of this struct is to act as the key for a per-font
+ * hash of rulesets. The user populates a ruleset description and
+ * gets the ruleset using pango_ot_ruleset_get_for_description()
+ * or create a new one using pango_ot_ruleset_new_from_description().
+ *
+ * Since: 1.18
+ */
struct _PangoOTRulesetDescription {
PangoScript script;
PangoLanguage *language;
diff --git a/pango/pango-script.c b/pango/pango-script.c
index 92f2ef1..95dd3e9 100644
--- a/pango/pango-script.c
+++ b/pango/pango-script.c
@@ -53,6 +53,15 @@
* of the copyright holder.
*/
+/**
+ * SECTION:scripts
+ * @short_description:Identifying writing systems and languages
+ * @title:Scripts and Languages
+ *
+ * The functions in this section are used to identify the writing
+ * system, or <firstterm>script</firstterm> of individual characters
+ * and of ranges within a larger text string.
+ */
#include "config.h"
#include <stdlib.h>
#include <string.h>
@@ -65,7 +74,7 @@
* @ch: a Unicode character
*
* Looks up the #PangoScript for a particular character (as defined by
- * Unicode Standard Annex #24). No check is made for @ch being a
+ * Unicode Standard Annex \#24). No check is made for @ch being a
* valid Unicode character; if you pass in invalid character, the
* result is undefined.
*
diff --git a/pango/pango-script.h b/pango/pango-script.h
index cc3d0ec..e370e3e 100644
--- a/pango/pango-script.h
+++ b/pango/pango-script.h
@@ -34,6 +34,108 @@ G_BEGIN_DECLS
**/
typedef struct _PangoScriptIter PangoScriptIter;
+/**
+ * PangoScript:
+ * @PANGO_SCRIPT_INVALID_CODE: a value never returned from pango_script_for_unichar()
+ * @PANGO_SCRIPT_COMMON: a character used by multiple different scripts
+ * @PANGO_SCRIPT_INHERITED: a mark glyph that takes its script from the
+ * base glyph to which it is attached
+ * @PANGO_SCRIPT_ARABIC: Arabic
+ * @PANGO_SCRIPT_ARMENIAN: Armenian
+ * @PANGO_SCRIPT_BENGALI: Bengali
+ * @PANGO_SCRIPT_BOPOMOFO: Bopomofo
+ * @PANGO_SCRIPT_CHEROKEE: Cherokee
+ * @PANGO_SCRIPT_COPTIC: Coptic
+ * @PANGO_SCRIPT_CYRILLIC: Cyrillic
+ * @PANGO_SCRIPT_DESERET: Deseret
+ * @PANGO_SCRIPT_DEVANAGARI: Devanagari
+ * @PANGO_SCRIPT_ETHIOPIC: Ethiopic
+ * @PANGO_SCRIPT_GEORGIAN: Georgian
+ * @PANGO_SCRIPT_GOTHIC: Gothic
+ * @PANGO_SCRIPT_GREEK: Greek
+ * @PANGO_SCRIPT_GUJARATI: Gujarati
+ * @PANGO_SCRIPT_GURMUKHI: Gurmukhi
+ * @PANGO_SCRIPT_HAN: Han
+ * @PANGO_SCRIPT_HANGUL: Hangul
+ * @PANGO_SCRIPT_HEBREW: Hebrew
+ * @PANGO_SCRIPT_HIRAGANA: Hiragana
+ * @PANGO_SCRIPT_KANNADA: Kannada
+ * @PANGO_SCRIPT_KATAKANA: Katakana
+ * @PANGO_SCRIPT_KHMER: Khmer
+ * @PANGO_SCRIPT_LAO: Lao
+ * @PANGO_SCRIPT_LATIN: Latin
+ * @PANGO_SCRIPT_MALAYALAM: Malayalam
+ * @PANGO_SCRIPT_MONGOLIAN: Mongolian
+ * @PANGO_SCRIPT_MYANMAR: Myanmar
+ * @PANGO_SCRIPT_OGHAM: Ogham
+ * @PANGO_SCRIPT_OLD_ITALIC: Old Italic
+ * @PANGO_SCRIPT_ORIYA: Oriya
+ * @PANGO_SCRIPT_RUNIC: Runic
+ * @PANGO_SCRIPT_SINHALA: Sinhala
+ * @PANGO_SCRIPT_SYRIAC: Syriac
+ * @PANGO_SCRIPT_TAMIL: Tamil
+ * @PANGO_SCRIPT_TELUGU: Telugu
+ * @PANGO_SCRIPT_THAANA: Thaana
+ * @PANGO_SCRIPT_THAI: Thai
+ * @PANGO_SCRIPT_TIBETAN: Tibetan
+ * @PANGO_SCRIPT_CANADIAN_ABORIGINAL: Canadian Aboriginal
+ * @PANGO_SCRIPT_YI: Yi
+ * @PANGO_SCRIPT_TAGALOG: Tagalog
+ * @PANGO_SCRIPT_HANUNOO: Hanunoo
+ * @PANGO_SCRIPT_BUHID: Buhid
+ * @PANGO_SCRIPT_TAGBANWA: Tagbanwa
+ * @PANGO_SCRIPT_BRAILLE: Braille
+ * @PANGO_SCRIPT_CYPRIOT: Cypriot
+ * @PANGO_SCRIPT_LIMBU: Limbu
+ * @PANGO_SCRIPT_OSMANYA: Osmanya
+ * @PANGO_SCRIPT_SHAVIAN: Shavian
+ * @PANGO_SCRIPT_LINEAR_B: Linear B
+ * @PANGO_SCRIPT_TAI_LE: Tai Le
+ * @PANGO_SCRIPT_UGARITIC: Ugaritic
+ * @PANGO_SCRIPT_NEW_TAI_LUE: New Tai Lue. Since 1.10
+ * @PANGO_SCRIPT_BUGINESE: Buginese. Since 1.10
+ * @PANGO_SCRIPT_GLAGOLITIC: Glagolitic. Since 1.10
+ * @PANGO_SCRIPT_TIFINAGH: Tifinagh. Since 1.10
+ * @PANGO_SCRIPT_SYLOTI_NAGRI: Syloti Nagri. Since 1.10
+ * @PANGO_SCRIPT_OLD_PERSIAN: Old Persian. Since 1.10
+ * @PANGO_SCRIPT_KHAROSHTHI: Kharoshthi. Since 1.10
+ * @PANGO_SCRIPT_UNKNOWN: an unassigned code point. Since 1.14
+ * @PANGO_SCRIPT_BALINESE: Balinese. Since 1.14
+ * @PANGO_SCRIPT_CUNEIFORM: Cuneiform. Since 1.14
+ * @PANGO_SCRIPT_PHOENICIAN: Phoenician. Since 1.14
+ * @PANGO_SCRIPT_PHAGS_PA: Phags-pa. Since 1.14
+ * @PANGO_SCRIPT_NKO: N'Ko. Since 1.14
+ * @PANGO_SCRIPT_KAYAH_LI: Kayah Li. Since 1.20.1
+ * @PANGO_SCRIPT_LEPCHA: Lepcha. Since 1.20.1
+ * @PANGO_SCRIPT_REJANG: Rejang. Since 1.20.1
+ * @PANGO_SCRIPT_SUNDANESE: Sundanese. Since 1.20.1
+ * @PANGO_SCRIPT_SAURASHTRA: Saurashtra. Since 1.20.1
+ * @PANGO_SCRIPT_CHAM: Cham. Since 1.20.1
+ * @PANGO_SCRIPT_OL_CHIKI: Ol Chiki. Since 1.20.1
+ * @PANGO_SCRIPT_VAI: Vai. Since 1.20.1
+ * @PANGO_SCRIPT_CARIAN: Carian. Since 1.20.1
+ * @PANGO_SCRIPT_LYCIAN: Lycian. Since 1.20.1
+ * @PANGO_SCRIPT_LYDIAN: Lydian. Since 1.20.1
+ * @PANGO_SCRIPT_BATAK: Batak. Since 1.32
+ * @PANGO_SCRIPT_BRAHMI: Brahmi. Since 1.32
+ * @PANGO_SCRIPT_MANDAIC: Mandaic. Since 1.32
+ * @PANGO_SCRIPT_CHAKMA: Chakma. Since: 1.32
+ * @PANGO_SCRIPT_MEROITIC_CURSIVE: Meroitic Cursive. Since: 1.32
+ * @PANGO_SCRIPT_MEROITIC_HIEROGLYPHS: Meroitic Hieroglyphs. Since: 1.32
+ * @PANGO_SCRIPT_MIAO: Miao. Since: 1.32
+ * @PANGO_SCRIPT_SHARADA: Sharada. Since: 1.32
+ * @PANGO_SCRIPT_SORA_SOMPENG: Sora Sompeng. Since: 1.32
+ * @PANGO_SCRIPT_TAKRI: Takri. Since: 1.32
+ *
+ * The #PangoScript enumeration identifies different writing
+ * systems. The values correspond to the names as defined in the
+ * Unicode standard.
+ * Note that new types may be added in the future. Applications should be ready
+ * to handle unknown values. This enumeration is interchangeable with
+ * #GUnicodeScript. See <ulink
+ * url="http://www.unicode.org/reports/tr24/";>Unicode Standard Annex
+ * #24: Script names</ulink>.
+ */
typedef enum { /* ISO 15924 code */
PANGO_SCRIPT_INVALID_CODE = -1,
PANGO_SCRIPT_COMMON = 0, /* Zyyy */
diff --git a/pango/pango-tabs.c b/pango/pango-tabs.c
index 751538c..1ffa835 100644
--- a/pango/pango-tabs.c
+++ b/pango/pango-tabs.c
@@ -19,6 +19,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:tab-stops
+ * @short_description:Structures for storing tab stops
+ * @title:Tab Stops
+ *
+ * Functions in this section are used to deal with #PangoTabArray objects
+ * that can be used to set tab stop positions in a #PangoLayout.
+ */
#include "config.h"
#include "pango-tabs.h"
#include "pango-impl-utils.h"
@@ -36,6 +44,12 @@ struct _PangoTab
*/
};
+/**
+ * PangoTabArray:
+ *
+ * A #PangoTabArray struct contains an array
+ * of tab stops. Each tab stop has an alignment and a position.
+ */
struct _PangoTabArray
{
gint size;
diff --git a/pango/pango-tabs.h b/pango/pango-tabs.h
index 7f52d1d..8a33bcb 100644
--- a/pango/pango-tabs.h
+++ b/pango/pango-tabs.h
@@ -28,6 +28,12 @@ G_BEGIN_DECLS
typedef struct _PangoTabArray PangoTabArray;
+/**
+ * PangoTabAlign:
+ * @PANGO_TAB_LEFT: the tab stop appears to the left of the text.
+ *
+ * A #PangoTabAlign specifies where a tab stop appears relative to the text.
+ */
typedef enum
{
PANGO_TAB_LEFT
@@ -41,6 +47,11 @@ typedef enum
*/
} PangoTabAlign;
+/**
+ * PANGO_TYPE_TAB_ARRAY:
+ *
+ * The #GObject type for #PangoTabArray.
+ */
#define PANGO_TYPE_TAB_ARRAY (pango_tab_array_get_type ())
PangoTabArray *pango_tab_array_new (gint initial_size,
diff --git a/pango/pango-types.h b/pango/pango-types.h
index c4ef843..0bf4bd7 100644
--- a/pango/pango-types.h
+++ b/pango/pango-types.h
@@ -40,10 +40,53 @@ typedef struct _PangoRectangle PangoRectangle;
/* A index of a glyph into a font. Rendering system dependent */
+/**
+ * PangoGlyph:
+ *
+ * A #PangoGlyph represents a single glyph in the output form of a string.
+ */
typedef guint32 PangoGlyph;
+/**
+ * PANGO_SCALE:
+ *
+ * The %PANGO_SCALE macro represents the scale between dimensions used
+ * for Pango distances and device units. (The definition of device
+ * units is dependent on the output device; it will typically be pixels
+ * for a screen, and points for a printer.) %PANGO_SCALE is currently
+ * 1024, but this may be changed in the future.
+ *
+ * When setting font sizes, device units are always considered to be
+ * points (as in "12 point font"), rather than pixels.
+ */
+/**
+ * PANGO_PIXELS:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by rounding.
+ *
+ * Return value: rounded dimension in device units.
+ */
+/**
+ * PANGO_PIXELS_FLOOR:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by flooring.
+ *
+ * Return value: floored dimension in device units.
+ * Since: 1.14
+ */
+/**
+ * PANGO_PIXELS_CEIL:
+ * @d: a dimension in Pango units.
+ *
+ * Converts a dimension to device units by ceiling.
+ *
+ * Return value: ceiled dimension in device units.
+ * Since: 1.14
+ */
#define PANGO_SCALE 1024
#define PANGO_PIXELS(d) (((int)(d) + 512) >> 10)
#define PANGO_PIXELS_FLOOR(d) (((int)(d)) >> 10)
@@ -57,6 +100,16 @@ typedef guint32 PangoGlyph;
* PANGO_PIXELS also behaves differently for +512 and -512.
*/
+/**
+ * PANGO_UNITS_ROUND:
+ * @d: a dimension in Pango units.
+ *
+ * Rounds a dimension to whole device units, but does not
+ * convert it to device units.
+ *
+ * Return value: rounded dimension in Pango units.
+ * Since: 1.18
+ */
#define PANGO_UNITS_ROUND(d) \
(((d) + (PANGO_SCALE >> 1)) & ~(PANGO_SCALE - 1))
@@ -66,8 +119,17 @@ double pango_units_to_double (int i) G_GNUC_CONST;
-/* A rectangle. Used to store logical and physical extents of glyphs,
- * runs, strings, etc.
+/**
+ * PangoRectangle:
+ * @x: X coordinate of the left side of the rectangle.
+ * @y: Y coordinate of the the top side of the rectangle.
+ * @width: width of the rectangle.
+ * @height: height of the rectangle.
+ *
+ * The #PangoRectangle structure represents a rectangle. It is frequently
+ * used to represent the logical or ink extents of a single glyph or section
+ * of text. (See, for instance, pango_font_get_glyph_extents())
+ *
*/
struct _PangoRectangle
{
@@ -79,6 +141,44 @@ struct _PangoRectangle
/* Macros to translate from extents rectangles to ascent/descent/lbearing/rbearing
*/
+/**
+ * PANGO_ASCENT:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>ascent</firstterm> from a #PangoRectangle
+ * representing glyph extents. The ascent is the distance from the
+ * baseline to the highest point of the character. This is positive if the
+ * glyph ascends above the baseline.
+ */
+/**
+ * PANGO_DESCENT:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>descent</firstterm> from a #PangoRectangle
+ * representing glyph extents. The descent is the distance from the
+ * baseline to the lowest point of the character. This is positive if the
+ * glyph descends below the baseline.
+ */
+/**
+ * PANGO_LBEARING:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>left bearing</firstterm> from a #PangoRectangle
+ * representing glyph extents. The left bearing is the distance from the
+ * horizontal origin to the farthest left point of the character.
+ * This is positive for characters drawn completely to the right of the
+ * glyph origin.
+ */
+/**
+ * PANGO_RBEARING:
+ * @rect: a #PangoRectangle
+ *
+ * Extracts the <firstterm>right bearing</firstterm> from a #PangoRectangle
+ * representing glyph extents. The right bearing is the distance from the
+ * horizontal origin to the farthest right point of the character.
+ * This is positive except for characters drawn completely to the left of the
+ * horizontal origin.
+ */
#define PANGO_ASCENT(rect) (-(rect).y)
#define PANGO_DESCENT(rect) ((rect).y + (rect).height)
#define PANGO_LBEARING(rect) ((rect).x)
diff --git a/pango/pango-utils.c b/pango/pango-utils.c
index 1ca2de6..b4ad451 100644
--- a/pango/pango-utils.c
+++ b/pango/pango-utils.c
@@ -19,6 +19,24 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pango-version
+ * @short_description:Tools for checking Pango version at compile- and run-time.
+ * @title:Version Checking
+ *
+ * The capital-letter macros defined here can be used to check the version of Pango
+ * at compile-time, and to <firstterm>encode</firstterm> Pango versions into integers.
+ *
+ * The functions can be used to check the version of the linked Pango library at run-time.
+ */
+/**
+ * SECTION:utils
+ * @short_description:Various convenience and utility functions
+ * @title: Miscellaneous Utilities
+ *
+ * The functions and utilities in this section are mostly used from Pango
+ * backends and modules, but may be useful for other purposes too.
+ */
#include "config.h"
#include <errno.h>
#include <string.h>
diff --git a/pango/pango-utils.h b/pango/pango-utils.h
index c55d6dd..9bac4f0 100644
--- a/pango/pango-utils.h
+++ b/pango/pango-utils.h
@@ -113,18 +113,62 @@ gboolean pango_is_zero_width (gunichar ch) G_GNUC_CONST;
/* Pango version checking */
/* Encode a Pango version as an integer */
+/**
+ * PANGO_VERSION_ENCODE:
+ * @major: the major component of the version number
+ * @minor: the minor component of the version number
+ * @micro: the micro component of the version number
+ *
+ * This macro encodes the given Pango version into an integer. The numbers
+ * returned by %PANGO_VERSION and pango_version() are encoded using this macro.
+ * Two encoded version numbers can be compared as integers.
+ */
#define PANGO_VERSION_ENCODE(major, minor, micro) ( \
((major) * 10000) \
+ ((minor) * 100) \
+ ((micro) * 1))
/* Encoded version of Pango at compile-time */
+/**
+ * PANGO_VERSION:
+ *
+ * The version of Pango available at compile-time, encoded using PANGO_VERSION_ENCODE().
+ */
+/**
+ * PANGO_VERSION_STRING:
+ *
+ * A string literal containing the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MAJOR:
+ *
+ * The major component of the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MINOR:
+ *
+ * The minor component of the version of Pango available at compile-time.
+ */
+/**
+ * PANGO_VERSION_MICRO:
+ *
+ * The micro component of the version of Pango available at compile-time.
+ */
#define PANGO_VERSION PANGO_VERSION_ENCODE( \
PANGO_VERSION_MAJOR, \
PANGO_VERSION_MINOR, \
PANGO_VERSION_MICRO)
/* Check that compile-time Pango is as new as required */
+/**
+ * PANGO_VERSION_CHECK:
+ * @major: the major component of the version number
+ * @minor: the minor component of the version number
+ * @micro: the micro component of the version number
+ *
+ * Checks that the version of Pango available at compile-time is not older than
+ * the provided version number.
+ */
#define PANGO_VERSION_CHECK(major,minor,micro) \
(PANGO_VERSION >= PANGO_VERSION_ENCODE(major,minor,micro))
diff --git a/pango/pangocairo-context.c b/pango/pangocairo-context.c
index 32b4ef1..9750fb0 100644
--- a/pango/pangocairo-context.c
+++ b/pango/pangocairo-context.c
@@ -260,7 +260,7 @@ pango_cairo_context_set_font_options (PangoContext *context,
* @context: a #PangoContext, from a pangocairo font map
*
* Retrieves any font rendering options previously set with
- * pango_cairo_font_map_set_font_options(). This function does not report options
+ * pango_cairo_context_set_font_options(). This function does not report options
* that are derived from the target surface by pango_cairo_update_context()
*
* Return value: the font options previously set on the context, or %NULL
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 4874344..03a2811 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -19,6 +19,139 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pangocairo
+ * @short_description:Rendering with the Cairo backend
+ * @title:Cairo Rendering
+ *
+ * The <ulink url="http://cairographics.org";>Cairo library</ulink> is a
+ * vector graphics library with a powerful rendering model. It has such
+ * features as anti-aliased primitives, alpha-compositing, and
+ * gradients. Multiple backends for Cairo are available, to allow
+ * rendering to images, to PDF files, and to the screen on X and on other
+ * windowing systems. The functions in this section allow using Pango
+ * to render to Cairo surfaces.
+ *
+ * Using Pango with Cairo is straightforward. A #PangoContext created
+ * with pango_cairo_font_map_create_context() can be used on any
+ * Cairo context (cairo_t), but needs to be updated to match the
+ * current transformation matrix and target surface of the Cairo context
+ * using pango_cairo_update_context(). The convenience functions
+ * pango_cairo_create_layout() and pango_cairo_update_layout() handle
+ * the common case where the program doesn't need to manipulate the
+ * properties of the #PangoContext.
+ *
+ * When you get the metrics of a layout or of a piece of a layout using
+ * functions such as pango_layout_get_extents(), the reported metrics
+ * are in user-space coordinates. If a piece of text is 10 units long,
+ * and you call cairo_scale (cr, 2.0), it still is more-or-less 10
+ * units long. However, the results will be affected by hinting
+ * (that is, the process of adjusting the text to look good on the
+ * pixel grid), so you shouldn't assume they are completely independent
+ * of the current transformation matrix. Note that the basic metrics
+ * functions in Pango report results in integer Pango units. To get
+ * to the floating point units used in Cairo divide by %PANGO_SCALE.
+ *
+ * <example id="rotated-example">
+ * <title>Using Pango with Cairo</title>
+ * <programlisting>
+ * #include <math.h>
+ * #include <pango/pangocairo.h>
+ *
+ * static void
+ * draw_text (cairo_t *cr)
+ * {
+ * #define RADIUS 150
+ * #define N_WORDS 10
+ * #define FONT "Sans Bold 27"
+ *
+ * PangoLayout *layout;
+ * PangoFontDescription *desc;
+ * int i;
+ *
+ * /* Center coordinates on the middle of the region we are drawing
+ * */
+ * cairo_translate (cr, RADIUS, RADIUS);
+ *
+ * /* Create a PangoLayout, set the font and text */
+ * layout = pango_cairo_create_layout (cr);
+ *
+ * pango_layout_set_text (layout, "Text", -1);
+ * desc = pango_font_description_from_string (FONT);
+ * pango_layout_set_font_description (layout, desc);
+ * pango_font_description_free (desc);
+ *
+ * /* Draw the layout N_WORDS times in a circle */
+ * for (i = 0; i < N_WORDS; i++)
+ * {
+ * int width, height;
+ * double angle = (360. * i) / N_WORDS;
+ * double red;
+ *
+ * cairo_save (cr);
+ *
+ * /* Gradient from red at angle == 60 to blue at angle == 240 */
+ * red = (1 + cos ((angle - 60) * G_PI / 180.)) / 2;
+ * cairo_set_source_rgb (cr, red, 0, 1.0 - red);
+ *
+ * cairo_rotate (cr, angle * G_PI / 180.);
+ *
+ * /* Inform Pango to re-layout the text with the new transformation */
+ * pango_cairo_update_layout (cr, layout);
+ *
+ * pango_layout_get_size (layout, &width, &height);
+ * cairo_move_to (cr, - ((double)width / PANGO_SCALE) / 2, - RADIUS);
+ * pango_cairo_show_layout (cr, layout);
+ *
+ * cairo_restore (cr);
+ * }
+ *
+ * /* free the layout object */
+ * g_object_unref (layout);
+ * }
+ *
+ * int main (int argc, char **argv)
+ * {
+ * cairo_t *cr;
+ * char *filename;
+ * cairo_status_t status;
+ * cairo_surface_t *surface;
+ *
+ * if (argc != 2)
+ * {
+ * g_printerr ("Usage: cairosimple OUTPUT_FILENAME\n");
+ * return 1;
+ * }
+ *
+ * filename = argv[1];
+ *
+ * surface = cairo_image_surface_create (CAIRO_FORMAT_ARGB32,
+ * 2 * RADIUS, 2 * RADIUS);
+ * cr = cairo_create (surface);
+ *
+ * cairo_set_source_rgb (cr, 1.0, 1.0, 1.0);
+ * cairo_paint (cr);
+ * draw_text (cr);
+ * cairo_destroy (cr);
+ *
+ * status = cairo_surface_write_to_png (surface, filename);
+ * cairo_surface_destroy (surface);
+ *
+ * if (status != CAIRO_STATUS_SUCCESS)
+ * {
+ * g_printerr ("Could not save png to '%s'\n", filename);
+ * return 1;
+ * }
+ *
+ * return 0;
+ * }
+ * </programlisting>
+ * </example>
+ * <figure id="rotated-example-output">
+ * <title>Output of <xref linkend="rotated-example"/></title>
+ * <graphic fileref="rotated-text.png" format="PNG"/>
+ * </figure>
+ */
#include "config.h"
#include <math.h>
diff --git a/pango/pangocairo.h b/pango/pangocairo.h
index 81e842d..73ad7ac 100644
--- a/pango/pangocairo.h
+++ b/pango/pangocairo.h
@@ -55,6 +55,20 @@ typedef struct _PangoCairoFontMap PangoCairoFontMap;
#define PANGO_CAIRO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_CAIRO_FONT_MAP,
PangoCairoFontMap))
#define PANGO_IS_CAIRO_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_CAIRO_FONT_MAP))
+/**
+ * PangoCairoShapeRendererFunc:
+ * @cr: a Cairo context with current point set to where the shape should
+ * be rendered
+ * @attr: the %PANGO_ATTR_SHAPE to render
+ * @do_path: whether only the shape path should be appended to current
+ * path of @cr and no filling/stroking done. This will be set
+ * to %TRUE when called from pango_cairo_layout_path() and
+ * pango_cairo_layout_line_path() rendering functions.
+ * @data: user data passed to pango_cairo_context_set_shape_renderer()
+ *
+ * Function type for rendering attributes of type %PANGO_ATTR_SHAPE
+ * with Pango's Cairo renderer.
+ */
typedef void (* PangoCairoShapeRendererFunc) (cairo_t *cr,
PangoAttrShape *attr,
gboolean do_path,
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index 36bcd82..d75b2e8 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -20,6 +20,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:coretext-fonts
+ * @short_description:Font handling with CoreText fonts
+ * @title:CoreText Fonts
+ *
+ * The macros and functions in this section are used to access fonts natively on
+ * OS X using the CoreText text rendering subsystem.
+ */
#include "config.h"
#include "pangocoretext.h"
diff --git a/pango/pangocoretext.h b/pango/pangocoretext.h
index 22dd9cb..9449189 100644
--- a/pango/pangocoretext.h
+++ b/pango/pangocoretext.h
@@ -38,6 +38,12 @@ typedef struct _PangoCoreTextFontClass PangoCoreTextFontClass;
#if defined(PANGO_ENABLE_ENGINE) || defined(PANGO_ENABLE_BACKEND)
+/**
+ * PANGO_RENDER_TYPE_CORE_TEXT:
+ *
+ * A string constant identifying the CoreText renderer. The associated quark (see
+ * g_quark_from_string()) is used to identify the renderer in pango_find_map().
+ */
#define PANGO_RENDER_TYPE_CORE_TEXT "PangoRenderCoreText"
#ifdef PANGO_ENABLE_BACKEND
diff --git a/pango/pangofc-decoder.c b/pango/pangofc-decoder.c
index 09a4eed..f11b4e0 100644
--- a/pango/pangofc-decoder.c
+++ b/pango/pangofc-decoder.c
@@ -19,6 +19,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pangofc-decoder
+ * @short_description:Custom font encoding handling
+ * @title:PangoFcDecoder
+ *
+ * PangoFcDecoder represents a decoder that an application provides
+ * for handling a font that is encoded in a custom way.
+ */
#include "config.h"
#include "pangofc-decoder.h"
diff --git a/pango/pangofc-font.c b/pango/pangofc-font.c
index 5830790..7056bca 100644
--- a/pango/pangofc-font.c
+++ b/pango/pangofc-font.c
@@ -19,6 +19,24 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pangofc-font
+ * @short_description:Base font class for Fontconfig-based backends
+ * @title:PangoFcFont
+ * @see_also:
+ * <variablelist><varlistentry><term>#PangoFcFontMap</term> <listitem>The base class for font maps; creating
a new
+ * Fontconfig-based backend involves deriving from both
+ * #PangoFcFontMap and #PangoFcFont.</listitem></varlistentry></variablelist>
+ *
+ * #PangoFcFont is a base class for font implementation using the
+ * Fontconfig and FreeType libraries. It is used in the
+ * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
+ * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
+ * backends shipped with Pango, but can also be used when creating
+ * new backends. Any backend deriving from this base class will
+ * take advantage of the wide range of shapers implemented using
+ * FreeType that come with Pango.
+ */
#include "config.h"
#include "pangofc-font.h"
diff --git a/pango/pangofc-fontmap.c b/pango/pangofc-fontmap.c
index 05fed2d..a4053f7 100644
--- a/pango/pangofc-fontmap.c
+++ b/pango/pangofc-fontmap.c
@@ -19,6 +19,27 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pangofc-fontmap
+ * @short_description:Base fontmap class for Fontconfig-based backends
+ * @title:PangoFcFontMap
+ * @see_also:
+ * <variablelist><varlistentry>
+ * <term>#PangoFcFont</term>
+ * <listitem>The base class for fonts; creating a new
+ * Fontconfig-based backend involves deriving from both
+ * #PangoFcFontMap and #PangoFcFont.</listitem>
+ * </varlistentry></variablelist>
+ *
+ * PangoFcFontMap is a base class for font map implementations using the
+ * Fontconfig and FreeType libraries. It is used in the
+ * <link linkend="pango-Xft-Fonts-and-Rendering">Xft</link> and
+ * <link linkend="pango-FreeType-Fonts-and-Rendering">FreeType</link>
+ * backends shipped with Pango, but can also be used when creating
+ * new backends. Any backend deriving from this base class will
+ * take advantage of the wide range of shapers implemented using
+ * FreeType that come with Pango.
+ */
#define FONTSET_CACHE_SIZE 256
#include "config.h"
diff --git a/pango/pangofc-fontmap.h b/pango/pangofc-fontmap.h
index 8421f18..3948b1f 100644
--- a/pango/pangofc-fontmap.h
+++ b/pango/pangofc-fontmap.h
@@ -117,7 +117,7 @@ struct _PangoFcFontMap
* may be null.
* @context_key_get: Gets an opaque key holding backend
* specific options for the context that will affect
- * fonts created by create_font(). The result must point to
+ * fonts created by @create_font(). The result must point to
* persistant storage owned by the fontmap. This key
* is used to index hash tables used to look up fontsets
* and fonts.
@@ -225,7 +225,7 @@ PangoFontDescription *pango_fc_font_description_from_pattern (FcPattern *pattern
*
* String representing a fontconfig property name that Pango sets on any
* fontconfig pattern it passes to fontconfig if a #PangoGravity other
- * than %PangoGravitySouth is desired.
+ * than %PANGO_GRAVITY_SOUTH is desired.
*
* The property will have a #PangoGravity value as a string, like "east".
* This can be used to write fontconfig configuration rules to choose
diff --git a/pango/pangoft2-fontmap.c b/pango/pangoft2-fontmap.c
index 3b43fbd..1904f01 100644
--- a/pango/pangoft2-fontmap.c
+++ b/pango/pangoft2-fontmap.c
@@ -37,6 +37,11 @@
typedef struct _PangoFT2Family PangoFT2Family;
typedef struct _PangoFT2FontMapClass PangoFT2FontMapClass;
+/**
+ * PangoFT2FontMap:
+ *
+ * The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts.
+ */
struct _PangoFT2FontMap
{
PangoFcFontMap parent_instance;
@@ -203,7 +208,7 @@ pango_ft2_font_map_set_default_substitute (PangoFT2FontMap *fontmap,
/**
* pango_ft2_font_map_substitute_changed:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
*
* Call this function any time the results of the
* default substitution function set with
@@ -224,7 +229,7 @@ pango_ft2_font_map_substitute_changed (PangoFT2FontMap *fontmap)
/**
* pango_ft2_font_map_set_resolution:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
* @dpi_x: dots per inch in the X direction
* @dpi_y: dots per inch in the Y direction
*
@@ -246,8 +251,8 @@ pango_ft2_font_map_set_resolution (PangoFT2FontMap *fontmap,
}
/**
- * pango_ft2_font_map_create_context:
- * @fontmap: a #PangoFT2Fontmap
+ * pango_ft2_font_map_create_context: (skip)
+ * @fontmap: a #PangoFT2FontMap
*
* Create a #PangoContext for the given fontmap.
*
@@ -266,12 +271,12 @@ pango_ft2_font_map_create_context (PangoFT2FontMap *fontmap)
}
/**
- * pango_ft2_get_context:
+ * pango_ft2_get_context: (skip)
* @dpi_x: the horizontal DPI of the target device
* @dpi_y: the vertical DPI of the target device
*
* Retrieves a #PangoContext for the default PangoFT2 fontmap
- * (see pango_ft2_fontmap_get_for_display()) and sets the resolution
+ * (see pango_ft2_font_map_for_display()) and sets the resolution
* for the default fontmap to @dpi_x by @dpi_y.
*
* Return value: the new #PangoContext
@@ -292,7 +297,7 @@ pango_ft2_get_context (double dpi_x, double dpi_y)
G_GNUC_END_IGNORE_DEPRECATIONS
/**
- * pango_ft2_font_map_for_display:
+ * pango_ft2_font_map_for_display: (skip)
*
* Returns a #PangoFT2FontMap. This font map is cached and should
* not be freed. If the font map is no longer needed, it can
@@ -341,7 +346,7 @@ _pango_ft2_font_map_get_library (PangoFontMap *fontmap)
/**
* _pango_ft2_font_map_get_renderer:
- * @fontmap: a #PangoFT2Fontmap
+ * @fontmap: a #PangoFT2FontMap
*
* Gets the singleton PangoFT2Renderer for this fontmap.
*
diff --git a/pango/pangoft2-render.c b/pango/pangoft2-render.c
index 42923f4..2b0ebd5 100644
--- a/pango/pangoft2-render.c
+++ b/pango/pangoft2-render.c
@@ -20,6 +20,17 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:pango-renderer
+ * @short_description:Rendering driver base class
+ * @title:PangoRenderer
+ *
+ * #PangoRenderer is a base class that contains the necessary logic for
+ * rendering a #PangoLayout or #PangoLayoutLine. By subclassing
+ * #PangoRenderer and overriding operations such as @draw_glyphs and
+ * @draw_rectangle, renderers for particular font backends and
+ * destinations can be created.
+ */
#include "config.h"
#include <math.h>
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index dc6db5d..3ada81c 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -20,6 +20,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:freetype-fonts
+ * @short_description:Functions for shape engines to manipulate FreeType fonts
+ * @title:FreeType Fonts and Rendering
+ *
+ * The macros and functions in this section are used to access fonts and render
+ * text to bitmaps using the FreeType 2 library.
+ */
#include "config.h"
#include <string.h>
@@ -467,12 +475,13 @@ pango_ft2_font_finalize (GObject *object)
/**
* pango_ft2_font_get_coverage:
- * @font: a #PangoFT2Font.
+ * @font: a <type>PangoFT2Font</type>.
* @language: a language tag.
- * @returns: a #PangoCoverage.
*
- * Gets the #PangoCoverage for a #PangoFT2Font. Use
+ * Gets the #PangoCoverage for a <type>PangoFT2Font</type>. Use
* pango_font_get_coverage() instead.
+ *
+ * Return value: a #PangoCoverage.
**/
PangoCoverage *
pango_ft2_font_get_coverage (PangoFont *font,
diff --git a/pango/pangoft2.h b/pango/pangoft2.h
index d2ba13d..2b9083c 100644
--- a/pango/pangoft2.h
+++ b/pango/pangoft2.h
@@ -31,6 +31,12 @@
G_BEGIN_DECLS
#ifndef PANGO_DISABLE_DEPRECATED
+/**
+ * PANGO_RENDER_TYPE_FT2:
+ *
+ * A string constant that was used to identify shape engines that work
+ * with the FreeType backend. See %PANGO_RENDER_TYPE_FC for the replacement.
+ */
#define PANGO_RENDER_TYPE_FT2 "PangoRenderFT2"
#endif
@@ -40,6 +46,13 @@ G_BEGIN_DECLS
typedef struct _PangoFT2FontMap PangoFT2FontMap;
+/**
+ * PangoFT2SubstituteFunc:
+ * @pattern: the <type>FcPattern</type> to tweak.
+ * @data: user data.
+ *
+ * Function type for doing final config tweaking on prepared FcPatterns.
+ */
typedef void (*PangoFT2SubstituteFunc) (FcPattern *pattern,
gpointer data);
diff --git a/pango/pangowin32-fontcache.c b/pango/pangowin32-fontcache.c
index cc389ee..a7cfec6 100644
--- a/pango/pangowin32-fontcache.c
+++ b/pango/pangowin32-fontcache.c
@@ -35,6 +35,11 @@
typedef struct _CacheEntry CacheEntry;
+/**
+ * PangoWin32FontCache:
+ *
+ * A #PangoWin32FontCache caches HFONTs by their LOGFONT descriptions.
+ */
struct _PangoWin32FontCache
{
GHashTable *forward;
diff --git a/pango/pangowin32-fontmap.c b/pango/pangowin32-fontmap.c
index 68ec2ee..3070068 100644
--- a/pango/pangowin32-fontmap.c
+++ b/pango/pangowin32-fontmap.c
@@ -736,7 +736,7 @@ _pango_win32_font_map_class_init (PangoWin32FontMapClass *class)
/**
* pango_win32_font_map_for_display:
*
- * Returns a #PangoWin32FontMap. Font maps are cached and should
+ * Returns a <type>PangoWin32FontMap</type>. Font maps are cached and should
* not be freed. If the font map is no longer needed, it can
* be released with pango_win32_shutdown_display().
*
@@ -1658,7 +1658,7 @@ pango_win32_face_list_sizes (PangoFontFace *face,
/**
* pango_win32_font_map_get_font_cache:
- * @font_map: a #PangoWin32FontMap.
+ * @font_map: a <type>PangoWin32FontMap</type>.
*
* Obtains the font cache associated with the given font map.
*
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index bb5b975..6948037 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -22,6 +22,14 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:win32-fonts
+ * @short_description:Functions for shape engines to manipulate Win32 fonts
+ * @title:Win32 Fonts and Rendering
+ *
+ * The macros and functions in this section are used to access fonts natively on
+ * Win32 systems and to render text in conjunction with Win32 APIs.
+ */
#include "config.h"
#include <string.h>
diff --git a/pango/pangowin32.h b/pango/pangowin32.h
index a27c473..ecfe5f8 100644
--- a/pango/pangowin32.h
+++ b/pango/pangowin32.h
@@ -37,6 +37,12 @@ G_BEGIN_DECLS
#include <windows.h>
#undef STRICT
+/**
+ * PANGO_RENDER_TYPE_WIN32:
+ *
+ * A string constant identifying the Win32 renderer. The associated quark (see
+ * g_quark_from_string()) is used to identify the renderer in pango_find_map().
+ */
#define PANGO_RENDER_TYPE_WIN32 "PangoRenderWin32"
/* Calls for applications
diff --git a/pango/pangoxft-font.c b/pango/pangoxft-font.c
index 2b1b674..4e5dcb7 100644
--- a/pango/pangoxft-font.c
+++ b/pango/pangoxft-font.c
@@ -19,6 +19,36 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:xft-fonts
+ * @short_description:Font handling and rendering with the Xft backend
+ * @title:Xft Fonts and Rendering
+ *
+ * The Xft library is a library for displaying fonts on the X window
+ * system; internally it uses the fontconfig library to locate font
+ * files, and the FreeType library to load and render fonts. The
+ * Xft backend is the recommended Pango font backend for screen
+ * display with X. (The <link linkend="pango-Cairo-Rendering">Cairo back end</link> is another possibility.)
+ *
+ * Using the Xft backend is generally straightforward;
+ * pango_xft_get_context() creates a context for a specified display
+ * and screen. You can then create a #PangoLayout with that context
+ * and render it with pango_xft_render_layout(). At a more advanced
+ * level, the low-level fontconfig options used for rendering fonts
+ * can be affected using pango_xft_set_default_substitute(), and
+ * pango_xft_substitute_changed().
+ *
+ * A range of functions for drawing pieces of a layout, such as
+ * individual layout lines and glyphs strings are provided. You can also
+ * directly create a #PangoXftRenderer. Finally, in some advanced cases, it
+ * is useful to derive from #PangoXftRenderer. Deriving from
+ * #PangoXftRenderer is useful for two reasons. One reason is be to
+ * support custom attributes by overriding #PangoRendererClass virtual
+ * functions like 'prepare_run' or 'draw_shape'. The reason is to
+ * customize exactly how the final bits are drawn to the destination by
+ * overriding the #PangoXftRendererClass virtual functions
+ * 'composite_glyphs' and 'composite_trapezoids'.
+ */
#include "config.h"
#include <stdlib.h>
diff --git a/pango/pangoxft-fontmap.c b/pango/pangoxft-fontmap.c
index 4976890..fd96816 100644
--- a/pango/pangoxft-fontmap.c
+++ b/pango/pangoxft-fontmap.c
@@ -213,7 +213,7 @@ register_display (Display *display)
* @display: an X display
* @screen: the screen number of a screen within @display
*
- * Returns the #PangoXftFontmap for the given display and screen.
+ * Returns the #PangoXftFontMap for the given display and screen.
* The fontmap is owned by Pango and will be valid until
* the display is closed.
*
@@ -389,7 +389,7 @@ pango_xft_get_context (Display *display,
/**
* _pango_xft_font_map_get_renderer:
- * @fontmap: a #PangoXftFontmap
+ * @fontmap: a #PangoXftFontMap
*
* Gets the singleton #PangoXFTRenderer for this fontmap.
*
diff --git a/pango/pangoxft.h b/pango/pangoxft.h
index c5c7501..da0c331 100644
--- a/pango/pangoxft.h
+++ b/pango/pangoxft.h
@@ -31,18 +31,44 @@
G_BEGIN_DECLS
+/**
+ * PANGO_RENDER_TYPE_XFT:
+ *
+ * A string constant that was used to identify shape engines that work
+ * with the Xft backend. See %PANGO_RENDER_TYPE_FC for the replacement.
+ */
#ifndef PANGO_DISABLE_DEPRECATED
#define PANGO_RENDER_TYPE_XFT "PangoRenderXft"
#endif
+/**
+ * PangoXftFontMap:
+ *
+ * #PangoXftFontMap is an implementation of #PangoFcFontMap suitable for
+ * the Xft library as the renderer. It is used in to create fonts of
+ * type #PangoXftFont.
+ */
#define PANGO_TYPE_XFT_FONT_MAP (pango_xft_font_map_get_type ())
#define PANGO_XFT_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_XFT_FONT_MAP,
PangoXftFontMap))
#define PANGO_XFT_IS_FONT_MAP(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_XFT_FONT_MAP))
typedef struct _PangoXftFontMap PangoXftFontMap;
+/**
+ * PangoXftFont:
+ *
+ * #PangoXftFont is an implementation of #PangoFcFont using the Xft
+ * library for rendering. It is used in conjunction with #PangoXftFontMap.
+ */
typedef struct _PangoXftFont PangoXftFont;
+/**
+ * PangoXftSubstituteFunc:
+ * @pattern: the FcPattern to tweak.
+ * @data: user data.
+ *
+ * Function type for doing final config tweaking on prepared FcPatterns.
+ */
typedef void (*PangoXftSubstituteFunc) (FcPattern *pattern,
gpointer data);
diff --git a/pango/shape.c b/pango/shape.c
index 63c36ab..7c805de 100644
--- a/pango/shape.c
+++ b/pango/shape.c
@@ -19,6 +19,16 @@
* Boston, MA 02111-1307, USA.
*/
+/**
+ * SECTION:glyphs
+ * @short_description:Structures for storing information about glyphs
+ * @title:Glyph Storage
+ *
+ * pango_shape() produces a string of glyphs which
+ * can be measured or drawn to the screen. The following
+ * structures are used to store information about
+ * glyphs.
+ */
#include "config.h"
#include "pango-impl-utils.h"
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
