manpagez: man pages & more
html files: pango
Home | html | info | man

Text Attributes

Text Attributes — Font and other attributes for annotating text

Functions

gboolean pango_parse_markup ()
GMarkupParseContext * pango_markup_parser_new ()
gboolean pango_markup_parser_finish ()
PangoAttrType pango_attr_type_register ()
const char * pango_attr_type_get_name ()
void pango_attribute_init ()
PangoAttribute * pango_attribute_copy ()
gboolean pango_attribute_equal ()
void pango_attribute_destroy ()
PangoAttribute * pango_attr_language_new ()
PangoAttribute * pango_attr_family_new ()
PangoAttribute * pango_attr_style_new ()
PangoAttribute * pango_attr_variant_new ()
PangoAttribute * pango_attr_stretch_new ()
PangoAttribute * pango_attr_weight_new ()
PangoAttribute * pango_attr_size_new ()
PangoAttribute * pango_attr_size_new_absolute ()
PangoAttribute * pango_attr_font_desc_new ()
PangoAttribute * pango_attr_foreground_new ()
PangoAttribute * pango_attr_background_new ()
PangoAttribute * pango_attr_strikethrough_new ()
PangoAttribute * pango_attr_strikethrough_color_new ()
PangoAttribute * pango_attr_underline_new ()
PangoAttribute * pango_attr_underline_color_new ()
PangoAttribute * pango_attr_shape_new ()
PangoAttribute * pango_attr_shape_new_with_data ()
gpointer (*PangoAttrDataCopyFunc) ()
PangoAttribute * pango_attr_scale_new ()
PangoAttribute * pango_attr_rise_new ()
PangoAttribute * pango_attr_letter_spacing_new ()
PangoAttribute * pango_attr_fallback_new ()
PangoAttribute * pango_attr_gravity_new ()
PangoAttribute * pango_attr_gravity_hint_new ()
PangoAttribute * pango_attr_font_features_new ()
PangoAttribute * pango_attr_foreground_alpha_new ()
PangoAttribute * pango_attr_background_alpha_new ()
gboolean pango_color_parse ()
PangoColor * pango_color_copy ()
void pango_color_free ()
gchar * pango_color_to_string ()
PangoAttrList * pango_attr_list_new ()
PangoAttrList * pango_attr_list_ref ()
void pango_attr_list_unref ()
PangoAttrList * pango_attr_list_copy ()
void pango_attr_list_insert ()
void pango_attr_list_insert_before ()
void pango_attr_list_change ()
void pango_attr_list_splice ()
PangoAttrList * pango_attr_list_filter ()
gboolean (*PangoAttrFilterFunc) ()
PangoAttrIterator * pango_attr_list_get_iterator ()
PangoAttrIterator * pango_attr_iterator_copy ()
gboolean pango_attr_iterator_next ()
void pango_attr_iterator_range ()
PangoAttribute * pango_attr_iterator_get ()
void pango_attr_iterator_get_font ()
GSList * pango_attr_iterator_get_attrs ()
void pango_attr_iterator_destroy ()

Object Hierarchy

    GBoxed
    ├── PangoAttrList
    ╰── PangoColor
    GEnum
    ├── PangoAttrType
    ╰── PangoUnderline

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.

Functions

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.

To parse a stream of pango markup incrementally, use pango_markup_parser_new().

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

Parameters

markup_text

markup to parse (see markup format)

 

length

length of markup_text , or -1 if nul-terminated

 

accel_marker

character that precedes an accelerator, or 0 for none

 

attr_list

address of return location for a PangoAttrList, or NULL.

[out][allow-none]

text

address of return location for text with tags stripped, or NULL.

[out][allow-none]

accel_char

address of return location for accelerator char, or NULL.

[out][allow-none]

error

address of return location for errors, or NULL

 

Returns

FALSE if error is set, otherwise TRUE


pango_markup_parser_new ()

GMarkupParseContext *
pango_markup_parser_new (gunichar accel_marker);

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 , when calling finish(). Two accel_marker characters following each other produce a single literal accel_marker character.

To feed markup to the parser, use g_markup_parse_context_parse() on the returned GMarkupParseContext. When done with feeding markup to the parser, use pango_markup_parser_finish() to get the data out of it, and then use g_markup_parse_context_free() to free it.

This function is designed for applications that read pango markup from streams. To simply parse a string containing pango markup, the simpler pango_parse_markup() API is recommended instead.

Parameters

accel_marker

character that precedes an accelerator, or 0 for none

 

Returns

a GMarkupParseContext that should be destroyed with g_markup_parse_context_free().

[transfer none]

Since: 1.31.0


pango_markup_parser_finish ()

gboolean
pango_markup_parser_finish (GMarkupParseContext *context,
                            PangoAttrList **attr_list,
                            char **text,
                            gunichar *accel_char,
                            GError **error);

After feeding a pango markup parser some data with g_markup_parse_context_parse(), use this function to get the list of pango attributes and text out of the markup. This function will not free context , use g_markup_parse_context_free() to do so.

Parameters

context

A valid parse context that was returned from pango_markup_parser_new()

 

attr_list

address of return location for a PangoAttrList, or NULL.

[out][allow-none]

text

address of return location for text with tags stripped, or NULL.

[out][allow-none]

accel_char

address of return location for accelerator char, or NULL.

[out][allow-none]

error

address of return location for errors, or NULL

 

Returns

FALSE if error is set, otherwise TRUE

Since: 1.31.0


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

Parameters

name

an identifier for the type

 

Returns

the new type ID.


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.

Parameters

type

an attribute type ID to fetch the name for

 

Returns

the type ID name (which may be NULL), or NULL if type is a built-in Pango attribute type or invalid.

[nullable]

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.

Parameters

attr

a PangoAttribute

 

klass

a PangoAttrClass

 

Since: 1.20


pango_attribute_copy ()

PangoAttribute *
pango_attribute_copy (const PangoAttribute *attr);

Make a copy of an attribute.

Parameters

attr

a PangoAttribute

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


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.

Parameters

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.

Parameters

attr

a PangoAttribute.

 

pango_attr_language_new ()

PangoAttribute *
pango_attr_language_new (PangoLanguage *language);

Create a new language tag attribute.

Parameters

language

language tag

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_family_new ()

PangoAttribute *
pango_attr_family_new (const char *family);

Create a new font family attribute.

Parameters

family

the family or comma separated list of families

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_style_new ()

PangoAttribute *
pango_attr_style_new (PangoStyle style);

Create a new font slant style attribute.

Parameters

style

the slant style

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_variant_new ()

PangoAttribute *
pango_attr_variant_new (PangoVariant variant);

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

Parameters

variant

the variant

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_stretch_new ()

PangoAttribute *
pango_attr_stretch_new (PangoStretch stretch);

Create a new font stretch attribute

Parameters

stretch

the stretch

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_weight_new ()

PangoAttribute *
pango_attr_weight_new (PangoWeight weight);

Create a new font weight attribute.

Parameters

weight

the weight

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_size_new ()

PangoAttribute *
pango_attr_size_new (int size);

Create a new font-size attribute in fractional points.

Parameters

size

the font size, in PANGO_SCALEths of a point.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_size_new_absolute ()

PangoAttribute *
pango_attr_size_new_absolute (int size);

Create a new font-size attribute in device units.

Parameters

size

the font size, in PANGO_SCALEths of a device unit.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

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.

Parameters

desc

the font description

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_foreground_new ()

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

Create a new foreground color attribute.

Parameters

red

the red value (ranging from 0 to 65535)

 

green

the green value

 

blue

the blue value

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_background_new ()

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

Create a new background color attribute.

Parameters

red

the red value (ranging from 0 to 65535)

 

green

the green value

 

blue

the blue value

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_strikethrough_new ()

PangoAttribute *
pango_attr_strikethrough_new (gboolean strikethrough);

Create a new strike-through attribute.

Parameters

strikethrough

TRUE if the text should be struck-through.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


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.

Parameters

red

the red value (ranging from 0 to 65535)

 

green

the green value

 

blue

the blue value

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.8


pango_attr_underline_new ()

PangoAttribute *
pango_attr_underline_new (PangoUnderline underline);

Create a new underline-style attribute.

Parameters

underline

the underline style.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


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.

Parameters

red

the red value (ranging from 0 to 65535)

 

green

the green value

 

blue

the blue value

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.8


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.

Parameters

ink_rect

ink rectangle to assign to each character

 

logical_rect

logical rectangle to assign to each character

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


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.

Parameters

ink_rect

ink rectangle to assign to each character

 

logical_rect

logical rectangle to assign to each character

 

data

user data pointer

 

copy_func

function to copy data when the attribute is copied. If NULL, data is simply copied as a pointer.

[allow-none]

destroy_func

function to free data when the attribute is freed, or NULL.

[allow-none]

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

Since: 1.8


PangoAttrDataCopyFunc ()

gpointer
(*PangoAttrDataCopyFunc) (gconstpointer user_data);

Type of a function that can duplicate user data for an attribute.

Parameters

user_data

user data to copy

 

Returns

new copy of 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 .

Parameters

scale_factor

factor to scale the font

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_rise_new ()

PangoAttribute *
pango_attr_rise_new (int rise);

Create a new baseline displacement attribute.

Parameters

rise

the amount that the text should be displaced vertically, in Pango units. Positive values displace the text upwards.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]


pango_attr_letter_spacing_new ()

PangoAttribute *
pango_attr_letter_spacing_new (int letter_spacing);

Create a new letter-spacing attribute.

Parameters

letter_spacing

amount of extra space to add between graphemes of the text, in Pango units.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

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.

Parameters

enable_fallback

TRUE if we should fall back on other fonts for characters the active font is missing.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.4


pango_attr_gravity_new ()

PangoAttribute *
pango_attr_gravity_new (PangoGravity gravity);

Create a new gravity attribute.

Parameters

gravity

the gravity value; should not be PANGO_GRAVITY_AUTO.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.16


pango_attr_gravity_hint_new ()

PangoAttribute *
pango_attr_gravity_hint_new (PangoGravityHint hint);

Create a new gravity hint attribute.

Parameters

hint

the gravity hint value.

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.16


pango_attr_font_features_new ()

PangoAttribute *
pango_attr_font_features_new (const gchar *features);

Create a new font features tag attribute.

Parameters

features

a string with OpenType font features, in CSS syntax

 

Returns

the newly allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.38


pango_attr_foreground_alpha_new ()

PangoAttribute *
pango_attr_foreground_alpha_new (guint16 alpha);

Create a new foreground alpha attribute.

Parameters

alpha

the alpha value, between 1 and 65536

 

Returns

the new allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.38


pango_attr_background_alpha_new ()

PangoAttribute *
pango_attr_background_alpha_new (guint16 alpha);

Create a new background alpha attribute.

Parameters

alpha

the alpha value, between 1 and 65536

 

Returns

the new allocated PangoAttribute, which should be freed with pango_attribute_destroy().

[transfer full]

Since: 1.38


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 CSS specification), or it can be a hexadecimal 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')

Parameters

color

a PangoColor structure in which to store the result, or NULL.

[nullable]

spec

a string specifying the new color

 

Returns

TRUE if parsing of the specifier succeeded, otherwise false.


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

Parameters

src

color to copy, may be NULL.

[nullable]

Returns

the newly allocated PangoColor, which should be freed with pango_color_free(), or NULL if src was NULL.

[nullable]


pango_color_free ()

void
pango_color_free (PangoColor *color);

Frees a color allocated by pango_color_copy().

Parameters

color

an allocated PangoColor, may be NULL.

[nullable]

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.

Parameters

color

a PangoColor

 

Returns

a newly-allocated text string that must be freed with g_free().

Since: 1.16


pango_attr_list_new ()

PangoAttrList *
pango_attr_list_new (void);

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

Returns

the newly allocated PangoAttrList, which should be freed with pango_attr_list_unref().

[transfer full]


pango_attr_list_ref ()

PangoAttrList *
pango_attr_list_ref (PangoAttrList *list);

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

Parameters

list

a PangoAttrList, may be NULL.

[nullable]

Returns

The attribute list passed in

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.

Parameters

list

a PangoAttrList, may be NULL.

[nullable]

pango_attr_list_copy ()

PangoAttrList *
pango_attr_list_copy (PangoAttrList *list);

Copy list and return an identical new list.

Parameters

list

a PangoAttrList, may be NULL.

[nullable]

Returns

the newly allocated PangoAttrList, with a reference count of one, which should be freed with pango_attr_list_unref(). Returns NULL if list was NULL.

[nullable]


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 .

Parameters

list

a PangoAttrList

 

attr

the attribute to insert. Ownership of this value is assumed by the list.

[transfer full]

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 .

Parameters

list

a PangoAttrList

 

attr

the attribute to insert. Ownership of this value is assumed by the list.

[transfer full]

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.

Parameters

list

a PangoAttrList

 

attr

the attribute to insert. Ownership of this value is assumed by the list.

[transfer full]

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.

Parameters

list

a PangoAttrList

 

other

another PangoAttrList

 

pos

the position in list at which to insert other

 

len

the length of the spliced segment. (Note that this must be specified since the attributes in other may only be present at some subsection of this range)

 

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.

Parameters

list

a PangoAttrList

 

func

callback function; returns TRUE if an attribute should be filtered out.

[scope call][closure data]

data

Data to be passed to func .

[closure]

Returns

the new PangoAttrList or NULL if no attributes of the given types were found.

[transfer full][nullable]

Since: 1.2


PangoAttrFilterFunc ()

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

Type of a function filtering a list of attributes.

Parameters

attribute

a Pango attribute

 

user_data

user data passed to the function

 

Returns

TRUE if the attribute should be selected for filtering, FALSE otherwise.


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.

Parameters

list

a PangoAttrList

 

Returns

the newly allocated PangoAttrIterator, which should be freed with pango_attr_iterator_destroy().

[transfer full]


pango_attr_iterator_copy ()

PangoAttrIterator *
pango_attr_iterator_copy (PangoAttrIterator *iterator);

Copy a PangoAttrIterator

Parameters

iterator

a PangoAttrIterator.

 

Returns

the newly allocated PangoAttrIterator, which should be freed with pango_attr_iterator_destroy().

[transfer full]


pango_attr_iterator_next ()

gboolean
pango_attr_iterator_next (PangoAttrIterator *iterator);

Advance the iterator until the next change of style.

Parameters

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

Parameters

iterator

a PangoAttrIterator

 

start

location to store the start of the range.

[out]

end

location to store the end of the range.

[out]

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.

Parameters

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.

[nullable]


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.

Parameters

iterator

a PangoAttrIterator

 

desc

a PangoFontDescription to fill in with the current values. The family name in this structure will be set using pango_font_description_set_family_static() using values from an attribute in the PangoAttrList associated with the iterator, so if you plan to keep it around, you must call: pango_font_description_set_family (desc, pango_font_description_get_family (desc)).

 

language

if non-NULL, location to store language tag for item, or NULL if none is found.

[allow-none]

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.

[allow-none][element-type Pango.Attribute][transfer full]

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.

Parameters

iterator

a PangoAttrIterator

 

Returns

a list of all attributes for the current range. To free this value, call pango_attribute_destroy() on each value and g_slist_free() on the list.

[element-type Pango.Attribute][transfer full]

Since: 1.2


pango_attr_iterator_destroy ()

void
pango_attr_iterator_destroy (PangoAttrIterator *iterator);

Destroy a PangoAttrIterator and free all associated memory.

Parameters

iterator

a PangoAttrIterator.

 

Types and Values

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

Members

PANGO_ATTR_INVALID

does not happen

 

PANGO_ATTR_LANGUAGE

language (PangoAttrLanguage)

 

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 points scaled by PANGO_SCALE (PangoAttrInt)

 

PANGO_ATTR_FONT_DESC

font description (PangoAttrFontDesc)

 

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)

 

PANGO_ATTR_SHAPE

shape (PangoAttrShape)

 

PANGO_ATTR_SCALE

font size scale factor (PangoAttrFloat)

 

PANGO_ATTR_FALLBACK

whether fallback is enabled (PangoAttrInt)

 

PANGO_ATTR_LETTER_SPACING

letter spacing (PangoAttrInt)

 

PANGO_ATTR_UNDERLINE_COLOR

underline color (PangoAttrColor)

 

PANGO_ATTR_STRIKETHROUGH_COLOR

strikethrough color (PangoAttrColor)

 

PANGO_ATTR_ABSOLUTE_SIZE

font size in pixels scaled by PANGO_SCALE (PangoAttrInt)

 

PANGO_ATTR_GRAVITY

base text gravity (PangoAttrInt)

 

PANGO_ATTR_GRAVITY_HINT

gravity hint (PangoAttrInt)

 

PANGO_ATTR_FONT_FEATURES

OpenType font features (PangoAttrString). Since 1.38

 

PANGO_ATTR_FOREGROUND_ALPHA

foreground alpha (PangoAttrInt). Since 1.38

 

PANGO_ATTR_BACKGROUND_ALPHA

background alpha (PangoAttrInt). Since 1.38

 

PANGO_TYPE_ATTR_TYPE

#define PANGO_TYPE_ATTR_TYPE (pango_attr_type_get_type ())

struct PangoAttrClass

struct PangoAttrClass {
  PangoAttrType type;
  PangoAttribute * (*copy) (const PangoAttribute *attr);
  void             (*destroy) (PangoAttribute *attr);
  gboolean         (*equal) (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.

Members

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

 

equal ()

function to check two attributes of this type for equality (see pango_attribute_equal())

 

struct PangoAttribute

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

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

Members

const PangoAttrClass *klass;

the class structure holding information about the type of the attribute

 

guint start_index;

the start index of the range (in bytes).

 

guint end_index;

end index of the range (in bytes). The character at this index is not included in the range.

 

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.

Since: 1.24


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.

Since: 1.24


struct PangoAttrString

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

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

Members

PangoAttribute attr;

the common portion of the attribute

 

char *value;

the string which is the value of the attribute

 

struct PangoAttrLanguage

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

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

Members

PangoAttribute attr;

the common portion of the attribute

 

PangoLanguage *value;

the PangoLanguage which is the value of the attribute

 

struct PangoAttrColor

struct PangoAttrColor {
  PangoAttribute attr;
  PangoColor color;
};

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

Members

PangoAttribute attr;

the common portion of the attribute

 

PangoColor color;

the PangoColor which is the value of the attribute

 

struct PangoAttrInt

struct PangoAttrInt {
  PangoAttribute attr;
  int value;
};

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

Members

PangoAttribute attr;

the common portion of the attribute

 

int value;

the value of the attribute

 

struct PangoAttrFloat

struct PangoAttrFloat {
  PangoAttribute attr;
  double value;
};

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

Members

PangoAttribute attr;

the common portion of the attribute

 

double value;

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

Members

PangoAttribute attr;

the common portion of the attribute

 

PangoFontDescription *desc;

the font description which is the value of this attribute

 

struct PangoAttrShape

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

  gpointer              data;
  PangoAttrDataCopyFunc copy_func;
  GDestroyNotify        destroy_func;
};

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

Members

PangoAttribute attr;

the common portion of the attribute

 

PangoRectangle ink_rect;

the ink rectangle to restrict to

 

PangoRectangle logical_rect;

the logical rectangle to restrict to

 

gpointer data;

user data set (see pango_attr_shape_new_with_data())

 

PangoAttrDataCopyFunc copy_func;

copy function for the user data

 

GDestroyNotify destroy_func;

destroy function for the user data

 

struct PangoAttrSize

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

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

Members

PangoAttribute attr;

the common portion of the attribute

 

int size;

size of font, in units of 1/PANGO_SCALE of a point (for PANGO_ATTR_SIZE) or of a device uni (for PANGO_ATTR_ABSOLUTE_SIZE)

 

guint absolute : 1;

whether the font size is in device units or points. This field is only present for compatibility with Pango-1.8.0 (PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will be FALSE for PANGO_ATTR_SIZE and TRUE for PANGO_ATTR_ABSOLUTE_SIZE.

 

struct PangoAttrFontFeatures

struct PangoAttrFontFeatures {
  PangoAttribute attr;
  gchar *features;
};

The PangoAttrFontFeatures structure is used to represent OpenType font features as an attribute.

Members

PangoAttribute attr;

the common portion of the attribute

 

gchar *features;

the featues, as a string in CSS syntax

 

Since: 1.38


enum PangoUnderline

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

Members

PANGO_UNDERLINE_NONE

no underline should be drawn

 

PANGO_UNDERLINE_SINGLE

a single underline should be drawn

 

PANGO_UNDERLINE_DOUBLE

a double underline should be drawn

 

PANGO_UNDERLINE_LOW

a 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_UNDERLINE_ERROR

a wavy underline should be drawn below. This underline is typically used to indicate an error such as a possilble mispelling; in some cases a contrasting color may automatically be used. This type of underlining is available since Pango 1.4.

 

PANGO_TYPE_UNDERLINE

#define PANGO_TYPE_UNDERLINE (pango_underline_get_type ())

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


struct PangoColor

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

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

Members

guint16 red;

value of red component

 

guint16 green;

value of green component

 

guint16 blue;

value of blue component

 

PANGO_TYPE_COLOR

#define PANGO_TYPE_COLOR pango_color_get_type ()

The GObject type for PangoColor.


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.


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.

© manpagez.com 2000-2017
Individual documents may contain additional copyright information.