enum PangoAttrType

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;

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.

PANGO_TYPE_ATTR_TYPE

#define PANGO_TYPE_ATTR_TYPE (pango_attr_type_get_type())

The GObject type for PangoAttrType.

PangoAttrClass

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

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.

PangoAttribute

typedef struct {
  const PangoAttrClass *klass;
  guint start_index; /* in bytes */
  guint end_index; /* in bytes. The character at this index is not included */
} PangoAttribute;

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 and should be initialized using pango_attribute_init(). By default an attribute will have an all-inclusive range of [0,G_MAXUINT].

PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING

#define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING 0

This value can be used to set the start_index member of a PangoAttribute such that the attribute covers from the beginning of the text.

PANGO_ATTR_INDEX_TO_TEXT_END

#define PANGO_ATTR_INDEX_TO_TEXT_END		G_MAXUINT

This value can be used to set the end_index member of a PangoAttribute such that the attribute covers to the end of the text.

PangoAttrString

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

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

PangoAttrLanguage

typedef struct {
  PangoAttribute attr;
  PangoLanguage *value;
} PangoAttrLanguage;

The PangoAttrLanguage structure is used to represent attributes that are languages.

PangoAttrColor

typedef struct {
  PangoAttribute attr;
  PangoColor color;
} PangoAttrColor;

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

PangoAttrInt

typedef struct {
  PangoAttribute attr;
  int value;
} PangoAttrInt;

The PangoAttrInt structure is used to represent attributes with an integer or enumeration value.

PangoAttrFloat

typedef struct {
  PangoAttribute attr;
  double value;
} PangoAttrFloat;

The PangoAttrFloat structure is used to represent attributes with a float or double value.

PangoAttrFontDesc

typedef struct {
  PangoAttribute attr;
  PangoFontDescription *desc;
} PangoAttrFontDesc;

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

PangoAttrShape

typedef struct {
  PangoAttribute attr;
  PangoRectangle ink_rect;
  PangoRectangle logical_rect;

  gpointer              data;
  PangoAttrDataCopyFunc copy_func;
  GDestroyNotify        destroy_func;
} PangoAttrShape;

The PangoAttrShape structure is used to represent attributes which impose shape restrictions.

PangoAttrSize

typedef struct {
  PangoAttribute attr;
  int size;
  guint absolute : 1;
} PangoAttrSize;

The PangoAttrShape structure is used to represent attributes which set font size.

pango_parse_markup ()

gboolean            pango_parse_markup                  (const char *markup_text,
                                                         int length,
                                                         gunichar accel_marker,
                                                         PangoAttrList **attr_list,
                                                         char **text,
                                                         gunichar *accel_char,
                                                         GError **error);

Parses marked-up text (see markup format) to create a plain-text string and an attribute list.

If accel_marker is nonzero, the given character will mark the character following it as an accelerator. For example, accel_marker might be an ampersand or underscore. All characters marked as an accelerator will receive a PANGO_UNDERLINE_LOW attribute, and the first character so marked will be returned in accel_char. Two accel_marker characters following each other produce a single literal accel_marker character.

If any error happens, none of the output arguments are touched except for error.

pango_attr_type_register ()

PangoAttrType       pango_attr_type_register            (const gchar *name);

Allocate a new attribute type ID. The attribute type name can be accessed later by using pango_attr_type_get_name().

pango_attr_type_get_name ()

const char *        pango_attr_type_get_name            (PangoAttrType type);

Fetches the attribute type name passed in when registering the type using pango_attr_type_register().

The returned value is an interned string (see g_intern_string() for what that means) that should not be modified or freed.

Since 1.22

pango_attribute_init ()

void                pango_attribute_init                (PangoAttribute *attr,
                                                         const PangoAttrClass *klass);

Initializes attr's klass to klass, it's start_index to PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING and end_index to PANGO_ATTR_INDEX_TO_TEXT_END such that the attribute applies to the entire text by default.

Since 1.20

pango_attribute_copy ()

PangoAttribute *    pango_attribute_copy                (const PangoAttribute *attr);

Make a copy of an attribute.

pango_attribute_equal ()

gboolean            pango_attribute_equal               (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_language_new ()

PangoAttribute *    pango_attr_language_new             (PangoLanguage *language);

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 in fractional points.

pango_attr_size_new_absolute ()

PangoAttribute *    pango_attr_size_new_absolute        (int size);

Create a new font-size attribute in device units.

Since 1.8

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 strike-through attribute.

pango_attr_strikethrough_color_new ()

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

Create a new strikethrough color attribute. This attribute modifies the color of strikethrough lines. If not set, strikethrough lines will use the foreground color.

Since 1.8

pango_attr_underline_new ()

PangoAttribute *    pango_attr_underline_new            (PangoUnderline underline);

Create a new underline-style attribute.

pango_attr_underline_color_new ()

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

Create a new underline color attribute. This attribute modifies the color of underlines. If not set, underlines will use the foreground color.

Since 1.8

enum PangoUnderline

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

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

PANGO_TYPE_UNDERLINE

#define PANGO_TYPE_UNDERLINE (pango_underline_get_type())

The GObject type for PangoUnderline.

pango_attr_shape_new ()

PangoAttribute *    pango_attr_shape_new                (const PangoRectangle *ink_rect,
                                                         const PangoRectangle *logical_rect);

Create a new shape attribute. A shape is used to impose a particular ink and logical rectangle on the result of shaping a particular glyph. This might be used, for instance, for embedding a picture or a widget inside a PangoLayout.

pango_attr_shape_new_with_data ()

PangoAttribute *    pango_attr_shape_new_with_data      (const PangoRectangle *ink_rect,
                                                         const PangoRectangle *logical_rect,
                                                         gpointer data,
                                                         PangoAttrDataCopyFunc copy_func,
                                                         GDestroyNotify destroy_func);

Like pango_attr_shape_new(), but a user data pointer is also provided; this pointer can be accessed when later rendering the glyph.

Since 1.8

PangoAttrDataCopyFunc ()

gpointer            (*PangoAttrDataCopyFunc)            (gconstpointer data);

A copy function passed to attribute new functions that take user data.

pango_attr_scale_new ()

PangoAttribute *    pango_attr_scale_new                (double scale_factor);

Create a new font size scale attribute. The base font for the affected text will have its size multiplied by scale_factor.

PANGO_SCALE_XX_SMALL

#define PANGO_SCALE_XX_SMALL ((double)0.5787037037037)

The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).

PANGO_SCALE_X_SMALL

#define PANGO_SCALE_X_SMALL  ((double)0.6444444444444)

The scale factor for two shrinking steps (1 / (1.2 * 1.2)).

PANGO_SCALE_SMALL

#define PANGO_SCALE_SMALL    ((double)0.8333333333333)

The scale factor for one shrinking step (1 / 1.2).

PANGO_SCALE_MEDIUM

#define PANGO_SCALE_MEDIUM   ((double)1.0)

The scale factor for normal size (1.0).

PANGO_SCALE_LARGE

#define PANGO_SCALE_LARGE    ((double)1.2)

The scale factor for one magnification step (1.2).

PANGO_SCALE_X_LARGE

#define PANGO_SCALE_X_LARGE  ((double)1.4399999999999)

The scale factor for two magnification steps (1.2 * 1.2).

PANGO_SCALE_XX_LARGE

#define PANGO_SCALE_XX_LARGE ((double)1.728)

The scale factor for three magnification steps (1.2 * 1.2 * 1.2).

pango_attr_rise_new ()

PangoAttribute *    pango_attr_rise_new                 (int rise);

Create a new baseline displacement attribute.

pango_attr_letter_spacing_new ()

PangoAttribute *    pango_attr_letter_spacing_new       (int letter_spacing);

Create a new letter-spacing attribute.

Since 1.6

pango_attr_fallback_new ()

PangoAttribute *    pango_attr_fallback_new             (gboolean enable_fallback);

Create a new font fallback attribute.

If fallback is disabled, characters will only be used from the closest matching font on the system. No fallback will be done to other fonts on the system that might contain the characters in the text.

Since 1.4

pango_attr_gravity_new ()

PangoAttribute *    pango_attr_gravity_new              (PangoGravity gravity);

Create a new gravity attribute.

Since 1.16

pango_attr_gravity_hint_new ()

PangoAttribute *    pango_attr_gravity_hint_new         (PangoGravityHint hint);

Create a new gravity hint attribute.

Since 1.16

PangoColor

typedef struct {
  guint16 red;
  guint16 green;
  guint16 blue;
} PangoColor;

The PangoColor structure is used to represent a color in an uncalibrated RGB color-space.

PANGO_TYPE_COLOR

#define PANGO_TYPE_COLOR pango_color_get_type ()

The GObject type for PangoColor.

pango_color_parse ()

gboolean            pango_color_parse                   (PangoColor *color,
                                                         const char *spec);

Fill in the fields of a color from a string specification. The string can either one of a large set of standard names. (Taken from the X11 rgb.txt file), or it can be a hex value in the form '#rgb' '#rrggbb' '#rrrgggbbb' or '#rrrrggggbbbb' where 'r', 'g' and 'b' are hex digits of the red, green, and blue components of the color, respectively. (White in the four forms is '#fff' '#ffffff' '#fffffffff' and '#ffffffffffff')

pango_color_copy ()

PangoColor *        pango_color_copy                    (const PangoColor *src);

Creates a copy of src, which should be freed with pango_color_free(). Primarily used by language bindings, not that useful otherwise (since colors can just be copied by assignment in C).

pango_color_free ()

void                pango_color_free                    (PangoColor *color);

Frees a color allocated by pango_color_copy().

pango_color_to_string ()

gchar *             pango_color_to_string               (const PangoColor *color);

Returns a textual specification of color in the hexadecimal form #rrrrggggbbbb, where r, g and b are hex digits representing the red, green, and blue components respectively.

Since 1.16

PangoAttrList

typedef struct _PangoAttrList 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_TYPE_ATTR_LIST

#define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()

The GObject type for PangoAttrList.

pango_attr_list_new ()

PangoAttrList *     pango_attr_list_new                 (void);

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

pango_attr_list_ref ()

PangoAttrList *     pango_attr_list_ref                 (PangoAttrList *list);

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

Since 1.10

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_splice ()

void                pango_attr_list_splice              (PangoAttrList *list,
                                                         PangoAttrList *other,
                                                         gint pos,
                                                         gint len);

This function opens up a hole in list, fills it in with attributes from the left, and then merges other on top of the hole.

This operation is equivalent to stretching every attribute that applies at position pos in list by an amount len, and then calling pango_attr_list_change() with a copy of each attribute in other in sequence (offset in position by pos).

This operation proves useful for, for instance, inserting a pre-edit string in the middle of an edit buffer.

pango_attr_list_filter ()

PangoAttrList *     pango_attr_list_filter              (PangoAttrList *list,
                                                         PangoAttrFilterFunc func,
                                                         gpointer data);

Given a PangoAttrList and callback function, removes any elements of list for which func returns TRUE and inserts them into a new list.

Since 1.2

PangoAttrFilterFunc ()

gboolean            (*PangoAttrFilterFunc)              (PangoAttribute *attribute,
                                                         gpointer data);

A predicate function used by pango_attr_list_filter() to filter out a subset of attributes for a 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 must not be modified until this iterator is freed.

PangoAttrIterator

typedef struct _PangoAttrIterator PangoAttrIterator;

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.

pango_attr_iterator_copy ()

PangoAttrIterator * pango_attr_iterator_copy            (PangoAttrIterator *iterator);

Copy a PangoAttrIterator

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. Note that the stored return values are signed, not unsigned like the values in PangoAttribute. To deal with this API oversight, stored return values that wouldn't fit into a signed integer are clamped to G_MAXINT.

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 *desc,
                                                         PangoLanguage **language,
                                                         GSList **extra_attrs);

Get the font and other attributes at the current iterator position.

pango_attr_iterator_get_attrs ()

GSList *            pango_attr_iterator_get_attrs       (PangoAttrIterator *iterator);

Gets a list of all attributes at the current position of the iterator.

Since 1.2

pango_attr_iterator_destroy ()

void                pango_attr_iterator_destroy         (PangoAttrIterator *iterator);

Destroy a PangoAttrIterator and free all associated memory.