atktext.h (22083B)
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 21 #ifndef __ATK_TEXT_H__ 22 #define __ATK_TEXT_H__ 23 24 #include <glib-object.h> 25 #include <atk/atkobject.h> 26 #include <atk/atkutil.h> 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif /* __cplusplus */ 31 32 /** 33 *AtkTextAttribute 34 *@ATK_TEXT_ATTR_INVALID: Invalid attribute 35 *@ATK_TEXT_ATTR_LEFT_MARGIN: The pixel width of the left margin 36 *@ATK_TEXT_ATTR_RIGHT_MARGIN: The pixel width of the right margin 37 *@ATK_TEXT_ATTR_INDENT: The number of pixels that the text is indented 38 *@ATK_TEXT_ATTR_INVISIBLE: Either "true" or "false" indicating whether text is visible or not 39 *@ATK_TEXT_ATTR_EDITABLE: Either "true" or "false" indicating whether text is editable or not 40 *@ATK_TEXT_ATTR_PIXELS_ABOVE_LINES: Pixels of blank space to leave above each newline-terminated line. 41 *@ATK_TEXT_ATTR_PIXELS_BELOW_LINES: Pixels of blank space to leave below each newline-terminated line. 42 *@ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP: Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph). 43 *@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. 44 *@ATK_TEXT_ATTR_RISE: Number of pixels that the characters are risen above the baseline 45 *@ATK_TEXT_ATTR_UNDERLINE: "none", "single", "double" or "low" 46 *@ATK_TEXT_ATTR_STRIKETHROUGH: "true" or "false" whether the text is strikethrough 47 *@ATK_TEXT_ATTR_SIZE: The size of the characters. 48 *@ATK_TEXT_ATTR_SCALE: The scale of the characters. The value is a string representation of a double 49 *@ATK_TEXT_ATTR_WEIGHT: The weight of the characters. 50 *@ATK_TEXT_ATTR_LANGUAGE: The language used 51 *@ATK_TEXT_ATTR_FAMILY_NAME: The font family name 52 *@ATK_TEXT_ATTR_BG_COLOR: The background color. The value is an RGB value of the format "%u,%u,%u" 53 *@ATK_TEXT_ATTR_FG_COLOR:The foreground color. The value is an RGB value of the format "%u,%u,%u" 54 *@ATK_TEXT_ATTR_BG_STIPPLE: "true" if a #GdkBitmap is set for stippling the background color. 55 *@ATK_TEXT_ATTR_FG_STIPPLE: "true" if a #GdkBitmap is set for stippling the foreground color. 56 *@ATK_TEXT_ATTR_WRAP_MODE: The wrap mode of the text, if any. Values are "none", "char" or "word" 57 *@ATK_TEXT_ATTR_DIRECTION: The direction of the text, if set. Values are "none", "ltr" or "rtl" 58 *@ATK_TEXT_ATTR_JUSTIFICATION: The justification of the text, if set. Values are "left", "right", "center" or "fill" 59 *@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" 60 *@ATK_TEXT_ATTR_VARIANT: The capitalization variant of the text, if set. Values are "normal" or "small_caps" 61 *@ATK_TEXT_ATTR_STYLE: The slant style of the text, if set. Values are "normal", "oblique" or "italic" 62 *@ATK_TEXT_ATTR_LAST_DEFINED: not a valid text attribute, used for finding end of enumeration 63 * 64 * Describes the text attributes supported 65 **/ 66 typedef enum 67 { 68 ATK_TEXT_ATTR_INVALID = 0, 69 ATK_TEXT_ATTR_LEFT_MARGIN, 70 ATK_TEXT_ATTR_RIGHT_MARGIN, 71 ATK_TEXT_ATTR_INDENT, 72 ATK_TEXT_ATTR_INVISIBLE, 73 ATK_TEXT_ATTR_EDITABLE, 74 ATK_TEXT_ATTR_PIXELS_ABOVE_LINES, 75 ATK_TEXT_ATTR_PIXELS_BELOW_LINES, 76 ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP, 77 ATK_TEXT_ATTR_BG_FULL_HEIGHT, 78 ATK_TEXT_ATTR_RISE, 79 ATK_TEXT_ATTR_UNDERLINE, 80 ATK_TEXT_ATTR_STRIKETHROUGH, 81 ATK_TEXT_ATTR_SIZE, 82 ATK_TEXT_ATTR_SCALE, 83 ATK_TEXT_ATTR_WEIGHT, 84 ATK_TEXT_ATTR_LANGUAGE, 85 ATK_TEXT_ATTR_FAMILY_NAME, 86 ATK_TEXT_ATTR_BG_COLOR, 87 ATK_TEXT_ATTR_FG_COLOR, 88 ATK_TEXT_ATTR_BG_STIPPLE, 89 ATK_TEXT_ATTR_FG_STIPPLE, 90 ATK_TEXT_ATTR_WRAP_MODE, 91 ATK_TEXT_ATTR_DIRECTION, 92 ATK_TEXT_ATTR_JUSTIFICATION, 93 ATK_TEXT_ATTR_STRETCH, 94 ATK_TEXT_ATTR_VARIANT, 95 ATK_TEXT_ATTR_STYLE, 96 ATK_TEXT_ATTR_LAST_DEFINED 97 } AtkTextAttribute; 98 99 AtkTextAttribute atk_text_attribute_register (const gchar *name); 100 101 102 #define ATK_TYPE_TEXT (atk_text_get_type ()) 103 #define ATK_IS_TEXT(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TEXT) 104 #define ATK_TEXT(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TEXT, AtkText) 105 #define ATK_TEXT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_TEXT, AtkTextIface)) 106 107 #ifndef _TYPEDEF_ATK_TEXT_ 108 #define _TYPEDEF_ATK_TEXT_ 109 typedef struct _AtkText AtkText; 110 #endif 111 typedef struct _AtkTextIface AtkTextIface; 112 113 /** 114 *AtkTextBoundary: 115 *@ATK_TEXT_BOUNDARY_CHAR: Boundary is the boundary between characters 116 * (including non-printing characters) 117 *@ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word. 118 *@ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last character) of a word. 119 *@ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence. 120 *@ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal) character in a sentence; 121 * in languages which use "sentence stop" punctuation such as English, the boundary is thus the 122 * '.', '?', or similar terminal punctuation character. 123 *@ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a 124 * character immediately following a newline, linefeed, or return character. 125 *@ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return character. 126 * 127 *Text boundary types used for specifying boundaries for regions of text 128 **/ 129 typedef enum { 130 ATK_TEXT_BOUNDARY_CHAR, 131 ATK_TEXT_BOUNDARY_WORD_START, 132 ATK_TEXT_BOUNDARY_WORD_END, 133 ATK_TEXT_BOUNDARY_SENTENCE_START, 134 ATK_TEXT_BOUNDARY_SENTENCE_END, 135 ATK_TEXT_BOUNDARY_LINE_START, 136 ATK_TEXT_BOUNDARY_LINE_END 137 } AtkTextBoundary; 138 139 /** 140 *AtkTextGranularity: 141 *@ATK_TEXT_GRANULARITY_CHAR: Granularity is defined by the boundaries between characters 142 * (including non-printing characters) 143 *@ATK_TEXT_GRANULARITY_WORD: Granularity is defined by the boundaries of a word, 144 * starting at the beginning of the current word and finishing at the beginning of 145 * the following one, if present. 146 *@ATK_TEXT_GRANULARITY_SENTENCE: Granularity is defined by the boundaries of a sentence, 147 * starting at the beginning of the current sentence and finishing at the beginning of 148 * the following one, if present. 149 *@ATK_TEXT_GRANULARITY_LINE: Granularity is defined by the boundaries of a line, 150 * starting at the beginning of the current line and finishing at the beginning of 151 * the following one, if present. 152 *@ATK_TEXT_GRANULARITY_PARAGRAPH: Granularity is defined by the boundaries of a paragraph, 153 * starting at the beginning of the current paragraph and finishing at the beginning of 154 * the following one, if present. 155 * 156 * Text granularity types used for specifying the granularity of the region of 157 * text we are interested in. 158 **/ 159 typedef enum { 160 ATK_TEXT_GRANULARITY_CHAR, 161 ATK_TEXT_GRANULARITY_WORD, 162 ATK_TEXT_GRANULARITY_SENTENCE, 163 ATK_TEXT_GRANULARITY_LINE, 164 ATK_TEXT_GRANULARITY_PARAGRAPH 165 } AtkTextGranularity; 166 167 /** 168 * AtkTextRectangle: 169 * @x: The horizontal coordinate of a rectangle 170 * @y: The vertical coordinate of a rectangle 171 * @width: The width of a rectangle 172 * @height: The height of a rectangle 173 * 174 * A structure used to store a rectangle used by AtkText. 175 **/ 176 177 typedef struct _AtkTextRectangle AtkTextRectangle; 178 179 struct _AtkTextRectangle { 180 gint x; 181 gint y; 182 gint width; 183 gint height; 184 }; 185 186 /** 187 * AtkTextRange: 188 * @bounds: A rectangle giving the bounds of the text range 189 * @start_offset: The start offset of a AtkTextRange 190 * @end_offset: The end offset of a AtkTextRange 191 * @content: The text in the text range 192 * 193 * A structure used to describe a text range. 194 **/ 195 typedef struct _AtkTextRange AtkTextRange; 196 197 struct _AtkTextRange { 198 AtkTextRectangle bounds; 199 gint start_offset; 200 gint end_offset; 201 gchar* content; 202 }; 203 204 /** 205 *AtkTextClipType 206 *@ATK_TEXT_CLIP_NONE: No clipping to be done 207 *@ATK_TEXT_CLIP_MIN: Text clipped by min coordinate is omitted 208 *@ATK_TEXT_CLIP_MAX: Text clipped by max coordinate is omitted 209 *@ATK_TEXT_CLIP_BOTH: Only text fully within mix/max bound is retained 210 * 211 *Describes the type of clipping required. 212 **/ 213 typedef enum { 214 ATK_TEXT_CLIP_NONE, 215 ATK_TEXT_CLIP_MIN, 216 ATK_TEXT_CLIP_MAX, 217 ATK_TEXT_CLIP_BOTH 218 } AtkTextClipType; 219 220 struct _AtkTextIface 221 { 222 GTypeInterface parent; 223 224 gchar* (* get_text) (AtkText *text, 225 gint start_offset, 226 gint end_offset); 227 gchar* (* get_text_after_offset) (AtkText *text, 228 gint offset, 229 AtkTextBoundary boundary_type, 230 gint *start_offset, 231 gint *end_offset); 232 gchar* (* get_text_at_offset) (AtkText *text, 233 gint offset, 234 AtkTextBoundary boundary_type, 235 gint *start_offset, 236 gint *end_offset); 237 gunichar (* get_character_at_offset) (AtkText *text, 238 gint offset); 239 gchar* (* get_text_before_offset) (AtkText *text, 240 gint offset, 241 AtkTextBoundary boundary_type, 242 gint *start_offset, 243 gint *end_offset); 244 gint (* get_caret_offset) (AtkText *text); 245 AtkAttributeSet* (* get_run_attributes) (AtkText *text, 246 gint offset, 247 gint *start_offset, 248 gint *end_offset); 249 AtkAttributeSet* (* get_default_attributes) (AtkText *text); 250 void (* get_character_extents) (AtkText *text, 251 gint offset, 252 gint *x, 253 gint *y, 254 gint *width, 255 gint *height, 256 AtkCoordType coords); 257 gint (* get_character_count) (AtkText *text); 258 gint (* get_offset_at_point) (AtkText *text, 259 gint x, 260 gint y, 261 AtkCoordType coords); 262 gint (* get_n_selections) (AtkText *text); 263 gchar* (* get_selection) (AtkText *text, 264 gint selection_num, 265 gint *start_offset, 266 gint *end_offset); 267 gboolean (* add_selection) (AtkText *text, 268 gint start_offset, 269 gint end_offset); 270 gboolean (* remove_selection) (AtkText *text, 271 gint selection_num); 272 gboolean (* set_selection) (AtkText *text, 273 gint selection_num, 274 gint start_offset, 275 gint end_offset); 276 gboolean (* set_caret_offset) (AtkText *text, 277 gint offset); 278 279 /* 280 * signal handlers 281 */ 282 void (* text_changed) (AtkText *text, 283 gint position, 284 gint length); 285 void (* text_caret_moved) (AtkText *text, 286 gint location); 287 void (* text_selection_changed) (AtkText *text); 288 289 void (* text_attributes_changed) (AtkText *text); 290 291 292 void (* get_range_extents) (AtkText *text, 293 gint start_offset, 294 gint end_offset, 295 AtkCoordType coord_type, 296 AtkTextRectangle *rect); 297 298 AtkTextRange** (* get_bounded_ranges) (AtkText *text, 299 AtkTextRectangle *rect, 300 AtkCoordType coord_type, 301 AtkTextClipType x_clip_type, 302 AtkTextClipType y_clip_type); 303 304 gchar* (* get_string_at_offset) (AtkText *text, 305 gint offset, 306 AtkTextGranularity granularity, 307 gint *start_offset, 308 gint *end_offset); 309 /* 310 * Scrolls this text range so it becomes visible on the screen. 311 * 312 * scroll_substring_to lets the implementation compute an appropriate target 313 * position on the screen, with type used as a positioning hint. 314 * 315 * scroll_substring_to_point lets the client specify a precise target position 316 * on the screen. 317 * 318 * Since ATK 2.32 319 */ 320 gboolean (* scroll_substring_to) (AtkText *text, 321 gint start_offset, 322 gint end_offset, 323 AtkScrollType type); 324 gboolean (* scroll_substring_to_point) (AtkText *text, 325 gint start_offset, 326 gint end_offset, 327 AtkCoordType coords, 328 gint x, 329 gint y); 330 }; 331 332 GType atk_text_get_type (void); 333 334 335 /* 336 * Additional AtkObject properties used by AtkText: 337 * "accessible_text" (accessible text has changed) 338 * "accessible_caret" (accessible text cursor position changed: 339 * editable text only) 340 */ 341 342 gchar* atk_text_get_text (AtkText *text, 343 gint start_offset, 344 gint end_offset); 345 gunichar atk_text_get_character_at_offset (AtkText *text, 346 gint offset); 347 gchar* atk_text_get_text_after_offset (AtkText *text, 348 gint offset, 349 AtkTextBoundary boundary_type, 350 gint *start_offset, 351 gint *end_offset); 352 gchar* atk_text_get_text_at_offset (AtkText *text, 353 gint offset, 354 AtkTextBoundary boundary_type, 355 gint *start_offset, 356 gint *end_offset); 357 gchar* atk_text_get_text_before_offset (AtkText *text, 358 gint offset, 359 AtkTextBoundary boundary_type, 360 gint *start_offset, 361 gint *end_offset); 362 gchar* atk_text_get_string_at_offset (AtkText *text, 363 gint offset, 364 AtkTextGranularity granularity, 365 gint *start_offset, 366 gint *end_offset); 367 gint atk_text_get_caret_offset (AtkText *text); 368 void atk_text_get_character_extents (AtkText *text, 369 gint offset, 370 gint *x, 371 gint *y, 372 gint *width, 373 gint *height, 374 AtkCoordType coords); 375 AtkAttributeSet* atk_text_get_run_attributes (AtkText *text, 376 gint offset, 377 gint *start_offset, 378 gint *end_offset); 379 AtkAttributeSet* atk_text_get_default_attributes (AtkText *text); 380 gint atk_text_get_character_count (AtkText *text); 381 gint atk_text_get_offset_at_point (AtkText *text, 382 gint x, 383 gint y, 384 AtkCoordType coords); 385 gint atk_text_get_n_selections (AtkText *text); 386 gchar* atk_text_get_selection (AtkText *text, 387 gint selection_num, 388 gint *start_offset, 389 gint *end_offset); 390 gboolean atk_text_add_selection (AtkText *text, 391 gint start_offset, 392 gint end_offset); 393 gboolean atk_text_remove_selection (AtkText *text, 394 gint selection_num); 395 gboolean atk_text_set_selection (AtkText *text, 396 gint selection_num, 397 gint start_offset, 398 gint end_offset); 399 gboolean atk_text_set_caret_offset (AtkText *text, 400 gint offset); 401 void atk_text_get_range_extents (AtkText *text, 402 403 gint start_offset, 404 gint end_offset, 405 AtkCoordType coord_type, 406 AtkTextRectangle *rect); 407 AtkTextRange** atk_text_get_bounded_ranges (AtkText *text, 408 AtkTextRectangle *rect, 409 AtkCoordType coord_type, 410 AtkTextClipType x_clip_type, 411 AtkTextClipType y_clip_type); 412 void atk_text_free_ranges (AtkTextRange **ranges); 413 void atk_attribute_set_free (AtkAttributeSet *attrib_set); 414 G_CONST_RETURN gchar* atk_text_attribute_get_name (AtkTextAttribute attr); 415 AtkTextAttribute atk_text_attribute_for_name (const gchar *name); 416 G_CONST_RETURN gchar* atk_text_attribute_get_value (AtkTextAttribute attr, 417 gint index_); 418 419 gboolean atk_text_scroll_substring_to (AtkText *text, 420 gint start_offset, 421 gint end_offset, 422 AtkScrollType type); 423 424 gboolean atk_text_scroll_substring_to_point (AtkText *text, 425 gint start_offset, 426 gint end_offset, 427 AtkCoordType coords, 428 gint x, 429 gint y); 430 431 #ifdef __cplusplus 432 } 433 #endif /* __cplusplus */ 434 435 436 #endif /* __ATK_TEXT_H__ */