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 <!-- ##### ENUM PangoAttrType ##### -->
27 distinguishes between different types of attributes. Along with the
28 predefined values, it is possible to allocate additional values
29 for custom attributes using pango_attr_type_register(). The predefined
30 values are given below. The type of structure used to store the
31 attribute is listed in parentheses after the description.
34 @PANGO_ATTR_INVALID: does not happen
35 @PANGO_ATTR_LANGUAGE: language (#PangoAttrLanguage)
36 @PANGO_ATTR_FAMILY: font family name list (#PangoAttrString)
37 @PANGO_ATTR_STYLE: font slant style (#PangoAttrInt)
38 @PANGO_ATTR_WEIGHT: font weight (#PangoAttrInt)
39 @PANGO_ATTR_VARIANT: font variant (normal or small caps) (#PangoAttrInt)
40 @PANGO_ATTR_STRETCH: font stretch (#PangoAttrInt)
41 @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE (#PangoAttrInt)
42 @PANGO_ATTR_FONT_DESC: font description (#PangoAttrFontDesc)
43 @PANGO_ATTR_FOREGROUND: foreground color (#PangoAttrColor)
44 @PANGO_ATTR_BACKGROUND: background color (#PangoAttrColor)
45 @PANGO_ATTR_UNDERLINE: whether the text has an underline (#PangoAttrInt)
46 @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through (#PangoAttrInt)
47 @PANGO_ATTR_RISE: baseline displacement (#PangoAttrInt)
48 @PANGO_ATTR_SHAPE: shape (#PangoAttrShape)
49 @PANGO_ATTR_SCALE: font size scale factor (#PangoAttrFloat)
50 @PANGO_ATTR_FALLBACK: whether fallback is enabled (#PangoAttrInt)
51 @PANGO_ATTR_LETTER_SPACING: letter spacing (#PangoAttrInt)
52 @PANGO_ATTR_UNDERLINE_COLOR: underline color (#PangoAttrColor)
53 @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color (#PangoAttrColor)
54 @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE (#PangoAttrInt)
55 @PANGO_ATTR_GRAVITY: base text gravity (#PangoAttrInt)
56 @PANGO_ATTR_GRAVITY_HINT: gravity hint (#PangoAttrInt)
58 <!-- ##### MACRO PANGO_TYPE_ATTR_TYPE ##### -->
60 The #GObject type for #PangoAttrType.
65 <!-- ##### STRUCT PangoAttrClass ##### -->
67 The #PangoAttrClass structure stores the type and operations for
68 a particular type of attribute. The functions in this structure should
69 not be called directly. Instead, one should use the wrapper functions
70 provided for #PangoAttribute.
73 @type: the type ID for this attribute
74 @copy: function to duplicate an attribute of this type (see pango_attribute_copy())
75 @destroy: function to free an attribute of this type (see pango_attribute_destroy())
76 @equal: function to check two attributes of this type for equality (see pango_attribute_equal())
78 <!-- ##### STRUCT PangoAttribute ##### -->
80 The #PangoAttribute structure represents the common portions of all
81 attributes. Particular types of attributes include this structure
82 as their initial portion. The common portion of the attribute holds
83 the range to which the value in the type-specific part of the attribute
84 applies and should be initialized using pango_attribute_init().
85 By default an attribute will have an all-inclusive range of [0,%G_MAXUINT].
88 @klass: the class structure holding information about the type of the attribute
89 @start_index: the start index of the range (in bytes).
90 @end_index: end index of the range (in bytes). The character at this index
91 is not included in the range.
93 <!-- ##### MACRO PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING ##### -->
95 This value can be used to set the start_index member of a #PangoAttribute
96 such that the attribute covers from the beginning of the text.
103 <!-- ##### MACRO PANGO_ATTR_INDEX_TO_TEXT_END ##### -->
105 This value can be used to set the end_index member of a #PangoAttribute
106 such that the attribute covers to the end of the text.
113 <!-- ##### STRUCT PangoAttrString ##### -->
115 The #PangoAttrString structure is used to represent attributes with
119 @attr: the common portion of the attribute
120 @value: the string which is the value of the attribute
122 <!-- ##### STRUCT PangoAttrLanguage ##### -->
124 The #PangoAttrLanguage structure is used to represent attributes that
128 @attr: the common portion of the attribute
129 @value: the #PangoLanguage which is the value of the attribute
131 <!-- ##### STRUCT PangoAttrColor ##### -->
133 The #PangoAttrColor structure is used to represent attributes that
137 @attr: the common portion of the attribute
138 @color: the #PangoColor which is the value of the attribute
140 <!-- ##### STRUCT PangoAttrInt ##### -->
142 The #PangoAttrInt structure is used to represent attributes with
143 an integer or enumeration value.
146 @attr: the common portion of the attribute
147 @value: the value of the attribute
149 <!-- ##### STRUCT PangoAttrFloat ##### -->
151 The #PangoAttrFloat structure is used to represent attributes with
152 a float or double value.
155 @attr: the common portion of the attribute
156 @value: the value of the attribute
158 <!-- ##### STRUCT PangoAttrFontDesc ##### -->
160 The #PangoAttrFontDesc structure is used to store an attribute that
161 sets all aspects of the font description at once.
164 @attr: the common portion of the attribute
165 @desc: the font description which is the value of this attribute
167 <!-- ##### STRUCT PangoAttrShape ##### -->
169 The #PangoAttrShape structure is used to represent attributes which
170 impose shape restrictions.
173 @attr: the common portion of the attribute
174 @ink_rect: the ink rectangle to restrict to
175 @logical_rect: the logical rectangle to restrict to
176 @data: user data set (see pango_attr_shape_new_with_data())
177 @copy_func: copy function for the user data
178 @destroy_func: destroy function for the user data
180 <!-- ##### STRUCT PangoAttrSize ##### -->
182 The #PangoAttrShape structure is used to represent attributes which
186 @attr: the common portion of the attribute
187 @size: size of font, in units of 1/%PANGO_SCALE of a point (for
188 %PANGO_ATTR_SIZE) or of a device uni (for %PANGO_ATTR_ABSOLUTE_SIZE)
189 @absolute: whether the font size is in device units or points.
190 This field is only present for compatibility with Pango-1.8.0
191 (%PANGO_ATTR_ABSOLUTE_SIZE was added in 1.8.1); and always will
192 be %FALSE for %PANGO_ATTR_SIZE and %TRUE for %PANGO_ATTR_ABSOLUTE_SIZE.
194 <!-- ##### FUNCTION pango_parse_markup ##### -->
209 <!-- ##### FUNCTION pango_attr_type_register ##### -->
218 <!-- ##### FUNCTION pango_attr_type_get_name ##### -->
227 <!-- ##### FUNCTION pango_attribute_init ##### -->
236 <!-- ##### FUNCTION pango_attribute_copy ##### -->
245 <!-- ##### FUNCTION pango_attribute_equal ##### -->
255 <!-- ##### FUNCTION pango_attribute_destroy ##### -->
263 <!-- ##### FUNCTION pango_attr_language_new ##### -->
272 <!-- ##### FUNCTION pango_attr_family_new ##### -->
281 <!-- ##### FUNCTION pango_attr_style_new ##### -->
290 <!-- ##### FUNCTION pango_attr_variant_new ##### -->
299 <!-- ##### FUNCTION pango_attr_stretch_new ##### -->
308 <!-- ##### FUNCTION pango_attr_weight_new ##### -->
317 <!-- ##### FUNCTION pango_attr_size_new ##### -->
326 <!-- ##### FUNCTION pango_attr_size_new_absolute ##### -->
335 <!-- ##### FUNCTION pango_attr_font_desc_new ##### -->
344 <!-- ##### FUNCTION pango_attr_foreground_new ##### -->
355 <!-- ##### FUNCTION pango_attr_background_new ##### -->
366 <!-- ##### FUNCTION pango_attr_strikethrough_new ##### -->
375 <!-- ##### FUNCTION pango_attr_strikethrough_color_new ##### -->
386 <!-- ##### FUNCTION pango_attr_underline_new ##### -->
395 <!-- ##### FUNCTION pango_attr_underline_color_new ##### -->
406 <!-- ##### ENUM PangoUnderline ##### -->
408 the #PangoUnderline enumeration is used to specify
409 whether text should be underlined, and if so, the type
413 @PANGO_UNDERLINE_NONE: no underline should be drawn
414 @PANGO_UNDERLINE_SINGLE: a single underline should be drawn
415 @PANGO_UNDERLINE_DOUBLE: a double underline should be drawn
416 @PANGO_UNDERLINE_LOW: a single underline should be drawn at a position
417 beneath the ink extents of the text being
418 underlined. This should be used only for underlining
419 single characters, such as for keyboard
420 accelerators. %PANGO_UNDERLINE_SINGLE should
421 be used for extended portions of text.
422 @PANGO_UNDERLINE_ERROR: a wavy underline should be drawn below.
423 This underline is typically used to indicate
424 an error such as a possilble mispelling; in some
425 cases a contrasting color may automatically
426 be used. This type of underlining is available
429 <!-- ##### MACRO PANGO_TYPE_UNDERLINE ##### -->
431 The #GObject type for #PangoUnderline.
436 <!-- ##### FUNCTION pango_attr_shape_new ##### -->
446 <!-- ##### FUNCTION pango_attr_shape_new_with_data ##### -->
459 <!-- ##### USER_FUNCTION PangoAttrDataCopyFunc ##### -->
461 A copy function passed to attribute new functions that take
466 @Returns: a new copy of @data.
469 <!-- ##### FUNCTION pango_attr_scale_new ##### -->
478 <!-- ##### MACRO PANGO_SCALE_XX_SMALL ##### -->
480 The scale factor for three shrinking steps (1 / (1.2 * 1.2 * 1.2)).
485 <!-- ##### MACRO PANGO_SCALE_X_SMALL ##### -->
487 The scale factor for two shrinking steps (1 / (1.2 * 1.2)).
492 <!-- ##### MACRO PANGO_SCALE_SMALL ##### -->
494 The scale factor for one shrinking step (1 / 1.2).
499 <!-- ##### MACRO PANGO_SCALE_MEDIUM ##### -->
501 The scale factor for normal size (1.0).
506 <!-- ##### MACRO PANGO_SCALE_LARGE ##### -->
508 The scale factor for one magnification step (1.2).
513 <!-- ##### MACRO PANGO_SCALE_X_LARGE ##### -->
515 The scale factor for two magnification steps (1.2 * 1.2).
520 <!-- ##### MACRO PANGO_SCALE_XX_LARGE ##### -->
522 The scale factor for three magnification steps (1.2 * 1.2 * 1.2).
527 <!-- ##### FUNCTION pango_attr_rise_new ##### -->
536 <!-- ##### FUNCTION pango_attr_letter_spacing_new ##### -->
545 <!-- ##### FUNCTION pango_attr_fallback_new ##### -->
554 <!-- ##### FUNCTION pango_attr_gravity_new ##### -->
563 <!-- ##### FUNCTION pango_attr_gravity_hint_new ##### -->
572 <!-- ##### STRUCT PangoColor ##### -->
574 The #PangoColor structure is used to
575 represent a color in an uncalibrated RGB color-space.
578 @red: The red component of the color. This is a value between 0 and 65535,
579 with 65535 indicating full intensity.
580 @green: The green component of the color. This is a value between 0 and 65535,
581 with 65535 indicating full intensity.
582 @blue: The blue component of the color. This is a value between 0 and 65535,
583 with 65535 indicating full intensity.
585 <!-- ##### MACRO PANGO_TYPE_COLOR ##### -->
587 The #GObject type for #PangoColor.
592 <!-- ##### FUNCTION pango_color_parse ##### -->
602 <!-- ##### FUNCTION pango_color_copy ##### -->
611 <!-- ##### FUNCTION pango_color_free ##### -->
619 <!-- ##### FUNCTION pango_color_to_string ##### -->
628 <!-- ##### STRUCT PangoAttrList ##### -->
630 The #PangoAttrList structure represents a list of attributes
631 that apply to a section of text. The attributes are, in general,
632 allowed to overlap in an arbitrary fashion, however, if the
633 attributes are manipulated only through pango_attr_list_change(),
634 the overlap between properties will meet stricter criteria.
637 Since the #PangoAttrList structure is stored as a linear list,
638 it is not suitable for storing attributes for large amounts
639 of text. In general, you should not use a single #PangoAttrList
640 for more than one paragraph of text.
644 <!-- ##### MACRO PANGO_TYPE_ATTR_LIST ##### -->
646 The #GObject type for #PangoAttrList.
651 <!-- ##### FUNCTION pango_attr_list_new ##### -->
659 <!-- ##### FUNCTION pango_attr_list_ref ##### -->
668 <!-- ##### FUNCTION pango_attr_list_unref ##### -->
676 <!-- ##### FUNCTION pango_attr_list_copy ##### -->
685 <!-- ##### FUNCTION pango_attr_list_insert ##### -->
694 <!-- ##### FUNCTION pango_attr_list_insert_before ##### -->
703 <!-- ##### FUNCTION pango_attr_list_change ##### -->
712 <!-- ##### FUNCTION pango_attr_list_splice ##### -->
723 <!-- ##### FUNCTION pango_attr_list_filter ##### -->
734 <!-- ##### USER_FUNCTION PangoAttrFilterFunc ##### -->
736 A predicate function used by pango_attr_list_filter()
737 to filter out a subset of attributes for a list.
740 @attribute: a #PangoAttribute
741 @data: callback data passed to pango_attr_list_filter()
742 @Returns: %TRUE if the attribute should be filtered out
745 <!-- ##### FUNCTION pango_attr_list_get_iterator ##### -->
754 <!-- ##### STRUCT PangoAttrIterator ##### -->
756 The #PangoAttrIterator structure is used to represent an
757 iterator through a #PangoAttrList. A new iterator is created
758 with pango_attr_list_get_iterator(). Once the iterator
759 is created, it can be advanced through the style changes
760 in the text using pango_attr_iterator_next(). At each
761 style change, the range of the current style segment and the
762 attributes currently in effect can be queried.
766 <!-- ##### FUNCTION pango_attr_iterator_copy ##### -->
775 <!-- ##### FUNCTION pango_attr_iterator_next ##### -->
784 <!-- ##### FUNCTION pango_attr_iterator_range ##### -->
794 <!-- ##### FUNCTION pango_attr_iterator_get ##### -->
804 <!-- ##### FUNCTION pango_attr_iterator_get_font ##### -->
815 <!-- ##### FUNCTION pango_attr_iterator_get_attrs ##### -->
824 <!-- ##### FUNCTION pango_attr_iterator_destroy ##### -->