diff options
| author | Behdad Esfahbod <behdad@behdad.org> | 2013-09-27 14:36:51 -0400 |
|---|---|---|
| committer | Behdad Esfahbod <behdad@behdad.org> | 2013-09-27 14:36:51 -0400 |
| commit | 6d08bcab0d2821365a2ffd955cbbb07270565664 (patch) | |
| tree | 6bffdc716a62ea60c0db7ed08d7f5a0d205302f1 | |
| parent | bb5c4c8497157afddcb5ced7e16c5dad4e893a03 (diff) | |
| download | pango-6d08bcab0d2821365a2ffd955cbbb07270565664.tar.gz | |
Bug 685167 - migrate docs to no-tmpl flavour
Patch from Rafał Mużyło.
85 files changed, 1975 insertions, 8026 deletions
diff --git a/configure.ac b/configure.ac index 5e97e020..fd64d95b 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 fe7d0182..56cb6f6f 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 02eba9dd..41db64d3 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/docs/tmpl/bidi.sgml b/docs/tmpl/bidi.sgml deleted file mode 100644 index e02d1ec9..00000000 --- a/docs/tmpl/bidi.sgml +++ /dev/null @@ -1,108 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Bidirectional Text - -<!-- ##### SECTION Short_Description ##### --> -Types and functions to help with handling bidirectional text - -<!-- ##### SECTION Long_Description ##### --> -<para> -Pango supports bidirectional text (like Arabic and Hebrew) automatically. -Some applications however, need some help to correctly handle bidirectional -text. -</para> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -pango_context_get_base_dir(), -pango_context_set_base_dir(), -pango_itemize_with_base_dir() -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### ENUM PangoDirection ##### --> -<para> -</para> - -@PANGO_DIRECTION_LTR: -@PANGO_DIRECTION_RTL: -@PANGO_DIRECTION_TTB_LTR: -@PANGO_DIRECTION_TTB_RTL: -@PANGO_DIRECTION_WEAK_LTR: -@PANGO_DIRECTION_WEAK_RTL: -@PANGO_DIRECTION_NEUTRAL: - -<!-- ##### FUNCTION pango_unichar_direction ##### --> -<para> - -</para> - -@ch: -@Returns: - - -<!-- ##### FUNCTION pango_find_base_dir ##### --> -<para> - -</para> - -@text: -@length: -@Returns: - - -<!-- ##### FUNCTION pango_get_mirror_char ##### --> -<para> - -</para> - -@ch: -@mirrored_ch: -@Returns: - - -<!-- ##### ENUM PangoBidiType ##### --> -<para> - -</para> - -@PANGO_BIDI_TYPE_L: -@PANGO_BIDI_TYPE_LRE: -@PANGO_BIDI_TYPE_LRO: -@PANGO_BIDI_TYPE_R: -@PANGO_BIDI_TYPE_AL: -@PANGO_BIDI_TYPE_RLE: -@PANGO_BIDI_TYPE_RLO: -@PANGO_BIDI_TYPE_PDF: -@PANGO_BIDI_TYPE_EN: -@PANGO_BIDI_TYPE_ES: -@PANGO_BIDI_TYPE_ET: -@PANGO_BIDI_TYPE_AN: -@PANGO_BIDI_TYPE_CS: -@PANGO_BIDI_TYPE_NSM: -@PANGO_BIDI_TYPE_BN: -@PANGO_BIDI_TYPE_B: -@PANGO_BIDI_TYPE_S: -@PANGO_BIDI_TYPE_WS: -@PANGO_BIDI_TYPE_ON: - -<!-- ##### FUNCTION pango_bidi_type_for_unichar ##### --> -<para> - -</para> - -@ch: -@Returns: - - diff --git a/docs/tmpl/coretext-fonts.sgml b/docs/tmpl/coretext-fonts.sgml deleted file mode 100644 index 69d5d029..00000000 --- a/docs/tmpl/coretext-fonts.sgml +++ /dev/null @@ -1,40 +0,0 @@ -<!-- ##### SECTION Title ##### --> -CoreText Fonts - -<!-- ##### SECTION Short_Description ##### --> -Font handling with CoreText fonts - -<!-- ##### SECTION Long_Description ##### --> -<para> -The macros and functions in this section are used to access fonts natively on -OS X using the CoreText text rendering subsystem. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### MACRO PANGO_RENDER_TYPE_CORE_TEXT ##### --> -<para> -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(). -</para> - - - -<!-- ##### FUNCTION pango_core_text_font_get_ctfont ##### --> -<para> - -</para> - -@font: -@Returns: - - diff --git a/docs/tmpl/coverage-maps.sgml b/docs/tmpl/coverage-maps.sgml deleted file mode 100644 index 7e0ced9c..00000000 --- a/docs/tmpl/coverage-maps.sgml +++ /dev/null @@ -1,140 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Coverage Maps - -<!-- ##### SECTION Short_Description ##### --> -Unicode character range coverage storage - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### ENUM PangoCoverageLevel ##### --> -<para> -Used to indicate how well a font can represent a particular Unicode -character point for a particular script. -</para> - -@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. - -<!-- ##### MACRO PANGO_TYPE_COVERAGE_LEVEL ##### --> -<para> -The #GObject type for #PangoCoverageLevel. -</para> - - - -<!-- ##### STRUCT PangoCoverage ##### --> -<para> -The #PangoCoverage structure represents a map from Unicode characters -to #PangoCoverageLevel. It is an opaque structure with no public fields. -</para> - - -<!-- ##### FUNCTION pango_coverage_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_coverage_ref ##### --> -<para> - -</para> - -@coverage: -@Returns: - - -<!-- ##### FUNCTION pango_coverage_unref ##### --> -<para> - -</para> - -@coverage: - - -<!-- ##### FUNCTION pango_coverage_copy ##### --> -<para> - -</para> - -@coverage: -@Returns: - - -<!-- ##### FUNCTION pango_coverage_get ##### --> -<para> - -</para> - -@coverage: -@index_: -@Returns: - - -<!-- ##### FUNCTION pango_coverage_max ##### --> -<para> - -</para> - -@coverage: -@other: - - -<!-- ##### FUNCTION pango_coverage_set ##### --> -<para> - -</para> - -@coverage: -@index_: -@level: - - -<!-- ##### FUNCTION pango_coverage_to_bytes ##### --> -<para> - -</para> - -@coverage: -@bytes: -@n_bytes: - - -<!-- ##### FUNCTION pango_coverage_from_bytes ##### --> -<para> - -</para> - -@bytes: -@n_bytes: -@Returns: - - diff --git a/docs/tmpl/engines.sgml b/docs/tmpl/engines.sgml deleted file mode 100644 index f9c56c6a..00000000 --- a/docs/tmpl/engines.sgml +++ /dev/null @@ -1,120 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Engines - -<!-- ##### SECTION Short_Description ##### --> -Language-specific and rendering-system-specific processing - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoEngineInfo ##### --> -<para> -The #PangoEngineInfo structure contains information about a particular -engine. It contains the following fields: -</para> - -@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. - -<!-- ##### STRUCT PangoEngineScriptInfo ##### --> -<para> -The #PangoEngineScriptInfo structure contains -information about how the shaper covers a particular -script. -</para> - -@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. - -<!-- ##### STRUCT PangoEngine ##### --> -<para> -</para> - - -<!-- ##### STRUCT PangoEngineClass ##### --> -<para> - -</para> - - -<!-- ##### MACRO PANGO_RENDER_TYPE_NONE ##### --> -<para> -A string constant defining the render type -for engines that are not rendering-system -specific. -</para> - - - -<!-- ##### FUNCTION script_engine_list ##### --> -<para> -</para> - -@engines: location to store a pointer to an array of engines. -@n_engines: location to store the number of elements in @engines. - - -<!-- ##### FUNCTION script_engine_init ##### --> -<para> - -</para> - -@module: - - -<!-- ##### FUNCTION script_engine_exit ##### --> -<para> - -</para> - -@void: - - -<!-- ##### FUNCTION script_engine_create ##### --> -<para> - -</para> - -@id: -@Returns: - - diff --git a/docs/tmpl/fonts.sgml b/docs/tmpl/fonts.sgml deleted file mode 100644 index ef83dd0f..00000000 --- a/docs/tmpl/fonts.sgml +++ /dev/null @@ -1,1036 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Fonts - -<!-- ##### SECTION Short_Description ##### --> -Structures representing abstract fonts - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoFontDescription ##### --> -<para> -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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT_DESCRIPTION ##### --> -<para> -The #GObject type for #PangoFontDescription. -</para> - - - -<!-- ##### ENUM PangoStyle ##### --> -<para> -</para> - -@PANGO_STYLE_NORMAL: -@PANGO_STYLE_OBLIQUE: -@PANGO_STYLE_ITALIC: - -<!-- ##### MACRO PANGO_TYPE_STYLE ##### --> -<para> -The #GObject type for #PangoStyle. -</para> - - - -<!-- ##### ENUM PangoWeight ##### --> -<para> -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: -</para> - -@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) - -<!-- ##### MACRO PANGO_TYPE_WEIGHT ##### --> -<para> -The #GObject type for #PangoWeight. -</para> - - - -<!-- ##### ENUM PangoVariant ##### --> -<para> -An enumeration specifying capitalization variant of the font. -</para> - -@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. - -<!-- ##### MACRO PANGO_TYPE_VARIANT ##### --> -<para> -The #GObject type for #PangoVariant. -</para> - - - -<!-- ##### ENUM PangoStretch ##### --> -<para> -An enumeration specifying the width of the font relative to other designs -within a family. -</para> - -@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 - -<!-- ##### MACRO PANGO_TYPE_STRETCH ##### --> -<para> -The #GObject type for #PangoStretch. -</para> - - - -<!-- ##### ENUM PangoFontMask ##### --> -<para> -The bits in a #PangoFontMask correspond to fields in a -#PangoFontDescription that have been set. -</para> - -@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.) - -<!-- ##### MACRO PANGO_TYPE_FONT_MASK ##### --> -<para> -The #GObject type for #PangoFontMask. -</para> - - - -<!-- ##### FUNCTION pango_font_description_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_copy ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_copy_static ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_hash ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_equal ##### --> -<para> - -</para> - -@desc1: -@desc2: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_free ##### --> -<para> - -</para> - -@desc: - - -<!-- ##### FUNCTION pango_font_descriptions_free ##### --> -<para> - -</para> - -@descs: -@n_descs: - - -<!-- ##### FUNCTION pango_font_description_set_family ##### --> -<para> - -</para> - -@desc: -@family: - - -<!-- ##### FUNCTION pango_font_description_set_family_static ##### --> -<para> - -</para> - -@desc: -@family: - - -<!-- ##### FUNCTION pango_font_description_get_family ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_style ##### --> -<para> - -</para> - -@desc: -@style: - - -<!-- ##### FUNCTION pango_font_description_get_style ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_variant ##### --> -<para> - -</para> - -@desc: -@variant: - - -<!-- ##### FUNCTION pango_font_description_get_variant ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_weight ##### --> -<para> - -</para> - -@desc: -@weight: - - -<!-- ##### FUNCTION pango_font_description_get_weight ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_stretch ##### --> -<para> - -</para> - -@desc: -@stretch: - - -<!-- ##### FUNCTION pango_font_description_get_stretch ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_size ##### --> -<para> - -</para> - -@desc: -@size: - - -<!-- ##### FUNCTION pango_font_description_get_size ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_absolute_size ##### --> -<para> - -</para> - -@desc: -@size: - - -<!-- ##### FUNCTION pango_font_description_get_size_is_absolute ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_set_gravity ##### --> -<para> - -</para> - -@desc: -@gravity: - - -<!-- ##### FUNCTION pango_font_description_get_gravity ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_get_set_fields ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_unset_fields ##### --> -<para> - -</para> - -@desc: -@to_unset: - - -<!-- ##### FUNCTION pango_font_description_merge ##### --> -<para> - -</para> - -@desc: -@desc_to_merge: -@replace_existing: - - -<!-- ##### FUNCTION pango_font_description_merge_static ##### --> -<para> - -</para> - -@desc: -@desc_to_merge: -@replace_existing: - - -<!-- ##### FUNCTION pango_font_description_better_match ##### --> -<para> - -</para> - -@desc: -@old_match: -@new_match: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_from_string ##### --> -<para> - -</para> - -@str: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_to_string ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_description_to_filename ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### STRUCT PangoFontMetrics ##### --> -<para> -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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT_METRICS ##### --> -<para> -The #GObject type for #PangoFontMetrics. -</para> - - - -<!-- ##### FUNCTION pango_font_metrics_ref ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_unref ##### --> -<para> - -</para> - -@metrics: - - -<!-- ##### FUNCTION pango_font_metrics_get_ascent ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_descent ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_approximate_char_width ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_approximate_digit_width ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_underline_thickness ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_underline_position ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_strikethrough_thickness ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### FUNCTION pango_font_metrics_get_strikethrough_position ##### --> -<para> - -</para> - -@metrics: -@Returns: - - -<!-- ##### STRUCT PangoFont ##### --> -<para> -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. -</para> -<para> -The #PangoFont structure contains one member -which the implementation fills in. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT ##### --> -<para> -The #GObject type for #PangoFont. -</para> - - - -<!-- ##### MACRO PANGO_FONT ##### --> -<para> -Casts a #GObject to a #PangoFont. -</para> - -@object: a #GObject. - - -<!-- ##### MACRO PANGO_IS_FONT ##### --> -<para> -Returns %TRUE if @object is a #PangoFont. -</para> - -@object: a #GObject. - - -<!-- ##### FUNCTION pango_font_find_shaper ##### --> -<para> - -</para> - -@font: -@language: -@ch: -@Returns: - - -<!-- ##### FUNCTION pango_font_describe ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_font_describe_with_absolute_size ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_font_get_coverage ##### --> -<para> - -</para> - -@font: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_font_get_glyph_extents ##### --> -<para> - -</para> - -@font: -@glyph: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_font_get_metrics ##### --> -<para> - -</para> - -@font: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_font_get_font_map ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### STRUCT PangoFontFamily ##### --> -<para> -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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT_FAMILY ##### --> -<para> -The #GObject type for #PangoFontFamily. -</para> - - - -<!-- ##### MACRO PANGO_FONT_FAMILY ##### --> -<para> -Casts a #GObject to a #PangoFontFamily. -</para> - -@object: a #GObject. - - -<!-- ##### MACRO PANGO_IS_FONT_FAMILY ##### --> -<para> -Returns %TRUE if @object is a #PangoFontFamily. -</para> - -@object: a #GObject. - - -<!-- ##### FUNCTION pango_font_family_get_name ##### --> -<para> - -</para> - -@family: -@Returns: - - -<!-- ##### FUNCTION pango_font_family_is_monospace ##### --> -<para> - -</para> - -@family: -@Returns: - - -<!-- ##### FUNCTION pango_font_family_list_faces ##### --> -<para> - -</para> - -@family: -@faces: -@n_faces: - - -<!-- ##### STRUCT PangoFontFace ##### --> -<para> -The #PangoFontFace structure is used to represent a group of fonts with -the same family, slant, weight, width, but varying sizes. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT_FACE ##### --> -<para> -The #GObject type for #PangoFontFace. -</para> - - - -<!-- ##### MACRO PANGO_FONT_FACE ##### --> -<para> -Casts a #GObject to a #PangoFontFace. -</para> - -@object: a #GObject. - - -<!-- ##### MACRO PANGO_IS_FONT_FACE ##### --> -<para> -Returns %TRUE if @object is a #PangoFontFace. -</para> - -@object: a #GObject. - - -<!-- ##### FUNCTION pango_font_face_get_face_name ##### --> -<para> - -</para> - -@face: -@Returns: - - -<!-- ##### FUNCTION pango_font_face_list_sizes ##### --> -<para> - -</para> - -@face: -@sizes: -@n_sizes: - - -<!-- ##### FUNCTION pango_font_face_describe ##### --> -<para> - -</para> - -@face: -@Returns: - - -<!-- ##### FUNCTION pango_font_face_is_synthesized ##### --> -<para> - -</para> - -@face: -@Returns: - - -<!-- ##### STRUCT PangoFontMap ##### --> -<para> -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. -</para> -<para> -The #PangoFontMap structure contains one member which the implementation -fills in. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONT_MAP ##### --> -<para> -The #GObject type for #PangoFontMap. -</para> - - - -<!-- ##### MACRO PANGO_FONT_MAP ##### --> -<para> -Casts a #GObject to a #PangoFontMap. -</para> - -@object: a #GObject. - - -<!-- ##### MACRO PANGO_IS_FONT_MAP ##### --> -<para> -Returns %TRUE if @object is a #PangoFontMap. -</para> - -@object: a #GObject. - - -<!-- ##### STRUCT PangoFontMapClass ##### --> -<para> -The #PangoFontMapClass structure holds the virtual functions for -a particular #PangoFontMap implementation. -</para> - -@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 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(). - -<!-- ##### MACRO PANGO_FONT_MAP_CLASS ##### --> -<para> -Casts a #GObject to a #PangoFontMapClass. -</para> - -@klass: a #GObject. - - -<!-- ##### MACRO PANGO_IS_FONT_MAP_CLASS ##### --> -<para> -Returns %TRUE if @klass is a subtype of #PangoFontMapClass. -</para> - -@klass: a #GObject. - - -<!-- ##### MACRO PANGO_FONT_MAP_GET_CLASS ##### --> -<para> -Returns the type of a #PangoFontMap. -</para> - -@obj: a #PangoFontMap. - - -<!-- ##### FUNCTION pango_font_map_create_context ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### FUNCTION pango_font_map_load_font ##### --> -<para> - -</para> - -@fontmap: -@context: -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_font_map_load_fontset ##### --> -<para> - -</para> - -@fontmap: -@context: -@desc: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_font_map_list_families ##### --> -<para> - -</para> - -@fontmap: -@families: -@n_families: - - -<!-- ##### FUNCTION pango_font_map_get_shape_engine_type ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### FUNCTION pango_font_map_get_serial ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### STRUCT PangoFontset ##### --> -<para> -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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONTSET ##### --> -<para> -The #GObject type for #PangoFontset. -</para> - - - -<!-- ##### STRUCT PangoFontsetClass ##### --> -<para> -The #PangoFontsetClass structure holds the virtual functions for -a particular #PangoFontset implementation. -</para> - -@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(). - -<!-- ##### FUNCTION pango_fontset_get_font ##### --> -<para> - -</para> - -@fontset: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_fontset_get_metrics ##### --> -<para> - -</para> - -@fontset: -@Returns: - - -<!-- ##### USER_FUNCTION PangoFontsetForeachFunc ##### --> -<para> - -</para> - -@fontset: -@font: -@user_data: -@Returns: - - -<!-- ##### FUNCTION pango_fontset_foreach ##### --> -<para> - -</para> - -@fontset: -@func: -@data: - - -<!-- ##### STRUCT PangoFontsetSimple ##### --> -<para> -#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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_FONTSET_SIMPLE ##### --> -<para> -The #GObject type for #PangoFontsetSimple. -</para> - - - -<!-- ##### FUNCTION pango_fontset_simple_new ##### --> -<para> - -</para> - -@language: -@Returns: - - -<!-- ##### FUNCTION pango_fontset_simple_append ##### --> -<para> - -</para> - -@fontset: -@font: - - -<!-- ##### FUNCTION pango_fontset_simple_size ##### --> -<para> - -</para> - -@fontset: -@Returns: - - diff --git a/docs/tmpl/freetype-fonts.sgml b/docs/tmpl/freetype-fonts.sgml deleted file mode 100644 index 2ed58bd3..00000000 --- a/docs/tmpl/freetype-fonts.sgml +++ /dev/null @@ -1,228 +0,0 @@ -<!-- ##### SECTION Title ##### --> -FreeType Fonts and Rendering - -<!-- ##### SECTION Short_Description ##### --> -Functions for shape engines to manipulate FreeType fonts - -<!-- ##### SECTION Long_Description ##### --> -<para> -The macros and functions in this section are used to access fonts and render -text to bitmaps using the FreeType 2 library. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoFT2FontMap ##### --> -<para> -The #PangoFT2FontMap is the #PangoFontMap implementation for FreeType fonts. -</para> - - -<!-- ##### MACRO PANGO_RENDER_TYPE_FT2 ##### --> -<para> -A string constant that was used to identify shape engines that work -with the FreeType backend. See %PANGO_RENDER_TYPE_FC for the replacement. -</para> - - - -<!-- ##### FUNCTION pango_ft2_font_map_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_font_map_set_resolution ##### --> -<para> - -</para> - -@fontmap: -@dpi_x: -@dpi_y: - - -<!-- ##### FUNCTION pango_ft2_font_map_create_context ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### USER_FUNCTION PangoFT2SubstituteFunc ##### --> -<para> -Function type for doing final config tweaking on prepared FcPatterns. -</para> - -@pattern: the <type>FcPattern</type> to tweak. -@data: user data. - - -<!-- ##### FUNCTION pango_ft2_font_map_set_default_substitute ##### --> -<para> - -</para> - -@fontmap: -@func: -@data: -@notify: - - -<!-- ##### FUNCTION pango_ft2_font_map_substitute_changed ##### --> -<para> - -</para> - -@fontmap: - - -<!-- ##### FUNCTION pango_ft2_get_context ##### --> -<para> - -</para> - -@dpi_x: -@dpi_y: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_render ##### --> -<para> - -</para> - -@bitmap: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_render_transformed ##### --> -<para> - -</para> - -@bitmap: -@matrix: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_render_layout_line ##### --> -<para> - -</para> - -@bitmap: -@line: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_render_layout_line_subpixel ##### --> -<para> - -</para> - -@bitmap: -@line: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_render_layout ##### --> -<para> - -</para> - -@bitmap: -@layout: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_render_layout_subpixel ##### --> -<para> - -</para> - -@bitmap: -@layout: -@x: -@y: - - -<!-- ##### FUNCTION pango_ft2_get_unknown_glyph ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_font_get_kerning ##### --> -<para> - -</para> - -@font: -@left: -@right: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_font_get_face ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_font_get_coverage ##### --> -<para> - -</para> - -@font: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_font_map_for_display ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_ft2_shutdown_display ##### --> -<para> - -</para> - -@void: - - diff --git a/docs/tmpl/glyphs.sgml b/docs/tmpl/glyphs.sgml deleted file mode 100644 index 926bf539..00000000 --- a/docs/tmpl/glyphs.sgml +++ /dev/null @@ -1,694 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Glyph Storage - -<!-- ##### SECTION Short_Description ##### --> -Structures for storing information about glyphs - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### MACRO PANGO_SCALE ##### --> -<para> -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. -</para> -<para> -When setting font sizes, device units are always considered to be -points (as in "12 point font"), rather than pixels. -</para> - - - -<!-- ##### MACRO PANGO_PIXELS ##### --> -<para> -Converts a dimension to device units by rounding. -</para> - -@d: a dimension in Pango units. -@Returns: rounded dimension in device units. - - -<!-- ##### MACRO PANGO_PIXELS_FLOOR ##### --> -<para> -Converts a dimension to device units by flooring. -</para> - -@d: a dimension in Pango units. -@Returns: floored dimension in device units. -@Since: 1.14 - - -<!-- ##### MACRO PANGO_PIXELS_CEIL ##### --> -<para> -Converts a dimension to device units by ceiling. -</para> - -@d: a dimension in Pango units. -@Returns: ceiled dimension in device units. -@Since: 1.14 - - -<!-- ##### MACRO PANGO_UNITS_ROUND ##### --> -<para> -Rounds a dimension to whole device units, but does not -convert it to device units. -</para> - -@d: a dimension in Pango units. -@Returns: rounded dimension in Pango units. -@Since: 1.18 - - -<!-- ##### FUNCTION pango_units_to_double ##### --> -<para> - -</para> - -@i: -@Returns: - - -<!-- ##### FUNCTION pango_units_from_double ##### --> -<para> - -</para> - -@d: -@Returns: - - -<!-- ##### STRUCT PangoRectangle ##### --> -<para> -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()) -</para> - -@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. - -<!-- ##### MACRO PANGO_ASCENT ##### --> -<para> -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. -</para> - -@rect: a #PangoRectangle - - -<!-- ##### MACRO PANGO_DESCENT ##### --> -<para> -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. -</para> - -@rect: a #PangoRectangle - - -<!-- ##### MACRO PANGO_LBEARING ##### --> -<para> -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. -</para> - -@rect: a #PangoRectangle - - -<!-- ##### MACRO PANGO_RBEARING ##### --> -<para> -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. -</para> - -@rect: a #PangoRectangle - - -<!-- ##### FUNCTION pango_extents_to_pixels ##### --> -<para> - -</para> - -@inclusive: -@nearest: - - -<!-- ##### STRUCT PangoMatrix ##### --> -<para> - -</para> - - -<!-- ##### MACRO PANGO_TYPE_MATRIX ##### --> -<para> - -</para> - - - -<!-- ##### MACRO PANGO_MATRIX_INIT ##### --> -<para> - -</para> - - - -<!-- ##### FUNCTION pango_matrix_copy ##### --> -<para> - -</para> - -@matrix: -@Returns: - - -<!-- ##### FUNCTION pango_matrix_free ##### --> -<para> - -</para> - -@matrix: - - -<!-- ##### FUNCTION pango_matrix_translate ##### --> -<para> - -</para> - -@matrix: -@tx: -@ty: - - -<!-- ##### FUNCTION pango_matrix_scale ##### --> -<para> - -</para> - -@matrix: -@scale_x: -@scale_y: - - -<!-- ##### FUNCTION pango_matrix_rotate ##### --> -<para> - -</para> - -@matrix: -@degrees: - - -<!-- ##### FUNCTION pango_matrix_concat ##### --> -<para> - -</para> - -@matrix: -@new_matrix: - - -<!-- ##### FUNCTION pango_matrix_transform_point ##### --> -<para> - -</para> - -@matrix: -@x: -@y: - - -<!-- ##### FUNCTION pango_matrix_transform_distance ##### --> -<para> - -</para> - -@matrix: -@dx: -@dy: - - -<!-- ##### FUNCTION pango_matrix_transform_rectangle ##### --> -<para> - -</para> - -@matrix: -@rect: - - -<!-- ##### FUNCTION pango_matrix_transform_pixel_rectangle ##### --> -<para> - -</para> - -@matrix: -@rect: - - -<!-- ##### FUNCTION pango_matrix_get_font_scale_factor ##### --> -<para> - -</para> - -@matrix: -@Returns: - - -<!-- ##### TYPEDEF PangoGlyph ##### --> -<para> -A #PangoGlyph represents a single glyph in the output form of a string. -</para> - - -<!-- ##### MACRO PANGO_GLYPH_EMPTY ##### --> -<para> -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()). -</para> - - - -<!-- ##### MACRO PANGO_GLYPH_INVALID_INPUT ##### --> -<para> -The %PANGO_GLYPH_EMPTY 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. -</para> - -@Since: 1.20 - - -<!-- ##### MACRO PANGO_GLYPH_UNKNOWN_FLAG ##### --> -<para> -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. -</para> - - - -<!-- ##### MACRO PANGO_GET_UNKNOWN_GLYPH ##### --> -<para> -Returns a #PangoGlyph value that means no glyph was found for @wc. -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. -</para> - -@wc: a Unicode character - - -<!-- ##### STRUCT PangoGlyphInfo ##### --> -<para> -The #PangoGlyphInfo structure represents a single glyph together with -positioning information and visual attributes. -It contains the following fields. -</para> - -@glyph: the glyph itself. -@geometry: the positional information about the glyph. -@attr: the visual attributes of the glyph. - -<!-- ##### STRUCT PangoGlyphGeometry ##### --> -<para> -The #PangoGlyphGeometry structure contains width and positioning -information for a single glyph. -</para> - -@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. - -<!-- ##### TYPEDEF PangoGlyphUnit ##### --> -<para> -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. -</para> - - -<!-- ##### STRUCT PangoGlyphVisAttr ##### --> -<para> -The PangoGlyphVisAttr is used to communicate information between -the shaping phase and the rendering phase. More attributes may be -added in the future. -</para> - -@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.) - -<!-- ##### STRUCT PangoGlyphString ##### --> -<para> -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. -</para> - - -<!-- ##### STRUCT PangoGlyphItem ##### --> -<para> -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. -</para> - - -<!-- ##### STRUCT PangoGlyphItemIter ##### --> -<para> -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. - -</para> - -@Since: 1.22 - -<!-- ##### MACRO PANGO_TYPE_GLYPH_STRING ##### --> -<para> -The #GObject type for #PangoGlyphString. -</para> - - - -<!-- ##### FUNCTION pango_glyph_string_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_string_copy ##### --> -<para> - -</para> - -@string: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_string_set_size ##### --> -<para> - -</para> - -@string: -@new_len: - - -<!-- ##### FUNCTION pango_glyph_string_free ##### --> -<para> - -</para> - -@string: - - -<!-- ##### FUNCTION pango_glyph_string_extents ##### --> -<para> - -</para> - -@glyphs: -@font: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_glyph_string_extents_range ##### --> -<para> - -</para> - -@glyphs: -@start: -@end: -@font: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_glyph_string_get_width ##### --> -<para> - -</para> - -@glyphs: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_string_index_to_x ##### --> -<para> - -</para> - -@glyphs: -@text: -@length: -@analysis: -@index_: -@trailing: -@x_pos: - - -<!-- ##### FUNCTION pango_glyph_string_x_to_index ##### --> -<para> - -</para> - -@glyphs: -@text: -@length: -@analysis: -@x_pos: -@index_: -@trailing: - - -<!-- ##### FUNCTION pango_glyph_string_get_logical_widths ##### --> -<para> - -</para> - -@glyphs: -@text: -@length: -@embedding_level: -@logical_widths: - - -<!-- ##### MACRO PANGO_TYPE_GLYPH_ITEM ##### --> -<para> -The #GObject type for #PangoGlyphItem. -</para> - -@Since: 1.20 - - -<!-- ##### FUNCTION pango_glyph_item_copy ##### --> -<para> - -</para> - -@orig: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_free ##### --> -<para> - -</para> - -@glyph_item: - - -<!-- ##### FUNCTION pango_glyph_item_split ##### --> -<para> - -</para> - -@orig: -@text: -@split_index: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_apply_attrs ##### --> -<para> - -</para> - -@glyph_item: -@text: -@list: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_letter_space ##### --> -<para> - -</para> - -@glyph_item: -@text: -@log_attrs: -@letter_spacing: - - -<!-- ##### FUNCTION pango_glyph_item_get_logical_widths ##### --> -<para> - -</para> - -@glyph_item: -@text: -@logical_widths: - - -<!-- ##### MACRO PANGO_TYPE_GLYPH_ITEM_ITER ##### --> -<para> -The #GObject type for #PangoGlyphItemIter. -</para> - -@Since: 1.22 - - -<!-- ##### FUNCTION pango_glyph_item_iter_copy ##### --> -<para> - -</para> - -@orig: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_iter_free ##### --> -<para> - -</para> - -@iter: - - -<!-- ##### FUNCTION pango_glyph_item_iter_init_start ##### --> -<para> - -</para> - -@iter: -@glyph_item: -@text: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_iter_init_end ##### --> -<para> - -</para> - -@iter: -@glyph_item: -@text: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_iter_next_cluster ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_glyph_item_iter_prev_cluster ##### --> -<para> - -</para> - -@iter: -@Returns: - - diff --git a/docs/tmpl/layout.sgml b/docs/tmpl/layout.sgml deleted file mode 100644 index e0a6ebf4..00000000 --- a/docs/tmpl/layout.sgml +++ /dev/null @@ -1,938 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Layout Objects - -<!-- ##### SECTION Short_Description ##### --> -High-level layout driver objects - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoLayout ##### --> -<para> -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. -</para> - -<para> -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. -</para> - -<figure id="parameters"> -<title>Adjustable parameters for a PangoLayout</title> -<graphic fileref="layout.gif" format="GIF"></graphic> -</figure> - -<para> -The #PangoLayout structure is opaque, and has no user-visible -fields. -</para> - - -<!-- ##### STRUCT PangoLayoutIter ##### --> -<para> -A #PangoLayoutIter structure can be used to -iterate over the visual extents of a #PangoLayout. -</para> -<para> -The #PangoLayoutIter structure is opaque, and -has no user-visible fields. -</para> - - -<!-- ##### FUNCTION pango_layout_new ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_layout_copy ##### --> -<para> - -</para> - -@src: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_context ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_context_changed ##### --> -<para> - -</para> - -@layout: - - -<!-- ##### FUNCTION pango_layout_get_serial ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_text ##### --> -<para> - -</para> - -@layout: -@text: -@length: - - -<!-- ##### FUNCTION pango_layout_get_text ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_character_count ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_markup ##### --> -<para> - -</para> - -@layout: -@markup: -@length: - - -<!-- ##### FUNCTION pango_layout_set_markup_with_accel ##### --> -<para> - -</para> - -@layout: -@markup: -@length: -@accel_marker: -@accel_char: - - -<!-- ##### FUNCTION pango_layout_set_attributes ##### --> -<para> - -</para> - -@layout: -@attrs: - - -<!-- ##### FUNCTION pango_layout_get_attributes ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_font_description ##### --> -<para> - -</para> - -@layout: -@desc: - - -<!-- ##### FUNCTION pango_layout_get_font_description ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_width ##### --> -<para> - -</para> - -@layout: -@width: - - -<!-- ##### FUNCTION pango_layout_get_width ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_height ##### --> -<para> - -</para> - -@layout: -@height: - - -<!-- ##### FUNCTION pango_layout_get_height ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_wrap ##### --> -<para> - -</para> - -@layout: -@wrap: - - -<!-- ##### FUNCTION pango_layout_get_wrap ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_is_wrapped ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### ENUM PangoWrapMode ##### --> -<para> -A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width. -</para> - -@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. - -<!-- ##### MACRO PANGO_TYPE_WRAP_MODE ##### --> -<para> -The #GObject type for #PangoWrapMode. -</para> - - - -<!-- ##### FUNCTION pango_layout_set_ellipsize ##### --> -<para> - -</para> - -@layout: -@ellipsize: - - -<!-- ##### FUNCTION pango_layout_get_ellipsize ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_is_ellipsized ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### ENUM PangoEllipsizeMode ##### --> -<para> - -</para> - -@PANGO_ELLIPSIZE_NONE: -@PANGO_ELLIPSIZE_START: -@PANGO_ELLIPSIZE_MIDDLE: -@PANGO_ELLIPSIZE_END: - -<!-- ##### MACRO PANGO_TYPE_ELLIPSIZE_MODE ##### --> -<para> -The #GObject type for #PangoEllipsizeMode. -</para> - - - -<!-- ##### FUNCTION pango_layout_set_indent ##### --> -<para> - -</para> - -@layout: -@indent: - - -<!-- ##### FUNCTION pango_layout_get_indent ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_spacing ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_spacing ##### --> -<para> - -</para> - -@layout: -@spacing: - - -<!-- ##### FUNCTION pango_layout_set_justify ##### --> -<para> - -</para> - -@layout: -@justify: - - -<!-- ##### FUNCTION pango_layout_get_justify ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_auto_dir ##### --> -<para> - -</para> - -@layout: -@auto_dir: - - -<!-- ##### FUNCTION pango_layout_get_auto_dir ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_alignment ##### --> -<para> - -</para> - -@layout: -@alignment: - - -<!-- ##### FUNCTION pango_layout_get_alignment ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_tabs ##### --> -<para> - -</para> - -@layout: -@tabs: - - -<!-- ##### FUNCTION pango_layout_get_tabs ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_set_single_paragraph_mode ##### --> -<para> - -</para> - -@layout: -@setting: - - -<!-- ##### FUNCTION pango_layout_get_single_paragraph_mode ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### ENUM PangoAlignment ##### --> -<para> -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. -</para> - -@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 - -<!-- ##### MACRO PANGO_TYPE_ALIGNMENT ##### --> -<para> -The #GObject type for #PangoAlignment. -</para> - - - -<!-- ##### FUNCTION pango_layout_get_unknown_glyphs_count ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_log_attrs ##### --> -<para> - -</para> - -@layout: -@attrs: -@n_attrs: - - -<!-- ##### FUNCTION pango_layout_get_log_attrs_readonly ##### --> -<para> - -</para> - -@layout: -@n_attrs: -@Returns: - - -<!-- ##### FUNCTION pango_layout_index_to_pos ##### --> -<para> - -</para> - -@layout: -@index_: -@pos: - - -<!-- ##### FUNCTION pango_layout_index_to_line_x ##### --> -<para> - -</para> - -@layout: -@index_: -@trailing: -@line: -@x_pos: - - -<!-- ##### FUNCTION pango_layout_xy_to_index ##### --> -<para> - -</para> - -@layout: -@x: -@y: -@index_: -@trailing: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_cursor_pos ##### --> -<para> - -</para> - -@layout: -@index_: -@strong_pos: -@weak_pos: - - -<!-- ##### FUNCTION pango_layout_move_cursor_visually ##### --> -<para> - -</para> - -@layout: -@strong: -@old_index: -@old_trailing: -@direction: -@new_index: -@new_trailing: - - -<!-- ##### FUNCTION pango_layout_get_extents ##### --> -<para> - -</para> - -@layout: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_get_pixel_extents ##### --> -<para> - -</para> - -@layout: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_get_size ##### --> -<para> - -</para> - -@layout: -@width: -@height: - - -<!-- ##### FUNCTION pango_layout_get_pixel_size ##### --> -<para> - -</para> - -@layout: -@width: -@height: - - -<!-- ##### FUNCTION pango_layout_get_baseline ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_line_count ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_line ##### --> -<para> - -</para> - -@layout: -@line: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_line_readonly ##### --> -<para> - -</para> - -@layout: -@line: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_lines ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_lines_readonly ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_get_iter ##### --> -<para> - -</para> - -@layout: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_copy ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_free ##### --> -<para> - -</para> - -@iter: - - -<!-- ##### FUNCTION pango_layout_iter_next_run ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_next_char ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_next_cluster ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_next_line ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_at_last_line ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_index ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_baseline ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_run ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_run_readonly ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_line ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_line_readonly ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_layout ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_layout_iter_get_char_extents ##### --> -<para> - -</para> - -@iter: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_iter_get_cluster_extents ##### --> -<para> - -</para> - -@iter: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_iter_get_run_extents ##### --> -<para> - -</para> - -@iter: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_iter_get_line_yrange ##### --> -<para> - -</para> - -@iter: -@y0_: -@y1_: - - -<!-- ##### FUNCTION pango_layout_iter_get_line_extents ##### --> -<para> - -</para> - -@iter: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_iter_get_layout_extents ##### --> -<para> - -</para> - -@iter: -@ink_rect: -@logical_rect: - - -<!-- ##### STRUCT PangoLayoutLine ##### --> -<para> -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. -</para> -<para> -Routines for rendering PangoLayout objects are provided in -code specific to each rendering system. -</para> - - -<!-- ##### TYPEDEF PangoLayoutRun ##### --> -<para> -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. -</para> - - -<!-- ##### FUNCTION pango_layout_line_ref ##### --> -<para> - -</para> - -@line: -@Returns: - - -<!-- ##### FUNCTION pango_layout_line_unref ##### --> -<para> - -</para> - -@line: - - -<!-- ##### FUNCTION pango_layout_line_get_extents ##### --> -<para> - -</para> - -@line: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_line_get_pixel_extents ##### --> -<para> - -</para> - -@layout_line: -@ink_rect: -@logical_rect: - - -<!-- ##### FUNCTION pango_layout_line_index_to_x ##### --> -<para> - -</para> - -@line: -@index_: -@trailing: -@x_pos: - - -<!-- ##### FUNCTION pango_layout_line_x_to_index ##### --> -<para> - -</para> - -@line: -@x_pos: -@index_: -@trailing: -@Returns: - - -<!-- ##### FUNCTION pango_layout_line_get_x_ranges ##### --> -<para> - -</para> - -@line: -@start_index: -@end_index: -@ranges: -@n_ranges: - - diff --git a/docs/tmpl/main.sgml b/docs/tmpl/main.sgml deleted file mode 100644 index ea6c2a74..00000000 --- a/docs/tmpl/main.sgml +++ /dev/null @@ -1,478 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Rendering - -<!-- ##### SECTION Short_Description ##### --> -Functions to run the rendering pipeline - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoContext ##### --> -<para> -The #PangoContext structure stores global information -used to control the itemization process. -</para> - - -<!-- ##### STRUCT PangoItem ##### --> -<para> -The #PangoItem structure stores information about -a segment of text. It contains the following fields: -</para> - - -<!-- ##### STRUCT PangoAnalysis ##### --> -<para> -The #PangoAnalysis structure stores information about -the properties of a segment of text. It has the following -fields: -</para> - -@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. - -<!-- ##### MACRO PANGO_ANALYSIS_FLAG_CENTERED_BASELINE ##### --> -<para> -Whether the segment should be shifted to center around the baseline. -Used in vertical writing directions mostly. - -Since: 1.16 -</para> - - - -<!-- ##### MACRO PANGO_TYPE_DIRECTION ##### --> -<para> -The #GObject type for #PangoDirection. -</para> - - - -<!-- ##### FUNCTION pango_itemize ##### --> -<para> - -</para> - -@context: -@text: -@start_index: -@length: -@attrs: -@cached_iter: -@Returns: - - -<!-- ##### FUNCTION pango_itemize_with_base_dir ##### --> -<para> - -</para> - -@context: -@base_dir: -@text: -@start_index: -@length: -@attrs: -@cached_iter: -@Returns: - - -<!-- ##### FUNCTION pango_item_free ##### --> -<para> - -</para> - -@item: - - -<!-- ##### FUNCTION pango_item_copy ##### --> -<para> - -</para> - -@item: -@Returns: - - -<!-- ##### FUNCTION pango_item_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_item_split ##### --> -<para> - -</para> - -@orig: -@split_index: -@split_offset: -@Returns: - - -<!-- ##### FUNCTION pango_reorder_items ##### --> -<para> - -</para> - -@logical_items: -@Returns: - - -<!-- ##### FUNCTION pango_context_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_context_changed ##### --> -<para> - -</para> - -@context: - - -<!-- ##### FUNCTION pango_context_get_serial ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_font_map ##### --> -<para> - -</para> - -@context: -@font_map: - - -<!-- ##### FUNCTION pango_context_get_font_map ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_get_font_description ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_font_description ##### --> -<para> - -</para> - -@context: -@desc: - - -<!-- ##### FUNCTION pango_context_get_language ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_language ##### --> -<para> - -</para> - -@context: -@language: - - -<!-- ##### FUNCTION pango_context_get_base_dir ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_base_dir ##### --> -<para> - -</para> - -@context: -@direction: - - -<!-- ##### FUNCTION pango_context_get_base_gravity ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_base_gravity ##### --> -<para> - -</para> - -@context: -@gravity: - - -<!-- ##### FUNCTION pango_context_get_gravity ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_get_gravity_hint ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_gravity_hint ##### --> -<para> - -</para> - -@context: -@hint: - - -<!-- ##### FUNCTION pango_context_get_matrix ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_context_set_matrix ##### --> -<para> - -</para> - -@context: -@matrix: - - -<!-- ##### FUNCTION pango_context_load_font ##### --> -<para> - -</para> - -@context: -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_context_load_fontset ##### --> -<para> - -</para> - -@context: -@desc: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_context_get_metrics ##### --> -<para> - -</para> - -@context: -@desc: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_context_list_families ##### --> -<para> - -</para> - -@context: -@families: -@n_families: - - -<!-- ##### FUNCTION pango_break ##### --> -<para> - -</para> - -@text: -@length: -@analysis: -@attrs: -@attrs_len: - - -<!-- ##### FUNCTION pango_get_log_attrs ##### --> -<para> - -</para> - -@text: -@length: -@level: -@language: -@log_attrs: -@attrs_len: - - -<!-- ##### FUNCTION pango_find_paragraph_boundary ##### --> -<para> - -</para> - -@text: -@length: -@paragraph_delimiter_index: -@next_paragraph_start: - - -<!-- ##### FUNCTION pango_default_break ##### --> -<para> - -</para> - -@text: -@length: -@analysis: -@attrs: -@attrs_len: - - -<!-- ##### STRUCT PangoLogAttr ##### --> -<para> -The #PangoLogAttr structure stores information -about the attributes of a single character. -</para> - -@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) - -<!-- ##### FUNCTION pango_shape ##### --> -<para> - -</para> - -@text: -@length: -@analysis: -@glyphs: - - -<!-- ##### FUNCTION pango_shape_full ##### --> -<para> - -</para> - -@item_text: -@item_length: -@paragraph_text: -@paragraph_length: -@analysis: -@glyphs: diff --git a/docs/tmpl/modules.sgml b/docs/tmpl/modules.sgml deleted file mode 100644 index faac809a..00000000 --- a/docs/tmpl/modules.sgml +++ /dev/null @@ -1,90 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Modules - -<!-- ##### SECTION Short_Description ##### --> -Support for loadable modules - -<!-- ##### SECTION Long_Description ##### --> -<para> -Functions and macros in this section are used to support loading dynamic -modules that add engines to Pango at run time. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoIncludedModule ##### --> -<para> -The #PangoIncludedModule structure for a statically linked module -contains the functions that would otherwise be loaded from a dynamically -loaded module. -</para> - -@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. - -<!-- ##### STRUCT PangoMap ##### --> -<para> -A #PangoMap structure can be used to determine the engine to -use for each character. -</para> - - -<!-- ##### STRUCT PangoMapEntry ##### --> -<para> -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. -</para> - - -<!-- ##### FUNCTION pango_find_map ##### --> -<para> - -</para> - -@language: -@engine_type_id: -@render_type_id: -@Returns: - - -<!-- ##### FUNCTION pango_map_get_engine ##### --> -<para> - -</para> - -@map: -@script: -@Returns: - - -<!-- ##### FUNCTION pango_map_get_engines ##### --> -<para> - -</para> - -@map: -@script: -@exact_engines: -@fallback_engines: - - -<!-- ##### FUNCTION pango_module_register ##### --> -<para> - -</para> - -@module: - - diff --git a/docs/tmpl/opentype.sgml b/docs/tmpl/opentype.sgml deleted file mode 100644 index cccc5187..00000000 --- a/docs/tmpl/opentype.sgml +++ /dev/null @@ -1,554 +0,0 @@ -<!-- ##### SECTION Title ##### --> -OpenType Font Handling - -<!-- ##### SECTION Short_Description ##### --> -Obtaining information from OpenType tables - -<!-- ##### SECTION Long_Description ##### --> -<para> -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 -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Unstable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### TYPEDEF PangoOTTag ##### --> -<para> -The <type>PangoOTTag</type> 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. -</para> - - -<!-- ##### STRUCT PangoOTInfo ##### --> -<para> -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_new(). -</para> - - -<!-- ##### STRUCT PangoOTBuffer ##### --> -<para> -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(). -</para> - - -<!-- ##### STRUCT PangoOTGlyph ##### --> -<para> -The #PangoOTGlyph structure represents a single glyph together with -information used for OpenType layout processing of the glyph. -It contains the following fields. -</para> - -@glyph: the glyph itself. -@properties: the properties value, identifying which features should be - applied on this glyph. See pango_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 - -<!-- ##### STRUCT PangoOTRuleset ##### --> -<para> -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(). -</para> - - -<!-- ##### STRUCT PangoOTRulesetDescription ##### --> -<para> -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(). -</para> - -@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. -@Since: 1.18 - -<!-- ##### ENUM PangoOTTableType ##### --> -<para> -The <type>PangoOTTableType</type> enumeration values are used to -identify the various OpenType tables in the -<function>pango_ot_info_*</function> functions. -</para> - -@PANGO_OT_TABLE_GSUB: The GSUB table. -@PANGO_OT_TABLE_GPOS: The GPOS table. - -<!-- ##### STRUCT PangoOTFeatureMap ##### --> -<para> -The <type>PangoOTFeatureMap</type> 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. -</para> - -@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. -@Since: 1.18 - -<!-- ##### MACRO PANGO_OT_TAG_MAKE ##### --> -<para> -Creates a #PangoOTTag from four characters. This is similar and -compatible with the <function>FT_MAKE_TAG()</function> macro from -FreeType. -</para> - -@c1: First character. -@c2: Second character. -@c3: Third character. -@c4: Fourth character. - - -<!-- ##### MACRO PANGO_OT_TAG_MAKE_FROM_STRING ##### --> -<para> -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. -</para> - -@s: The string representation of the tag. - - -<!-- ##### MACRO PANGO_OT_ALL_GLYPHS ##### --> -<para> -This is used as the property bit in pango_ot_ruleset_add_feature() when a -feature should be applied to all glyphs. -</para> - -@Since: 1.16 - - -<!-- ##### MACRO PANGO_OT_NO_FEATURE ##### --> -<para> -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_rulset_add_feature() function -automatically skips this value, so no special handling is required by the -user. -</para> - -@Since: 1.18 - - -<!-- ##### MACRO PANGO_OT_NO_SCRIPT ##### --> -<para> -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. -</para> - -@Since: 1.18 - - -<!-- ##### MACRO PANGO_OT_DEFAULT_LANGUAGE ##### --> -<para> -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. -</para> - -@Since: 1.16 - - -<!-- ##### MACRO PANGO_OT_TAG_DEFAULT_LANGUAGE ##### --> -<para> -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. -</para> - -@Since: 1.18 - - -<!-- ##### MACRO PANGO_OT_TAG_DEFAULT_SCRIPT ##### --> -<para> -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. -</para> - -@Since: 1.18 - - -<!-- ##### FUNCTION pango_ot_info_get ##### --> -<para> - -</para> - -@face: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_find_script ##### --> -<para> - -</para> - -@info: -@table_type: -@script_tag: -@script_index: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_find_language ##### --> -<para> - -</para> - -@info: -@table_type: -@script_index: -@language_tag: -@language_index: -@required_feature_index: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_find_feature ##### --> -<para> - -</para> - -@info: -@table_type: -@feature_tag: -@script_index: -@language_index: -@feature_index: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_list_scripts ##### --> -<para> - -</para> - -@info: -@table_type: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_list_languages ##### --> -<para> - -</para> - -@info: -@table_type: -@script_index: -@language_tag: -@Returns: - - -<!-- ##### FUNCTION pango_ot_info_list_features ##### --> -<para> - -</para> - -@info: -@table_type: -@tag: -@script_index: -@language_index: -@Returns: - - -<!-- ##### FUNCTION pango_ot_buffer_new ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_ot_buffer_destroy ##### --> -<para> - -</para> - -@buffer: - - -<!-- ##### FUNCTION pango_ot_buffer_clear ##### --> -<para> - -</para> - -@buffer: - - -<!-- ##### FUNCTION pango_ot_buffer_add_glyph ##### --> -<para> - -</para> - -@buffer: -@glyph: -@properties: -@cluster: - - -<!-- ##### FUNCTION pango_ot_buffer_set_rtl ##### --> -<para> - -</para> - -@buffer: -@rtl: - - -<!-- ##### FUNCTION pango_ot_buffer_set_zero_width_marks ##### --> -<para> - -</para> - -@buffer: -@zero_width_marks: - - -<!-- ##### FUNCTION pango_ot_buffer_get_glyphs ##### --> -<para> - -</para> - -@buffer: -@glyphs: -@n_glyphs: - - -<!-- ##### FUNCTION pango_ot_buffer_output ##### --> -<para> - -</para> - -@buffer: -@glyphs: - - -<!-- ##### FUNCTION pango_ot_ruleset_get_for_description ##### --> -<para> - -</para> - -@info: -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_new ##### --> -<para> - -</para> - -@info: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_new_for ##### --> -<para> - -</para> - -@info: -@script: -@language: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_new_from_description ##### --> -<para> - -</para> - -@info: -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_add_feature ##### --> -<para> - -</para> - -@ruleset: -@table_type: -@feature_index: -@property_bit: - - -<!-- ##### FUNCTION pango_ot_ruleset_maybe_add_feature ##### --> -<para> - -</para> - -@ruleset: -@table_type: -@feature_tag: -@property_bit: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_maybe_add_features ##### --> -<para> - -</para> - -@ruleset: -@table_type: -@features: -@n_features: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_get_feature_count ##### --> -<para> - -</para> - -@ruleset: -@n_gsub_features: -@n_gpos_features: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_substitute ##### --> -<para> - -</para> - -@ruleset: -@buffer: - - -<!-- ##### FUNCTION pango_ot_ruleset_position ##### --> -<para> - -</para> - -@ruleset: -@buffer: - - -<!-- ##### FUNCTION pango_ot_ruleset_description_copy ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_description_equal ##### --> -<para> - -</para> - -@desc1: -@desc2: -@Returns: - - -<!-- ##### FUNCTION pango_ot_ruleset_description_free ##### --> -<para> - -</para> - -@desc: - - -<!-- ##### FUNCTION pango_ot_ruleset_description_hash ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_ot_tag_from_language ##### --> -<para> - -</para> - -@language: -@Returns: - - -<!-- ##### FUNCTION pango_ot_tag_from_script ##### --> -<para> - -</para> - -@script: -@Returns: - - -<!-- ##### FUNCTION pango_ot_tag_to_language ##### --> -<para> - -</para> - -@language_tag: -@Returns: - - -<!-- ##### FUNCTION pango_ot_tag_to_script ##### --> -<para> - -</para> - -@script_tag: -@Returns: - - diff --git a/docs/tmpl/pango-engine-lang.sgml b/docs/tmpl/pango-engine-lang.sgml deleted file mode 100644 index 73df49c2..00000000 --- a/docs/tmpl/pango-engine-lang.sgml +++ /dev/null @@ -1,56 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoEngineLang - -<!-- ##### SECTION Short_Description ##### --> -Rendering-system independent script engines - -<!-- ##### SECTION Long_Description ##### --> -<para> -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(). -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Unstable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoEngineLang ##### --> -<para> -</para> - - -<!-- ##### STRUCT PangoEngineLangClass ##### --> -<para> - -</para> - -@script_break: - -<!-- ##### MACRO PANGO_ENGINE_TYPE_LANG ##### --> -<para> -A string constant defining the engine type -for language engines. -These engines derive from #PangoEngineLang. -</para> - - - -<!-- ##### MACRO PANGO_ENGINE_LANG_DEFINE_TYPE ##### --> -<para> - -</para> - -@name: -@prefix: -@class_init: -@instance_init: - - diff --git a/docs/tmpl/pango-engine-shape.sgml b/docs/tmpl/pango-engine-shape.sgml deleted file mode 100644 index 3d5dd3b8..00000000 --- a/docs/tmpl/pango-engine-shape.sgml +++ /dev/null @@ -1,57 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoEngineShape - -<!-- ##### SECTION Short_Description ##### --> -Rendering-system dependent script engines - -<!-- ##### SECTION Long_Description ##### --> -<para> -The <firstterm>shape engines</firstterm> are rendering-system dependent -engines that convert character strings into glyph strings. -These engines are used in pango_shape(). -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> -Unstable - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoEngineShape ##### --> -<para> -</para> - - -<!-- ##### STRUCT PangoEngineShapeClass ##### --> -<para> - -</para> - -@script_shape: -@covers: - -<!-- ##### MACRO PANGO_ENGINE_TYPE_SHAPE ##### --> -<para> -A string constant defining the engine type -for shaping engines. -These engines derive from #PangoEngineShape. -</para> - - - -<!-- ##### MACRO PANGO_ENGINE_SHAPE_DEFINE_TYPE ##### --> -<para> - -</para> - -@name: -@prefix: -@class_init: -@instance_init: - - diff --git a/docs/tmpl/pango-renderer.sgml b/docs/tmpl/pango-renderer.sgml deleted file mode 100644 index f8e524a6..00000000 --- a/docs/tmpl/pango-renderer.sgml +++ /dev/null @@ -1,246 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoRenderer - -<!-- ##### SECTION Short_Description ##### --> -Rendering driver base class - -<!-- ##### SECTION Long_Description ##### --> -<para> -#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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoRenderer ##### --> -<para> - -</para> - -@matrix: - -<!-- ##### ENUM PangoRenderPart ##### --> -<para> - -</para> - -@PANGO_RENDER_PART_FOREGROUND: -@PANGO_RENDER_PART_BACKGROUND: -@PANGO_RENDER_PART_UNDERLINE: -@PANGO_RENDER_PART_STRIKETHROUGH: - -<!-- ##### MACRO PANGO_TYPE_RENDER_PART ##### --> -<para> -The #GObject type for #PangoRenderPart. -</para> - - - -<!-- ##### STRUCT PangoRendererClass ##### --> -<para> - -</para> - -@draw_glyphs: -@draw_rectangle: -@draw_error_underline: -@draw_shape: -@draw_trapezoid: -@draw_glyph: -@part_changed: -@begin: -@end: -@prepare_run: -@draw_glyph_item: - -<!-- ##### FUNCTION pango_renderer_draw_layout ##### --> -<para> - -</para> - -@renderer: -@layout: -@x: -@y: - - -<!-- ##### FUNCTION pango_renderer_draw_layout_line ##### --> -<para> - -</para> - -@renderer: -@line: -@x: -@y: - - -<!-- ##### FUNCTION pango_renderer_draw_glyphs ##### --> -<para> - -</para> - -@renderer: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_renderer_draw_glyph_item ##### --> -<para> - -</para> - -@renderer: -@text: -@glyph_item: -@x: -@y: - - -<!-- ##### FUNCTION pango_renderer_draw_rectangle ##### --> -<para> - -</para> - -@renderer: -@part: -@x: -@y: -@width: -@height: - - -<!-- ##### FUNCTION pango_renderer_draw_error_underline ##### --> -<para> - -</para> - -@renderer: -@x: -@y: -@width: -@height: - - -<!-- ##### FUNCTION pango_renderer_draw_trapezoid ##### --> -<para> - -</para> - -@renderer: -@part: -@y1_: -@x11: -@x21: -@y2: -@x12: -@x22: - - -<!-- ##### FUNCTION pango_renderer_draw_glyph ##### --> -<para> - -</para> - -@renderer: -@font: -@glyph: -@x: -@y: - - -<!-- ##### FUNCTION pango_renderer_activate ##### --> -<para> - -</para> - -@renderer: - - -<!-- ##### FUNCTION pango_renderer_deactivate ##### --> -<para> - -</para> - -@renderer: - - -<!-- ##### FUNCTION pango_renderer_part_changed ##### --> -<para> - -</para> - -@renderer: -@part: - - -<!-- ##### FUNCTION pango_renderer_set_color ##### --> -<para> - -</para> - -@renderer: -@part: -@color: - - -<!-- ##### FUNCTION pango_renderer_get_color ##### --> -<para> - -</para> - -@renderer: -@part: -@Returns: - - -<!-- ##### FUNCTION pango_renderer_set_matrix ##### --> -<para> - -</para> - -@renderer: -@matrix: - - -<!-- ##### FUNCTION pango_renderer_get_matrix ##### --> -<para> - -</para> - -@renderer: -@Returns: - - -<!-- ##### FUNCTION pango_renderer_get_layout ##### --> -<para> - -</para> - -@renderer: -@Returns: - - -<!-- ##### FUNCTION pango_renderer_get_layout_line ##### --> -<para> - -</para> - -@renderer: -@Returns: - - diff --git a/docs/tmpl/pango-version.sgml b/docs/tmpl/pango-version.sgml deleted file mode 100644 index 923fac87..00000000 --- a/docs/tmpl/pango-version.sgml +++ /dev/null @@ -1,115 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Version Checking - -<!-- ##### SECTION Short_Description ##### --> -Tools for checking Pango version at compile- and run-time. - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### MACRO PANGO_VERSION_ENCODE ##### --> -<para> -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. -</para> - -@major: the major component of the version number -@minor: the minor component of the version number -@micro: the micro component of the version number - - -<!-- ##### MACRO PANGO_VERSION ##### --> -<para> -The version of Pango available at compile-time, encoded using -PANGO_VERSION_ENCODE(). -</para> - - - -<!-- ##### MACRO PANGO_VERSION_MAJOR ##### --> -<para> -The major component of the version of Pango available at compile-time. -</para> - - - -<!-- ##### MACRO PANGO_VERSION_MINOR ##### --> -<para> -The minor component of the version of Pango available at compile-time. -</para> - - - -<!-- ##### MACRO PANGO_VERSION_MICRO ##### --> -<para> -The micro component of the version of Pango available at compile-time. -</para> - - - -<!-- ##### MACRO PANGO_VERSION_STRING ##### --> -<para> -A string literal containing the version of Pango available at compile-time. -</para> - - - -<!-- ##### MACRO PANGO_VERSION_CHECK ##### --> -<para> -Checks that the version of Pango available at compile-time is not older than -the provided version number. -</para> - -@major: the major component of the version number -@minor: the minor component of the version number -@micro: the micro component of the version number - - -<!-- ##### FUNCTION pango_version ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_version_string ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_version_check ##### --> -<para> - -</para> - -@required_major: -@required_minor: -@required_micro: -@Returns: - - diff --git a/docs/tmpl/pangocairo.sgml b/docs/tmpl/pangocairo.sgml deleted file mode 100644 index 32f3ca68..00000000 --- a/docs/tmpl/pangocairo.sgml +++ /dev/null @@ -1,441 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Cairo Rendering - -<!-- ##### SECTION Short_Description ##### --> -Rendering with the Cairo backend - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> -<para> -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. -</para> -<para> -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. -</para> -<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> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoCairoFont ##### --> -<para> - -</para> - - -<!-- ##### STRUCT PangoCairoFontMap ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION pango_cairo_font_map_get_default ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_map_set_default ##### --> -<para> - -</para> - -@fontmap: - - -<!-- ##### FUNCTION pango_cairo_font_map_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_map_new_for_font_type ##### --> -<para> - -</para> - -@fonttype: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_map_get_font_type ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_map_set_resolution ##### --> -<para> - -</para> - -@fontmap: -@dpi: - - -<!-- ##### FUNCTION pango_cairo_font_map_get_resolution ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_map_create_context ##### --> -<para> - -</para> - -@fontmap: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_font_get_scaled_font ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_context_set_resolution ##### --> -<para> - -</para> - -@context: -@dpi: - - -<!-- ##### FUNCTION pango_cairo_context_get_resolution ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_context_set_font_options ##### --> -<para> - -</para> - -@context: -@options: - - -<!-- ##### FUNCTION pango_cairo_context_get_font_options ##### --> -<para> - -</para> - -@context: -@Returns: - - -<!-- ##### USER_FUNCTION PangoCairoShapeRendererFunc ##### --> -<para> -Function type for rendering attributes of type %PANGO_ATTR_SHAPE -with Pango's Cairo renderer. -</para> - -@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 pango_cairo_context_set_shape_renderer ##### --> -<para> - -</para> - -@context: -@func: -@data: -@dnotify: - - -<!-- ##### FUNCTION pango_cairo_context_get_shape_renderer ##### --> -<para> - -</para> - -@context: -@data: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_create_context ##### --> -<para> - -</para> - -@cr: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_update_context ##### --> -<para> - -</para> - -@cr: -@context: - - -<!-- ##### FUNCTION pango_cairo_create_layout ##### --> -<para> - -</para> - -@cr: -@Returns: - - -<!-- ##### FUNCTION pango_cairo_update_layout ##### --> -<para> - -</para> - -@cr: -@layout: - - -<!-- ##### FUNCTION pango_cairo_show_glyph_string ##### --> -<para> - -</para> - -@cr: -@font: -@glyphs: - - -<!-- ##### FUNCTION pango_cairo_show_glyph_item ##### --> -<para> - -</para> - -@cr: -@text: -@glyph_item: - - -<!-- ##### FUNCTION pango_cairo_show_layout_line ##### --> -<para> - -</para> - -@cr: -@line: - - -<!-- ##### FUNCTION pango_cairo_show_layout ##### --> -<para> - -</para> - -@cr: -@layout: - - -<!-- ##### FUNCTION pango_cairo_show_error_underline ##### --> -<para> - -</para> - -@cr: -@x: -@y: -@width: -@height: - - -<!-- ##### FUNCTION pango_cairo_glyph_string_path ##### --> -<para> - -</para> - -@cr: -@font: -@glyphs: - - -<!-- ##### FUNCTION pango_cairo_layout_line_path ##### --> -<para> - -</para> - -@cr: -@line: - - -<!-- ##### FUNCTION pango_cairo_layout_path ##### --> -<para> - -</para> - -@cr: -@layout: - - -<!-- ##### FUNCTION pango_cairo_error_underline_path ##### --> -<para> - -</para> - -@cr: -@x: -@y: -@width: -@height: - - diff --git a/docs/tmpl/pangofc-decoder.sgml b/docs/tmpl/pangofc-decoder.sgml deleted file mode 100644 index 7b80410c..00000000 --- a/docs/tmpl/pangofc-decoder.sgml +++ /dev/null @@ -1,58 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoFcDecoder - -<!-- ##### SECTION Short_Description ##### --> -Custom font encoding handling - -<!-- ##### SECTION Long_Description ##### --> -<para> -PangoFcDecoder represents a decoder that an application provides -for handling a font that is encoded in a custom way. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoFcDecoder ##### --> -<para> - -</para> - - -<!-- ##### STRUCT PangoFcDecoderClass ##### --> -<para> - -</para> - -@get_charset: -@get_glyph: - -<!-- ##### FUNCTION pango_fc_decoder_get_charset ##### --> -<para> - -</para> - -@decoder: -@fcfont: -@Returns: - - -<!-- ##### FUNCTION pango_fc_decoder_get_glyph ##### --> -<para> - -</para> - -@decoder: -@fcfont: -@wc: -@Returns: - - diff --git a/docs/tmpl/pangofc-font.sgml b/docs/tmpl/pangofc-font.sgml deleted file mode 100644 index 80292a21..00000000 --- a/docs/tmpl/pangofc-font.sgml +++ /dev/null @@ -1,130 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoFcFont - -<!-- ##### SECTION Short_Description ##### --> -Base font class for Fontconfig-based backends - -<!-- ##### SECTION Long_Description ##### --> -<para> -#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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -<variablelist> - -<varlistentry> -<term>#PangoFcFontMap</term> -<listitem><para>The base class for font maps; creating a new -Fontconfig-based backend involves deriving from both -#PangoFcFontMap and #PangoFcFont. -.</para></listitem> -</varlistentry> - -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoFcFont ##### --> -<para> - -</para> - - -<!-- ##### ARG PangoFcFont:fontmap ##### --> -<para> - -</para> - -<!-- ##### ARG PangoFcFont:pattern ##### --> -<para> - -</para> - -<!-- ##### STRUCT PangoFcFontClass ##### --> -<para> - -</para> - -@lock_face: -@unlock_face: -@has_char: -@get_glyph: -@get_unknown_glyph: -@shutdown: - -<!-- ##### MACRO PANGO_RENDER_TYPE_FC ##### --> -<para> - -</para> - - - -<!-- ##### FUNCTION pango_fc_font_lock_face ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_unlock_face ##### --> -<para> - -</para> - -@font: - - -<!-- ##### FUNCTION pango_fc_font_has_char ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_get_glyph ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_get_unknown_glyph ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_kern_glyphs ##### --> -<para> - -</para> - -@font: -@glyphs: - - diff --git a/docs/tmpl/pangofc-fontmap.sgml b/docs/tmpl/pangofc-fontmap.sgml deleted file mode 100644 index 2896c4b8..00000000 --- a/docs/tmpl/pangofc-fontmap.sgml +++ /dev/null @@ -1,241 +0,0 @@ -<!-- ##### SECTION Title ##### --> -PangoFcFontMap - -<!-- ##### SECTION Short_Description ##### --> -Base fontmap class for Fontconfig-based backends - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -<variablelist> - -<varlistentry> -<term>#PangoFcFont</term> -<listitem><para>The base class for fonts; creating a new -Fontconfig-based backend involves deriving from both -#PangoFcFontMap and #PangoFcFont. -</para></listitem> -</varlistentry> - -</variablelist> -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoFcFontMap ##### --> -<para> - -</para> - - -<!-- ##### STRUCT PangoFcFontMapClass ##### --> -<para> - -</para> - -@default_substitute: -@new_font: -@get_resolution: -@context_key_get: -@context_key_copy: -@context_key_free: -@context_key_hash: -@context_key_equal: -@fontset_key_substitute: -@create_font: - -<!-- ##### FUNCTION pango_fc_font_map_create_context ##### --> -<para> - -</para> - -@fcfontmap: -@Returns: - - -<!-- ##### USER_FUNCTION PangoFcDecoderFindFunc ##### --> -<para> - -</para> - -@pattern: -@user_data: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_map_add_decoder_find_func ##### --> -<para> - -</para> - -@fcfontmap: -@findfunc: -@user_data: -@dnotify: - - -<!-- ##### FUNCTION pango_fc_font_map_find_decoder ##### --> -<para> - -</para> - -@fcfontmap: -@pattern: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_map_cache_clear ##### --> -<para> - -</para> - -@fcfontmap: - - -<!-- ##### FUNCTION pango_fc_font_map_shutdown ##### --> -<para> - -</para> - -@fcfontmap: - - -<!-- ##### FUNCTION pango_fc_font_description_from_pattern ##### --> -<para> - -</para> - -@pattern: -@include_size: -@Returns: - - -<!-- ##### MACRO PANGO_FC_GRAVITY ##### --> -<para> - -</para> - - - -<!-- ##### MACRO PANGO_FC_VERSION ##### --> -<para> - -</para> - - - -<!-- ##### MACRO PANGO_FC_PRGNAME ##### --> -<para> - -</para> - - - -<!-- ##### STRUCT PangoFcFontsetKey ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_context_key ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_description ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_language ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_matrix ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_absolute_size ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_fontset_key_get_resolution ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### STRUCT PangoFcFontKey ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION pango_fc_font_key_get_context_key ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_key_get_matrix ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_fc_font_key_get_pattern ##### --> -<para> - -</para> - -@key: -@Returns: - - diff --git a/docs/tmpl/scripts.sgml b/docs/tmpl/scripts.sgml deleted file mode 100644 index 789f26b3..00000000 --- a/docs/tmpl/scripts.sgml +++ /dev/null @@ -1,280 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Scripts and Languages - -<!-- ##### SECTION Short_Description ##### --> -Identifying writing systems and languages - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### ENUM PangoScript ##### --> -<para> -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>. -</para> - -@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 - -<!-- ##### MACRO PANGO_TYPE_SCRIPT ##### --> -<para> -The #GObject type for #PangoScript -</para> - - - -<!-- ##### STRUCT PangoScriptIter ##### --> -<para> - -</para> - - -<!-- ##### FUNCTION pango_script_for_unichar ##### --> -<para> - -</para> - -@ch: -@Returns: - - -<!-- ##### FUNCTION pango_script_get_sample_language ##### --> -<para> - -</para> - -@script: -@Returns: - - -<!-- ##### FUNCTION pango_script_iter_new ##### --> -<para> - -</para> - -@text: -@length: -@Returns: - - -<!-- ##### FUNCTION pango_script_iter_get_range ##### --> -<para> - -</para> - -@iter: -@start: -@end: -@script: - - -<!-- ##### FUNCTION pango_script_iter_next ##### --> -<para> - -</para> - -@iter: -@Returns: - - -<!-- ##### FUNCTION pango_script_iter_free ##### --> -<para> - -</para> - -@iter: - - -<!-- ##### STRUCT PangoLanguage ##### --> -<para> -The #PangoLanguage structure is used to -represent a language. -</para> -<para> -#PangoLanguage pointers can be efficiently -copied and compared with each other. -</para> - - -<!-- ##### MACRO PANGO_TYPE_LANGUAGE ##### --> -<para> -The #GObject type for #PangoLanguage. -</para> - - - -<!-- ##### FUNCTION pango_language_from_string ##### --> -<para> - -</para> - -@language: -@Returns: - - -<!-- ##### FUNCTION pango_language_to_string ##### --> -<para> - -</para> - -@language: -@Returns: - - -<!-- ##### FUNCTION pango_language_matches ##### --> -<para> - -</para> - -@language: -@range_list: -@Returns: - - -<!-- ##### FUNCTION pango_language_includes_script ##### --> -<para> - -</para> - -@language: -@script: -@Returns: - - -<!-- ##### FUNCTION pango_language_get_scripts ##### --> -<para> - -</para> - -@language: -@num_scripts: -@Returns: - - -<!-- ##### FUNCTION pango_language_get_default ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_language_get_sample_string ##### --> -<para> - -</para> - -@language: -@Returns: - - diff --git a/docs/tmpl/tab-stops.sgml b/docs/tmpl/tab-stops.sgml deleted file mode 100644 index 0e28a72e..00000000 --- a/docs/tmpl/tab-stops.sgml +++ /dev/null @@ -1,150 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Tab Stops - -<!-- ##### SECTION Short_Description ##### --> -Structures for storing tab stops - -<!-- ##### SECTION Long_Description ##### --> -<para> -Functions in this section are used to deal with #PangoTabArray objects -that can be used to set tab stop positions in a #PangoLayout. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoTabArray ##### --> -<para> -A #PangoTabArray struct contains an array -of tab stops. Each tab stop has an alignment and a position. -</para> - - -<!-- ##### MACRO PANGO_TYPE_TAB_ARRAY ##### --> -<para> -The #GObject type for #PangoTabArray. -</para> - - - -<!-- ##### ENUM PangoTabAlign ##### --> -<para> -A #PangoTabAlign specifies where a tab stop appears relative to the text. -</para> - -@PANGO_TAB_LEFT: the tab stop appears to the left of the text. - -<!-- ##### MACRO PANGO_TYPE_TAB_ALIGN ##### --> -<para> -The #GObject type for #PangoTabAlign. -</para> - - - -<!-- ##### FUNCTION pango_tab_array_new ##### --> -<para> - -</para> - -@initial_size: -@positions_in_pixels: -@Returns: - - -<!-- ##### FUNCTION pango_tab_array_new_with_positions ##### --> -<para> - -</para> - -@size: -@positions_in_pixels: -@first_alignment: -@first_position: -@...: -@Returns: - - -<!-- ##### FUNCTION pango_tab_array_copy ##### --> -<para> - -</para> - -@src: -@Returns: - - -<!-- ##### FUNCTION pango_tab_array_free ##### --> -<para> - -</para> - -@tab_array: - - -<!-- ##### FUNCTION pango_tab_array_get_size ##### --> -<para> - -</para> - -@tab_array: -@Returns: - - -<!-- ##### FUNCTION pango_tab_array_resize ##### --> -<para> - -</para> - -@tab_array: -@new_size: - - -<!-- ##### FUNCTION pango_tab_array_set_tab ##### --> -<para> - -</para> - -@tab_array: -@tab_index: -@alignment: -@location: - - -<!-- ##### FUNCTION pango_tab_array_get_tab ##### --> -<para> - -</para> - -@tab_array: -@tab_index: -@alignment: -@location: - - -<!-- ##### FUNCTION pango_tab_array_get_tabs ##### --> -<para> - -</para> - -@tab_array: -@alignments: -@locations: - - -<!-- ##### FUNCTION pango_tab_array_get_positions_in_pixels ##### --> -<para> - -</para> - -@tab_array: -@Returns: - - diff --git a/docs/tmpl/text-attributes.sgml b/docs/tmpl/text-attributes.sgml deleted file mode 100644 index 1f58e0dc..00000000 --- a/docs/tmpl/text-attributes.sgml +++ /dev/null @@ -1,833 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Text Attributes - -<!-- ##### SECTION Short_Description ##### --> -Font and other attributes for annotating text - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### ENUM PangoAttrType ##### --> -<para> -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. -</para> - -@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) - -<!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### --> -<para> -The #GObject type for #PangoAttrType. -</para> - - - -<!-- ##### STRUCT PangoAttrClass ##### --> -<para> -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. -</para> - -@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()) - -<!-- ##### STRUCT PangoAttribute ##### --> -<para> -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]. -</para> - -@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. - -<!-- ##### MACRO PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING ##### --> -<para> -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. -</para> - -Since: 1.24 - - - -<!-- ##### MACRO PANGO_ATTR_INDEX_TO_TEXT_END ##### --> -<para> -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. -</para> - -Since: 1.24 - - - -<!-- ##### STRUCT PangoAttrString ##### --> -<para> -The #PangoAttrString structure is used to represent attributes with -a string value. -</para> - -@attr: the common portion of the attribute -@value: the string which is the value of the attribute - -<!-- ##### STRUCT PangoAttrLanguage ##### --> -<para> -The #PangoAttrLanguage structure is used to represent attributes that -are languages. -</para> - -@attr: the common portion of the attribute -@value: the #PangoLanguage which is the value of the attribute - -<!-- ##### STRUCT PangoAttrColor ##### --> -<para> -The #PangoAttrColor structure is used to represent attributes that -are colors. -</para> - -@attr: the common portion of the attribute -@color: the #PangoColor which is the value of the attribute - -<!-- ##### STRUCT PangoAttrInt ##### --> -<para> -The #PangoAttrInt structure is used to represent attributes with -an integer or enumeration value. -</para> - -@attr: the common portion of the attribute -@value: the value of the attribute - -<!-- ##### STRUCT PangoAttrFloat ##### --> -<para> -The #PangoAttrFloat structure is used to represent attributes with -a float or double value. -</para> - -@attr: the common portion of the attribute -@value: the value of the attribute - -<!-- ##### STRUCT PangoAttrFontDesc ##### --> -<para> -The #PangoAttrFontDesc structure is used to store an attribute that -sets all aspects of the font description at once. -</para> - -@attr: the common portion of the attribute -@desc: the font description which is the value of this attribute - -<!-- ##### STRUCT PangoAttrShape ##### --> -<para> -The #PangoAttrShape structure is used to represent attributes which -impose shape restrictions. -</para> - -@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 - -<!-- ##### STRUCT PangoAttrSize ##### --> -<para> -The #PangoAttrShape structure is used to represent attributes which -set font size. -</para> - -@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. - -<!-- ##### FUNCTION pango_parse_markup ##### --> -<para> - -</para> - -@markup_text: -@length: -@accel_marker: -@attr_list: -@text: -@accel_char: -@error: -@Returns: - - -<!-- ##### FUNCTION pango_attr_type_register ##### --> -<para> - -</para> - -@name: -@Returns: - - -<!-- ##### FUNCTION pango_attr_type_get_name ##### --> -<para> - -</para> - -@type: -@Returns: - - -<!-- ##### FUNCTION pango_attribute_init ##### --> -<para> - -</para> - -@attr: -@klass: - - -<!-- ##### FUNCTION pango_attribute_copy ##### --> -<para> - -</para> - -@attr: -@Returns: - - -<!-- ##### FUNCTION pango_attribute_equal ##### --> -<para> - -</para> - -@attr1: -@attr2: -@Returns: - - -<!-- ##### FUNCTION pango_attribute_destroy ##### --> -<para> - -</para> - -@attr: - - -<!-- ##### FUNCTION pango_attr_language_new ##### --> -<para> - -</para> - -@language: -@Returns: - - -<!-- ##### FUNCTION pango_attr_family_new ##### --> -<para> - -</para> - -@family: -@Returns: - - -<!-- ##### FUNCTION pango_attr_style_new ##### --> -<para> - -</para> - -@style: -@Returns: - - -<!-- ##### FUNCTION pango_attr_variant_new ##### --> -<para> - -</para> - -@variant: -@Returns: - - -<!-- ##### FUNCTION pango_attr_stretch_new ##### --> -<para> - -</para> - -@stretch: -@Returns: - - -<!-- ##### FUNCTION pango_attr_weight_new ##### --> -<para> - -</para> - -@weight: -@Returns: - - -<!-- ##### FUNCTION pango_attr_size_new ##### --> -<para> - -</para> - -@size: -@Returns: - - -<!-- ##### FUNCTION pango_attr_size_new_absolute ##### --> -<para> - -</para> - -@size: -@Returns: - - -<!-- ##### FUNCTION pango_attr_font_desc_new ##### --> -<para> - -</para> - -@desc: -@Returns: - - -<!-- ##### FUNCTION pango_attr_foreground_new ##### --> -<para> - -</para> - -@red: -@green: -@blue: -@Returns: - - -<!-- ##### FUNCTION pango_attr_background_new ##### --> -<para> - -</para> - -@red: -@green: -@blue: -@Returns: - - -<!-- ##### FUNCTION pango_attr_strikethrough_new ##### --> -<para> - -</para> - -@strikethrough: -@Returns: - - -<!-- ##### FUNCTION pango_attr_strikethrough_color_new ##### --> -<para> - -</para> - -@red: -@green: -@blue: -@Returns: - - -<!-- ##### FUNCTION pango_attr_underline_new ##### --> -<para> - -</para> - -@underline: -@Returns: - - -<!-- ##### FUNCTION pango_attr_underline_color_new ##### --> -<para> - -</para> - -@red: -@green: -@blue: -@Returns: - - -<!-- ##### ENUM PangoUnderline ##### --> -<para> -the #PangoUnderline enumeration is used to specify -whether text should be underlined, and if so, the type -of underlining. -</para> - -@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. - -<!-- ##### MACRO PANGO_TYPE_UNDERLINE ##### --> -<para> -The #GObject type for #PangoUnderline. -</para> - - - -<!-- ##### FUNCTION pango_attr_shape_new ##### --> -<para> - -</para> - -@ink_rect: -@logical_rect: -@Returns: - - -<!-- ##### FUNCTION pango_attr_shape_new_with_data ##### --> -<para> - -</para> - -@ink_rect: -@logical_rect: -@data: -@copy_func: -@destroy_func: -@Returns: - - -<!-- ##### USER_FUNCTION PangoAttrDataCopyFunc ##### --> -<para> -A copy function passed to attribute new functions that take -user data. -</para> - -@user_data: -@Returns: a new copy of @data. -<!-- # Unused Parameters # --> -@data: the user data - - -<!-- ##### FUNCTION pango_attr_scale_new ##### --> -<para> - -</para> - -@scale_factor: -@Returns: - - -<!-- ##### MACRO PANGO_SCALE_XX_SMALL ##### --> -<para> -The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_X_SMALL ##### --> -<para> -The scale factor for two shrinking steps (1 / (1.2 * 1.2)). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_SMALL ##### --> -<para> -The scale factor for one shrinking step (1 / 1.2). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_MEDIUM ##### --> -<para> -The scale factor for normal size (1.0). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_LARGE ##### --> -<para> -The scale factor for one magnification step (1.2). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_X_LARGE ##### --> -<para> -The scale factor for two magnification steps (1.2 * 1.2). -</para> - - - -<!-- ##### MACRO PANGO_SCALE_XX_LARGE ##### --> -<para> -The scale factor for three magnification steps (1.2 * 1.2 * 1.2). -</para> - - - -<!-- ##### FUNCTION pango_attr_rise_new ##### --> -<para> - -</para> - -@rise: -@Returns: - - -<!-- ##### FUNCTION pango_attr_letter_spacing_new ##### --> -<para> - -</para> - -@letter_spacing: -@Returns: - - -<!-- ##### FUNCTION pango_attr_fallback_new ##### --> -<para> - -</para> - -@enable_fallback: -@Returns: - - -<!-- ##### FUNCTION pango_attr_gravity_new ##### --> -<para> - -</para> - -@gravity: -@Returns: - - -<!-- ##### FUNCTION pango_attr_gravity_hint_new ##### --> -<para> - -</para> - -@hint: -@Returns: - - -<!-- ##### STRUCT PangoColor ##### --> -<para> -The #PangoColor structure is used to -represent a color in an uncalibrated RGB color-space. -</para> - - -<!-- ##### MACRO PANGO_TYPE_COLOR ##### --> -<para> -The #GObject type for #PangoColor. -</para> - - - -<!-- ##### FUNCTION pango_color_parse ##### --> -<para> - -</para> - -@color: -@spec: -@Returns: - - -<!-- ##### FUNCTION pango_color_copy ##### --> -<para> - -</para> - -@src: -@Returns: - - -<!-- ##### FUNCTION pango_color_free ##### --> -<para> - -</para> - -@color: - - -<!-- ##### FUNCTION pango_color_to_string ##### --> -<para> - -</para> - -@color: -@Returns: - - -<!-- ##### STRUCT PangoAttrList ##### --> -<para> -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. -</para> -<para> -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. -</para> - - -<!-- ##### MACRO PANGO_TYPE_ATTR_LIST ##### --> -<para> -The #GObject type for #PangoAttrList. -</para> - - - -<!-- ##### FUNCTION pango_attr_list_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_attr_list_ref ##### --> -<para> - -</para> - -@list: -@Returns: - - -<!-- ##### FUNCTION pango_attr_list_unref ##### --> -<para> - -</para> - -@list: - - -<!-- ##### FUNCTION pango_attr_list_copy ##### --> -<para> - -</para> - -@list: -@Returns: - - -<!-- ##### FUNCTION pango_attr_list_insert ##### --> -<para> - -</para> - -@list: -@attr: - - -<!-- ##### FUNCTION pango_attr_list_insert_before ##### --> -<para> - -</para> - -@list: -@attr: - - -<!-- ##### FUNCTION pango_attr_list_change ##### --> -<para> - -</para> - -@list: -@attr: - - -<!-- ##### FUNCTION pango_attr_list_splice ##### --> -<para> - -</para> - -@list: -@other: -@pos: -@len: - - -<!-- ##### FUNCTION pango_attr_list_filter ##### --> -<para> - -</para> - -@list: -@func: -@data: -@Returns: - - -<!-- ##### USER_FUNCTION PangoAttrFilterFunc ##### --> -<para> -A predicate function used by pango_attr_list_filter() -to filter out a subset of attributes for a list. -</para> - -@attribute: a #PangoAttribute -@user_data: -@Returns: %TRUE if the attribute should be filtered out -<!-- # Unused Parameters # --> -@data: callback data passed to pango_attr_list_filter() - - -<!-- ##### FUNCTION pango_attr_list_get_iterator ##### --> -<para> - -</para> - -@list: -@Returns: - - -<!-- ##### STRUCT PangoAttrIterator ##### --> -<para> -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. -</para> - - -<!-- ##### FUNCTION pango_attr_iterator_copy ##### --> -<para> - -</para> - -@iterator: -@Returns: - - -<!-- ##### FUNCTION pango_attr_iterator_next ##### --> -<para> - -</para> - -@iterator: -@Returns: - - -<!-- ##### FUNCTION pango_attr_iterator_range ##### --> -<para> - -</para> - -@iterator: -@start: -@end: - - -<!-- ##### FUNCTION pango_attr_iterator_get ##### --> -<para> - -</para> - -@iterator: -@type: -@Returns: - - -<!-- ##### FUNCTION pango_attr_iterator_get_font ##### --> -<para> - -</para> - -@iterator: -@desc: -@language: -@extra_attrs: - - -<!-- ##### FUNCTION pango_attr_iterator_get_attrs ##### --> -<para> - -</para> - -@iterator: -@Returns: - - -<!-- ##### FUNCTION pango_attr_iterator_destroy ##### --> -<para> - -</para> - -@iterator: - - diff --git a/docs/tmpl/utils.sgml b/docs/tmpl/utils.sgml deleted file mode 100644 index aa6ed771..00000000 --- a/docs/tmpl/utils.sgml +++ /dev/null @@ -1,222 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Miscellaneous Utilities - -<!-- ##### SECTION Short_Description ##### --> -Various convenience and utility functions - -<!-- ##### SECTION Long_Description ##### --> -<para> -The functions and utilities in this section are mostly used from Pango -backends and modules, but may be useful for other purposes too. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### FUNCTION pango_split_file_list ##### --> -<para> - -</para> - -@str: -@Returns: - - -<!-- ##### FUNCTION pango_trim_string ##### --> -<para> - -</para> - -@str: -@Returns: - - -<!-- ##### FUNCTION pango_read_line ##### --> -<para> - -</para> - -@stream: -@str: -@Returns: - - -<!-- ##### FUNCTION pango_skip_space ##### --> -<para> - -</para> - -@pos: -@Returns: - - -<!-- ##### FUNCTION pango_scan_word ##### --> -<para> - -</para> - -@pos: -@out: -@Returns: - - -<!-- ##### FUNCTION pango_scan_string ##### --> -<para> - -</para> - -@pos: -@out: -@Returns: - - -<!-- ##### FUNCTION pango_scan_int ##### --> -<para> - -</para> - -@pos: -@out: -@Returns: - - -<!-- ##### FUNCTION pango_config_key_get ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_config_key_get_system ##### --> -<para> - -</para> - -@key: -@Returns: - - -<!-- ##### FUNCTION pango_lookup_aliases ##### --> -<para> - -</para> - -@fontname: -@families: -@n_families: - - -<!-- ##### FUNCTION pango_parse_enum ##### --> -<para> - -</para> - -@type: -@str: -@value: -@warn: -@possible_values: -@Returns: - - -<!-- ##### FUNCTION pango_parse_style ##### --> -<para> - -</para> - -@str: -@style: -@warn: -@Returns: - - -<!-- ##### FUNCTION pango_parse_variant ##### --> -<para> - -</para> - -@str: -@variant: -@warn: -@Returns: - - -<!-- ##### FUNCTION pango_parse_weight ##### --> -<para> - -</para> - -@str: -@weight: -@warn: -@Returns: - - -<!-- ##### FUNCTION pango_parse_stretch ##### --> -<para> - -</para> - -@str: -@stretch: -@warn: -@Returns: - - -<!-- ##### FUNCTION pango_get_sysconf_subdirectory ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_get_lib_subdirectory ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_log2vis_get_embedding_levels ##### --> -<para> - -</para> - -@text: -@length: -@pbase_dir: -@Returns: - - -<!-- ##### FUNCTION pango_is_zero_width ##### --> -<para> - -</para> - -@ch: -@Returns: - - -<!-- ##### FUNCTION pango_quantize_line_geometry ##### --> -<para> - -</para> - -@thickness: -@position: - - diff --git a/docs/tmpl/vertical.sgml b/docs/tmpl/vertical.sgml deleted file mode 100644 index 382f3234..00000000 --- a/docs/tmpl/vertical.sgml +++ /dev/null @@ -1,155 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Vertical Text - -<!-- ##### SECTION Short_Description ##### --> -Laying text out in vertical directions - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> -<para> -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. -</para> -<para> -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. -</para> -<para> -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(). -</para> -<para> -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. -</para> -<para> -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. -</para> -<para> -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(). -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> -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() -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### ENUM PangoGravity ##### --> -<para> - -</para> - -@PANGO_GRAVITY_SOUTH: -@PANGO_GRAVITY_EAST: -@PANGO_GRAVITY_NORTH: -@PANGO_GRAVITY_WEST: -@PANGO_GRAVITY_AUTO: - -<!-- ##### ENUM PangoGravityHint ##### --> -<para> - -</para> - -@PANGO_GRAVITY_HINT_NATURAL: -@PANGO_GRAVITY_HINT_STRONG: -@PANGO_GRAVITY_HINT_LINE: - -<!-- ##### MACRO PANGO_GRAVITY_IS_IMPROPER ##### --> -<para> - -</para> - -@gravity: - - -<!-- ##### MACRO PANGO_GRAVITY_IS_VERTICAL ##### --> -<para> - -</para> - -@gravity: - - -<!-- ##### FUNCTION pango_gravity_get_for_matrix ##### --> -<para> - -</para> - -@matrix: -@Returns: - - -<!-- ##### FUNCTION pango_gravity_get_for_script ##### --> -<para> - -</para> - -@script: -@base_gravity: -@hint: -@Returns: - - -<!-- ##### FUNCTION pango_gravity_get_for_script_and_width ##### --> -<para> - -</para> - -@script: -@wide: -@base_gravity: -@hint: -@Returns: - - -<!-- ##### FUNCTION pango_gravity_to_rotation ##### --> -<para> - -</para> - -@gravity: -@Returns: - - diff --git a/docs/tmpl/win32-fonts.sgml b/docs/tmpl/win32-fonts.sgml deleted file mode 100644 index eb208ade..00000000 --- a/docs/tmpl/win32-fonts.sgml +++ /dev/null @@ -1,267 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Win32 Fonts and Rendering - -<!-- ##### SECTION Short_Description ##### --> -Functions for shape engines to manipulate Win32 fonts - -<!-- ##### SECTION Long_Description ##### --> -<para> -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. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### MACRO PANGO_RENDER_TYPE_WIN32 ##### --> -<para> -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(). -</para> - - - -<!-- ##### FUNCTION pango_win32_get_context ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_win32_render ##### --> -<para> - -</para> - -@hdc: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_win32_render_transformed ##### --> -<para> - -</para> - -@hdc: -@matrix: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_win32_render_layout_line ##### --> -<para> - -</para> - -@hdc: -@line: -@x: -@y: - - -<!-- ##### FUNCTION pango_win32_render_layout ##### --> -<para> - -</para> - -@hdc: -@layout: -@x: -@y: - - -<!-- ##### FUNCTION pango_win32_get_unknown_glyph ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_get_glyph_index ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_select_font ##### --> -<para> - -</para> - -@font: -@hdc: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_done_font ##### --> -<para> - -</para> - -@font: - - -<!-- ##### FUNCTION pango_win32_font_get_metrics_factor ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_win32_get_debug_flag ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_win32_get_dc ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### STRUCT PangoWin32FontCache ##### --> -<para> -A #PangoWin32FontCache caches -HFONTs by their LOGFONT descriptions. -</para> - - -<!-- ##### FUNCTION pango_win32_font_cache_new ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_cache_free ##### --> -<para> - -</para> - -@cache: - - -<!-- ##### FUNCTION pango_win32_font_cache_load ##### --> -<para> - -</para> - -@cache: -@logfont: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_cache_loadw ##### --> -<para> - -</para> - -@cache: -@logfont: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_cache_unload ##### --> -<para> - -</para> - -@cache: -@hfont: - - -<!-- ##### FUNCTION pango_win32_font_map_for_display ##### --> -<para> - -</para> - -@void: -@Returns: - - -<!-- ##### FUNCTION pango_win32_shutdown_display ##### --> -<para> - -</para> - -@void: - - -<!-- ##### FUNCTION pango_win32_font_map_get_font_cache ##### --> -<para> - -</para> - -@font_map: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_logfont ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_logfontw ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_description_from_logfont ##### --> -<para> - -</para> - -@lfp: -@Returns: - - -<!-- ##### FUNCTION pango_win32_font_description_from_logfontw ##### --> -<para> - -</para> - -@lfp: -@Returns: - - diff --git a/docs/tmpl/xft-fonts.sgml b/docs/tmpl/xft-fonts.sgml deleted file mode 100644 index d996eba7..00000000 --- a/docs/tmpl/xft-fonts.sgml +++ /dev/null @@ -1,311 +0,0 @@ -<!-- ##### SECTION Title ##### --> -Xft Fonts and Rendering - -<!-- ##### SECTION Short_Description ##### --> -Font handling and rendering with the Xft backend - -<!-- ##### SECTION Long_Description ##### --> -<para> -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.) -</para> -<para> -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(). -</para> -<para> -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'. -</para> - -<!-- ##### SECTION See_Also ##### --> -<para> - -</para> - -<!-- ##### SECTION Stability_Level ##### --> - - -<!-- ##### SECTION Image ##### --> - - -<!-- ##### STRUCT PangoXftFont ##### --> -<para> -#PangoXftFont is an implementation of #PangoFcFont using the Xft -library for rendering. It is used in conjunction with #PangoXftFontMap. -</para> - - -<!-- ##### STRUCT PangoXftFontMap ##### --> -<para> -#PangoXftFontMap is an implementation of #PangoFcFontMap suitable for -the Xft library as the renderer. It is used in to create fonts of -type #PangoXftFont. -</para> - - -<!-- ##### MACRO PANGO_RENDER_TYPE_XFT ##### --> -<para> -A string constant that was used to identify shape engines that work -with the Xft backend. See %PANGO_RENDER_TYPE_FC for the replacement. -</para> - - - -<!-- ##### FUNCTION pango_xft_get_context ##### --> -<para> - -</para> - -@display: -@screen: -@Returns: - - -<!-- ##### FUNCTION pango_xft_get_font_map ##### --> -<para> - -</para> - -@display: -@screen: -@Returns: - - -<!-- ##### FUNCTION pango_xft_set_default_substitute ##### --> -<para> - -</para> - -@display: -@screen: -@func: -@data: -@notify: - - -<!-- ##### USER_FUNCTION PangoXftSubstituteFunc ##### --> -<para> -Function type for doing final config tweaking on prepared FcPatterns. -</para> - -@pattern: the FcPattern to tweak. -@data: user data. - - -<!-- ##### FUNCTION pango_xft_substitute_changed ##### --> -<para> - -</para> - -@display: -@screen: - - -<!-- ##### FUNCTION pango_xft_shutdown_display ##### --> -<para> - -</para> - -@display: -@screen: - - -<!-- ##### FUNCTION pango_xft_font_get_font ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_xft_font_get_display ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_xft_font_has_char ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_xft_font_lock_face ##### --> -<para> - -</para> - -@font: -@Returns: - - -<!-- ##### FUNCTION pango_xft_font_unlock_face ##### --> -<para> - -</para> - -@font: - - -<!-- ##### FUNCTION pango_xft_font_get_glyph ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### FUNCTION pango_xft_font_get_unknown_glyph ##### --> -<para> - -</para> - -@font: -@wc: -@Returns: - - -<!-- ##### STRUCT PangoXftRenderer ##### --> -<para> - -</para> - - -<!-- ##### ARG PangoXftRenderer:display ##### --> -<para> - -</para> - -<!-- ##### ARG PangoXftRenderer:screen ##### --> -<para> - -</para> - -<!-- ##### STRUCT PangoXftRendererClass ##### --> -<para> - -</para> - -@composite_trapezoids: -@composite_glyphs: - -<!-- ##### FUNCTION pango_xft_renderer_new ##### --> -<para> - -</para> - -@display: -@screen: -@Returns: - - -<!-- ##### FUNCTION pango_xft_renderer_set_draw ##### --> -<para> - -</para> - -@xftrenderer: -@draw: - - -<!-- ##### FUNCTION pango_xft_renderer_set_default_color ##### --> -<para> - -</para> - -@xftrenderer: -@default_color: - - -<!-- ##### FUNCTION pango_xft_render ##### --> -<para> - -</para> - -@draw: -@color: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_xft_picture_render ##### --> -<para> - -</para> - -@display: -@src_picture: -@dest_picture: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_xft_render_transformed ##### --> -<para> - -</para> - -@draw: -@color: -@matrix: -@font: -@glyphs: -@x: -@y: - - -<!-- ##### FUNCTION pango_xft_render_layout_line ##### --> -<para> - -</para> - -@draw: -@color: -@line: -@x: -@y: - - -<!-- ##### FUNCTION pango_xft_render_layout ##### --> -<para> - -</para> - -@draw: -@color: -@layout: -@x: -@y: - - diff --git a/pango/fonts.c b/pango/fonts.c index f3fa2350..4a72d327 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 ca8d4885..73935bdc 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 9551eb60..9059b1de 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 897d07dd..1e0feb7c 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 a61e255f..462e7b00 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 5c326dd4..70f8aedf 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 8bb6a86e..4e1fb1fa 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 d84a5cd3..eccd4f99 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 e1e8d133..592d2b1c 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 04de3df7..6634ff04 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 51ac8c2e..0b8abbe3 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 eea27b4e..e4ed4e0f 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 9f31801c..207bac77 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 282c2cd9..7aa7d30e 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 71c4ab31..61b5ec47 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 91bae32a..4b25d084 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 603c3776..a72b67bc 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 0775003c..b8e8ab67 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 7fc7078e..15d5fb64 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 31660ca3..8648a3a6 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 82a3283c..a024d11b 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 8177612c..25ce9cf4 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 5dbcfe9f..aec79e76 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 11637306..35d66bce 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 cd1778df..f6dc1ac0 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 81ae7e84..0d803ec1 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 93ba6174..2d8f1503 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 cca5ef51..a27ed201 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 92f2ef11..95dd3e9a 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 cc3d0ecc..e370e3e0 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 751538cd..1ffa8356 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 7f52d1d0..8a33bcbb 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 c4ef8437..0bf4bd7d 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 1ca2de6f..b4ad4511 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 c55d6dd5..9bac4f0c 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 32b4ef1e..9750fb03 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 48743444..03a2811a 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 81e842de..73ad7aca 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 36bcd825..d75b2e8d 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 22dd9cb0..9449189a 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 09a4eed0..f11b4e07 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 58307906..7056bca9 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 05fed2d5..a4053f71 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 8421f180..3948b1f1 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 3b43fbd6..1904f015 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 42923f49..2b0ebd53 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 dc6db5da..3ada81c9 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 d2ba13dd..2b9083c7 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 cc389eef..a7cfec69 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 68ec2ee0..30700683 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 bb5b9751..6948037f 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 a27c4730..ecfe5f8e 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 2b1b6740..4e5dcb7b 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 4976890c..fd96816d 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 c5c7501c..da0c3315 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 63c36ab7..7c805dec 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" |