Text Attributes

enum PangoAttrType

typedef enum {
  PANGO_ATTR_LANG,		/* PangoAttrString */
  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 */
} 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_register_type(). The predefined values are given below. The type of structure used to store the attribute is listed in parentheses after the description.

struct PangoAttrClass

struct PangoAttrClass
{
  PangoAttrType type;
  PangoAttribute * (*copy) (const PangoAttribute *attr);
  void             (*destroy) (PangoAttribute *attr);
  gboolean         (*compare) (const PangoAttribute *attr1, const PangoAttribute *attr2);
};

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 PangoAttribute

struct PangoAttribute
{
  const PangoAttrClass *klass;
  guint start_index;
  guint end_index;
};

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.

struct PangoAttrString

struct PangoAttrString
{
  PangoAttribute attr;
  char *value;
};

The PangoAttrString structure is used to represent attributes with a string value.

struct PangoAttrColor

struct PangoAttrColor
{
  PangoAttribute attr;
  guint16 red;
  guint16 green;
  guint16 blue;
};

The PangoAttrString structure is used to represent attributes that are colors.

struct PangoAttrInt

struct PangoAttrInt
{
  PangoAttribute attr;
  int value;
};

The PangoAttrString structure is used to represent attributes with a integer or enumeration value.

struct PangoAttrFontDesc

struct PangoAttrFontDesc
{
  PangoAttribute attr;
  PangoFontDescription desc;
};

The PangoAttrFontDesc structure is used to store an attribute that sets all aspects of the font description at once.

pango_attr_type_register ()

PangoAttrType pango_attr_type_register      (const gchar *name);

Allocate a new attribute type ID.

pango_attribute_copy ()

PangoAttribute* pango_attribute_copy        (const PangoAttribute *attr);

Make a copy of an attribute.

pango_attribute_compare ()

gboolean    pango_attribute_compare         (const PangoAttribute *attr1,
                                             const PangoAttribute *attr2);

Compare two attributes for equality. This compares only the actual value of the two attributes and not the ranges that the attributes apply to.

pango_attribute_destroy ()

void        pango_attribute_destroy         (PangoAttribute *attr);

Destroy a PangoAttribute and free all associated memory.

pango_attr_lang_new ()

PangoAttribute* pango_attr_lang_new         (const char *lang);

Create a new language tag attribute.

pango_attr_family_new ()

PangoAttribute* pango_attr_family_new       (const char *family);

Create a new font family attribute.

pango_attr_style_new ()

PangoAttribute* pango_attr_style_new        (PangoStyle style);

Create a new font slant style attribute.

pango_attr_variant_new ()

PangoAttribute* pango_attr_variant_new      (PangoVariant variant);

Create a new font variant attribute (normal or small caps)

pango_attr_stretch_new ()

PangoAttribute* pango_attr_stretch_new      (PangoStretch stretch);

Create a new font stretch attribute

pango_attr_weight_new ()

PangoAttribute* pango_attr_weight_new       (PangoWeight weight);

Create a new font weight attribute.

pango_attr_size_new ()

PangoAttribute* pango_attr_size_new         (int size);

Create a new font-size attribute.

pango_attr_font_desc_new ()

PangoAttribute* pango_attr_font_desc_new    (const PangoFontDescription *desc);

Create a new font description attribute. (This attribute allows setting family, style, weight, variant, stretch, and size simultaneously.)

pango_attr_foreground_new ()

PangoAttribute* pango_attr_foreground_new   (guint16 red,
                                             guint16 green,
                                             guint16 blue);

Create a new foreground color attribute.

pango_attr_background_new ()

PangoAttribute* pango_attr_background_new   (guint16 red,
                                             guint16 green,
                                             guint16 blue);

Create a new background color attribute.

pango_attr_strikethrough_new ()

PangoAttribute* pango_attr_strikethrough_new
                                            (gboolean strikethrough);

Create a new font strike-through attribute.

pango_attr_underline_new ()

PangoAttribute* pango_attr_underline_new    (PangoUnderline underline);

Create a new underline-style object.

enum PangoUnderline

typedef enum {
  PANGO_UNDERLINE_NONE,
  PANGO_UNDERLINE_SINGLE,
  PANGO_UNDERLINE_DOUBLE,
  PANGO_UNDERLINE_LOW
} PangoUnderline;

the PangoUnderline enumeration is used to specify whether text should be underlined, and if so, the type of underlining.

pango_attr_rise_new ()

PangoAttribute* pango_attr_rise_new         (int rise);

Create a new baseline displacement attribute.

struct PangoAttrList

struct 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.

pango_attr_list_new ()

PangoAttrList* pango_attr_list_new          (void);

Create a new empty attribute list with a reference count of 1.

pango_attr_list_ref ()

void        pango_attr_list_ref             (PangoAttrList *list);

Increase the reference count of the given attribute list by one.

pango_attr_list_unref ()

void        pango_attr_list_unref           (PangoAttrList *list);

Decrease the reference count of the given attribute list by one. If the result is zero, free the attribute list and the attributes it contains.

pango_attr_list_copy ()

PangoAttrList* pango_attr_list_copy         (PangoAttrList *list);

Copy list and return an identical, new list.

pango_attr_list_insert ()

void        pango_attr_list_insert          (PangoAttrList *list,
                                             PangoAttribute *attr);

Insert the given attribute into the PangoAttrList. It will be inserted after all other attributes with a matching start_index.

pango_attr_list_insert_before ()

void        pango_attr_list_insert_before   (PangoAttrList *list,
                                             PangoAttribute *attr);

Insert the given attribute into the PangoAttrList. It will be inserted before all other attributes with a matching start_index.

pango_attr_list_change ()

void        pango_attr_list_change          (PangoAttrList *list,
                                             PangoAttribute *attr);

Insert the given attribute into the PangoAttrList. It will replace any attributes of the same type on that segment and be merged with any adjoining attributes that are identical.

This function is slower than pango_attr_list_insert() for creating a attribute list in order (potentially much slower for large lists). However, pango_attr_list_insert() is not suitable for continually changing a set of attributes since it never removes or combines existing attributes.

pango_attr_list_get_iterator ()

PangoAttrIterator* pango_attr_list_get_iterator
                                            (PangoAttrList *list);

Create a iterator initialized to the beginning of the list.

struct PangoAttrIterator

struct PangoAttrIterator;

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.

pango_attr_iterator_copy ()

PangoAttrIterator* pango_attr_iterator_copy (PangoAttrIterator *iterator);

pango_attr_iterator_next ()

gboolean    pango_attr_iterator_next        (PangoAttrIterator *iterator);

Advance the iterator until the next change of style.

pango_attr_iterator_range ()

void        pango_attr_iterator_range       (PangoAttrIterator *iterator,
                                             gint *start,
                                             gint *end);

Get the range of the current segment.

pango_attr_iterator_get ()

PangoAttribute* pango_attr_iterator_get     (PangoAttrIterator *iterator,
                                             PangoAttrType type);

Find the current attribute of a particular type at the iterator location. When multiple attributes of the same type overlap, the attribute whose range starts closest to the current location is used.

pango_attr_iterator_get_font ()

void        pango_attr_iterator_get_font    (PangoAttrIterator *iterator,
                                             PangoFontDescription *base,
                                             PangoFontDescription *current,
                                             GSList **extra_attrs);

Get the font

pango_attr_iterator_destroy ()

void        pango_attr_iterator_destroy     (PangoAttrIterator *iterator);

Destroy a PangoAttrIterator and free all associated memory.