1/* ATK - The Accessibility Toolkit for GTK+
2 * Copyright 2001 Sun Microsystems Inc.
3 *
4 * This library is free software; you can redistribute it and/or
5 * modify it under the terms of the GNU Library General Public
6 * License as published by the Free Software Foundation; either
7 * version 2 of the License, or (at your option) any later version.
8 *
9 * This library is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12 * Library General Public License for more details.
13 *
14 * You should have received a copy of the GNU Library General Public
15 * License along with this library; if not, write to the
16 * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
17 * Boston, MA 02111-1307, USA.
18 */
19
20#ifndef __ATK_TEXT_H__
21#define __ATK_TEXT_H__
22
23#if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined(__ATK_H_INSIDE__) && !defined(ATK_COMPILATION)
24#error "Only <atk/atk.h> can be included directly."
25#endif
26
27#include <atk/atkcomponent.h>
28#include <atk/atkobject.h>
29#include <atk/atkutil.h>
30#include <glib-object.h>
31
32G_BEGIN_DECLS
33
34/**
35 *AtkTextAttribute:
36 *@ATK_TEXT_ATTR_INVALID: Invalid attribute, like bad spelling or grammar.
37 *@ATK_TEXT_ATTR_LEFT_MARGIN: The pixel width of the left margin
38 *@ATK_TEXT_ATTR_RIGHT_MARGIN: The pixel width of the right margin
39 *@ATK_TEXT_ATTR_INDENT: The number of pixels that the text is indented
40 *@ATK_TEXT_ATTR_INVISIBLE: Either "true" or "false" indicating whether text is visible or not
41 *@ATK_TEXT_ATTR_EDITABLE: Either "true" or "false" indicating whether text is editable or not
42 *@ATK_TEXT_ATTR_PIXELS_ABOVE_LINES: Pixels of blank space to leave above each newline-terminated line.
43 *@ATK_TEXT_ATTR_PIXELS_BELOW_LINES: Pixels of blank space to leave below each newline-terminated line.
44 *@ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP: Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph).
45 *@ATK_TEXT_ATTR_BG_FULL_HEIGHT: "true" or "false" whether to make the background color for each character the height of the highest font used on the current line, or the height of the font used for the current character.
46 *@ATK_TEXT_ATTR_RISE: Number of pixels that the characters are risen above the baseline. See also ATK_TEXT_ATTR_TEXT_POSITION.
47 *@ATK_TEXT_ATTR_UNDERLINE: "none", "single", "double", "low", or "error"
48 *@ATK_TEXT_ATTR_STRIKETHROUGH: "true" or "false" whether the text is strikethrough
49 *@ATK_TEXT_ATTR_SIZE: The size of the characters in points. eg: 10
50 *@ATK_TEXT_ATTR_SCALE: The scale of the characters. The value is a string representation of a double
51 *@ATK_TEXT_ATTR_WEIGHT: The weight of the characters.
52 *@ATK_TEXT_ATTR_LANGUAGE: The language used
53 *@ATK_TEXT_ATTR_FAMILY_NAME: The font family name
54 *@ATK_TEXT_ATTR_BG_COLOR: The background color. The value is an RGB value of the format "%u,%u,%u"
55 *@ATK_TEXT_ATTR_FG_COLOR:The foreground color. The value is an RGB value of the format "%u,%u,%u"
56 *@ATK_TEXT_ATTR_BG_STIPPLE: "true" if a #GdkBitmap is set for stippling the background color.
57 *@ATK_TEXT_ATTR_FG_STIPPLE: "true" if a #GdkBitmap is set for stippling the foreground color.
58 *@ATK_TEXT_ATTR_WRAP_MODE: The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char".
59 *@ATK_TEXT_ATTR_DIRECTION: The direction of the text, if set. Values are "none", "ltr" or "rtl"
60 *@ATK_TEXT_ATTR_JUSTIFICATION: The justification of the text, if set. Values are "left", "right", "center" or "fill"
61 *@ATK_TEXT_ATTR_STRETCH: The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed", "condensed", "semi_condensed", "normal", "semi_expanded", "expanded", "extra_expanded" or "ultra_expanded"
62 *@ATK_TEXT_ATTR_VARIANT: The capitalization variant of the text, if set. Values are "normal" or "small_caps"
63 *@ATK_TEXT_ATTR_STYLE: The slant style of the text, if set. Values are "normal", "oblique" or "italic"
64 *@ATK_TEXT_ATTR_TEXT_POSITION: The vertical position with respect to the baseline. Values are "baseline", "super", or "sub". Note that a super or sub text attribute refers to position with respect to the baseline of the prior character.
65 *@ATK_TEXT_ATTR_LAST_DEFINED: not a valid text attribute, used for finding end of enumeration
66 *
67 * Describes the text attributes supported
68 **/
69typedef enum
70{
71 ATK_TEXT_ATTR_INVALID = 0,
72 ATK_TEXT_ATTR_LEFT_MARGIN,
73 ATK_TEXT_ATTR_RIGHT_MARGIN,
74 ATK_TEXT_ATTR_INDENT,
75 ATK_TEXT_ATTR_INVISIBLE,
76 ATK_TEXT_ATTR_EDITABLE,
77 ATK_TEXT_ATTR_PIXELS_ABOVE_LINES,
78 ATK_TEXT_ATTR_PIXELS_BELOW_LINES,
79 ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP,
80 ATK_TEXT_ATTR_BG_FULL_HEIGHT,
81 ATK_TEXT_ATTR_RISE,
82 ATK_TEXT_ATTR_UNDERLINE,
83 ATK_TEXT_ATTR_STRIKETHROUGH,
84 ATK_TEXT_ATTR_SIZE,
85 ATK_TEXT_ATTR_SCALE,
86 ATK_TEXT_ATTR_WEIGHT,
87 ATK_TEXT_ATTR_LANGUAGE,
88 ATK_TEXT_ATTR_FAMILY_NAME,
89 ATK_TEXT_ATTR_BG_COLOR,
90 ATK_TEXT_ATTR_FG_COLOR,
91 ATK_TEXT_ATTR_BG_STIPPLE,
92 ATK_TEXT_ATTR_FG_STIPPLE,
93 ATK_TEXT_ATTR_WRAP_MODE,
94 ATK_TEXT_ATTR_DIRECTION,
95 ATK_TEXT_ATTR_JUSTIFICATION,
96 ATK_TEXT_ATTR_STRETCH,
97 ATK_TEXT_ATTR_VARIANT,
98 ATK_TEXT_ATTR_STYLE,
99 ATK_TEXT_ATTR_TEXT_POSITION,
100 ATK_TEXT_ATTR_LAST_DEFINED
101} AtkTextAttribute;
102
103ATK_AVAILABLE_IN_ALL
104AtkTextAttribute atk_text_attribute_register (const gchar *name);
105
106#define ATK_TYPE_TEXT (atk_text_get_type ())
107#define ATK_IS_TEXT(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TEXT)
108#define ATK_TEXT(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TEXT, AtkText)
109#define ATK_TEXT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_TEXT, AtkTextIface))
110
111#ifndef _TYPEDEF_ATK_TEXT_
112#define _TYPEDEF_ATK_TEXT_
113typedef struct _AtkText AtkText;
114#endif
115typedef struct _AtkTextIface AtkTextIface;
116
117/**
118 *AtkTextBoundary:
119 *@ATK_TEXT_BOUNDARY_CHAR: Boundary is the boundary between characters
120 * (including non-printing characters)
121 *@ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word.
122 *@ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last
123 * character) of a word.
124 *@ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence.
125 *@ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal)
126 * character in a sentence; in languages which use "sentence stop"
127 * punctuation such as English, the boundary is thus the '.', '?', or
128 * similar terminal punctuation character.
129 *@ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a
130 * character immediately following a newline, linefeed, or return character.
131 *@ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return
132 * character.
133 *
134 * Text boundary types used for specifying boundaries for regions of text.
135 * This enumeration is deprecated since 2.9.4 and should not be used. Use
136 * AtkTextGranularity with #atk_text_get_string_at_offset instead.
137 **/
138typedef enum
139{
140 ATK_TEXT_BOUNDARY_CHAR,
141 ATK_TEXT_BOUNDARY_WORD_START,
142 ATK_TEXT_BOUNDARY_WORD_END,
143 ATK_TEXT_BOUNDARY_SENTENCE_START,
144 ATK_TEXT_BOUNDARY_SENTENCE_END,
145 ATK_TEXT_BOUNDARY_LINE_START,
146 ATK_TEXT_BOUNDARY_LINE_END
147} AtkTextBoundary;
148
149/**
150 *AtkTextGranularity:
151 *@ATK_TEXT_GRANULARITY_CHAR: Granularity is defined by the boundaries between characters
152 * (including non-printing characters)
153 *@ATK_TEXT_GRANULARITY_WORD: Granularity is defined by the boundaries of a word,
154 * starting at the beginning of the current word and finishing at the beginning of
155 * the following one, if present.
156 *@ATK_TEXT_GRANULARITY_SENTENCE: Granularity is defined by the boundaries of a sentence,
157 * starting at the beginning of the current sentence and finishing at the beginning of
158 * the following one, if present.
159 *@ATK_TEXT_GRANULARITY_LINE: Granularity is defined by the boundaries of a line,
160 * starting at the beginning of the current line and finishing at the beginning of
161 * the following one, if present.
162 *@ATK_TEXT_GRANULARITY_PARAGRAPH: Granularity is defined by the boundaries of a paragraph,
163 * starting at the beginning of the current paragraph and finishing at the beginning of
164 * the following one, if present.
165 *
166 * Text granularity types used for specifying the granularity of the region of
167 * text we are interested in.
168 **/
169typedef enum
170{
171 ATK_TEXT_GRANULARITY_CHAR,
172 ATK_TEXT_GRANULARITY_WORD,
173 ATK_TEXT_GRANULARITY_SENTENCE,
174 ATK_TEXT_GRANULARITY_LINE,
175 ATK_TEXT_GRANULARITY_PARAGRAPH
176} AtkTextGranularity;
177
178/**
179 * AtkTextRectangle:
180 * @x: The horizontal coordinate of a rectangle
181 * @y: The vertical coordinate of a rectangle
182 * @width: The width of a rectangle
183 * @height: The height of a rectangle
184 *
185 * A structure used to store a rectangle used by AtkText.
186 **/
187
188typedef struct _AtkTextRectangle AtkTextRectangle;
189
190struct _AtkTextRectangle
191{
192 gint x;
193 gint y;
194 gint width;
195 gint height;
196};
197
198/**
199 * AtkTextRange:
200 * @bounds: A rectangle giving the bounds of the text range
201 * @start_offset: The start offset of a AtkTextRange
202 * @end_offset: The end offset of a AtkTextRange
203 * @content: The text in the text range
204 *
205 * A structure used to describe a text range.
206 **/
207typedef struct _AtkTextRange AtkTextRange;
208
209struct _AtkTextRange
210{
211 AtkTextRectangle bounds;
212 gint start_offset;
213 gint end_offset;
214 gchar *content;
215};
216
217ATK_AVAILABLE_IN_ALL
218GType atk_text_range_get_type (void);
219
220/**
221 *AtkTextClipType:
222 *@ATK_TEXT_CLIP_NONE: No clipping to be done
223 *@ATK_TEXT_CLIP_MIN: Text clipped by min coordinate is omitted
224 *@ATK_TEXT_CLIP_MAX: Text clipped by max coordinate is omitted
225 *@ATK_TEXT_CLIP_BOTH: Only text fully within mix/max bound is retained
226 *
227 *Describes the type of clipping required.
228 **/
229typedef enum
230{
231 ATK_TEXT_CLIP_NONE,
232 ATK_TEXT_CLIP_MIN,
233 ATK_TEXT_CLIP_MAX,
234 ATK_TEXT_CLIP_BOTH
235} AtkTextClipType;
236
237/**
238 * AtkTextIface:
239 * @get_text_after_offset: Gets specified text. This virtual function
240 * is deprecated and it should not be overridden.
241 * @get_text_at_offset: Gets specified text. This virtual function
242 * is deprecated and it should not be overridden.
243 * @get_text_before_offset: Gets specified text. This virtual function
244 * is deprecated and it should not be overridden.
245 * @get_string_at_offset: Gets a portion of the text exposed through
246 * an AtkText according to a given offset and a specific
247 * granularity, along with the start and end offsets defining the
248 * boundaries of such a portion of text.
249 * @text_changed: the signal handler which is executed when there is a
250 * text change. This virtual function is deprecated sice 2.9.4 and
251 * it should not be overriden.
252 */
253struct _AtkTextIface
254{
255 GTypeInterface parent;
256
257 gchar *(*get_text) (AtkText *text,
258 gint start_offset,
259 gint end_offset);
260 gchar *(*get_text_after_offset) (AtkText *text,
261 gint offset,
262 AtkTextBoundary boundary_type,
263 gint *start_offset,
264 gint *end_offset);
265 gchar *(*get_text_at_offset) (AtkText *text,
266 gint offset,
267 AtkTextBoundary boundary_type,
268 gint *start_offset,
269 gint *end_offset);
270 gunichar (*get_character_at_offset) (AtkText *text,
271 gint offset);
272 gchar *(*get_text_before_offset) (AtkText *text,
273 gint offset,
274 AtkTextBoundary boundary_type,
275 gint *start_offset,
276 gint *end_offset);
277 gint (*get_caret_offset) (AtkText *text);
278 AtkAttributeSet *(*get_run_attributes) (AtkText *text,
279 gint offset,
280 gint *start_offset,
281 gint *end_offset);
282 AtkAttributeSet *(*get_default_attributes) (AtkText *text);
283 void (*get_character_extents) (AtkText *text,
284 gint offset,
285 gint *x,
286 gint *y,
287 gint *width,
288 gint *height,
289 AtkCoordType coords);
290 gint (*get_character_count) (AtkText *text);
291 gint (*get_offset_at_point) (AtkText *text,
292 gint x,
293 gint y,
294 AtkCoordType coords);
295 gint (*get_n_selections) (AtkText *text);
296 gchar *(*get_selection) (AtkText *text,
297 gint selection_num,
298 gint *start_offset,
299 gint *end_offset);
300 gboolean (*add_selection) (AtkText *text,
301 gint start_offset,
302 gint end_offset);
303 gboolean (*remove_selection) (AtkText *text,
304 gint selection_num);
305 gboolean (*set_selection) (AtkText *text,
306 gint selection_num,
307 gint start_offset,
308 gint end_offset);
309 gboolean (*set_caret_offset) (AtkText *text,
310 gint offset);
311
312 /*
313 * signal handlers
314 */
315 void (*text_changed) (AtkText *text,
316 gint position,
317 gint length);
318 void (*text_caret_moved) (AtkText *text,
319 gint location);
320 void (*text_selection_changed) (AtkText *text);
321
322 void (*text_attributes_changed) (AtkText *text);
323
324 void (*get_range_extents) (AtkText *text,
325 gint start_offset,
326 gint end_offset,
327 AtkCoordType coord_type,
328 AtkTextRectangle *rect);
329
330 AtkTextRange **(*get_bounded_ranges) (AtkText *text,
331 AtkTextRectangle *rect,
332 AtkCoordType coord_type,
333 AtkTextClipType x_clip_type,
334 AtkTextClipType y_clip_type);
335
336 gchar *(*get_string_at_offset) (AtkText *text,
337 gint offset,
338 AtkTextGranularity granularity,
339 gint *start_offset,
340 gint *end_offset);
341 /*
342 * Scrolls this text range so it becomes visible on the screen.
343 *
344 * scroll_substring_to lets the implementation compute an appropriate target
345 * position on the screen, with type used as a positioning hint.
346 *
347 * scroll_substring_to_point lets the client specify a precise target position
348 * on the screen for the top-left of the substring.
349 *
350 * Since ATK 2.32
351 */
352 gboolean (*scroll_substring_to) (AtkText *text,
353 gint start_offset,
354 gint end_offset,
355 AtkScrollType type);
356 gboolean (*scroll_substring_to_point) (AtkText *text,
357 gint start_offset,
358 gint end_offset,
359 AtkCoordType coords,
360 gint x,
361 gint y);
362};
363
364ATK_AVAILABLE_IN_ALL
365GType atk_text_get_type (void);
366
367/*
368 * Additional AtkObject properties used by AtkText:
369 * "accessible_text" (accessible text has changed)
370 * "accessible_caret" (accessible text cursor position changed:
371 * editable text only)
372 */
373
374ATK_AVAILABLE_IN_ALL
375gchar *atk_text_get_text (AtkText *text,
376 gint start_offset,
377 gint end_offset);
378ATK_AVAILABLE_IN_ALL
379gunichar atk_text_get_character_at_offset (AtkText *text,
380 gint offset);
381ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
382gchar *atk_text_get_text_after_offset (AtkText *text,
383 gint offset,
384 AtkTextBoundary boundary_type,
385 gint *start_offset,
386 gint *end_offset);
387ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
388gchar *atk_text_get_text_at_offset (AtkText *text,
389 gint offset,
390 AtkTextBoundary boundary_type,
391 gint *start_offset,
392 gint *end_offset);
393ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
394gchar *atk_text_get_text_before_offset (AtkText *text,
395 gint offset,
396 AtkTextBoundary boundary_type,
397 gint *start_offset,
398 gint *end_offset);
399ATK_AVAILABLE_IN_2_10
400gchar *atk_text_get_string_at_offset (AtkText *text,
401 gint offset,
402 AtkTextGranularity granularity,
403 gint *start_offset,
404 gint *end_offset);
405ATK_AVAILABLE_IN_ALL
406gint atk_text_get_caret_offset (AtkText *text);
407ATK_AVAILABLE_IN_ALL
408void atk_text_get_character_extents (AtkText *text,
409 gint offset,
410 gint *x,
411 gint *y,
412 gint *width,
413 gint *height,
414 AtkCoordType coords);
415ATK_AVAILABLE_IN_ALL
416AtkAttributeSet *atk_text_get_run_attributes (AtkText *text,
417 gint offset,
418 gint *start_offset,
419 gint *end_offset);
420ATK_AVAILABLE_IN_ALL
421AtkAttributeSet *atk_text_get_default_attributes (AtkText *text);
422ATK_AVAILABLE_IN_ALL
423gint atk_text_get_character_count (AtkText *text);
424ATK_AVAILABLE_IN_ALL
425gint atk_text_get_offset_at_point (AtkText *text,
426 gint x,
427 gint y,
428 AtkCoordType coords);
429ATK_AVAILABLE_IN_ALL
430gint atk_text_get_n_selections (AtkText *text);
431ATK_AVAILABLE_IN_ALL
432gchar *atk_text_get_selection (AtkText *text,
433 gint selection_num,
434 gint *start_offset,
435 gint *end_offset);
436ATK_AVAILABLE_IN_ALL
437gboolean atk_text_add_selection (AtkText *text,
438 gint start_offset,
439 gint end_offset);
440ATK_AVAILABLE_IN_ALL
441gboolean atk_text_remove_selection (AtkText *text,
442 gint selection_num);
443ATK_AVAILABLE_IN_ALL
444gboolean atk_text_set_selection (AtkText *text,
445 gint selection_num,
446 gint start_offset,
447 gint end_offset);
448ATK_AVAILABLE_IN_ALL
449gboolean atk_text_set_caret_offset (AtkText *text,
450 gint offset);
451ATK_AVAILABLE_IN_ALL
452void atk_text_get_range_extents (AtkText *text,
453
454 gint start_offset,
455 gint end_offset,
456 AtkCoordType coord_type,
457 AtkTextRectangle *rect);
458ATK_AVAILABLE_IN_ALL
459AtkTextRange **atk_text_get_bounded_ranges (AtkText *text,
460 AtkTextRectangle *rect,
461 AtkCoordType coord_type,
462 AtkTextClipType x_clip_type,
463 AtkTextClipType y_clip_type);
464ATK_AVAILABLE_IN_ALL
465void atk_text_free_ranges (AtkTextRange **ranges);
466ATK_AVAILABLE_IN_ALL
467void atk_attribute_set_free (AtkAttributeSet *attrib_set);
468ATK_AVAILABLE_IN_ALL
469const gchar *atk_text_attribute_get_name (AtkTextAttribute attr);
470ATK_AVAILABLE_IN_ALL
471AtkTextAttribute atk_text_attribute_for_name (const gchar *name);
472ATK_AVAILABLE_IN_ALL
473const gchar *atk_text_attribute_get_value (AtkTextAttribute attr,
474 gint index_);
475
476ATK_AVAILABLE_IN_2_32
477gboolean atk_text_scroll_substring_to (AtkText *text,
478 gint start_offset,
479 gint end_offset,
480 AtkScrollType type);
481
482ATK_AVAILABLE_IN_2_32
483gboolean atk_text_scroll_substring_to_point (AtkText *text,
484 gint start_offset,
485 gint end_offset,
486 AtkCoordType coords,
487 gint x,
488 gint y);
489
490G_END_DECLS
491
492#endif /* __ATK_TEXT_H__ */
493

source code of include/atk-1.0/atk/atktext.h