1/* Pango
2 * pango-layout.h: High-level layout driver
3 *
4 * Copyright (C) 2000 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_LAYOUT_H__
23#define __PANGO_LAYOUT_H__
24
25#include <pango/pango-attributes.h>
26#include <pango/pango-context.h>
27#include <pango/pango-glyph-item.h>
28#include <pango/pango-tabs.h>
29
30G_BEGIN_DECLS
31
32typedef struct _PangoLayout PangoLayout;
33typedef struct _PangoLayoutClass PangoLayoutClass;
34typedef struct _PangoLayoutLine PangoLayoutLine;
35
36/**
37 * PangoLayoutRun:
38 *
39 * The #PangoLayoutRun structure represents a single run within
40 * a #PangoLayoutLine; it is simply an alternate name for
41 * #PangoGlyphItem.
42 * See the #PangoGlyphItem docs for details on the fields.
43 */
44typedef PangoGlyphItem PangoLayoutRun;
45
46/**
47 * PangoAlignment:
48 * @PANGO_ALIGN_LEFT: Put all available space on the right
49 * @PANGO_ALIGN_CENTER: Center the line within the available space
50 * @PANGO_ALIGN_RIGHT: Put all available space on the left
51 *
52 * A #PangoAlignment describes how to align the lines of a #PangoLayout within the
53 * available space. If the #PangoLayout is set to justify
54 * using pango_layout_set_justify(), this only has effect for partial lines.
55 */
56typedef enum {
57 PANGO_ALIGN_LEFT,
58 PANGO_ALIGN_CENTER,
59 PANGO_ALIGN_RIGHT
60} PangoAlignment;
61
62/**
63 * PangoWrapMode:
64 * @PANGO_WRAP_WORD: wrap lines at word boundaries.
65 * @PANGO_WRAP_CHAR: wrap lines at character boundaries.
66 * @PANGO_WRAP_WORD_CHAR: wrap lines at word boundaries, but fall back to character boundaries if there is not
67 * enough space for a full word.
68 *
69 * A #PangoWrapMode describes how to wrap the lines of a #PangoLayout to the desired width.
70 */
71typedef enum {
72 PANGO_WRAP_WORD,
73 PANGO_WRAP_CHAR,
74 PANGO_WRAP_WORD_CHAR
75} PangoWrapMode;
76
77/**
78 * PangoEllipsizeMode:
79 * @PANGO_ELLIPSIZE_NONE: No ellipsization
80 * @PANGO_ELLIPSIZE_START: Omit characters at the start of the text
81 * @PANGO_ELLIPSIZE_MIDDLE: Omit characters in the middle of the text
82 * @PANGO_ELLIPSIZE_END: Omit characters at the end of the text
83 *
84 * The #PangoEllipsizeMode type describes what sort of (if any)
85 * ellipsization should be applied to a line of text. In
86 * the ellipsization process characters are removed from the
87 * text in order to make it fit to a given width and replaced
88 * with an ellipsis.
89 */
90typedef enum {
91 PANGO_ELLIPSIZE_NONE,
92 PANGO_ELLIPSIZE_START,
93 PANGO_ELLIPSIZE_MIDDLE,
94 PANGO_ELLIPSIZE_END
95} PangoEllipsizeMode;
96
97/**
98 * PangoLayoutLine:
99 * @layout: (allow-none): the layout this line belongs to, might be %NULL
100 * @start_index: start of line as byte index into layout->text
101 * @length: length of line in bytes
102 * @runs: (allow-none) (element-type Pango.LayoutRun): list of runs in the
103 * line, from left to right
104 * @is_paragraph_start: #TRUE if this is the first line of the paragraph
105 * @resolved_dir: #Resolved PangoDirection of line
106 *
107 * The #PangoLayoutLine structure represents one of the lines resulting
108 * from laying out a paragraph via #PangoLayout. #PangoLayoutLine
109 * structures are obtained by calling pango_layout_get_line() and
110 * are only valid until the text, attributes, or settings of the
111 * parent #PangoLayout are modified.
112 *
113 * Routines for rendering PangoLayout objects are provided in
114 * code specific to each rendering system.
115 */
116struct _PangoLayoutLine
117{
118 PangoLayout *layout;
119 gint start_index; /* start of line as byte index into layout->text */
120 gint length; /* length of line in bytes */
121 GSList *runs;
122 guint is_paragraph_start : 1; /* TRUE if this is the first line of the paragraph */
123 guint resolved_dir : 3; /* Resolved PangoDirection of line */
124};
125
126#define PANGO_TYPE_LAYOUT (pango_layout_get_type ())
127#define PANGO_LAYOUT(object) (G_TYPE_CHECK_INSTANCE_CAST ((object), PANGO_TYPE_LAYOUT, PangoLayout))
128#define PANGO_LAYOUT_CLASS(klass) (G_TYPE_CHECK_CLASS_CAST ((klass), PANGO_TYPE_LAYOUT, PangoLayoutClass))
129#define PANGO_IS_LAYOUT(object) (G_TYPE_CHECK_INSTANCE_TYPE ((object), PANGO_TYPE_LAYOUT))
130#define PANGO_IS_LAYOUT_CLASS(klass) (G_TYPE_CHECK_CLASS_TYPE ((klass), PANGO_TYPE_LAYOUT))
131#define PANGO_LAYOUT_GET_CLASS(obj) (G_TYPE_INSTANCE_GET_CLASS ((obj), PANGO_TYPE_LAYOUT, PangoLayoutClass))
132
133/* The PangoLayout and PangoLayoutClass structs are private; if you
134 * need to create a subclass of these, file a bug.
135 */
136
137PANGO_AVAILABLE_IN_ALL
138GType pango_layout_get_type (void) G_GNUC_CONST;
139PANGO_AVAILABLE_IN_ALL
140PangoLayout *pango_layout_new (PangoContext *context);
141PANGO_AVAILABLE_IN_ALL
142PangoLayout *pango_layout_copy (PangoLayout *src);
143
144PANGO_AVAILABLE_IN_ALL
145PangoContext *pango_layout_get_context (PangoLayout *layout);
146
147PANGO_AVAILABLE_IN_ALL
148void pango_layout_set_attributes (PangoLayout *layout,
149 PangoAttrList *attrs);
150PANGO_AVAILABLE_IN_ALL
151PangoAttrList *pango_layout_get_attributes (PangoLayout *layout);
152
153PANGO_AVAILABLE_IN_ALL
154void pango_layout_set_text (PangoLayout *layout,
155 const char *text,
156 int length);
157PANGO_AVAILABLE_IN_ALL
158const char *pango_layout_get_text (PangoLayout *layout);
159
160PANGO_AVAILABLE_IN_1_30
161gint pango_layout_get_character_count (PangoLayout *layout);
162
163PANGO_AVAILABLE_IN_ALL
164void pango_layout_set_markup (PangoLayout *layout,
165 const char *markup,
166 int length);
167
168PANGO_AVAILABLE_IN_ALL
169void pango_layout_set_markup_with_accel (PangoLayout *layout,
170 const char *markup,
171 int length,
172 gunichar accel_marker,
173 gunichar *accel_char);
174
175PANGO_AVAILABLE_IN_ALL
176void pango_layout_set_font_description (PangoLayout *layout,
177 const PangoFontDescription *desc);
178
179PANGO_AVAILABLE_IN_1_8
180const PangoFontDescription *pango_layout_get_font_description (PangoLayout *layout);
181
182PANGO_AVAILABLE_IN_ALL
183void pango_layout_set_width (PangoLayout *layout,
184 int width);
185PANGO_AVAILABLE_IN_ALL
186int pango_layout_get_width (PangoLayout *layout);
187PANGO_AVAILABLE_IN_1_20
188void pango_layout_set_height (PangoLayout *layout,
189 int height);
190PANGO_AVAILABLE_IN_1_20
191int pango_layout_get_height (PangoLayout *layout);
192PANGO_AVAILABLE_IN_ALL
193void pango_layout_set_wrap (PangoLayout *layout,
194 PangoWrapMode wrap);
195PANGO_AVAILABLE_IN_ALL
196PangoWrapMode pango_layout_get_wrap (PangoLayout *layout);
197PANGO_AVAILABLE_IN_1_16
198gboolean pango_layout_is_wrapped (PangoLayout *layout);
199PANGO_AVAILABLE_IN_ALL
200void pango_layout_set_indent (PangoLayout *layout,
201 int indent);
202PANGO_AVAILABLE_IN_ALL
203int pango_layout_get_indent (PangoLayout *layout);
204PANGO_AVAILABLE_IN_ALL
205void pango_layout_set_spacing (PangoLayout *layout,
206 int spacing);
207PANGO_AVAILABLE_IN_ALL
208int pango_layout_get_spacing (PangoLayout *layout);
209PANGO_AVAILABLE_IN_ALL
210void pango_layout_set_justify (PangoLayout *layout,
211 gboolean justify);
212PANGO_AVAILABLE_IN_ALL
213gboolean pango_layout_get_justify (PangoLayout *layout);
214PANGO_AVAILABLE_IN_1_4
215void pango_layout_set_auto_dir (PangoLayout *layout,
216 gboolean auto_dir);
217PANGO_AVAILABLE_IN_1_4
218gboolean pango_layout_get_auto_dir (PangoLayout *layout);
219PANGO_AVAILABLE_IN_ALL
220void pango_layout_set_alignment (PangoLayout *layout,
221 PangoAlignment alignment);
222PANGO_AVAILABLE_IN_ALL
223PangoAlignment pango_layout_get_alignment (PangoLayout *layout);
224
225PANGO_AVAILABLE_IN_ALL
226void pango_layout_set_tabs (PangoLayout *layout,
227 PangoTabArray *tabs);
228
229PANGO_AVAILABLE_IN_ALL
230PangoTabArray* pango_layout_get_tabs (PangoLayout *layout);
231
232PANGO_AVAILABLE_IN_ALL
233void pango_layout_set_single_paragraph_mode (PangoLayout *layout,
234 gboolean setting);
235PANGO_AVAILABLE_IN_ALL
236gboolean pango_layout_get_single_paragraph_mode (PangoLayout *layout);
237
238PANGO_AVAILABLE_IN_1_6
239void pango_layout_set_ellipsize (PangoLayout *layout,
240 PangoEllipsizeMode ellipsize);
241PANGO_AVAILABLE_IN_1_6
242PangoEllipsizeMode pango_layout_get_ellipsize (PangoLayout *layout);
243PANGO_AVAILABLE_IN_1_16
244gboolean pango_layout_is_ellipsized (PangoLayout *layout);
245
246PANGO_AVAILABLE_IN_1_16
247int pango_layout_get_unknown_glyphs_count (PangoLayout *layout);
248
249PANGO_AVAILABLE_IN_ALL
250void pango_layout_context_changed (PangoLayout *layout);
251PANGO_AVAILABLE_IN_1_32
252guint pango_layout_get_serial (PangoLayout *layout);
253
254PANGO_AVAILABLE_IN_ALL
255void pango_layout_get_log_attrs (PangoLayout *layout,
256 PangoLogAttr **attrs,
257 gint *n_attrs);
258
259PANGO_AVAILABLE_IN_1_30
260const PangoLogAttr *pango_layout_get_log_attrs_readonly (PangoLayout *layout,
261 gint *n_attrs);
262
263PANGO_AVAILABLE_IN_ALL
264void pango_layout_index_to_pos (PangoLayout *layout,
265 int index_,
266 PangoRectangle *pos);
267PANGO_AVAILABLE_IN_ALL
268void pango_layout_index_to_line_x (PangoLayout *layout,
269 int index_,
270 gboolean trailing,
271 int *line,
272 int *x_pos);
273PANGO_AVAILABLE_IN_ALL
274void pango_layout_get_cursor_pos (PangoLayout *layout,
275 int index_,
276 PangoRectangle *strong_pos,
277 PangoRectangle *weak_pos);
278PANGO_AVAILABLE_IN_ALL
279void pango_layout_move_cursor_visually (PangoLayout *layout,
280 gboolean strong,
281 int old_index,
282 int old_trailing,
283 int direction,
284 int *new_index,
285 int *new_trailing);
286PANGO_AVAILABLE_IN_ALL
287gboolean pango_layout_xy_to_index (PangoLayout *layout,
288 int x,
289 int y,
290 int *index_,
291 int *trailing);
292PANGO_AVAILABLE_IN_ALL
293void pango_layout_get_extents (PangoLayout *layout,
294 PangoRectangle *ink_rect,
295 PangoRectangle *logical_rect);
296PANGO_AVAILABLE_IN_ALL
297void pango_layout_get_pixel_extents (PangoLayout *layout,
298 PangoRectangle *ink_rect,
299 PangoRectangle *logical_rect);
300PANGO_AVAILABLE_IN_ALL
301void pango_layout_get_size (PangoLayout *layout,
302 int *width,
303 int *height);
304PANGO_AVAILABLE_IN_ALL
305void pango_layout_get_pixel_size (PangoLayout *layout,
306 int *width,
307 int *height);
308PANGO_AVAILABLE_IN_1_22
309int pango_layout_get_baseline (PangoLayout *layout);
310
311PANGO_AVAILABLE_IN_ALL
312int pango_layout_get_line_count (PangoLayout *layout);
313PANGO_AVAILABLE_IN_ALL
314PangoLayoutLine *pango_layout_get_line (PangoLayout *layout,
315 int line);
316PANGO_AVAILABLE_IN_1_16
317PangoLayoutLine *pango_layout_get_line_readonly (PangoLayout *layout,
318 int line);
319PANGO_AVAILABLE_IN_ALL
320GSList * pango_layout_get_lines (PangoLayout *layout);
321PANGO_AVAILABLE_IN_1_16
322GSList * pango_layout_get_lines_readonly (PangoLayout *layout);
323
324
325#define PANGO_TYPE_LAYOUT_LINE (pango_layout_line_get_type ())
326
327PANGO_AVAILABLE_IN_ALL
328GType pango_layout_line_get_type (void) G_GNUC_CONST;
329
330PANGO_AVAILABLE_IN_1_10
331PangoLayoutLine *pango_layout_line_ref (PangoLayoutLine *line);
332PANGO_AVAILABLE_IN_ALL
333void pango_layout_line_unref (PangoLayoutLine *line);
334
335PANGO_AVAILABLE_IN_ALL
336gboolean pango_layout_line_x_to_index (PangoLayoutLine *line,
337 int x_pos,
338 int *index_,
339 int *trailing);
340PANGO_AVAILABLE_IN_ALL
341void pango_layout_line_index_to_x (PangoLayoutLine *line,
342 int index_,
343 gboolean trailing,
344 int *x_pos);
345PANGO_AVAILABLE_IN_ALL
346void pango_layout_line_get_x_ranges (PangoLayoutLine *line,
347 int start_index,
348 int end_index,
349 int **ranges,
350 int *n_ranges);
351PANGO_AVAILABLE_IN_ALL
352void pango_layout_line_get_extents (PangoLayoutLine *line,
353 PangoRectangle *ink_rect,
354 PangoRectangle *logical_rect);
355PANGO_AVAILABLE_IN_ALL
356void pango_layout_line_get_pixel_extents (PangoLayoutLine *layout_line,
357 PangoRectangle *ink_rect,
358 PangoRectangle *logical_rect);
359
360typedef struct _PangoLayoutIter PangoLayoutIter;
361
362#define PANGO_TYPE_LAYOUT_ITER (pango_layout_iter_get_type ())
363
364PANGO_AVAILABLE_IN_ALL
365GType pango_layout_iter_get_type (void) G_GNUC_CONST;
366
367PANGO_AVAILABLE_IN_ALL
368PangoLayoutIter *pango_layout_get_iter (PangoLayout *layout);
369PANGO_AVAILABLE_IN_1_20
370PangoLayoutIter *pango_layout_iter_copy (PangoLayoutIter *iter);
371PANGO_AVAILABLE_IN_ALL
372void pango_layout_iter_free (PangoLayoutIter *iter);
373
374PANGO_AVAILABLE_IN_ALL
375int pango_layout_iter_get_index (PangoLayoutIter *iter);
376PANGO_AVAILABLE_IN_ALL
377PangoLayoutRun *pango_layout_iter_get_run (PangoLayoutIter *iter);
378PANGO_AVAILABLE_IN_1_16
379PangoLayoutRun *pango_layout_iter_get_run_readonly (PangoLayoutIter *iter);
380PANGO_AVAILABLE_IN_ALL
381PangoLayoutLine *pango_layout_iter_get_line (PangoLayoutIter *iter);
382PANGO_AVAILABLE_IN_1_16
383PangoLayoutLine *pango_layout_iter_get_line_readonly (PangoLayoutIter *iter);
384PANGO_AVAILABLE_IN_ALL
385gboolean pango_layout_iter_at_last_line (PangoLayoutIter *iter);
386PANGO_AVAILABLE_IN_1_20
387PangoLayout *pango_layout_iter_get_layout (PangoLayoutIter *iter);
388
389PANGO_AVAILABLE_IN_ALL
390gboolean pango_layout_iter_next_char (PangoLayoutIter *iter);
391PANGO_AVAILABLE_IN_ALL
392gboolean pango_layout_iter_next_cluster (PangoLayoutIter *iter);
393PANGO_AVAILABLE_IN_ALL
394gboolean pango_layout_iter_next_run (PangoLayoutIter *iter);
395PANGO_AVAILABLE_IN_ALL
396gboolean pango_layout_iter_next_line (PangoLayoutIter *iter);
397
398PANGO_AVAILABLE_IN_ALL
399void pango_layout_iter_get_char_extents (PangoLayoutIter *iter,
400 PangoRectangle *logical_rect);
401PANGO_AVAILABLE_IN_ALL
402void pango_layout_iter_get_cluster_extents (PangoLayoutIter *iter,
403 PangoRectangle *ink_rect,
404 PangoRectangle *logical_rect);
405PANGO_AVAILABLE_IN_ALL
406void pango_layout_iter_get_run_extents (PangoLayoutIter *iter,
407 PangoRectangle *ink_rect,
408 PangoRectangle *logical_rect);
409PANGO_AVAILABLE_IN_ALL
410void pango_layout_iter_get_line_extents (PangoLayoutIter *iter,
411 PangoRectangle *ink_rect,
412 PangoRectangle *logical_rect);
413/* All the yranges meet, unlike the logical_rect's (i.e. the yranges
414 * assign between-line spacing to the nearest line)
415 */
416PANGO_AVAILABLE_IN_ALL
417void pango_layout_iter_get_line_yrange (PangoLayoutIter *iter,
418 int *y0_,
419 int *y1_);
420PANGO_AVAILABLE_IN_ALL
421void pango_layout_iter_get_layout_extents (PangoLayoutIter *iter,
422 PangoRectangle *ink_rect,
423 PangoRectangle *logical_rect);
424PANGO_AVAILABLE_IN_ALL
425int pango_layout_iter_get_baseline (PangoLayoutIter *iter);
426
427G_END_DECLS
428
429#endif /* __PANGO_LAYOUT_H__ */
430
431