path: root/docs/tmpl/text-attributes.sgml

<!-- ##### 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>

<!-- ##### ENUM PangoAttrType ##### -->
<para>
distinguishes between different types of attributes. Along with the
predefined values, it is possible to allocate additional values
for custom attributes using pango_attr_register_type(). 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_LANG: language tag (#PangoAttrString)
@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 1000th's of a point (#PangoAttrInt)
@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)

<!-- ##### 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())
@compare: function to compare two attributes of this type (see pango_attribute_compare())

<!-- ##### 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.
@end_index: end index of the range. 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 value of the attribute

<!-- ##### STRUCT PangoAttrColor ##### -->
<para>
The #PangoAttrString structure is used to represent attributes that
are colors.
</para>

@attr: the common portion of the attribute
@red: the red value, in the range 0 to 65535
@green: the green value
@blue: the blue value

<!-- ##### STRUCT PangoAttrInt ##### -->
<para>
The #PangoAttrString structure is used to represent attributes with
a integer or enumeration value.
</para>

@attr: the common portion of the attribute
@value: the value of the attribute

<!-- ##### FUNCTION pango_attr_type_register ##### -->
<para>

</para>

@name: 
@Returns: 


<!-- ##### FUNCTION pango_attribute_copy ##### -->
<para>

</para>

@attr: 
@Returns: 


<!-- ##### FUNCTION pango_attribute_compare ##### -->
<para>

</para>

@attr1: 
@attr2: 
@Returns: 


<!-- ##### FUNCTION pango_attribute_destroy ##### -->
<para>

</para>

@attr: 


<!-- ##### FUNCTION pango_attr_lang_new ##### -->
<para>

</para>

@lang: 
@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_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_underline_new ##### -->
<para>

</para>

@underline: 
@Returns: 


<!-- ##### FUNCTION pango_attr_rise_new ##### -->
<para>

</para>

@rise: 
@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>


<!-- ##### FUNCTION pango_attr_list_new ##### -->
<para>

</para>

@Returns: 


<!-- ##### FUNCTION pango_attr_list_ref ##### -->
<para>

</para>

@list: 


<!-- ##### FUNCTION pango_attr_list_unref ##### -->
<para>

</para>

@list: 


<!-- ##### FUNCTION pango_attr_list_insert ##### -->
<para>

</para>

@list: 
@attr: 


<!-- ##### FUNCTION pango_attr_list_change ##### -->
<para>

</para>

@list: 
@attr: 


<!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
<para>

</para>

@list: 
@Returns: 


<!-- ##### STRUCT PangoAttrIterator ##### -->
<para>
The #PangoAttrIterator structure is used to represent an
iterator through a #PangoList. 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_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: 
@base: 
@current: 


<!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->
<para>

</para>

@iterator: