Text Attributes

Name

Text Attributes -- Font and other attributes for annotating text.

Synopsis



enum        PangoAttrType;
struct      PangoAttrClass;
struct      PangoAttribute;
struct      PangoAttrString;
struct      PangoAttrColor;
struct      PangoAttrInt;
struct      PangoAttrFontDesc;
PangoAttrType pango_attr_type_register      (const gchar *name);
PangoAttribute* pango_attribute_copy        (const PangoAttribute *attr);
gboolean    pango_attribute_compare         (const PangoAttribute *attr1,
                                             const PangoAttribute *attr2);
void        pango_attribute_destroy         (PangoAttribute *attr);

PangoAttribute* pango_attr_lang_new         (const char *lang);
PangoAttribute* pango_attr_family_new       (const char *family);
PangoAttribute* pango_attr_style_new        (PangoStyle style);
PangoAttribute* pango_attr_variant_new      (PangoVariant variant);
PangoAttribute* pango_attr_stretch_new      (PangoStretch stretch);
PangoAttribute* pango_attr_weight_new       (PangoWeight weight);
PangoAttribute* pango_attr_size_new         (int size);
PangoAttribute* pango_attr_font_desc_new    (const PangoFontDescription *desc);
PangoAttribute* pango_attr_foreground_new   (guint16 red,
                                             guint16 green,
                                             guint16 blue);
PangoAttribute* pango_attr_background_new   (guint16 red,
                                             guint16 green,
                                             guint16 blue);
PangoAttribute* pango_attr_strikethrough_new
                                            (gboolean strikethrough);
PangoAttribute* pango_attr_underline_new    (PangoUnderline underline);
enum        PangoUnderline;
PangoAttribute* pango_attr_rise_new         (int rise);

struct      PangoAttrList;
PangoAttrList* pango_attr_list_new          (void);
void        pango_attr_list_ref             (PangoAttrList *list);
void        pango_attr_list_unref           (PangoAttrList *list);
PangoAttrList* pango_attr_list_copy         (PangoAttrList *list);
void        pango_attr_list_insert          (PangoAttrList *list,
                                             PangoAttribute *attr);
void        pango_attr_list_insert_before   (PangoAttrList *list,
                                             PangoAttribute *attr);
void        pango_attr_list_change          (PangoAttrList *list,
                                             PangoAttribute *attr);
PangoAttrIterator* pango_attr_list_get_iterator
                                            (PangoAttrList *list);
struct      PangoAttrIterator;
PangoAttrIterator* pango_attr_iterator_copy (PangoAttrIterator *iterator);
gboolean    pango_attr_iterator_next        (PangoAttrIterator *iterator);
void        pango_attr_iterator_range       (PangoAttrIterator *iterator,
                                             gint *start,
                                             gint *end);
PangoAttribute* pango_attr_iterator_get     (PangoAttrIterator *iterator,
                                             PangoAttrType type);
void        pango_attr_iterator_get_font    (PangoAttrIterator *iterator,
                                             PangoFontDescription *base,
                                             PangoFontDescription *current,
                                             GSList **extra_attrs);
void        pango_attr_iterator_destroy     (PangoAttrIterator *iterator);

Description

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.

Details

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.

PANGO_ATTR_LANGlanguage tag (PangoAttrString)
PANGO_ATTR_FAMILYfont family name list (PangoAttrString)
PANGO_ATTR_STYLEfont slant style (PangoAttrInt)
PANGO_ATTR_WEIGHTfont weight (PangoAttrInt)
PANGO_ATTR_VARIANTfont variant (normal or small caps) (PangoAttrInt)
PANGO_ATTR_STRETCHfont stretch (PangoAttrInt)
PANGO_ATTR_SIZEfont size in 1000th's of a point (PangoAttrInt)
PANGO_ATTR_FONT_DESC 
PANGO_ATTR_FOREGROUNDforeground color (PangoAttrColor)
PANGO_ATTR_BACKGROUNDbackground color (PangoAttrColor)
PANGO_ATTR_UNDERLINEwhether the text has an underline (PangoAttrInt)
PANGO_ATTR_STRIKETHROUGHwhether the text is struck-through (PangoAttrInt)
PANGO_ATTR_RISEbaseline displacement (PangoAttrInt)


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.

PangoAttrType typethe type ID for this attribute
PangoAttribute* (*copy) (const PangoAttribute *attr)function to duplicate an attribute of this type (see pango_attribute_copy())
void (*destroy) (PangoAttribute *attr)function to free an attribute of this type (see pango_attribute_destroy())
gboolean (*compare) (const PangoAttribute *attr1, const PangoAttribute *attr2)function to compare two attributes of this type (see pango_attribute_compare())


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.

const PangoAttrClass *klassthe class structure holding information about the type of the attribute
guint start_indexthe start index of the range.
guint end_indexend index of the range. The character at this index is not included in the range.


struct PangoAttrString

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

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

PangoAttribute attrthe common portion of the attribute
char *valuethe value of the attribute


struct PangoAttrColor

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

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

PangoAttribute attrthe common portion of the attribute
guint16 redthe red value, in the range 0 to 65535
guint16 greenthe green value
guint16 bluethe blue value


struct PangoAttrInt

struct PangoAttrInt
{
  PangoAttribute attr;
  int value;
};

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

PangoAttribute attrthe common portion of the attribute
int valuethe value of the attribute


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.

PangoAttribute attrthe common portion of the attribute
PangoFontDescription descthe font description which is the value of this attribute


pango_attr_type_register ()

PangoAttrType pango_attr_type_register      (const gchar *name);

Allocate a new attribute type ID.

name : an identifier for the type. (Currently unused.)
Returns : the new type ID.


pango_attribute_copy ()

PangoAttribute* pango_attribute_copy        (const PangoAttribute *attr);

Make a copy of an attribute.

attr : a PangoAttribute.
Returns : a newly allocated PangoAttribute.


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.

attr1 : a PangoAttribute
attr2 : another PangoAttribute
Returns : TRUE if the two attributes have the same value.


pango_attribute_destroy ()

void        pango_attribute_destroy         (PangoAttribute *attr);

Destroy a PangoAttribute and free all associated memory.

attr : a PangoAttribute.


pango_attr_lang_new ()

PangoAttribute* pango_attr_lang_new         (const char *lang);

Create a new language tag attribute.

lang : language tag (in the form "en_US")
Returns : the new PangoAttribute.


pango_attr_family_new ()

PangoAttribute* pango_attr_family_new       (const char *family);

Create a new font family attribute.

family : the family or comma separated list of families
Returns : the new PangoAttribute.


pango_attr_style_new ()

PangoAttribute* pango_attr_style_new        (PangoStyle style);

Create a new font slant style attribute.

style : the slant style
Returns : the new PangoAttribute.


pango_attr_variant_new ()

PangoAttribute* pango_attr_variant_new      (PangoVariant variant);

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

variant : the variant
Returns : the new PangoAttribute.


pango_attr_stretch_new ()

PangoAttribute* pango_attr_stretch_new      (PangoStretch stretch);

Create a new font stretch attribute

stretch : the stretch
Returns : the new PangoAttribute.


pango_attr_weight_new ()

PangoAttribute* pango_attr_weight_new       (PangoWeight weight);

Create a new font weight attribute.

weight : the weight
Returns : the new PangoAttribute.


pango_attr_size_new ()

PangoAttribute* pango_attr_size_new         (int size);

Create a new font-size attribute.

size : the font size, in 1000ths of a point.
Returns : the new PangoAttribute.


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

desc : 
Returns : 


pango_attr_foreground_new ()

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

Create a new foreground color attribute.

red : the red value (ranging from 0 to 65535)
green : the green value
blue : the blue value
Returns : the new PangoAttribute.


pango_attr_background_new ()

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

Create a new background color attribute.

red : the red value (ranging from 0 to 65535)
green : the green value
blue : the blue value
Returns : the new PangoAttribute.


pango_attr_strikethrough_new ()

PangoAttribute* pango_attr_strikethrough_new
                                            (gboolean strikethrough);

Create a new font strike-through attribute.

strikethrough : TRUE if the text should be struck-through.
Returns : the new PangoAttribute.


pango_attr_underline_new ()

PangoAttribute* pango_attr_underline_new    (PangoUnderline underline);

Create a new underline-style object.

underline : the underline style.
Returns : the new PangoAttribute.


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_UNDERLINE_NONEno underline should be drawn.
PANGO_UNDERLINE_SINGLEa single underline should be drawn.
PANGO_UNDERLINE_DOUBLEa double underline should be drawn.
PANGO_UNDERLINE_LOWa 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_attr_rise_new ()

PangoAttribute* pango_attr_rise_new         (int rise);

Create a new baseline displacement attribute.

rise : the amount that the text should be displaced vertically, in 10'000ths of an em. Positive values displace the text upwards.
Returns : the new PangoAttribute.


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.

Returns : the newly allocated PangoAttrList.


pango_attr_list_ref ()

void        pango_attr_list_ref             (PangoAttrList *list);

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

list : a PangoAttrList


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.

list : a PangoAttrList


pango_attr_list_copy ()

PangoAttrList* pango_attr_list_copy         (PangoAttrList *list);

Copy list and return an identical, new list.

list : a PangoAttrList
Returns : new attribute 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.

list : a PangoAttrList
attr : the attribute to insert. Ownership of this value is assumed by the list.


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.

list : a PangoAttrList
attr : the attribute to insert. Ownership of this value is assumed by the list.


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.

list : a PangoAttrList
attr : the attribute to insert. Ownership of this value is assumed by the list.


pango_attr_list_get_iterator ()

PangoAttrIterator* pango_attr_list_get_iterator
                                            (PangoAttrList *list);

Create a iterator initialized to the beginning of the list.

list : a PangoAttrList
Returns : a new PangoIterator. list must not be modified until this iterator is freed with pango_attr_iterator_destroy().


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);

iterator : 
Returns : 


pango_attr_iterator_next ()

gboolean    pango_attr_iterator_next        (PangoAttrIterator *iterator);

Advance the iterator until the next change of style.

iterator : a PangoAttrIterator
Returns : FALSE if the iterator is at the end of the list, otherwise TRUE


pango_attr_iterator_range ()

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

Get the range of the current segment.

iterator : a PangoAttrIterator
start : location to store the start of the range
end : location to store the end of the range


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.

iterator : a PangoAttrIterator
type : the type of attribute to find.
Returns : the current attribute of the given type, or NULL if no attribute of that type applies to the current location.


pango_attr_iterator_get_font ()

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

Get the font

iterator : a PangoAttrIterator
base : the default values to use for fields not currently overridden.
current : a PangoFontDescription to fill in with the current values. This PangoFontDescription structure cannot be freed with pango_font_description_free. The family member of this structure will be filled in with a string that is either shared with an attribute in the PangoAttrList associated with the structure, or with base. If you want to save this value, you should allocate it on the stack and then use pango_font_description_copy().
extra_attrs : if non-NULL, location in which to store a list of non-font attributes at the the current position; only the highest priority value of each attribute will be added to this list. In order to free this value, you must call pango_attribute_destroy() on each member.


pango_attr_iterator_destroy ()

void        pango_attr_iterator_destroy     (PangoAttrIterator *iterator);

Destroy a PangoAttrIterator and free all associated memory.

iterator : a PangoAttrIterator.