pango-attributes.h 30.5 KB
Newer Older
Owen Taylor's avatar
Owen Taylor committed
1
2
3
4
5
6
7
8
9
10
11
12
/* Pango
 * pango-attributes.h: Attributed text
 *
 * Copyright (C) 2000 Red Hat Software
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Library General Public
 * License as published by the Free Software Foundation; either
 * version 2 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
Owen Taylor's avatar
Owen Taylor committed
14
15
16
17
18
19
20
21
22
23
24
 * Library General Public License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with this library; if not, write to the
 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 * Boston, MA 02111-1307, USA.
 */

#ifndef __PANGO_ATTRIBUTES_H__
#define __PANGO_ATTRIBUTES_H__

25
#include <pango/pango-font.h>
26
#include <pango/pango-color.h>
27
#include <glib-object.h>
Owen Taylor's avatar
Owen Taylor committed
28

Owen Taylor's avatar
Owen Taylor committed
29
G_BEGIN_DECLS
Owen Taylor's avatar
Owen Taylor committed
30

31

32
33
typedef struct _PangoAttribute        PangoAttribute;
typedef struct _PangoAttrClass        PangoAttrClass;
34

35
36
37
38
39
40
41
42
typedef struct _PangoAttrString       PangoAttrString;
typedef struct _PangoAttrLanguage     PangoAttrLanguage;
typedef struct _PangoAttrInt          PangoAttrInt;
typedef struct _PangoAttrSize         PangoAttrSize;
typedef struct _PangoAttrFloat        PangoAttrFloat;
typedef struct _PangoAttrColor        PangoAttrColor;
typedef struct _PangoAttrFontDesc     PangoAttrFontDesc;
typedef struct _PangoAttrShape        PangoAttrShape;
43
typedef struct _PangoAttrFontFeatures PangoAttrFontFeatures;
44

45
46
47
/**
 * PangoAttrType:
 * @PANGO_ATTR_INVALID: does not happen
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
 * @PANGO_ATTR_LANGUAGE: language ([struct@Pango.AttrLanguage])
 * @PANGO_ATTR_FAMILY: font family name list ([struct@Pango.AttrString])
 * @PANGO_ATTR_STYLE: font slant style ([struct@Pango.AttrInt])
 * @PANGO_ATTR_WEIGHT: font weight ([struct@Pango.AttrInt])
 * @PANGO_ATTR_VARIANT: font variant (normal or small caps) ([struct@Pango.AttrInt])
 * @PANGO_ATTR_STRETCH: font stretch ([struct@Pango.AttrInt])
 * @PANGO_ATTR_SIZE: font size in points scaled by %PANGO_SCALE ([struct@Pango.AttrInt])
 * @PANGO_ATTR_FONT_DESC: font description ([struct@Pango.AttrFontDesc])
 * @PANGO_ATTR_FOREGROUND: foreground color ([struct@Pango.AttrColor])
 * @PANGO_ATTR_BACKGROUND: background color ([struct@Pango.AttrColor])
 * @PANGO_ATTR_UNDERLINE: whether the text has an underline ([struct@Pango.AttrInt])
 * @PANGO_ATTR_STRIKETHROUGH: whether the text is struck-through ([struct@Pango.AttrInt])
 * @PANGO_ATTR_RISE: baseline displacement ([struct@Pango.AttrInt])
 * @PANGO_ATTR_SHAPE: shape ([struct@Pango.AttrShape])
 * @PANGO_ATTR_SCALE: font size scale factor ([struct@Pango.AttrFloat])
 * @PANGO_ATTR_FALLBACK: whether fallback is enabled ([struct@Pango.AttrInt])
 * @PANGO_ATTR_LETTER_SPACING: letter spacing ([struct@PangoAttrInt])
 * @PANGO_ATTR_UNDERLINE_COLOR: underline color ([struct@Pango.AttrColor])
 * @PANGO_ATTR_STRIKETHROUGH_COLOR: strikethrough color ([struct@Pango.AttrColor])
 * @PANGO_ATTR_ABSOLUTE_SIZE: font size in pixels scaled by %PANGO_SCALE ([struct@Pango.AttrInt])
 * @PANGO_ATTR_GRAVITY: base text gravity ([struct@Pango.AttrInt])
 * @PANGO_ATTR_GRAVITY_HINT: gravity hint ([struct@Pango.AttrInt])
Matthias Clasen's avatar
Matthias Clasen committed
70
 * @PANGO_ATTR_FONT_FEATURES: OpenType font features ([struct@Pango.AttrFontFeatures]). Since 1.38
71
72
73
74
75
76
77
 * @PANGO_ATTR_FOREGROUND_ALPHA: foreground alpha ([struct@Pango.AttrInt]). Since 1.38
 * @PANGO_ATTR_BACKGROUND_ALPHA: background alpha ([struct@Pango.AttrInt]). Since 1.38
 * @PANGO_ATTR_ALLOW_BREAKS: whether breaks are allowed ([struct@Pango.AttrInt]). Since 1.44
 * @PANGO_ATTR_SHOW: how to render invisible characters ([struct@Pango.AttrInt]). Since 1.44
 * @PANGO_ATTR_INSERT_HYPHENS: whether to insert hyphens at intra-word line breaks ([struct@Pango.AttrInt]). Since 1.44
 * @PANGO_ATTR_OVERLINE: whether the text has an overline ([struct@Pango.AttrInt]). Since 1.46
 * @PANGO_ATTR_OVERLINE_COLOR: overline color ([struct@Pango.AttrColor]). Since 1.46
Matthias Clasen's avatar
Matthias Clasen committed
78
 * @PANGO_ATTR_LINE_HEIGHT: line height factor ([struct@Pango.AttrFloat]). Since: 1.50
79
 * @PANGO_ATTR_ABSOLUTE_LINE_HEIGHT: line height ([struct@Pango.AttrInt]). Since: 1.50
Matthias Clasen's avatar
Matthias Clasen committed
80
81
 * @PANGO_ATTR_WORD: override segmentation to classify the range of the attribute as a single word ([struct@Pango.AttrInt]). Since 1.50
 * @PANGO_ATTR_SENTENCE: override segmentation to classify the range of the attribute as a single sentence ([struct@Pango.AttrInt]). Since 1.50
82
83
 * @PANGO_ATTR_BASELINE_SHIFT: baseline displacement ([struct@Pango.AttrInt]). Since 1.50
 * @PANGO_ATTR_FONT_SCALE: font-relative size change ([struct@Pango.AttrInt]). Since 1.50
84
85
86
87
 *
 * The `PangoAttrType` distinguishes between different types of attributes.
 *
 * Along with the predefined values, it is possible to allocate additional
Matthias Clasen's avatar
Matthias Clasen committed
88
 * values for custom attributes using [func@AttrType.register]. The predefined
89
90
 * values are given below. The type of structure used to store the attribute is
 * listed in parentheses after the description.
91
 */
92
93
typedef enum
{
94
  PANGO_ATTR_INVALID,           /* 0 is an invalid attribute type */
95
96
97
98
99
100
101
102
103
104
105
106
107
108
  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 */
109
  PANGO_ATTR_SCALE,             /* PangoAttrFloat */
110
  PANGO_ATTR_FALLBACK,          /* PangoAttrInt */
111
  PANGO_ATTR_LETTER_SPACING,    /* PangoAttrInt */
112
  PANGO_ATTR_UNDERLINE_COLOR,   /* PangoAttrColor */
113
  PANGO_ATTR_STRIKETHROUGH_COLOR,/* PangoAttrColor */
114
115
116
  PANGO_ATTR_ABSOLUTE_SIZE,     /* PangoAttrSize */
  PANGO_ATTR_GRAVITY,           /* PangoAttrInt */
  PANGO_ATTR_GRAVITY_HINT,      /* PangoAttrInt */
Matthias Clasen's avatar
Matthias Clasen committed
117
  PANGO_ATTR_FONT_FEATURES,     /* PangoAttrFontFeatures */
118
119
120
121
122
123
124
125
  PANGO_ATTR_FOREGROUND_ALPHA,  /* PangoAttrInt */
  PANGO_ATTR_BACKGROUND_ALPHA,  /* PangoAttrInt */
  PANGO_ATTR_ALLOW_BREAKS,      /* PangoAttrInt */
  PANGO_ATTR_SHOW,              /* PangoAttrInt */
  PANGO_ATTR_INSERT_HYPHENS,    /* PangoAttrInt */
  PANGO_ATTR_OVERLINE,          /* PangoAttrInt */
  PANGO_ATTR_OVERLINE_COLOR,    /* PangoAttrColor */
  PANGO_ATTR_LINE_HEIGHT,       /* PangoAttrFloat */
Matthias Clasen's avatar
Matthias Clasen committed
126
  PANGO_ATTR_ABSOLUTE_LINE_HEIGHT, /* PangoAttrInt */
127
  PANGO_ATTR_TEXT_TRANSFORM,    /* PangoAttrInt */
Matthias Clasen's avatar
Matthias Clasen committed
128
129
  PANGO_ATTR_WORD,              /* PangoAttrInt */
  PANGO_ATTR_SENTENCE,          /* PangoAttrInt */
Matthias Clasen's avatar
Matthias Clasen committed
130
  PANGO_ATTR_BASELINE_SHIFT,    /* PangoAttrSize */
131
  PANGO_ATTR_FONT_SCALE,        /* PangoAttrInt */
Owen Taylor's avatar
Owen Taylor committed
132
133
} PangoAttrType;

134
135
136
137
138
/**
 * PangoUnderline:
 * @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
Matthias Clasen's avatar
Matthias Clasen committed
139
 * @PANGO_UNDERLINE_LOW: a single underline should be drawn at a
140
141
142
143
144
 *   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.
145
 * @PANGO_UNDERLINE_ERROR: an underline indicating an error should
146
147
148
149
150
151
152
 *   be drawn below. The exact style of rendering is up to the
 *   `PangoRenderer` in use, but typical styles include wavy
 *   or dotted lines.
 *   This underline is typically used to indicate an error such
 *   as a possible mispelling; in some cases a contrasting color
 *   may automatically be used. This type of underlining is
 *   available since Pango 1.4.
153
 * @PANGO_UNDERLINE_SINGLE_LINE: Like @PANGO_UNDERLINE_SINGLE, but
154
155
 *   drawn continuously across multiple runs. This type
 *   of underlining is available since Pango 1.46.
156
 * @PANGO_UNDERLINE_DOUBLE_LINE: Like @PANGO_UNDERLINE_DOUBLE, but
157
158
 *   drawn continuously across multiple runs. This type
 *   of underlining is available since Pango 1.46.
159
 * @PANGO_UNDERLINE_ERROR_LINE: Like @PANGO_UNDERLINE_ERROR, but
160
161
 *   drawn continuously across multiple runs. This type
 *   of underlining is available since Pango 1.46.
162
 *
163
164
 * The `PangoUnderline` enumeration is used to specify whether text
 * should be underlined, and if so, the type of underlining.
165
 */
166
167
168
169
typedef enum {
  PANGO_UNDERLINE_NONE,
  PANGO_UNDERLINE_SINGLE,
  PANGO_UNDERLINE_DOUBLE,
170
  PANGO_UNDERLINE_LOW,
171
172
173
  PANGO_UNDERLINE_ERROR,
  PANGO_UNDERLINE_SINGLE_LINE,
  PANGO_UNDERLINE_DOUBLE_LINE,
174
  PANGO_UNDERLINE_ERROR_LINE
175
176
} PangoUnderline;

Matthias Clasen's avatar
Matthias Clasen committed
177
178
179
180
181

/**
 * PangoOverline:
 * @PANGO_OVERLINE_NONE: no overline should be drawn
 * @PANGO_OVERLINE_SINGLE: Draw a single line above the ink
182
 *   extents of the text being underlined.
Matthias Clasen's avatar
Matthias Clasen committed
183
 *
184
185
 * The `PangoOverline` enumeration is used to specify whether text
 * should be overlined, and if so, the type of line.
Matthias Clasen's avatar
Matthias Clasen committed
186
187
188
189
190
 *
 * Since: 1.46
 */
typedef enum {
  PANGO_OVERLINE_NONE,
191
  PANGO_OVERLINE_SINGLE
Matthias Clasen's avatar
Matthias Clasen committed
192
193
} PangoOverline;

194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
/**
 * PangoShowFlags:
 * @PANGO_SHOW_NONE: No special treatment for invisible characters
 * @PANGO_SHOW_SPACES: Render spaces, tabs and newlines visibly
 * @PANGO_SHOW_LINE_BREAKS: Render line breaks visibly
 * @PANGO_SHOW_IGNORABLES: Render default-ignorable Unicode
 *   characters visibly
 *
 * These flags affect how Pango treats characters that are normally
 * not visible in the output.
 *
 * Since: 1.44
 */
typedef enum {
  PANGO_SHOW_NONE        = 0,
  PANGO_SHOW_SPACES      = 1 << 0,
  PANGO_SHOW_LINE_BREAKS = 1 << 1,
  PANGO_SHOW_IGNORABLES  = 1 << 2
} PangoShowFlags;

214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
/**
 * PangoTextTransform:
 * @PANGO_TEXT_TRANSFORM_NONE: Leave text unchanged
 * @PANGO_TEXT_TRANSFORM_LOWERCASE: Display letters and numbers as lowercase
 * @PANGO_TEXT_TRANSFORM_UPPERCASE: Display letters and numbers as uppercase
 * @PANGO_TEXT_TRANSFORM_CAPITALIZE: Display the first character of a word
 *   in titlecase
 *
 * An enumeration that affects how Pango treats characters during shaping.
 *
 * Since: 1.50
 */
typedef enum {
  PANGO_TEXT_TRANSFORM_NONE,
  PANGO_TEXT_TRANSFORM_LOWERCASE,
  PANGO_TEXT_TRANSFORM_UPPERCASE,
  PANGO_TEXT_TRANSFORM_CAPITALIZE,
} PangoTextTransform;

Matthias Clasen's avatar
Matthias Clasen committed
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
/**
 * PangoBaselineShift:
 * @PANGO_BASELINE_SHIFT_SUPERSCRIPT: Shift the baseline to the superscript position,
 *   relative to the previous run
 * @PANGO_BASELINE_SHIFT_SUBSCRIPT: Shift the baseline to the subscript position,
 *   relative to the previous run
 *
 * An enumeration that affects baseline shifts between runs.
 *
 * Since: 1.50
 */
typedef enum {
  PANGO_BASELINE_SHIFT_NONE,
  PANGO_BASELINE_SHIFT_SUPERSCRIPT,
  PANGO_BASELINE_SHIFT_SUBSCRIPT,
} PangoBaselineShift;

250
251
252
253
254
255
typedef enum {
  PANGO_FONT_SCALE_NONE,
  PANGO_FONT_SCALE_SUPERSCRIPT,
  PANGO_FONT_SCALE_SUBSCRIPT,
} PangoFontScale;

256
257
258
/**
 * PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING:
 *
Matthias Clasen's avatar
Matthias Clasen committed
259
260
 * Value for @start_index in `PangoAttribute` that indicates
 * the beginning of the text.
261
262
263
 *
 * Since: 1.24
 */
Matthias Clasen's avatar
Matthias Clasen committed
264
#define PANGO_ATTR_INDEX_FROM_TEXT_BEGINNING ((guint)0)
Matthias Clasen's avatar
Matthias Clasen committed
265

266
/**
Matthias Clasen's avatar
Matthias Clasen committed
267
 * PANGO_ATTR_INDEX_TO_TEXT_END: (value 4294967295)
268
 *
Matthias Clasen's avatar
Matthias Clasen committed
269
270
 * Value for @end_index in `PangoAttribute` that indicates
 * the end of the text.
271
272
273
 *
 * Since: 1.24
 */
Matthias Clasen's avatar
Matthias Clasen committed
274
#define PANGO_ATTR_INDEX_TO_TEXT_END ((guint)(G_MAXUINT + 0))
275

276
277
278
279
280
/**
 * PangoAttribute:
 * @klass: the class structure holding information about the type of the attribute
 * @start_index: the start index of the range (in bytes).
 * @end_index: end index of the range (in bytes). The character at this index
281
 *   is not included in the range.
282
 *
283
284
285
286
287
288
289
290
 * 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 [method@Pango.Attribute.init]. By default, an attribute
 * will have an all-inclusive range of [0,%G_MAXUINT].
291
 */
Owen Taylor's avatar
Owen Taylor committed
292
293
struct _PangoAttribute
{
294
  const PangoAttrClass *klass;
295
296
  guint start_index;
  guint end_index;
Owen Taylor's avatar
Owen Taylor committed
297
298
};

Behdad Esfahbod's avatar
Behdad Esfahbod committed
299
300
301
302
303
304
305
/**
 * PangoAttrFilterFunc:
 * @attribute: a Pango attribute
 * @user_data: user data passed to the function
 *
 * Type of a function filtering a list of attributes.
 *
306
 * Return value: %TRUE if the attribute should be selected for
307
308
 *   filtering, %FALSE otherwise.
 */
309
typedef gboolean (*PangoAttrFilterFunc) (PangoAttribute *attribute,
310
                                         gpointer        user_data);
311

Behdad Esfahbod's avatar
Behdad Esfahbod committed
312
313
314
315
316
317
318
319
/**
 * PangoAttrDataCopyFunc:
 * @user_data: user data to copy
 *
 * Type of a function that can duplicate user data for an attribute.
 *
 * Return value: new copy of @user_data.
 **/
320
typedef gpointer (*PangoAttrDataCopyFunc) (gconstpointer user_data);
321

322
323
324
/**
 * PangoAttrClass:
 * @type: the type ID for this attribute
325
326
327
328
329
330
331
332
 * @copy: function to duplicate an attribute of this type
 *   (see [method@Pango.Attribute.copy])
 * @destroy: function to free an attribute of this type
 *   (see [method@Pango.Attribute.destroy])
 * @equal: function to check two attributes of this type for equality
 *   (see [method@Pango.Attribute.equal])
 *
 * The `PangoAttrClass` structure stores the type and operations for
Matthias Clasen's avatar
Matthias Clasen committed
333
334
335
336
 * 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`.
337
 */
Owen Taylor's avatar
Owen Taylor committed
338
339
struct _PangoAttrClass
{
Owen Taylor's avatar
Owen Taylor committed
340
  /*< public >*/
341
  PangoAttrType type;
Owen Taylor's avatar
Owen Taylor committed
342
343
  PangoAttribute * (*copy) (const PangoAttribute *attr);
  void             (*destroy) (PangoAttribute *attr);
344
  gboolean         (*equal) (const PangoAttribute *attr1, const PangoAttribute *attr2);
Owen Taylor's avatar
Owen Taylor committed
345
346
};

347
348
349
350
351
/**
 * PangoAttrString:
 * @attr: the common portion of the attribute
 * @value: the string which is the value of the attribute
 *
352
 * The `PangoAttrString` structure is used to represent attributes with
353
354
 * a string value.
 */
355
struct _PangoAttrString
Owen Taylor's avatar
Owen Taylor committed
356
357
{
  PangoAttribute attr;
358
  char *value;
Owen Taylor's avatar
Owen Taylor committed
359
};
360
361
362
/**
 * PangoAttrLanguage:
 * @attr: the common portion of the attribute
363
 * @value: the `PangoLanguage` which is the value of the attribute
364
 *
365
 * The `PangoAttrLanguage` structure is used to represent attributes that
366
367
 * are languages.
 */
368
369
370
371
372
struct _PangoAttrLanguage
{
  PangoAttribute attr;
  PangoLanguage *value;
};
373
374
375
376
377
/**
 * PangoAttrInt:
 * @attr: the common portion of the attribute
 * @value: the value of the attribute
 *
378
 * The `PangoAttrInt` structure is used to represent attributes with
379
380
 * an integer or enumeration value.
 */
381
struct _PangoAttrInt
Owen Taylor's avatar
Owen Taylor committed
382
383
{
  PangoAttribute attr;
384
  int value;
Owen Taylor's avatar
Owen Taylor committed
385
};
386
387
388
389
390
/**
 * PangoAttrFloat:
 * @attr: the common portion of the attribute
 * @value: the value of the attribute
 *
391
 * The `PangoAttrFloat` structure is used to represent attributes with
392
393
 * a float or double value.
 */
394
395
396
397
398
struct _PangoAttrFloat
{
  PangoAttribute attr;
  double value;
};
399
400
401
/**
 * PangoAttrColor:
 * @attr: the common portion of the attribute
402
 * @color: the `PangoColor` which is the value of the attribute
403
 *
404
 * The `PangoAttrColor` structure is used to represent attributes that
405
406
 * are colors.
 */
Owen Taylor's avatar
Owen Taylor committed
407
408
409
struct _PangoAttrColor
{
  PangoAttribute attr;
410
  PangoColor color;
Owen Taylor's avatar
Owen Taylor committed
411
412
};

413
414
415
416
/**
 * PangoAttrSize:
 * @attr: the common portion of the attribute
 * @size: size of font, in units of 1/%PANGO_SCALE of a point (for
417
 *   %PANGO_ATTR_SIZE) or of a device unit (for %PANGO_ATTR_ABSOLUTE_SIZE)
418
 * @absolute: whether the font size is in device units or points.
419
420
421
 *   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.
422
 *
423
 * The `PangoAttrSize` structure is used to represent attributes which
424
425
 * set font size.
 */
426
427
428
429
430
431
432
struct _PangoAttrSize
{
  PangoAttribute attr;
  int size;
  guint absolute : 1;
};

433
434
435
436
437
/**
 * PangoAttrShape:
 * @attr: the common portion of the attribute
 * @ink_rect: the ink rectangle to restrict to
 * @logical_rect: the logical rectangle to restrict to
Matthias Clasen's avatar
Matthias Clasen committed
438
 * @data: user data set (see [func@Pango.AttrShape.new_with_data])
439
440
441
 * @copy_func: copy function for the user data
 * @destroy_func: destroy function for the user data
 *
442
 * The `PangoAttrShape` structure is used to represent attributes which
443
444
 * impose shape restrictions.
 */
Owen Taylor's avatar
Owen Taylor committed
445
446
447
448
449
struct _PangoAttrShape
{
  PangoAttribute attr;
  PangoRectangle ink_rect;
  PangoRectangle logical_rect;
450

451
452
453
  gpointer              data;
  PangoAttrDataCopyFunc copy_func;
  GDestroyNotify        destroy_func;
Owen Taylor's avatar
Owen Taylor committed
454
455
};

456
457
458
459
460
/**
 * PangoAttrFontDesc:
 * @attr: the common portion of the attribute
 * @desc: the font description which is the value of this attribute
 *
461
 * The `PangoAttrFontDesc` structure is used to store an attribute that
462
463
 * sets all aspects of the font description at once.
 */
464
465
466
struct _PangoAttrFontDesc
{
  PangoAttribute attr;
Owen Taylor's avatar
Owen Taylor committed
467
  PangoFontDescription *desc;
468
469
};

470
471
472
473
474
/**
 * PangoAttrFontFeatures:
 * @attr: the common portion of the attribute
 * @features: the featues, as a string in CSS syntax
 *
475
 * The `PangoAttrFontFeatures` structure is used to represent OpenType
476
477
478
479
480
481
482
483
484
485
 * font features as an attribute.
 *
 * Since: 1.38
 */
struct _PangoAttrFontFeatures
{
  PangoAttribute attr;
  gchar *features;
};

486
PANGO_AVAILABLE_IN_ALL
487
GType                   pango_attribute_get_type                (void) G_GNUC_CONST;
488

489
490
491
492
PANGO_AVAILABLE_IN_ALL
PangoAttrType           pango_attr_type_register                (const char                 *name);
PANGO_AVAILABLE_IN_1_22
const char *            pango_attr_type_get_name                (PangoAttrType               type) G_GNUC_CONST;
493
PANGO_AVAILABLE_IN_1_20
494
495
void                    pango_attribute_init                    (PangoAttribute             *attr,
                                                                 const PangoAttrClass       *klass);
496
PANGO_AVAILABLE_IN_ALL
497
PangoAttribute *        pango_attribute_copy                    (const PangoAttribute       *attr);
498
PANGO_AVAILABLE_IN_ALL
499
void                    pango_attribute_destroy                 (PangoAttribute             *attr);
500
PANGO_AVAILABLE_IN_ALL
501
502
gboolean                pango_attribute_equal                   (const PangoAttribute       *attr1,
                                                                 const PangoAttribute       *attr2) G_GNUC_PURE;
Owen Taylor's avatar
Owen Taylor committed
503

504
PANGO_AVAILABLE_IN_ALL
505
PangoAttribute *        pango_attr_language_new                 (PangoLanguage              *language);
506
PANGO_AVAILABLE_IN_ALL
507
PangoAttribute *        pango_attr_family_new                   (const char                 *family);
508
PANGO_AVAILABLE_IN_ALL
509
510
511
PangoAttribute *        pango_attr_foreground_new               (guint16                     red,
                                                                 guint16                     green,
                                                                 guint16                     blue);
512
PANGO_AVAILABLE_IN_ALL
513
514
515
PangoAttribute *        pango_attr_background_new               (guint16                     red,
                                                                 guint16                     green,
                                                                 guint16                     blue);
516
PANGO_AVAILABLE_IN_ALL
517
PangoAttribute *        pango_attr_size_new                     (int                         size);
518
PANGO_AVAILABLE_IN_1_8
519
PangoAttribute *        pango_attr_size_new_absolute            (int                         size);
520
PANGO_AVAILABLE_IN_ALL
521
PangoAttribute *        pango_attr_style_new                    (PangoStyle                  style);
522
PANGO_AVAILABLE_IN_ALL
523
PangoAttribute *        pango_attr_weight_new                   (PangoWeight                 weight);
524
PANGO_AVAILABLE_IN_ALL
525
PangoAttribute *        pango_attr_variant_new                  (PangoVariant                variant);
526
PANGO_AVAILABLE_IN_ALL
527
PangoAttribute *        pango_attr_stretch_new                  (PangoStretch                stretch);
528
PANGO_AVAILABLE_IN_ALL
529
PangoAttribute *        pango_attr_font_desc_new                (const PangoFontDescription *desc);
530

531
PANGO_AVAILABLE_IN_ALL
532
PangoAttribute *        pango_attr_underline_new                (PangoUnderline              underline);
533
PANGO_AVAILABLE_IN_1_8
534
535
536
PangoAttribute *        pango_attr_underline_color_new          (guint16                     red,
                                                                 guint16                     green,
                                                                 guint16                     blue);
537
PANGO_AVAILABLE_IN_ALL
538
PangoAttribute *        pango_attr_strikethrough_new            (gboolean                    strikethrough);
539
PANGO_AVAILABLE_IN_1_8
540
541
542
PangoAttribute *        pango_attr_strikethrough_color_new      (guint16                     red,
                                                                 guint16                     green,
                                                                 guint16                     blue);
543
PANGO_AVAILABLE_IN_ALL
544
PangoAttribute *        pango_attr_rise_new                     (int                         rise);
Matthias Clasen's avatar
Matthias Clasen committed
545
546
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_baseline_shift_new           (int                         shift);
547
548
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_font_scale_new               (PangoFontScale              scale);
549
PANGO_AVAILABLE_IN_ALL
550
PangoAttribute *        pango_attr_scale_new                    (double                      scale_factor);
551
PANGO_AVAILABLE_IN_1_4
552
PangoAttribute *        pango_attr_fallback_new                 (gboolean                    enable_fallback);
553
PANGO_AVAILABLE_IN_1_6
554
PangoAttribute *        pango_attr_letter_spacing_new           (int                         letter_spacing);
555
PANGO_AVAILABLE_IN_ALL
556
557
PangoAttribute *        pango_attr_shape_new                    (const PangoRectangle        *ink_rect,
                                                                 const PangoRectangle        *logical_rect);
558
PANGO_AVAILABLE_IN_1_8
559
560
561
562
563
PangoAttribute *        pango_attr_shape_new_with_data          (const PangoRectangle        *ink_rect,
                                                                 const PangoRectangle        *logical_rect,
                                                                 gpointer                     data,
                                                                 PangoAttrDataCopyFunc        copy_func,
                                                                 GDestroyNotify               destroy_func);
564
PANGO_AVAILABLE_IN_1_16
565
PangoAttribute *        pango_attr_gravity_new                  (PangoGravity                 gravity);
566
PANGO_AVAILABLE_IN_1_16
567
PangoAttribute *        pango_attr_gravity_hint_new             (PangoGravityHint             hint);
568
PANGO_AVAILABLE_IN_1_38
569
PangoAttribute *        pango_attr_font_features_new            (const char                  *features);
570
PANGO_AVAILABLE_IN_1_38
571
PangoAttribute *        pango_attr_foreground_alpha_new         (guint16                      alpha);
572
PANGO_AVAILABLE_IN_1_38
573
PangoAttribute *        pango_attr_background_alpha_new         (guint16                      alpha);
574
PANGO_AVAILABLE_IN_1_44
575
PangoAttribute *        pango_attr_allow_breaks_new             (gboolean                     allow_breaks);
Matthias Clasen's avatar
Matthias Clasen committed
576
577
578
579
580
581

PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_word_new                     (void);
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_sentence_new                 (void);

582
PANGO_AVAILABLE_IN_1_44
583
PangoAttribute *        pango_attr_insert_hyphens_new           (gboolean                     insert_hyphens);
Matthias Clasen's avatar
Matthias Clasen committed
584
PANGO_AVAILABLE_IN_1_46
585
PangoAttribute *        pango_attr_overline_new                 (PangoOverline                overline);
Matthias Clasen's avatar
Matthias Clasen committed
586
PANGO_AVAILABLE_IN_1_46
587
588
589
590
591
592
593
594
595
PangoAttribute *        pango_attr_overline_color_new           (guint16                      red,
                                                                 guint16                      green,
                                                                 guint16                      blue);
PANGO_AVAILABLE_IN_1_44
PangoAttribute *        pango_attr_show_new                     (PangoShowFlags               flags);
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_line_height_new              (double                       factor);
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_line_height_new_absolute     (int                          height);
596
597
PANGO_AVAILABLE_IN_1_50
PangoAttribute *        pango_attr_text_transform_new           (PangoTextTransform transform);
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623

PANGO_AVAILABLE_IN_1_50
PangoAttrString       * pango_attribute_as_string               (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrLanguage     * pango_attribute_as_language             (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrInt          * pango_attribute_as_int                  (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrSize         * pango_attribute_as_size                 (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrFloat        * pango_attribute_as_float                (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrColor        * pango_attribute_as_color                (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrFontDesc     * pango_attribute_as_font_desc            (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrShape        * pango_attribute_as_shape                (PangoAttribute              *attr);
PANGO_AVAILABLE_IN_1_50
PangoAttrFontFeatures * pango_attribute_as_font_features        (PangoAttribute              *attr);

/* Attribute lists */

typedef struct _PangoAttrList     PangoAttrList;
typedef struct _PangoAttrIterator PangoAttrIterator;

#define PANGO_TYPE_ATTR_LIST pango_attr_list_get_type ()
Matthias Clasen's avatar
Matthias Clasen committed
624

625
/**
626
 * PangoAttrIterator:
627
 *
628
629
630
631
632
633
634
 * A `PangoAttrIterator` is used to iterate through a `PangoAttrList`.
 *
 * A new iterator is created with [method@Pango.AttrList.get_iterator].
 * Once the iterator is created, it can be advanced through the style
 * changes in the text using [method@Pango.AttrIterator.next]. At each
 * style change, the range of the current style segment and the attributes
 * currently in effect can be queried.
635
636
 */

637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
/**
 * PangoAttrList:
 *
 * A `PangoAttrList` represents a list of attributes that apply to a section
 * of text.
 *
 * The attributes in a `PangoAttrList` are, in general, allowed to overlap in
 * an arbitrary fashion. However, if the attributes are manipulated only through
 * [method@Pango.AttrList.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.
 */
Matthias Clasen's avatar
Matthias Clasen committed
652

653
PANGO_AVAILABLE_IN_ALL
654
655
GType                   pango_attr_list_get_type        (void) G_GNUC_CONST;

656
PANGO_AVAILABLE_IN_ALL
657
PangoAttrList *         pango_attr_list_new             (void);
658
PANGO_AVAILABLE_IN_1_10
659
PangoAttrList *         pango_attr_list_ref             (PangoAttrList         *list);
660
PANGO_AVAILABLE_IN_ALL
661
void                    pango_attr_list_unref           (PangoAttrList         *list);
662
PANGO_AVAILABLE_IN_ALL
663
PangoAttrList *         pango_attr_list_copy            (PangoAttrList         *list);
664
PANGO_AVAILABLE_IN_ALL
665
666
void                    pango_attr_list_insert          (PangoAttrList         *list,
                                                         PangoAttribute        *attr);
667
PANGO_AVAILABLE_IN_ALL
668
669
void                    pango_attr_list_insert_before   (PangoAttrList         *list,
                                                         PangoAttribute        *attr);
670
PANGO_AVAILABLE_IN_ALL
671
672
void                    pango_attr_list_change          (PangoAttrList         *list,
                                                         PangoAttribute        *attr);
673
PANGO_AVAILABLE_IN_ALL
674
675
676
677
void                    pango_attr_list_splice          (PangoAttrList         *list,
                                                         PangoAttrList         *other,
                                                         int                    pos,
                                                         int                    len);
678
PANGO_AVAILABLE_IN_1_44
679
680
681
682
void                    pango_attr_list_update          (PangoAttrList         *list,
                                                         int                    pos,
                                                         int                    remove,
                                                         int                    add);
683

684
PANGO_AVAILABLE_IN_1_2
685
686
687
PangoAttrList *         pango_attr_list_filter          (PangoAttrList         *list,
                                                         PangoAttrFilterFunc    func,
                                                         gpointer               data);
688

689
PANGO_AVAILABLE_IN_1_44
690
GSList *                pango_attr_list_get_attributes  (PangoAttrList         *list);
691

692
PANGO_AVAILABLE_IN_1_46
693
694
gboolean                pango_attr_list_equal           (PangoAttrList         *list,
                                                         PangoAttrList         *other_list);
695

696
PANGO_AVAILABLE_IN_1_44
697
GType                   pango_attr_iterator_get_type    (void) G_GNUC_CONST;
698

699
PANGO_AVAILABLE_IN_ALL
700
PangoAttrIterator *     pango_attr_list_get_iterator    (PangoAttrList         *list);
Owen Taylor's avatar
Owen Taylor committed
701

702
PANGO_AVAILABLE_IN_ALL
703
704
705
void                    pango_attr_iterator_range       (PangoAttrIterator     *iterator,
                                                         int                   *start,
                                                         int                   *end);
706
PANGO_AVAILABLE_IN_ALL
707
gboolean                pango_attr_iterator_next        (PangoAttrIterator     *iterator);
708
PANGO_AVAILABLE_IN_ALL
709
PangoAttrIterator *     pango_attr_iterator_copy        (PangoAttrIterator     *iterator);
710
PANGO_AVAILABLE_IN_ALL
711
void                    pango_attr_iterator_destroy     (PangoAttrIterator     *iterator);
712
PANGO_AVAILABLE_IN_ALL
713
714
PangoAttribute *        pango_attr_iterator_get         (PangoAttrIterator     *iterator,
                                                         PangoAttrType          type);
715
PANGO_AVAILABLE_IN_ALL
716
717
718
719
void                    pango_attr_iterator_get_font    (PangoAttrIterator     *iterator,
                                                         PangoFontDescription  *desc,
                                                         PangoLanguage        **language,
                                                         GSList               **extra_attrs);
720
PANGO_AVAILABLE_IN_1_2
721
GSList *                pango_attr_iterator_get_attrs   (PangoAttrIterator     *iterator);
722

Owen Taylor's avatar
Owen Taylor committed
723
G_END_DECLS
Owen Taylor's avatar
Owen Taylor committed
724

725
#endif /* __PANGO_ATTRIBUTES_H__ */