text-attributes.xml

Pango is a library for layout and rendering of text, with an emphasis on internationalization. Pang

<refentry id="pango-Text-Attributes">
<refmeta>
<refentrytitle role="top_of_page" id="pango-Text-Attributes.top_of_page">Text Attributes</refentrytitle>
<manvolnum>3</manvolnum>
<refmiscinfo>PANGO Library</refmiscinfo>
</refmeta>

<refnamediv>
<refname>Text Attributes</refname>
<refpurpose>Font and other attributes for annotating text</refpurpose>
<!--[<xref linkend="desc" endterm="desc.title"/>]-->
</refnamediv>

<refsynopsisdiv id="pango-Text-Attributes.synopsis" role="synopsis">
<title role="synopsis.title">Synopsis</title>

<synopsis>
enum                <link linkend="PangoAttrType">PangoAttrType</link>;
#define             <link linkend="PANGO-TYPE-ATTR-TYPE:CAPS">PANGO_TYPE_ATTR_TYPE</link>
                    <link linkend="PangoAttrClass">PangoAttrClass</link>;
                    <link linkend="PangoAttribute">PangoAttribute</link>;
                    <link linkend="PangoAttrString">PangoAttrString</link>;
                    <link linkend="PangoAttrLanguage">PangoAttrLanguage</link>;
                    <link linkend="PangoAttrColor">PangoAttrColor</link>;
                    <link linkend="PangoAttrInt">PangoAttrInt</link>;
                    <link linkend="PangoAttrFloat">PangoAttrFloat</link>;
                    <link linkend="PangoAttrFontDesc">PangoAttrFontDesc</link>;
                    <link linkend="PangoAttrShape">PangoAttrShape</link>;
                    <link linkend="PangoAttrSize">PangoAttrSize</link>;
<link linkend="gboolean">gboolean</link>            <link linkend="pango-parse-markup">pango_parse_markup</link>                  (const <link linkend="char">char</link> *markup_text,
                                                         <link linkend="int">int</link> length,
                                                         <link linkend="gunichar">gunichar</link> accel_marker,
                                                         <link linkend="PangoAttrList">PangoAttrList</link> **attr_list,
                                                         <link linkend="char">char</link> **text,
                                                         <link linkend="gunichar">gunichar</link> *accel_char,
                                                         <link linkend="GError">GError</link> **error);
<link linkend="PangoAttrType">PangoAttrType</link>       <link linkend="pango-attr-type-register">pango_attr_type_register</link>            (const <link linkend="gchar">gchar</link> *name);
<link linkend="void">void</link>                <link linkend="pango-attribute-init">pango_attribute_init</link>                (<link linkend="PangoAttribute">PangoAttribute</link> *attr,
                                                         const <link linkend="PangoAttrClass">PangoAttrClass</link> *klass);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attribute-copy">pango_attribute_copy</link>                (const <link linkend="PangoAttribute">PangoAttribute</link> *attr);
<link linkend="gboolean">gboolean</link>            <link linkend="pango-attribute-equal">pango_attribute_equal</link>               (const <link linkend="PangoAttribute">PangoAttribute</link> *attr1,
                                                         const <link linkend="PangoAttribute">PangoAttribute</link> *attr2);
<link linkend="void">void</link>                <link linkend="pango-attribute-destroy">pango_attribute_destroy</link>             (<link linkend="PangoAttribute">PangoAttribute</link> *attr);

<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-language-new">pango_attr_language_new</link>             (<link linkend="PangoLanguage">PangoLanguage</link> *language);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-family-new">pango_attr_family_new</link>               (const <link linkend="char">char</link> *family);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-style-new">pango_attr_style_new</link>                (<link linkend="PangoStyle">PangoStyle</link> style);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-variant-new">pango_attr_variant_new</link>              (<link linkend="PangoVariant">PangoVariant</link> variant);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-stretch-new">pango_attr_stretch_new</link>              (<link linkend="PangoStretch">PangoStretch</link> stretch);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-weight-new">pango_attr_weight_new</link>               (<link linkend="PangoWeight">PangoWeight</link> weight);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-size-new">pango_attr_size_new</link>                 (<link linkend="int">int</link> size);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-size-new-absolute">pango_attr_size_new_absolute</link>        (<link linkend="int">int</link> size);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-font-desc-new">pango_attr_font_desc_new</link>            (const <link linkend="PangoFontDescription">PangoFontDescription</link> *desc);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-foreground-new">pango_attr_foreground_new</link>           (<link linkend="guint16">guint16</link> red,
                                                         <link linkend="guint16">guint16</link> green,
                                                         <link linkend="guint16">guint16</link> blue);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-background-new">pango_attr_background_new</link>           (<link linkend="guint16">guint16</link> red,
                                                         <link linkend="guint16">guint16</link> green,
                                                         <link linkend="guint16">guint16</link> blue);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-strikethrough-new">pango_attr_strikethrough_new</link>        (<link linkend="gboolean">gboolean</link> strikethrough);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-strikethrough-color-new">pango_attr_strikethrough_color_new</link>  (<link linkend="guint16">guint16</link> red,
                                                         <link linkend="guint16">guint16</link> green,
                                                         <link linkend="guint16">guint16</link> blue);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-underline-new">pango_attr_underline_new</link>            (<link linkend="PangoUnderline">PangoUnderline</link> underline);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-underline-color-new">pango_attr_underline_color_new</link>      (<link linkend="guint16">guint16</link> red,
                                                         <link linkend="guint16">guint16</link> green,
                                                         <link linkend="guint16">guint16</link> blue);
enum                <link linkend="PangoUnderline">PangoUnderline</link>;
#define             <link linkend="PANGO-TYPE-UNDERLINE:CAPS">PANGO_TYPE_UNDERLINE</link>
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-shape-new">pango_attr_shape_new</link>                (const <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
                                                         const <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-shape-new-with-data">pango_attr_shape_new_with_data</link>      (const <link linkend="PangoRectangle">PangoRectangle</link> *ink_rect,
                                                         const <link linkend="PangoRectangle">PangoRectangle</link> *logical_rect,
                                                         <link linkend="gpointer">gpointer</link> data,
                                                         <link linkend="PangoAttrDataCopyFunc">PangoAttrDataCopyFunc</link> copy_func,
                                                         <link linkend="GDestroyNotify">GDestroyNotify</link> destroy_func);
<link linkend="gpointer">gpointer</link>            (<link linkend="PangoAttrDataCopyFunc">*PangoAttrDataCopyFunc</link>)            (<link linkend="gconstpointer">gconstpointer</link> data);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-scale-new">pango_attr_scale_new</link>                (<link linkend="double">double</link> scale_factor);
#define             <link linkend="PANGO-SCALE-XX-SMALL:CAPS">PANGO_SCALE_XX_SMALL</link>
#define             <link linkend="PANGO-SCALE-X-SMALL:CAPS">PANGO_SCALE_X_SMALL</link>
#define             <link linkend="PANGO-SCALE-SMALL:CAPS">PANGO_SCALE_SMALL</link>
#define             <link linkend="PANGO-SCALE-MEDIUM:CAPS">PANGO_SCALE_MEDIUM</link>
#define             <link linkend="PANGO-SCALE-LARGE:CAPS">PANGO_SCALE_LARGE</link>
#define             <link linkend="PANGO-SCALE-X-LARGE:CAPS">PANGO_SCALE_X_LARGE</link>
#define             <link linkend="PANGO-SCALE-XX-LARGE:CAPS">PANGO_SCALE_XX_LARGE</link>
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-rise-new">pango_attr_rise_new</link>                 (<link linkend="int">int</link> rise);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-letter-spacing-new">pango_attr_letter_spacing_new</link>       (<link linkend="int">int</link> letter_spacing);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-fallback-new">pango_attr_fallback_new</link>             (<link linkend="gboolean">gboolean</link> enable_fallback);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-gravity-new">pango_attr_gravity_new</link>              (<link linkend="PangoGravity">PangoGravity</link> gravity);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-gravity-hint-new">pango_attr_gravity_hint_new</link>         (<link linkend="PangoGravityHint">PangoGravityHint</link> hint);
                    <link linkend="PangoColor">PangoColor</link>;
#define             <link linkend="PANGO-TYPE-COLOR:CAPS">PANGO_TYPE_COLOR</link>
<link linkend="gboolean">gboolean</link>            <link linkend="pango-color-parse">pango_color_parse</link>                   (<link linkend="PangoColor">PangoColor</link> *color,
                                                         const <link linkend="char">char</link> *spec);
<link linkend="PangoColor">PangoColor</link>*         <link linkend="pango-color-copy">pango_color_copy</link>                    (const <link linkend="PangoColor">PangoColor</link> *src);
<link linkend="void">void</link>                <link linkend="pango-color-free">pango_color_free</link>                    (<link linkend="PangoColor">PangoColor</link> *color);
<link linkend="gchar">gchar</link>*              <link linkend="pango-color-to-string">pango_color_to_string</link>               (const <link linkend="PangoColor">PangoColor</link> *color);
                    <link linkend="PangoLanguage">PangoLanguage</link>;
#define             <link linkend="PANGO-TYPE-LANGUAGE:CAPS">PANGO_TYPE_LANGUAGE</link>
<link linkend="PangoLanguage">PangoLanguage</link>*      <link linkend="pango-language-from-string">pango_language_from_string</link>          (const <link linkend="char">char</link> *language);
#define             <link linkend="pango-language-to-string">pango_language_to_string</link>            (language)
<link linkend="gboolean">gboolean</link>            <link linkend="pango-language-matches">pango_language_matches</link>              (<link linkend="PangoLanguage">PangoLanguage</link> *language,
                                                         const <link linkend="char">char</link> *range_list);

                    <link linkend="PangoAttrList">PangoAttrList</link>;
#define             <link linkend="PANGO-TYPE-ATTR-LIST:CAPS">PANGO_TYPE_ATTR_LIST</link>
<link linkend="PangoAttrList">PangoAttrList</link>*      <link linkend="pango-attr-list-new">pango_attr_list_new</link>                 (void);
<link linkend="PangoAttrList">PangoAttrList</link>*      <link linkend="pango-attr-list-ref">pango_attr_list_ref</link>                 (<link linkend="PangoAttrList">PangoAttrList</link> *list);
<link linkend="void">void</link>                <link linkend="pango-attr-list-unref">pango_attr_list_unref</link>               (<link linkend="PangoAttrList">PangoAttrList</link> *list);
<link linkend="PangoAttrList">PangoAttrList</link>*      <link linkend="pango-attr-list-copy">pango_attr_list_copy</link>                (<link linkend="PangoAttrList">PangoAttrList</link> *list);
<link linkend="void">void</link>                <link linkend="pango-attr-list-insert">pango_attr_list_insert</link>              (<link linkend="PangoAttrList">PangoAttrList</link> *list,
                                                         <link linkend="PangoAttribute">PangoAttribute</link> *attr);
<link linkend="void">void</link>                <link linkend="pango-attr-list-insert-before">pango_attr_list_insert_before</link>       (<link linkend="PangoAttrList">PangoAttrList</link> *list,
                                                         <link linkend="PangoAttribute">PangoAttribute</link> *attr);
<link linkend="void">void</link>                <link linkend="pango-attr-list-change">pango_attr_list_change</link>              (<link linkend="PangoAttrList">PangoAttrList</link> *list,
                                                         <link linkend="PangoAttribute">PangoAttribute</link> *attr);
<link linkend="void">void</link>                <link linkend="pango-attr-list-splice">pango_attr_list_splice</link>              (<link linkend="PangoAttrList">PangoAttrList</link> *list,
                                                         <link linkend="PangoAttrList">PangoAttrList</link> *other,
                                                         <link linkend="gint">gint</link> pos,
                                                         <link linkend="gint">gint</link> len);
<link linkend="PangoAttrList">PangoAttrList</link>*      <link linkend="pango-attr-list-filter">pango_attr_list_filter</link>              (<link linkend="PangoAttrList">PangoAttrList</link> *list,
                                                         <link linkend="PangoAttrFilterFunc">PangoAttrFilterFunc</link> func,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="gboolean">gboolean</link>            (<link linkend="PangoAttrFilterFunc">*PangoAttrFilterFunc</link>)              (<link linkend="PangoAttribute">PangoAttribute</link> *attribute,
                                                         <link linkend="gpointer">gpointer</link> data);
<link linkend="PangoAttrIterator">PangoAttrIterator</link>*  <link linkend="pango-attr-list-get-iterator">pango_attr_list_get_iterator</link>        (<link linkend="PangoAttrList">PangoAttrList</link> *list);
                    <link linkend="PangoAttrIterator">PangoAttrIterator</link>;
<link linkend="PangoAttrIterator">PangoAttrIterator</link>*  <link linkend="pango-attr-iterator-copy">pango_attr_iterator_copy</link>            (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator);
<link linkend="gboolean">gboolean</link>            <link linkend="pango-attr-iterator-next">pango_attr_iterator_next</link>            (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator);
<link linkend="void">void</link>                <link linkend="pango-attr-iterator-range">pango_attr_iterator_range</link>           (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator,
                                                         <link linkend="gint">gint</link> *start,
                                                         <link linkend="gint">gint</link> *end);
<link linkend="PangoAttribute">PangoAttribute</link>*     <link linkend="pango-attr-iterator-get">pango_attr_iterator_get</link>             (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator,
                                                         <link linkend="PangoAttrType">PangoAttrType</link> type);
<link linkend="void">void</link>                <link linkend="pango-attr-iterator-get-font">pango_attr_iterator_get_font</link>        (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator,
                                                         <link linkend="PangoFontDescription">PangoFontDescription</link> *desc,
                                                         <link linkend="PangoLanguage">PangoLanguage</link> **language,
                                                         <link linkend="GSList">GSList</link> **extra_attrs);
<link linkend="GSList">GSList</link>*             <link linkend="pango-attr-iterator-get-attrs">pango_attr_iterator_get_attrs</link>       (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator);
<link linkend="void">void</link>                <link linkend="pango-attr-iterator-destroy">pango_attr_iterator_destroy</link>         (<link linkend="PangoAttrIterator">PangoAttrIterator</link> *iterator);
</synopsis>
</refsynopsisdiv>









<refsect1 id="pango-Text-Attributes.description" role="desc">
<title role="desc.title">Description</title>
<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 <link linkend="PangoLayout"><type>PangoLayout</type></link>. The data types and functions in
this section are used to represent and manipulate sets
of attributes applied to a portion of text.
</para>
</refsect1>

<refsect1 id="pango-Text-Attributes.details" role="details">
<title role="details.title">Details</title>
<refsect2 id="PangoAttrType" role="enum">
<title>enum PangoAttrType</title>
<indexterm zone="PangoAttrType"><primary>PangoAttrType</primary></indexterm><programlisting>typedef enum
{
  PANGO_ATTR_INVALID,           /* 0 is an invalid attribute type */
  PANGO_ATTR_LANGUAGE,		/* PangoAttrLanguage */
  PANGO_ATTR_FAMILY,		/* PangoAttrString */
  PANGO_ATTR_STYLE,		/* PangoAttrInt */
  PANGO_ATTR_WEIGHT,		/* PangoAttrInt */
  PANGO_ATTR_VARIANT,		/* PangoAttrInt */
  PANGO_ATTR_STRETCH,		/* PangoAttrInt */
  PANGO_ATTR_SIZE,		/* PangoAttrSize */
  PANGO_ATTR_FONT_DESC,		/* PangoAttrFontDesc */
  PANGO_ATTR_FOREGROUND,	/* PangoAttrColor */
  PANGO_ATTR_BACKGROUND,	/* PangoAttrColor */
  PANGO_ATTR_UNDERLINE,		/* PangoAttrInt */
  PANGO_ATTR_STRIKETHROUGH,	/* PangoAttrInt */
  PANGO_ATTR_RISE,		/* PangoAttrInt */
  PANGO_ATTR_SHAPE,		/* PangoAttrShape */
  PANGO_ATTR_SCALE,             /* PangoAttrFloat */
  PANGO_ATTR_FALLBACK,          /* PangoAttrInt */
  PANGO_ATTR_LETTER_SPACING,    /* PangoAttrInt */
  PANGO_ATTR_UNDERLINE_COLOR,	/* PangoAttrColor */
  PANGO_ATTR_STRIKETHROUGH_COLOR,/* PangoAttrColor */
  PANGO_ATTR_ABSOLUTE_SIZE,	/* PangoAttrSize */
  PANGO_ATTR_GRAVITY,		/* PangoAttrInt */
  PANGO_ATTR_GRAVITY_HINT	/* PangoAttrInt */
} PangoAttrType;
</programlisting>
<para>
The <link linkend="PangoAttrType"><type>PangoAttrType</type></link>
distinguishes between different types of attributes. Along with the
predefined values, it is possible to allocate additional values
for custom attributes using <link linkend="pango-attr-type-register"><function>pango_attr_type_register()</function></link>. The predefined
values are given below. The type of structure used to store the
attribute is listed in parentheses after the description.
</para><variablelist role="enum">