diff options
Diffstat (limited to 'trunk/docs/tmpl/text-attributes.sgml')
| -rw-r--r-- | trunk/docs/tmpl/text-attributes.sgml | 838 |
1 files changed, 838 insertions, 0 deletions
diff --git a/trunk/docs/tmpl/text-attributes.sgml b/trunk/docs/tmpl/text-attributes.sgml new file mode 100644 index 00000000..79f9ac94 --- /dev/null +++ b/trunk/docs/tmpl/text-attributes.sgml @@ -0,0 +1,838 @@ +<!-- ##### 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 ##### --> + + +<!-- ##### 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. +</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. + +<!-- ##### 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_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> + +@data: the user data +@Returns: a new copy of @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> + +@red: The red component of the color. This is a value between 0 and 65535, + with 65535 indicating full intensity. +@green: The green component of the color. This is a value between 0 and 65535, + with 65535 indicating full intensity. +@blue: The blue component of the color. This is a value between 0 and 65535, + with 65535 indicating full intensity. + +<!-- ##### 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 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: + + +<!-- ##### MACRO pango_language_to_string ##### --> +<para> +Returns a RFC-3066 format string representing the given language tag. +</para> + +@language: a language tag. +@Returns: a string representing the language tag. + + +<!-- ##### FUNCTION pango_language_matches ##### --> +<para> + +</para> + +@language: +@range_list: +@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> + +@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 +@data: callback data passed to pango_attr_list_filter() +@Returns: %TRUE if the attribute should be filtered out + + +<!-- ##### 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: + + |