1/* Pango
2 * pango-glyph-item.h: Pair of PangoItem and a glyph string
3 *
4 * Copyright (C) 2002 Red Hat Software
5 *
6 * This library is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU Library General Public
8 * License as published by the Free Software Foundation; either
9 * version 2 of the License, or (at your option) any later version.
10 *
11 * This library is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
14 * Library General Public License for more details.
15 *
16 * You should have received a copy of the GNU Library General Public
17 * License along with this library; if not, write to the
18 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
19 * Boston, MA 02111-1307, USA.
20 */
21
22#ifndef __PANGO_GLYPH_ITEM_H__
23#define __PANGO_GLYPH_ITEM_H__
24
25#include <pango/pango-attributes.h>
26#include <pango/pango-break.h>
27#include <pango/pango-item.h>
28#include <pango/pango-glyph.h>
29
30G_BEGIN_DECLS
31
32/**
33 * PangoGlyphItem:
34 * @item: corresponding `PangoItem`
35 * @glyphs: corresponding `PangoGlyphString`
36 * @y_offset: shift of the baseline, relative to the baseline
37 * of the containing line. Positive values shift upwards
38 * @start_x_offset: horizontal displacement to apply before the
39 * glyph item. Positive values shift right
40 * @end_x_offset: horizontal displacement to apply after th
41 * glyph item. Positive values shift right
42 *
43 * A `PangoGlyphItem` is a pair of a `PangoItem` and the glyphs
44 * resulting from shaping the items text.
45 *
46 * As an example of the usage of `PangoGlyphItem`, the results
47 * of shaping text with `PangoLayout` is a list of `PangoLayoutLine`,
48 * each of which contains a list of `PangoGlyphItem`.
49 */
50typedef struct _PangoGlyphItem PangoGlyphItem;
51
52struct _PangoGlyphItem
53{
54 PangoItem *item;
55 PangoGlyphString *glyphs;
56 int y_offset;
57 int start_x_offset;
58 int end_x_offset;
59};
60
61#define PANGO_TYPE_GLYPH_ITEM (pango_glyph_item_get_type ())
62
63PANGO_AVAILABLE_IN_ALL
64GType pango_glyph_item_get_type (void) G_GNUC_CONST;
65
66PANGO_AVAILABLE_IN_1_2
67PangoGlyphItem *pango_glyph_item_split (PangoGlyphItem *orig,
68 const char *text,
69 int split_index);
70PANGO_AVAILABLE_IN_1_20
71PangoGlyphItem *pango_glyph_item_copy (PangoGlyphItem *orig);
72PANGO_AVAILABLE_IN_1_6
73void pango_glyph_item_free (PangoGlyphItem *glyph_item);
74PANGO_AVAILABLE_IN_1_2
75GSList * pango_glyph_item_apply_attrs (PangoGlyphItem *glyph_item,
76 const char *text,
77 PangoAttrList *list);
78PANGO_AVAILABLE_IN_1_6
79void pango_glyph_item_letter_space (PangoGlyphItem *glyph_item,
80 const char *text,
81 PangoLogAttr *log_attrs,
82 int letter_spacing);
83PANGO_AVAILABLE_IN_1_26
84void pango_glyph_item_get_logical_widths (PangoGlyphItem *glyph_item,
85 const char *text,
86 int *logical_widths);
87
88
89/**
90 * PangoGlyphItemIter:
91 *
92 * A `PangoGlyphItemIter` is an iterator over the clusters in a
93 * `PangoGlyphItem`.
94 *
95 * The *forward direction* of the iterator is the logical direction of text.
96 * That is, with increasing @start_index and @start_char values. If @glyph_item
97 * is right-to-left (that is, if `glyph_item->item->analysis.level` is odd),
98 * then @start_glyph decreases as the iterator moves forward. Moreover,
99 * in right-to-left cases, @start_glyph is greater than @end_glyph.
100 *
101 * An iterator should be initialized using either
102 * pango_glyph_item_iter_init_start() or
103 * pango_glyph_item_iter_init_end(), for forward and backward iteration
104 * respectively, and walked over using any desired mixture of
105 * pango_glyph_item_iter_next_cluster() and
106 * pango_glyph_item_iter_prev_cluster().
107 *
108 * A common idiom for doing a forward iteration over the clusters is:
109 *
110 * ```
111 * PangoGlyphItemIter cluster_iter;
112 * gboolean have_cluster;
113 *
114 * for (have_cluster = pango_glyph_item_iter_init_start (&cluster_iter,
115 * glyph_item, text);
116 * have_cluster;
117 * have_cluster = pango_glyph_item_iter_next_cluster (&cluster_iter))
118 * {
119 * ...
120 * }
121 * ```
122 *
123 * Note that @text is the start of the text for layout, which is then
124 * indexed by `glyph_item->item->offset` to get to the text of @glyph_item.
125 * The @start_index and @end_index values can directly index into @text. The
126 * @start_glyph, @end_glyph, @start_char, and @end_char values however are
127 * zero-based for the @glyph_item. For each cluster, the item pointed at by
128 * the start variables is included in the cluster while the one pointed at by
129 * end variables is not.
130 *
131 * None of the members of a `PangoGlyphItemIter` should be modified manually.
132 *
133 * Since: 1.22
134 */
135typedef struct _PangoGlyphItemIter PangoGlyphItemIter;
136
137struct _PangoGlyphItemIter
138{
139 PangoGlyphItem *glyph_item;
140 const gchar *text;
141
142 int start_glyph;
143 int start_index;
144 int start_char;
145
146 int end_glyph;
147 int end_index;
148 int end_char;
149};
150
151#define PANGO_TYPE_GLYPH_ITEM_ITER (pango_glyph_item_iter_get_type ())
152
153PANGO_AVAILABLE_IN_1_22
154GType pango_glyph_item_iter_get_type (void) G_GNUC_CONST;
155PANGO_AVAILABLE_IN_1_22
156PangoGlyphItemIter *pango_glyph_item_iter_copy (PangoGlyphItemIter *orig);
157PANGO_AVAILABLE_IN_1_22
158void pango_glyph_item_iter_free (PangoGlyphItemIter *iter);
159
160PANGO_AVAILABLE_IN_1_22
161gboolean pango_glyph_item_iter_init_start (PangoGlyphItemIter *iter,
162 PangoGlyphItem *glyph_item,
163 const char *text);
164PANGO_AVAILABLE_IN_1_22
165gboolean pango_glyph_item_iter_init_end (PangoGlyphItemIter *iter,
166 PangoGlyphItem *glyph_item,
167 const char *text);
168PANGO_AVAILABLE_IN_1_22
169gboolean pango_glyph_item_iter_next_cluster (PangoGlyphItemIter *iter);
170PANGO_AVAILABLE_IN_1_22
171gboolean pango_glyph_item_iter_prev_cluster (PangoGlyphItemIter *iter);
172
173G_END_DECLS
174
175#endif /* __PANGO_GLYPH_ITEM_H__ */
176

source code of include/pango-1.0/pango/pango-glyph-item.h