atk/atktext.h

   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  * AtkAttributeSet:
  34  *
  35  * This is a singly-linked list (a #GSList) of #AtkAttribute. It is
  36  * used by atk_text_ref_run_attributes() and atk_editable_text_set_run_attributes()
  37  **/
  38 typedef GSList AtkAttributeSet;
  39
  40 /**
  41  * AtkAttribute:
  42  * @name: The attribute name. See the ATK_ATTRIBUTE macros, eg #ATK_ATTRIBUTE_LEFT_MARGIN for examples.
  43  * @value: the value of the attribute, represented as a string. See the ATK_ATTRIBUTE macros, eg #ATK_ATTRIBUTE_LEFT_MARGIN for example.
  44  *
  45  * A string name/value pair representing a text attribute.
  46  **/
  47 typedef struct _AtkAttribute AtkAttribute;
  48
  49 struct _AtkAttribute {
  50   gchar* name;
  51   gchar* value;
  52 };
  53
  54 /**
  55  * ATK_ATTRIBUTE_LEFT_MARGIN:
  56  *
  57  * An #AtkAttribute name/value pair. The pixel width of the left margin
  58  **/
  59 #define ATK_ATTRIBUTE_LEFT_MARGIN        "left_margin"
  60
  61 /**
  62  * ATK_ATTRIBUTE_RIGHT_MARGIN:
  63  *
  64  * An #AtkAttribute name/value pair. The pixel width of the right margin
  65  **/
  66 #define ATK_ATTRIBUTE_RIGHT_MARGIN        "right_margin"
  67
  68 /**
  69  * ATK_ATTRIBUTE_INDENT:
  70  *
  71  * An #AtkAttribute name/value pair. The number of pixels that the text is indented
  72  **/
  73 #define ATK_ATTRIBUTE_INDENT              "indent"
  74
  75 /**
  76  * ATK_ATTRIBUTE_INVISIBLE:
  77  *
  78  * An #AtkAttribute name/value pair.
  79  * Either "true" or "false" indicating whether text is visible or not
  80  **/
  81 #define ATK_ATTRIBUTE_INVISIBLE          "invisible"
  82
  83 /**
  84  * ATK_ATTRIBUTE_EDITABLE:
  85  *
  86  * An #AtkAttribute name/value pair.
  87  * Either "true" or "false" indicating whether text is editable or not
  88  **/
  89 #define ATK_ATTRIBUTE_EDITABLE           "editable"
  90
  91 /**
  92  * ATK_ATTRIBUTE_PIXELS_ABOVE_LINES:
  93  *
  94  * An #AtkAttribute name/value pair.
  95  * Pixels of blank space to leave above each newline-terminated line.
  96  **/
  97 #define ATK_ATTRIBUTE_PIXELS_ABOVE_LINES "pixels_above_lines"
  98
  99 /**
 100  * ATK_ATTRIBUTE_PIXELS_BELOW_LINES:
 101  *
 102  * An #AtkAttribute name/value pair.
 103  * Pixels of blank space to leave below each newline-terminated line.
 104  **/
 105 #define ATK_ATTRIBUTE_PIXELS_BELOW_LINES "pixels_below_lines"
 106
 107 /**
 108  * ATK_ATTRIBUTE_PIXELS_INSIDE_WRAP:
 109  *
 110  * An #AtkAttribute name/value pair.
 111  * Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph).
 112  **/
 113 #define ATK_ATTRIBUTE_PIXELS_INSIDE_WRAP "pixels_inside_wrap"
 114
 115 /**
 116  * ATK_ATTRIBUTE_BG_FULL_HEIGHT:
 117  *
 118  * An #AtkAttribute name/value pair.
 119  * "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.
 120  **/
 121 #define ATK_ATTRIBUTE_BG_FULL_HEIGHT     "bg_full_height"
 122
 123 /**
 124  * ATK_ATTRIBUTE_RISE:
 125  *
 126  * An #AtkAttribute name/value pair.
 127  * Number of pixels that the characters are risen above the baseline
 128  * The value is a string representation of an integer
 129  **/
 130 #define ATK_ATTRIBUTE_RISE               "rise"
 131
 132 /**
 133  * ATK_ATTRIBUTE_UNDERLINE:
 134  *
 135  * An #AtkAttribute name/value pair.
 136  * "true" or "false" whether the text is underlined
 137  **/
 138 #define ATK_ATTRIBUTE_UNDERLINE          "underline"
 139
 140 /**
 141  * ATK_ATTRIBUTE_STRIKETHROUGH:
 142  *
 143  * An #AtkAttribute name/value pair.
 144  * "true" or "false" whether the text is strikethrough
 145  **/
 146 #define ATK_ATTRIBUTE_STRIKETHROUGH      "strikethrough"
 147
 148 /**
 149  * ATK_ATTRIBUTE_SIZE:
 150  *
 151  * An #AtkAttribute name/value pair.
 152  * The size of the characters.
 153  * The value is a string representation of an integer
 154  **/
 155 #define ATK_ATTRIBUTE_SIZE               "size"
 156
 157 /**
 158  * ATK_ATTRIBUTE_SCALE:
 159  *
 160  * An #AtkAttribute name/value pair.
 161  * The scale of the characters. The value is a string representation of a double
 162  **/
 163 #define ATK_ATTRIBUTE_SCALE              "scale"
 164
 165 /**
 166  * ATK_ATTRIBUTE_WEIGHT:
 167  *
 168  * An #AtkAttribute name/value pair.
 169  * The weight of the characters. The value is a string representation of an integer
 170  **/
 171 #define ATK_ATTRIBUTE_WEIGHT             "weight"
 172
 173 /**
 174  * ATK_ATTRIBUTE_LANGUAGE:
 175  *
 176  * An #AtkAttribute name/value pair.
 177  * The language used
 178  **/
 179 #define ATK_ATTRIBUTE_LANGUAGE           "language"
 180
 181 /**
 182  * ATK_ATTRIBUTE_FAMILY_NAME:
 183  *
 184  * An #AtkAttribute name/value pair.
 185  * The font family name
 186  **/
 187 #define ATK_ATTRIBUTE_FAMILY_NAME        "family_name"
 188
 189 /**
 190  * ATK_ATTRIBUTE_BG_COLOR:
 191  *
 192  * An #AtkAttribute name/value pair.
 193  * The background color. The value is an RGB value of the format "%u,%u,%u"
 194  **/
 195 #define ATK_ATTRIBUTE_BG_COLOR           "bg_color"
 196
 197 /**
 198  * ATK_ATTRIBUTE_FG_COLOR:
 199  *
 200  * An #AtkAttribute name/value pair.
 201  * The foreground color. The value is an RGB value of the format "%u,%u,%u"
 202  **/
 203 #define ATK_ATTRIBUTE_FG_COLOR           "fg_color"
 204
 205 /**
 206  * ATK_ATTRIBUTE_BG_STIPPLE:
 207  *
 208  * An #AtkAttribute name/value pair.
 209  * "true" if a #GdkBitmap is set for stippling the background color.
 210  **/
 211 #define ATK_ATTRIBUTE_BG_STIPPLE         "bg_stipple"
 212
 213 /**
 214  * ATK_ATTRIBUTE_FG_STIPPLE:
 215  *
 216  * An #AtkAttribute name/value pair.
 217  * "true" if a #GdkBitmap is set for stippling the foreground color.
 218  **/
 219 #define ATK_ATTRIBUTE_FG_STIPPLE         "fg_stipple"
 220
 221 /**
 222  * ATK_ATTRIBUTE_WRAP_MODE:
 223  *
 224  * An #AtkAttribute name/value pair.
 225  * The wrap mode of the text, if any. Values are "none", "char" or "word"
 226  **/
 227 #define ATK_ATTRIBUTE_WRAP_MODE          "wrap_mode"
 228
 229 /**
 230  * ATK_ATTRIBUTE_DIRECTION:
 231  *
 232  * An #AtkAttribute name/value pair.
 233  * The direction of the text, if set. Values are "none", "ltr" or "rtl"
 234  **/
 235 #define ATK_ATTRIBUTE_DIRECTION          "direction"
 236
 237 /**
 238  * ATK_ATTRIBUTE_JUSTIFICATION:
 239  *
 240  * An #AtkAttribute name/value pair.
 241  * The justification of the text, if set. Values are "left", "right", "center" or "fill"
 242  **/
 243 #define ATK_ATTRIBUTE_JUSTIFICATION      "justification"
 244
 245 /**
 246  * ATK_ATTRIBUTE_STRETCH:
 247  *
 248  * An #AtkAttribute name/value pair.
 249  * The stretch of the text, if set. Values are "ultra_condensed", "extra_condensed",
 250  * or "ultra_expanded"
 251  **/
 252 #define ATK_ATTRIBUTE_STRETCH            "stretch"
 253
 254 /**
 255  * ATK_ATTRIBUTE_VARIANT:
 256  *
 257  * An #AtkAttribute name/value pair.
 258  * The capitalization variant of the text, if set. Values are "normal" or "small_caps"
 259  **/
 260 #define ATK_ATTRIBUTE_VARIANT            "variant"
 261
 262 /**
 263  * ATK_ATTRIBUTE_STYLE:
 264  *
 265  * An #AtkAttribute name/value pair.
 266  * The slant style of the text, if set. Values are "normal", "oblique" or "italic"
 267  **/
 268 #define ATK_ATTRIBUTE_STYLE              "slant_style"
 269
 270 #define ATK_TYPE_TEXT                    (atk_text_get_type ())
 271 #define ATK_IS_TEXT(obj)                 G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TEXT)
 272 #define ATK_TEXT(obj)                    G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TEXT, AtkText)
 273 #define ATK_TEXT_GET_IFACE(obj)          (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_TEXT, AtkTextIface))
 274
 275 #ifndef _TYPEDEF_ATK_TEXT_
 276 #define _TYPEDEF_ATK_TEXT_
 277 typedef struct _AtkText AtkText;
 278 #endif
 279 typedef struct _AtkTextIface AtkTextIface;
 280
 281 /**
 282  *AtkTextBoundary:
 283  *@ATK_TEXT_BOUNDARY_CHAR:
 284  *@ATK_TEXT_BOUNDARY_WORD_START:
 285  *@ATK_TEXT_BOUNDARY_WORD_END:
 286  *@ATK_TEXT_BOUNDARY_SENTENCE_START:
 287  *@ATK_TEXT_BOUNDARY_SENTENCE_END:
 288  *@ATK_TEXT_BOUNDARY_LINE_START:
 289  *@ATK_TEXT_BOUNDARY_LINE_END:
 290  *
 291  *Text boundary types used for specifying boundaries for regions of text
 292  **/
 293 typedef enum {
 294   ATK_TEXT_BOUNDARY_CHAR,
 295   ATK_TEXT_BOUNDARY_WORD_START,
 296   ATK_TEXT_BOUNDARY_WORD_END,
 297   ATK_TEXT_BOUNDARY_SENTENCE_START,
 298   ATK_TEXT_BOUNDARY_SENTENCE_END,
 299   ATK_TEXT_BOUNDARY_LINE_START,
 300   ATK_TEXT_BOUNDARY_LINE_END
 301 } AtkTextBoundary;
 302
 303 struct _AtkTextIface
 304 {
 305   GTypeInterface parent;
 306
 307   gchar*         (* get_text)                     (AtkText          *text,
 308                                                    gint             start_offset,
 309                                                    gint             end_offset);
 310   gchar*         (* get_text_after_offset)        (AtkText          *text,
 311                                                    gint             offset,
 312                                                    AtkTextBoundary  boundary_type,
 313                                                    gint             *startOffset,
 314                                                    gint             *endOffset);
 315   gchar*         (* get_text_at_offset)           (AtkText          *text,
 316                                                    gint             offset,
 317                                                    AtkTextBoundary  boundary_type,
 318                                                    gint             *startOffset,
 319                                                    gint             *endOffset);
 320   gunichar       (* get_character_at_offset)      (AtkText          *text,
 321                                                    gint             offset);
 322   gchar*         (* get_text_before_offset)       (AtkText          *text,
 323                                                    gint             offset,
 324                                                    AtkTextBoundary  boundary_type,
 325                                                    gint             *startOffset,
 326                                                    gint             *endOffset);
 327   gint           (* get_caret_offset)             (AtkText          *text);
 328   AtkAttributeSet* (* ref_run_attributes)         (AtkText          *text,
 329                                                    gint             offset,
 330                                                    gint             *start_offset,
 331                                                    gint             *end_offset);
 332   void           (* get_character_extents)        (AtkText          *text,
 333                                                    gint             offset,
 334                                                    gint             *x,
 335                                                    gint             *y,
 336                                                    gint             *length,
 337                                                    gint             *width,
 338                                                    AtkCoordType     coords);
 339   gint           (* get_character_count)          (AtkText          *text);
 340   gint           (* get_offset_at_point)          (AtkText          *text,
 341                                                    gint             x,
 342                                                    gint             y,
 343                                                    AtkCoordType     coords);
 344   gint           (* get_n_selections)             (AtkText          *text);
 345   gchar*         (* get_selection)                (AtkText          *text,
 346                                                    gint             selection_num,
 347                                                    gint             *start_offset,
 348                                                    gint             *end_offset);
 349   gboolean       (* add_selection)                (AtkText          *text,
 350                                                    gint             start_offset,
 351                                                    gint             end_offset);
 352   gboolean       (* remove_selection)             (AtkText          *text,
 353                                                    gint             selection_num);
 354   gboolean       (* set_selection)                (AtkText          *text,
 355                                                    gint             selection_num,
 356                                                    gint             start_offset,
 357                                                    gint             end_offset);
 358   gboolean       (* set_caret_offset)             (AtkText          *text,
 359                                                    gint             offset);
 360
 361   /*
 362    * signal handlers
 363    */
 364   void           (* text_changed)                 (AtkText          *text);
 365   void           (* caret_changed)                (AtkText          *text,
 366                                                    gint             location);
 367 };
 368
 369 GType            atk_text_get_type (void);
 370
 371
 372 /*
 373  * Additional AtkObject properties used by AtkText:
 374  *    "accessible_text" (accessible text has changed)
 375  *    "accessible_caret" (accessible text cursor position changed:
 376  *                         editable text only)
 377  */
 378
 379 gchar*        atk_text_get_text                           (AtkText          *text,
 380                                                            gint             start_offset,
 381                                                            gint             end_offset);
 382 gunichar      atk_text_get_character_at_offset            (AtkText          *text,
 383                                                            gint             offset);
 384 gchar*        atk_text_get_text_after_offset              (AtkText          *text,
 385                                                            gint             offset,
 386                                                            AtkTextBoundary  boundary_type,
 387                                                            gint             *startOffset,
 388                                                            gint             *endOffset);
 389 gchar*        atk_text_get_text_at_offset                 (AtkText          *text,
 390                                                            gint             offset,
 391                                                            AtkTextBoundary  boundary_type,
 392                                                            gint             *startOffset,
 393                                                            gint             *endOffset);
 394 gchar*        atk_text_get_text_before_offset             (AtkText          *text,
 395                                                            gint             offset,
 396                                                            AtkTextBoundary  boundary_type,
 397                                                            gint             *startOffset,
 398                                                            gint             *endOffset);
 399 gint          atk_text_get_caret_offset                   (AtkText          *text);
 400 void          atk_text_get_character_extents              (AtkText          *text,
 401                                                            gint             offset,
 402                                                            gint             *x,
 403                                                            gint             *y,
 404                                                            gint             *length,
 405                                                            gint             *width,
 406                                                            AtkCoordType     coords);
 407 AtkAttributeSet* atk_text_ref_run_attributes              (AtkText          *text,
 408                                                            gint             offset,
 409                                                            gint             *start_offset,
 410                                                            gint             *end_offset);
 411 gint          atk_text_get_character_count                (AtkText          *text);
 412 gint          atk_text_get_offset_at_point                (AtkText          *text,
 413                                                            gint             x,
 414                                                            gint             y,
 415                                                            AtkCoordType     coords);
 416 gint          atk_text_get_n_selections                   (AtkText          *text);
 417 gchar*        atk_text_get_selection                      (AtkText          *text,
 418                                                            gint             selection_num,
 419                                                            gint             *start_offset,
 420                                                            gint             *end_offset);
 421 gboolean      atk_text_add_selection                      (AtkText          *text,
 422                                                            gint             start_offset,
 423                                                            gint             end_offset);
 424 gboolean      atk_text_remove_selection                   (AtkText          *text,
 425                                                            gint             selection_num);
 426 gboolean      atk_text_set_selection                      (AtkText          *text,
 427                                                            gint             selection_num,
 428                                                            gint             start_offset,
 429                                                            gint             end_offset);
 430 gboolean      atk_text_set_caret_offset                   (AtkText          *text,
 431                                                            gint             offset);
 432 void          AtkAttributeSet_free                        (AtkAttributeSet  *attrib_set);
 433
 434 #ifdef __cplusplus
 435 }
 436 #endif /* __cplusplus */
 437
 438
 439 #endif /* __ATK_TEXT_H__ */