1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Font and other attributes for annotating text
7 <!-- ##### SECTION Long_Description ##### -->
9 Attributed text is used in a number of places in Pango. It
10 is used as the input to the itemization process and also when
11 creating a #PangoLayout. The data types and functions in
12 this section are used to represent and manipulate sets
13 of attributes applied to a portion of text.
16 <!-- ##### SECTION See_Also ##### -->
21 <!-- ##### SECTION Stability_Level ##### -->
24 <!-- ##### SECTION Image ##### -->
27 <!-- ##### ENUM PangoAttrType ##### -->
30 distinguishes between different types of attributes. Along with the
31 predefined values, it is possible to allocate additional values
32 for custom attributes using pango_attr_type_register(). The predefined
33 values are given below. The type of structure used to store the
34 attribute is listed in parentheses after the description.
37 @PANGO_ATTR_INVALID: does not happen
38 @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
39 @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
40 @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
41 @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
42 @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
43 @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
44 @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
45 @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
46 @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
47 @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
48 @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
49 @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
50 @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
51 @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
52 @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
53 @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
54 @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
55 @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
56 @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
57 @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
58 @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt)
59 @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt)
61 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
63 The #GObject type for #PangoAttrType.
68 <!-- ##### STRUCT PangoAttrClass ##### -->
70 The #PangoAttrClass structure stores the type and operations for
71 a particular type of attribute. The functions in this structure should
72 not be called directly. Instead, one should use the wrapper functions
73 provided for #PangoAttribute.
76 @type: the type ID for this attribute
77 @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
78 @destroy: function to free an attribute of this type (see pango_attribute_destroy())
79 @equal: function to check two attributes of this type for equality (see pango_attribute_equal())
81 <!-- ##### STRUCT PangoAttribute ##### -->
83 The #PangoAttribute structure represents the common portions of all
84 attributes. Particular types of attributes include this structure
85 as their initial portion. The common portion of the attribute holds
86 the range to which the value in the type-specific part of the attribute
87 applies and should be initialized using pango_attribute_init().
88 By default an attribute will have an all-inclusive range of [0,%G_MAXUINT].
91 @klass: the class structure holding information about the type of the attribute
92 @start_index: the start index of the range (in bytes).
93 @end_index: end index of the range (in bytes). The character at this index
94 is not included in the range.
96 <!-- ##### MACRO PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING ##### -->
98 This value can be used to set the start_index member of a #PangoAttribute
99 such that the attribute covers from the beginning of the text.
106 <!-- ##### MACRO PANGO_ATTR_INDEX_TO_TEXT_END ##### -->
108 This value can be used to set the end_index member of a #PangoAttribute
109 such that the attribute covers to the end of the text.
116 <!-- ##### STRUCT PangoAttrString ##### -->
118 The #PangoAttrString structure is used to represent attributes with
122 @attr: the common portion of the attribute
123 @value: the string which is the value of the attribute
125 <!-- ##### STRUCT PangoAttrLanguage ##### -->
127 The #PangoAttrLanguage structure is used to represent attributes that
131 @attr: the common portion of the attribute
132 @value: the #PangoLanguage which is the value of the attribute
134 <!-- ##### STRUCT PangoAttrColor ##### -->
136 The #PangoAttrColor structure is used to represent attributes that
140 @attr: the common portion of the attribute
141 @color: the #PangoColor which is the value of the attribute
143 <!-- ##### STRUCT PangoAttrInt ##### -->
145 The #PangoAttrInt structure is used to represent attributes with
146 an integer or enumeration value.
149 @attr: the common portion of the attribute
150 @value: the value of the attribute
152 <!-- ##### STRUCT PangoAttrFloat ##### -->
154 The #PangoAttrFloat structure is used to represent attributes with
155 a float or double value.
158 @attr: the common portion of the attribute
159 @value: the value of the attribute
161 <!-- ##### STRUCT PangoAttrFontDesc ##### -->
163 The #PangoAttrFontDesc structure is used to store an attribute that
164 sets all aspects of the font description at once.
167 @attr: the common portion of the attribute
168 @desc: the font description which is the value of this attribute
170 <!-- ##### STRUCT PangoAttrShape ##### -->
172 The #PangoAttrShape structure is used to represent attributes which
173 impose shape restrictions.
176 @attr: the common portion of the attribute
177 @ink_rect: the ink rectangle to restrict to
178 @logical_rect: the logical rectangle to restrict to
179 @data: user data set (see pango_attr_shape_new_with_data())
180 @copy_func: copy function for the user data
181 @destroy_func: destroy function for the user data
183 <!-- ##### STRUCT PangoAttrSize ##### -->
185 The #PangoAttrShape structure is used to represent attributes which
189 @attr: the common portion of the attribute
190 @size: size of font, in units of 1/%PANGO_SCALE of a point (for
191 %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE)
192 @absolute: whether the font size is in device units or points.
193 This field is only present for compatibility with Pango-1.8.0
194 (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
195 be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
197 <!-- ##### FUNCTION pango_parse_markup ##### -->
212 <!-- ##### FUNCTION pango_attr_type_register ##### -->
221 <!-- ##### FUNCTION pango_attr_type_get_name ##### -->
230 <!-- ##### FUNCTION pango_attribute_init ##### -->
239 <!-- ##### FUNCTION pango_attribute_copy ##### -->
248 <!-- ##### FUNCTION pango_attribute_equal ##### -->
258 <!-- ##### FUNCTION pango_attribute_destroy ##### -->
266 <!-- ##### FUNCTION pango_attr_language_new ##### -->
275 <!-- ##### FUNCTION pango_attr_family_new ##### -->
284 <!-- ##### FUNCTION pango_attr_style_new ##### -->
293 <!-- ##### FUNCTION pango_attr_variant_new ##### -->
302 <!-- ##### FUNCTION pango_attr_stretch_new ##### -->
311 <!-- ##### FUNCTION pango_attr_weight_new ##### -->
320 <!-- ##### FUNCTION pango_attr_size_new ##### -->
329 <!-- ##### FUNCTION pango_attr_size_new_absolute ##### -->
338 <!-- ##### FUNCTION pango_attr_font_desc_new ##### -->
347 <!-- ##### FUNCTION pango_attr_foreground_new ##### -->
358 <!-- ##### FUNCTION pango_attr_background_new ##### -->
369 <!-- ##### FUNCTION pango_attr_strikethrough_new ##### -->
378 <!-- ##### FUNCTION pango_attr_strikethrough_color_new ##### -->
389 <!-- ##### FUNCTION pango_attr_underline_new ##### -->
398 <!-- ##### FUNCTION pango_attr_underline_color_new ##### -->
409 <!-- ##### ENUM PangoUnderline ##### -->
411 the #PangoUnderline enumeration is used to specify
412 whether text should be underlined, and if so, the type
416 @PANGO_UNDERLINE_NONE: no underline should be drawn
417 @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
418 @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
419 @PANGO_UNDERLINE_LOW: a single underline should be drawn at a position
420 beneath the ink extents of the text being
421 underlined. This should be used only for underlining
422 single characters, such as for keyboard
423 accelerators. %PANGO_UNDERLINE_SINGLE should
424 be used for extended portions of text.
425 @PANGO_UNDERLINE_ERROR: a wavy underline should be drawn below.
426 This underline is typically used to indicate
427 an error such as a possilble mispelling; in some
428 cases a contrasting color may automatically
429 be used. This type of underlining is available
432 <!-- ##### MACRO PANGO_TYPE_UNDERLINE ##### -->
434 The #GObject type for #PangoUnderline.
439 <!-- ##### FUNCTION pango_attr_shape_new ##### -->
449 <!-- ##### FUNCTION pango_attr_shape_new_with_data ##### -->
462 <!-- ##### USER_FUNCTION PangoAttrDataCopyFunc ##### -->
464 A copy function passed to attribute new functions that take
469 @Returns: a new copy of @data.
472 <!-- ##### FUNCTION pango_attr_scale_new ##### -->
481 <!-- ##### MACRO PANGO_SCALE_XX_SMALL ##### -->
483 The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).
488 <!-- ##### MACRO PANGO_SCALE_X_SMALL ##### -->
490 The scale factor for two shrinking steps (1 / (1.2 * 1.2)).
495 <!-- ##### MACRO PANGO_SCALE_SMALL ##### -->
497 The scale factor for one shrinking step (1 / 1.2).
502 <!-- ##### MACRO PANGO_SCALE_MEDIUM ##### -->
504 The scale factor for normal size (1.0).
509 <!-- ##### MACRO PANGO_SCALE_LARGE ##### -->
511 The scale factor for one magnification step (1.2).
516 <!-- ##### MACRO PANGO_SCALE_X_LARGE ##### -->
518 The scale factor for two magnification steps (1.2 * 1.2).
523 <!-- ##### MACRO PANGO_SCALE_XX_LARGE ##### -->
525 The scale factor for three magnification steps (1.2 * 1.2 * 1.2).
530 <!-- ##### FUNCTION pango_attr_rise_new ##### -->
539 <!-- ##### FUNCTION pango_attr_letter_spacing_new ##### -->
548 <!-- ##### FUNCTION pango_attr_fallback_new ##### -->
557 <!-- ##### FUNCTION pango_attr_gravity_new ##### -->
566 <!-- ##### FUNCTION pango_attr_gravity_hint_new ##### -->
575 <!-- ##### STRUCT PangoColor ##### -->
577 The #PangoColor structure is used to
578 represent a color in an uncalibrated RGB color-space.
582 <!-- ##### MACRO PANGO_TYPE_COLOR ##### -->
584 The #GObject type for #PangoColor.
589 <!-- ##### FUNCTION pango_color_parse ##### -->
599 <!-- ##### FUNCTION pango_color_copy ##### -->
608 <!-- ##### FUNCTION pango_color_free ##### -->
616 <!-- ##### FUNCTION pango_color_to_string ##### -->
625 <!-- ##### STRUCT PangoAttrList ##### -->
627 The #PangoAttrList structure represents a list of attributes
628 that apply to a section of text. The attributes are, in general,
629 allowed to overlap in an arbitrary fashion, however, if the
630 attributes are manipulated only through pango_attr_list_change(),
631 the overlap between properties will meet stricter criteria.
634 Since the #PangoAttrList structure is stored as a linear list,
635 it is not suitable for storing attributes for large amounts
636 of text. In general, you should not use a single #PangoAttrList
637 for more than one paragraph of text.
641 <!-- ##### MACRO PANGO_TYPE_ATTR_LIST ##### -->
643 The #GObject type for #PangoAttrList.
648 <!-- ##### FUNCTION pango_attr_list_new ##### -->
657 <!-- ##### FUNCTION pango_attr_list_ref ##### -->
666 <!-- ##### FUNCTION pango_attr_list_unref ##### -->
674 <!-- ##### FUNCTION pango_attr_list_copy ##### -->
683 <!-- ##### FUNCTION pango_attr_list_insert ##### -->
692 <!-- ##### FUNCTION pango_attr_list_insert_before ##### -->
701 <!-- ##### FUNCTION pango_attr_list_change ##### -->
710 <!-- ##### FUNCTION pango_attr_list_splice ##### -->
721 <!-- ##### FUNCTION pango_attr_list_filter ##### -->
732 <!-- ##### USER_FUNCTION PangoAttrFilterFunc ##### -->
734 A predicate function used by pango_attr_list_filter()
735 to filter out a subset of attributes for a list.
738 @attribute: a #PangoAttribute
739 @data: callback data passed to pango_attr_list_filter()
740 @Returns: %TRUE if the attribute should be filtered out
743 <!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
752 <!-- ##### STRUCT PangoAttrIterator ##### -->
754 The #PangoAttrIterator structure is used to represent an
755 iterator through a #PangoAttrList. A new iterator is created
756 with pango_attr_list_get_iterator(). Once the iterator
757 is created, it can be advanced through the style changes
758 in the text using pango_attr_iterator_next(). At each
759 style change, the range of the current style segment and the
760 attributes currently in effect can be queried.
764 <!-- ##### FUNCTION pango_attr_iterator_copy ##### -->
773 <!-- ##### FUNCTION pango_attr_iterator_next ##### -->
782 <!-- ##### FUNCTION pango_attr_iterator_range ##### -->
792 <!-- ##### FUNCTION pango_attr_iterator_get ##### -->
802 <!-- ##### FUNCTION pango_attr_iterator_get_font ##### -->
813 <!-- ##### FUNCTION pango_attr_iterator_get_attrs ##### -->
822 <!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->