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