atk-1.0/atk/atktext.h

0001 /* ATK - The Accessibility Toolkit for GTK+
0002  * Copyright 2001 Sun Microsystems Inc.
0003  *
0004  * This library is free software; you can redistribute it and/or
0005  * modify it under the terms of the GNU Library General Public
0006  * License as published by the Free Software Foundation; either
0007  * version 2 of the License, or (at your option) any later version.
0008  *
0009  * This library is distributed in the hope that it will be useful,
0010  * but WITHOUT ANY WARRANTY; without even the implied warranty of
0011  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012  * Library General Public License for more details.
0013  *
0014  * You should have received a copy of the GNU Library General Public
0015  * License along with this library; if not, write to the
0016  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
0017  * Boston, MA 02111-1307, USA.
0018  */
0019
0020 #ifndef __ATK_TEXT_H__
0021 #define __ATK_TEXT_H__
0022
0023 #if defined(ATK_DISABLE_SINGLE_INCLUDES) && !defined(__ATK_H_INSIDE__) && !defined(ATK_COMPILATION)
0024 #error "Only <atk/atk.h> can be included directly."
0025 #endif
0026
0027 #include <atk/atkcomponent.h>
0028 #include <atk/atkobject.h>
0029 #include <atk/atkutil.h>
0030 #include <glib-object.h>
0031
0032 G_BEGIN_DECLS
0033
0034 /**
0035  *AtkTextAttribute:
0036  *@ATK_TEXT_ATTR_INVALID: Invalid attribute, like bad spelling or grammar.
0037  *@ATK_TEXT_ATTR_LEFT_MARGIN: The pixel width of the left margin
0038  *@ATK_TEXT_ATTR_RIGHT_MARGIN: The pixel width of the right margin
0039  *@ATK_TEXT_ATTR_INDENT: The number of pixels that the text is indented
0040  *@ATK_TEXT_ATTR_INVISIBLE: Either "true" or "false" indicating whether text is visible or not
0041  *@ATK_TEXT_ATTR_EDITABLE: Either "true" or "false" indicating whether text is editable or not
0042  *@ATK_TEXT_ATTR_PIXELS_ABOVE_LINES: Pixels of blank space to leave above each newline-terminated line.
0043  *@ATK_TEXT_ATTR_PIXELS_BELOW_LINES: Pixels of blank space to leave below each newline-terminated line.
0044  *@ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP: Pixels of blank space to leave between wrapped lines inside the same newline-terminated line (paragraph).
0045  *@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.
0046  *@ATK_TEXT_ATTR_RISE: Number of pixels that the characters are risen above the baseline. See also ATK_TEXT_ATTR_TEXT_POSITION.
0047  *@ATK_TEXT_ATTR_UNDERLINE: "none", "single", "double", "low", or "error"
0048  *@ATK_TEXT_ATTR_STRIKETHROUGH: "true" or "false" whether the text is strikethrough
0049  *@ATK_TEXT_ATTR_SIZE: The size of the characters in points. eg: 10
0050  *@ATK_TEXT_ATTR_SCALE: The scale of the characters. The value is a string representation of a double
0051  *@ATK_TEXT_ATTR_WEIGHT: The weight of the characters.
0052  *@ATK_TEXT_ATTR_LANGUAGE: The language used
0053  *@ATK_TEXT_ATTR_FAMILY_NAME: The font family name
0054  *@ATK_TEXT_ATTR_BG_COLOR: The background color. The value is an RGB value of the format "%u,%u,%u"
0055  *@ATK_TEXT_ATTR_FG_COLOR:The foreground color. The value is an RGB value of the format "%u,%u,%u"
0056  *@ATK_TEXT_ATTR_BG_STIPPLE: "true" if a #GdkBitmap is set for stippling the background color.
0057  *@ATK_TEXT_ATTR_FG_STIPPLE: "true" if a #GdkBitmap is set for stippling the foreground color.
0058  *@ATK_TEXT_ATTR_WRAP_MODE: The wrap mode of the text, if any. Values are "none", "char", "word", or "word_char".
0059  *@ATK_TEXT_ATTR_DIRECTION: The direction of the text, if set. Values are "none", "ltr" or "rtl"
0060  *@ATK_TEXT_ATTR_JUSTIFICATION: The justification of the text, if set. Values are "left", "right", "center" or "fill"
0061  *@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"
0062  *@ATK_TEXT_ATTR_VARIANT: The capitalization variant of the text, if set. Values are "normal" or "small_caps"
0063  *@ATK_TEXT_ATTR_STYLE: The slant style of the text, if set. Values are "normal", "oblique" or "italic"
0064  *@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.
0065  *@ATK_TEXT_ATTR_LAST_DEFINED: not a valid text attribute, used for finding end of enumeration
0066  *
0067  * Describes the text attributes supported
0068  **/
0069 typedef enum
0070 {
0071   ATK_TEXT_ATTR_INVALID = 0,
0072   ATK_TEXT_ATTR_LEFT_MARGIN,
0073   ATK_TEXT_ATTR_RIGHT_MARGIN,
0074   ATK_TEXT_ATTR_INDENT,
0075   ATK_TEXT_ATTR_INVISIBLE,
0076   ATK_TEXT_ATTR_EDITABLE,
0077   ATK_TEXT_ATTR_PIXELS_ABOVE_LINES,
0078   ATK_TEXT_ATTR_PIXELS_BELOW_LINES,
0079   ATK_TEXT_ATTR_PIXELS_INSIDE_WRAP,
0080   ATK_TEXT_ATTR_BG_FULL_HEIGHT,
0081   ATK_TEXT_ATTR_RISE,
0082   ATK_TEXT_ATTR_UNDERLINE,
0083   ATK_TEXT_ATTR_STRIKETHROUGH,
0084   ATK_TEXT_ATTR_SIZE,
0085   ATK_TEXT_ATTR_SCALE,
0086   ATK_TEXT_ATTR_WEIGHT,
0087   ATK_TEXT_ATTR_LANGUAGE,
0088   ATK_TEXT_ATTR_FAMILY_NAME,
0089   ATK_TEXT_ATTR_BG_COLOR,
0090   ATK_TEXT_ATTR_FG_COLOR,
0091   ATK_TEXT_ATTR_BG_STIPPLE,
0092   ATK_TEXT_ATTR_FG_STIPPLE,
0093   ATK_TEXT_ATTR_WRAP_MODE,
0094   ATK_TEXT_ATTR_DIRECTION,
0095   ATK_TEXT_ATTR_JUSTIFICATION,
0096   ATK_TEXT_ATTR_STRETCH,
0097   ATK_TEXT_ATTR_VARIANT,
0098   ATK_TEXT_ATTR_STYLE,
0099   ATK_TEXT_ATTR_TEXT_POSITION,
0100   ATK_TEXT_ATTR_LAST_DEFINED
0101 } AtkTextAttribute;
0102
0103 ATK_AVAILABLE_IN_ALL
0104 AtkTextAttribute atk_text_attribute_register (const gchar *name);
0105
0106 #define ATK_TYPE_TEXT (atk_text_get_type ())
0107 #define ATK_IS_TEXT(obj) G_TYPE_CHECK_INSTANCE_TYPE ((obj), ATK_TYPE_TEXT)
0108 #define ATK_TEXT(obj) G_TYPE_CHECK_INSTANCE_CAST ((obj), ATK_TYPE_TEXT, AtkText)
0109 #define ATK_TEXT_GET_IFACE(obj) (G_TYPE_INSTANCE_GET_INTERFACE ((obj), ATK_TYPE_TEXT, AtkTextIface))
0110
0111 #ifndef _TYPEDEF_ATK_TEXT_
0112 #define _TYPEDEF_ATK_TEXT_
0113 typedef struct _AtkText AtkText;
0114 #endif
0115 typedef struct _AtkTextIface AtkTextIface;
0116
0117 /**
0118  *AtkTextBoundary:
0119  *@ATK_TEXT_BOUNDARY_CHAR: Boundary is the boundary between characters
0120  * (including non-printing characters)
0121  *@ATK_TEXT_BOUNDARY_WORD_START: Boundary is the start (i.e. first character) of a word.
0122  *@ATK_TEXT_BOUNDARY_WORD_END: Boundary is the end (i.e. last
0123  * character) of a word.
0124  *@ATK_TEXT_BOUNDARY_SENTENCE_START: Boundary is the first character in a sentence.
0125  *@ATK_TEXT_BOUNDARY_SENTENCE_END: Boundary is the last (terminal)
0126  * character in a sentence; in languages which use "sentence stop"
0127  * punctuation such as English, the boundary is thus the '.', '?', or
0128  * similar terminal punctuation character.
0129  *@ATK_TEXT_BOUNDARY_LINE_START: Boundary is the initial character of the content or a
0130  * character immediately following a newline, linefeed, or return character.
0131  *@ATK_TEXT_BOUNDARY_LINE_END: Boundary is the linefeed, or return
0132  * character.
0133  *
0134  * Text boundary types used for specifying boundaries for regions of text.
0135  * This enumeration is deprecated since 2.9.4 and should not be used. Use
0136  * AtkTextGranularity with #atk_text_get_string_at_offset instead.
0137  **/
0138 typedef enum
0139 {
0140   ATK_TEXT_BOUNDARY_CHAR,
0141   ATK_TEXT_BOUNDARY_WORD_START,
0142   ATK_TEXT_BOUNDARY_WORD_END,
0143   ATK_TEXT_BOUNDARY_SENTENCE_START,
0144   ATK_TEXT_BOUNDARY_SENTENCE_END,
0145   ATK_TEXT_BOUNDARY_LINE_START,
0146   ATK_TEXT_BOUNDARY_LINE_END
0147 } AtkTextBoundary;
0148
0149 /**
0150  *AtkTextGranularity:
0151  *@ATK_TEXT_GRANULARITY_CHAR: Granularity is defined by the boundaries between characters
0152  * (including non-printing characters)
0153  *@ATK_TEXT_GRANULARITY_WORD: Granularity is defined by the boundaries of a word,
0154  * starting at the beginning of the current word and finishing at the beginning of
0155  * the following one, if present.
0156  *@ATK_TEXT_GRANULARITY_SENTENCE: Granularity is defined by the boundaries of a sentence,
0157  * starting at the beginning of the current sentence and finishing at the beginning of
0158  * the following one, if present.
0159  *@ATK_TEXT_GRANULARITY_LINE: Granularity is defined by the boundaries of a line,
0160  * starting at the beginning of the current line and finishing at the beginning of
0161  * the following one, if present.
0162  *@ATK_TEXT_GRANULARITY_PARAGRAPH: Granularity is defined by the boundaries of a paragraph,
0163  * starting at the beginning of the current paragraph and finishing at the beginning of
0164  * the following one, if present.
0165  *
0166  * Text granularity types used for specifying the granularity of the region of
0167  * text we are interested in.
0168  **/
0169 typedef enum
0170 {
0171   ATK_TEXT_GRANULARITY_CHAR,
0172   ATK_TEXT_GRANULARITY_WORD,
0173   ATK_TEXT_GRANULARITY_SENTENCE,
0174   ATK_TEXT_GRANULARITY_LINE,
0175   ATK_TEXT_GRANULARITY_PARAGRAPH
0176 } AtkTextGranularity;
0177
0178 /**
0179  * AtkTextRectangle:
0180  * @x: The horizontal coordinate of a rectangle
0181  * @y: The vertical coordinate of a rectangle
0182  * @width: The width of a rectangle
0183  * @height: The height of a rectangle
0184  *
0185  * A structure used to store a rectangle used by AtkText.
0186  **/
0187
0188 typedef struct _AtkTextRectangle AtkTextRectangle;
0189
0190 struct _AtkTextRectangle
0191 {
0192   gint x;
0193   gint y;
0194   gint width;
0195   gint height;
0196 };
0197
0198 /**
0199  * AtkTextRange:
0200  * @bounds: A rectangle giving the bounds of the text range
0201  * @start_offset: The start offset of a AtkTextRange
0202  * @end_offset: The end offset of a AtkTextRange
0203  * @content: The text in the text range
0204  *
0205  * A structure used to describe a text range.
0206  **/
0207 typedef struct _AtkTextRange AtkTextRange;
0208
0209 struct _AtkTextRange
0210 {
0211   AtkTextRectangle bounds;
0212   gint start_offset;
0213   gint end_offset;
0214   gchar *content;
0215 };
0216
0217 ATK_AVAILABLE_IN_ALL
0218 GType atk_text_range_get_type (void);
0219
0220 /**
0221  *AtkTextClipType:
0222  *@ATK_TEXT_CLIP_NONE: No clipping to be done
0223  *@ATK_TEXT_CLIP_MIN: Text clipped by min coordinate is omitted
0224  *@ATK_TEXT_CLIP_MAX: Text clipped by max coordinate is omitted
0225  *@ATK_TEXT_CLIP_BOTH: Only text fully within mix/max bound is retained
0226  *
0227  *Describes the type of clipping required.
0228  **/
0229 typedef enum
0230 {
0231   ATK_TEXT_CLIP_NONE,
0232   ATK_TEXT_CLIP_MIN,
0233   ATK_TEXT_CLIP_MAX,
0234   ATK_TEXT_CLIP_BOTH
0235 } AtkTextClipType;
0236
0237 /**
0238  * AtkTextIface:
0239  * @get_text_after_offset: Gets specified text. This virtual function
0240  *   is deprecated and it should not be overridden.
0241  * @get_text_at_offset: Gets specified text. This virtual function
0242  *   is deprecated and it should not be overridden.
0243  * @get_text_before_offset: Gets specified text. This virtual function
0244  *   is deprecated and it should not be overridden.
0245  * @get_string_at_offset: Gets a portion of the text exposed through
0246  *   an AtkText according to a given offset and a specific
0247  *   granularity, along with the start and end offsets defining the
0248  *   boundaries of such a portion of text.
0249  * @text_changed: the signal handler which is executed when there is a
0250  *   text change. This virtual function is deprecated sice 2.9.4 and
0251  *   it should not be overriden.
0252  */
0253 struct _AtkTextIface
0254 {
0255   GTypeInterface parent;
0256
0257   gchar *(*get_text) (AtkText *text,
0258                       gint start_offset,
0259                       gint end_offset);
0260   gchar *(*get_text_after_offset) (AtkText *text,
0261                                    gint offset,
0262                                    AtkTextBoundary boundary_type,
0263                                    gint *start_offset,
0264                                    gint *end_offset);
0265   gchar *(*get_text_at_offset) (AtkText *text,
0266                                 gint offset,
0267                                 AtkTextBoundary boundary_type,
0268                                 gint *start_offset,
0269                                 gint *end_offset);
0270   gunichar (*get_character_at_offset) (AtkText *text,
0271                                        gint offset);
0272   gchar *(*get_text_before_offset) (AtkText *text,
0273                                     gint offset,
0274                                     AtkTextBoundary boundary_type,
0275                                     gint *start_offset,
0276                                     gint *end_offset);
0277   gint (*get_caret_offset) (AtkText *text);
0278   AtkAttributeSet *(*get_run_attributes) (AtkText *text,
0279                                           gint offset,
0280                                           gint *start_offset,
0281                                           gint *end_offset);
0282   AtkAttributeSet *(*get_default_attributes) (AtkText *text);
0283   void (*get_character_extents) (AtkText *text,
0284                                  gint offset,
0285                                  gint *x,
0286                                  gint *y,
0287                                  gint *width,
0288                                  gint *height,
0289                                  AtkCoordType coords);
0290   gint (*get_character_count) (AtkText *text);
0291   gint (*get_offset_at_point) (AtkText *text,
0292                                gint x,
0293                                gint y,
0294                                AtkCoordType coords);
0295   gint (*get_n_selections) (AtkText *text);
0296   gchar *(*get_selection) (AtkText *text,
0297                            gint selection_num,
0298                            gint *start_offset,
0299                            gint *end_offset);
0300   gboolean (*add_selection) (AtkText *text,
0301                              gint start_offset,
0302                              gint end_offset);
0303   gboolean (*remove_selection) (AtkText *text,
0304                                 gint selection_num);
0305   gboolean (*set_selection) (AtkText *text,
0306                              gint selection_num,
0307                              gint start_offset,
0308                              gint end_offset);
0309   gboolean (*set_caret_offset) (AtkText *text,
0310                                 gint offset);
0311
0312   /*
0313    * signal handlers
0314    */
0315   void (*text_changed) (AtkText *text,
0316                         gint position,
0317                         gint length);
0318   void (*text_caret_moved) (AtkText *text,
0319                             gint location);
0320   void (*text_selection_changed) (AtkText *text);
0321
0322   void (*text_attributes_changed) (AtkText *text);
0323
0324   void (*get_range_extents) (AtkText *text,
0325                              gint start_offset,
0326                              gint end_offset,
0327                              AtkCoordType coord_type,
0328                              AtkTextRectangle *rect);
0329
0330   AtkTextRange **(*get_bounded_ranges) (AtkText *text,
0331                                         AtkTextRectangle *rect,
0332                                         AtkCoordType coord_type,
0333                                         AtkTextClipType x_clip_type,
0334                                         AtkTextClipType y_clip_type);
0335
0336   gchar *(*get_string_at_offset) (AtkText *text,
0337                                   gint offset,
0338                                   AtkTextGranularity granularity,
0339                                   gint *start_offset,
0340                                   gint *end_offset);
0341   /*
0342    * Scrolls this text range so it becomes visible on the screen.
0343    *
0344    * scroll_substring_to lets the implementation compute an appropriate target
0345    * position on the screen, with type used as a positioning hint.
0346    *
0347    * scroll_substring_to_point lets the client specify a precise target position
0348    * on the screen for the top-left of the substring.
0349    *
0350    * Since ATK 2.32
0351    */
0352   gboolean (*scroll_substring_to) (AtkText *text,
0353                                    gint start_offset,
0354                                    gint end_offset,
0355                                    AtkScrollType type);
0356   gboolean (*scroll_substring_to_point) (AtkText *text,
0357                                          gint start_offset,
0358                                          gint end_offset,
0359                                          AtkCoordType coords,
0360                                          gint x,
0361                                          gint y);
0362 };
0363
0364 ATK_AVAILABLE_IN_ALL
0365 GType atk_text_get_type (void);
0366
0367 /*
0368  * Additional AtkObject properties used by AtkText:
0369  *    "accessible_text" (accessible text has changed)
0370  *    "accessible_caret" (accessible text cursor position changed:
0371  *                         editable text only)
0372  */
0373
0374 ATK_AVAILABLE_IN_ALL
0375 gchar *atk_text_get_text (AtkText *text,
0376                           gint start_offset,
0377                           gint end_offset);
0378 ATK_AVAILABLE_IN_ALL
0379 gunichar atk_text_get_character_at_offset (AtkText *text,
0380                                            gint offset);
0381 ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
0382 gchar *atk_text_get_text_after_offset (AtkText *text,
0383                                        gint offset,
0384                                        AtkTextBoundary boundary_type,
0385                                        gint *start_offset,
0386                                        gint *end_offset);
0387 ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
0388 gchar *atk_text_get_text_at_offset (AtkText *text,
0389                                     gint offset,
0390                                     AtkTextBoundary boundary_type,
0391                                     gint *start_offset,
0392                                     gint *end_offset);
0393 ATK_DEPRECATED_IN_2_10_FOR (atk_text_get_string_at_offset)
0394 gchar *atk_text_get_text_before_offset (AtkText *text,
0395                                         gint offset,
0396                                         AtkTextBoundary boundary_type,
0397                                         gint *start_offset,
0398                                         gint *end_offset);
0399 ATK_AVAILABLE_IN_2_10
0400 gchar *atk_text_get_string_at_offset (AtkText *text,
0401                                       gint offset,
0402                                       AtkTextGranularity granularity,
0403                                       gint *start_offset,
0404                                       gint *end_offset);
0405 ATK_AVAILABLE_IN_ALL
0406 gint atk_text_get_caret_offset (AtkText *text);
0407 ATK_AVAILABLE_IN_ALL
0408 void atk_text_get_character_extents (AtkText *text,
0409                                      gint offset,
0410                                      gint *x,
0411                                      gint *y,
0412                                      gint *width,
0413                                      gint *height,
0414                                      AtkCoordType coords);
0415 ATK_AVAILABLE_IN_ALL
0416 AtkAttributeSet *atk_text_get_run_attributes (AtkText *text,
0417                                               gint offset,
0418                                               gint *start_offset,
0419                                               gint *end_offset);
0420 ATK_AVAILABLE_IN_ALL
0421 AtkAttributeSet *atk_text_get_default_attributes (AtkText *text);
0422 ATK_AVAILABLE_IN_ALL
0423 gint atk_text_get_character_count (AtkText *text);
0424 ATK_AVAILABLE_IN_ALL
0425 gint atk_text_get_offset_at_point (AtkText *text,
0426                                    gint x,
0427                                    gint y,
0428                                    AtkCoordType coords);
0429 ATK_AVAILABLE_IN_ALL
0430 gint atk_text_get_n_selections (AtkText *text);
0431 ATK_AVAILABLE_IN_ALL
0432 gchar *atk_text_get_selection (AtkText *text,
0433                                gint selection_num,
0434                                gint *start_offset,
0435                                gint *end_offset);
0436 ATK_AVAILABLE_IN_ALL
0437 gboolean atk_text_add_selection (AtkText *text,
0438                                  gint start_offset,
0439                                  gint end_offset);
0440 ATK_AVAILABLE_IN_ALL
0441 gboolean atk_text_remove_selection (AtkText *text,
0442                                     gint selection_num);
0443 ATK_AVAILABLE_IN_ALL
0444 gboolean atk_text_set_selection (AtkText *text,
0445                                  gint selection_num,
0446                                  gint start_offset,
0447                                  gint end_offset);
0448 ATK_AVAILABLE_IN_ALL
0449 gboolean atk_text_set_caret_offset (AtkText *text,
0450                                     gint offset);
0451 ATK_AVAILABLE_IN_ALL
0452 void atk_text_get_range_extents (AtkText *text,
0453
0454                                  gint start_offset,
0455                                  gint end_offset,
0456                                  AtkCoordType coord_type,
0457                                  AtkTextRectangle *rect);
0458 ATK_AVAILABLE_IN_ALL
0459 AtkTextRange **atk_text_get_bounded_ranges (AtkText *text,
0460                                             AtkTextRectangle *rect,
0461                                             AtkCoordType coord_type,
0462                                             AtkTextClipType x_clip_type,
0463                                             AtkTextClipType y_clip_type);
0464 ATK_AVAILABLE_IN_ALL
0465 void atk_text_free_ranges (AtkTextRange **ranges);
0466 ATK_AVAILABLE_IN_ALL
0467 void atk_attribute_set_free (AtkAttributeSet *attrib_set);
0468 ATK_AVAILABLE_IN_ALL
0469 const gchar *atk_text_attribute_get_name (AtkTextAttribute attr);
0470 ATK_AVAILABLE_IN_ALL
0471 AtkTextAttribute atk_text_attribute_for_name (const gchar *name);
0472 ATK_AVAILABLE_IN_ALL
0473 const gchar *atk_text_attribute_get_value (AtkTextAttribute attr,
0474                                            gint index_);
0475
0476 ATK_AVAILABLE_IN_2_32
0477 gboolean atk_text_scroll_substring_to (AtkText *text,
0478                                        gint start_offset,
0479                                        gint end_offset,
0480                                        AtkScrollType type);
0481
0482 ATK_AVAILABLE_IN_2_32
0483 gboolean atk_text_scroll_substring_to_point (AtkText *text,
0484                                              gint start_offset,
0485                                              gint end_offset,
0486                                              AtkCoordType coords,
0487                                              gint x,
0488                                              gint y);
0489
0490 G_END_DECLS
0491
0492 #endif /* __ATK_TEXT_H__ */