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