idl/Accessibility_Text.idl

   1 /*
   2  * AT-SPI - Assistive Technology Service Provider Interface
   3  * (Gnome Accessibility Project; http://developer.gnome.org/projects/gap)
   4  *
   5  * Copyright 2001 Sun Microsystems, Inc.
   6  *
   7  * This library is free software; you can redistribute it and/or
   8  * modify it under the terms of the GNU Library General Public
   9  * License as published by the Free Software Foundation; either
  10  * version 2 of the License, or (at your option) any later version.
  11  *
  12  * This library is distributed in the hope that it will be useful,
  13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  15  * Library General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU Library General Public
  18  * License along with this library; if not, write to the
  19  * Free Software Foundation, Inc., 59 Temple Place - Suite 330,
  20  * Boston, MA 02111-1307, USA.
  21  */
  22
  23 module Accessibility {
  24
  25   /**
  26    * Specifies the boundary conditions determining a run of text as returned from
  27    * getTextAtOffset, getTextAfterOffset, and getTextBeforeOffset.
  28    */
  29   enum TEXT_BOUNDARY_TYPE {
  30     TEXT_BOUNDARY_CHAR,/**< Text is bounded by this character only.
  31                         * Start and end offsets differ by one, by definition, for this value.
  32                         */
  33     TEXT_BOUNDARY_WORD_START,/**< Boundary condition is start of a word; i.e. range is from start of
  34                               * one word to the start of another word.
  35                               */
  36     TEXT_BOUNDARY_WORD_END,/**< Boundary condition is the end of a word; i.e. range is from
  37                             * the end of one word to the end of another.
  38                             * @note some locales may not distinguish between words and
  39                             * characters or glyphs, in particular those locales which use
  40                             * wholly or partially ideographic character sets.  In these cases,
  41                             * characters may be returned in lieu of multi-character substrings.
  42                             */
  43     TEXT_BOUNDARY_SENTENCE_START,/**< Boundary condition is start of a sentence, as determined
  44                                 *  by the application.
  45                                 *  @note Some locales or character sets may not include explicit sentence
  46                                 *  delimiters, so this boundary type can not always be honored.
  47                                 *  Some locales will return lines of text instead of grammatical sentences.
  48                                   */
  49     TEXT_BOUNDARY_SENTENCE_END,/**< Boundary condition is end of a sentence, as determined by the application,
  50                                 *  including the sentence-delimiting character, for instance '.'
  51                                 *  @note Some locales or character sets may not include explicit sentence
  52                                 *  delimiters, so this boundary type can not always be honored.
  53                                 *  Some locales will return lines of text instead of grammatical sentences.
  54                                 */
  55     TEXT_BOUNDARY_LINE_START,/**< Boundary condition is the start of a line; i.e. range is
  56                               * from start of one line to the start of another.  This generally
  57                               * means that an end-of-line character will appear at the end of the range.
  58                               */
  59     TEXT_BOUNDARY_LINE_END /**< Boundary condition is the end of a line; i.e. range is
  60                             * from start of one line to the start of another.  This generally
  61                             * means that an end-of-line character will be the first character of the range.
  62                             */
  63   };
  64
  65   /**
  66    * TEXT_CLIP_TYPE:
  67    * CLIP_MIN means text clipped by min coordinate is omitted,
  68    * CLIP_MAX clips text interescted by the max coord, and CLIP_BOTH
  69    * will retain only text falling fully within the min/max bounds.
  70    *
  71    **/
  72   enum TEXT_CLIP_TYPE {
  73     TEXT_CLIP_NONE,
  74     TEXT_CLIP_MIN,/**< characters/glyphs clipped by the minimum coordinate are omitted */
  75     TEXT_CLIP_MAX,/**< characters/glyphs which intersect the maximum coordinate are omitted */
  76     TEXT_CLIP_BOTH /**< only glyphs falling entirely within the region bounded by min and max are retained. */
  77   };
  78
  79     /**
  80      * The text interface should be implemented by objects which place textual information onscreen as character
  81      * strings or glyphs.  The text interface allows access to textual content, including display attributes and
  82      * semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings.
  83      * It also allows portions of textual content to be selected, if the object's StateSet includes
  84      * STATE_SELECTABLE_TEXT.
  85      *
  86      * In some cases a Text object may have, as its content, an empty string.  In particular this can
  87      * occur in the case of Hypertext objects which do not display explicitly textual information onscreen,
  88      * as Hypertext is derived from the Text interface.  @see Hypertext.
  89      *
  90      * Typographic and semantic attributes of onscreen textual content, for instance typeface, weight,
  91      * language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes.
  92      * Contiguous sequences of characters over which these attributes are unchanged are referred to as
  93      * "attribute runs", and are available via Text::getAttributeRun.  Where possible, implementing clients
  94      * will report textual attributes which are the same over the entire text object, for instance those
  95      * inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them
  96      * explicitly for each character.  Therefore, for any span of text, the attributes in effect are the union
  97      * of the set returned by Text::getDefaultAttributes, and the set returned at a particular character
  98      * offset via Text::getAttributeRun.
  99      *
 100      * @note Events that may be emitted by instances of Text include:
 101      * \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over
 102      *         which attributes apply, has changed.
 103      * \li \c "object:text-changed" The text content of this object has changed.
 104      * \li \c "object:text-bounds-changed" The character bounds of a text object have changed,
 105      *         for instance in response to a reformatting or reflow operation.
 106      * \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within
 107      *         this object has changed.  Events of this type may also be generated when an onscreen
 108      *         text caret appears or disappears.
 109      * \li \c "object:text-selection-changed" The range or number of text selections within this text object
 110      *         has changed.
 111      *
 112      * @note In some cases, objects which are not onscreen may implement Text, but if such objects
 113      * implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE
 114      * and STATE_SHOWING) before exposing them to the user.  Objects which implement Text but not Component
 115      * may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual
 116      * interfaces to allow non-graphical access to application features.  These instances should be considered
 117      * the exception, rather than the rule.
 118      */
 119   interface Text : Bonobo::Unknown {
 120
 121     /** A structure used to define a continguous range of text, including its
 122      * (unattributed) textual content.
 123      **/
 124     struct Range {
 125       long startOffset;
 126       long endOffset;
 127       string content;
 128       any  data;
 129     };
 130
 131     typedef sequence<Range> RangeList;
 132
 133     /** The total current number of characters in the Text object,
 134      * including whitespace and non-spacing characters.
 135      **/
 136     readonly attribute long characterCount;
 137
 138     /** The current offset of the text caret in the Text object.
 139      * This caret may be virtual, e.g. non-visual and notional-only, but if an
 140      * onscreen representation of the caret position is visible, it will correspond to this offset.
 141      * The caret offset is given as a character offset, as opposed to a byte offset into
 142      * a text buffer or a column offset.
 143      **/
 144     readonly attribute long caretOffset;
 145
 146       /**
 147        * Obtain all or part of the onscreen textual content of a Text object.  If endOffset is specified as
 148        * "-1", then this method will return the entire onscreen textual contents of the Text object.
 149        * @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort
 150        * of coordinate visibility clipping or window-stack-ordering clipping.  The text thus reported
 151        * corresponds to the text which would be presented onscreen if the object implementing the Text interface
 152        * were entirely unobscured.
 153        * @returns the textual content of the current Text object beginning startOffset (inclusive)
 154        * up to but not including the character at endOffset.
 155        **/
 156     string getText (in long startOffset, in long endOffset);
 157
 158       /** Programmatically move the text caret (visible or virtual, as above) to a given position.
 159        * @param offset a long int indicating the desired character offset.  Not all implementations of
 160        * Text will honor setCaretOffset requests, so the return value below should be checked by the client.
 161        * @returns \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to
 162        * the requested position.
 163        **/
 164     boolean setCaretOffset (in long offset);
 165
 166       /**
 167        * Obtain a subset of the text content of an object which entirely precedes \c offset,
 168        * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
 169        * starting and ending offsets of the resulting substring are returned in \c startOffset
 170        * and \c endOffset.  By definition, if such a substring exists, \c endOffset is less than or
 171        * equal to \c offset.
 172        * @param offset the offset from which the substring search begins.
 173        * @param type the text-boundary delimiter which determines whether the returned text constitures
 174        *        a character, word, line, or sentence (and possibly attendant whitespace),
 175        *        and whether the start or ending of such a substring forms the boundary condition.
 176        * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
 177        * @param endOffset back-filled with the offset of the character immediately following the resulting
 178        *                  substring, if one exists.
 179        * @see TEXT_BOUNDARY_TYPE
 180        * @returns a string which is a substring of the text content of the object, delimited by the
 181        * specified boundary condition.
 182        */
 183     string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 184                                 out long startOffset, out long endOffset);
 185       /**
 186        * Obtain a subset of the text content of an object which includes the specified \c offset,
 187        * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
 188        * starting and ending offsets of the resulting substring are returned in \c startOffset
 189        * and \c endOffset.
 190        * @param offset the offset from which the substring search begins, and which must
 191        *        lie within the returned substring.
 192        * @param type the text-boundary delimiter which determines whether the returned text constitures
 193        *        a character, word, line, or sentence (and possibly attendant whitespace),
 194        *        and whether the start or ending of such a substring forms the boundary condition.
 195        * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
 196        * @param endOffset back-filled with the offset of the character immediately following the resulting
 197        *                  substring, if one exists.
 198        * @see TEXT_BOUNDARY_TYPE
 199        * @returns a string which is a substring of the text content of the object, delimited by the
 200        * specified boundary condition.
 201        */
 202     string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 203                                                         out long startOffset, out long endOffset);
 204       /**
 205        * Obtain a subset of the text content of an object which entirely follows \c offset,
 206        * delimited by character, word, line, or sentence boundaries as specified by \c type.  The
 207        * starting and ending offsets of the resulting substring are returned in \c startOffset
 208        * and \c endOffset.  By definition, if such a substring exists, \c startOffset must be greater than
 209        * \c offset.
 210        * @param offset the offset from which the substring search begins, and which must
 211        *        lie before the returned substring.
 212        * @param type the text-boundary delimiter which determines whether the returned text constitures
 213        *        a character, word, line, or sentence (and possibly attendant whitespace),
 214        *        and whether the start or ending of such a substring forms the boundary condition.
 215        * @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
 216        * @param endOffset back-filled with the offset of the character immediately following the resulting
 217        *                  substring, if one exists.
 218        * @see TEXT_BOUNDARY_TYPE
 219        * @returns a string which is a substring of the text content of the object, delimited by the
 220        * specified boundary condition.
 221        */
 222     string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
 223                                                         out long startOffset, out long endOffset);
 224       /**
 225        * @returns an unsigned long integer whose value corresponds to the UCS-4 representation of the
 226        * character at the specified text offset, or 0 if offset is out of range.
 227        */
 228     unsigned long getCharacterAtOffset (in long offset);  /* long instead of wchar,
 229                                                            * to allow unicode chars > 16 bits
 230                                                            */
 231     /**
 232      * Get the string value of a named attribute at a given offset, if defined.
 233      * @param offset the offset of the character for which the attribute run is to be obtained.
 234      * @param attributeName the name of the attribute for which the value is to be returned, if defined.
 235      * @param startOffset back-filled with the offset of the first character in the attribute run
 236      * containing the character at \c offset.
 237      * @param endOffset back-filled with the offset of the first character past the end of the
 238      * attribute run containing the character at \c offset.
 239      * @param defined back-filled with \c True if the attributeName has a defined value at \c offset,
 240      * \c False otherwise.
 241      * @returns the value of attribute (name-value pair) corresponding to "name", if defined.
 242      **/
 243     string getAttributeValue (in long offset, in string attributeName,
 244                               out long startOffset,
 245                               out long endOffset,
 246                               out boolean defined);
 247     /**
 248      * getAttributes is deprecated in favor of getAttributeRun.
 249      * @returns the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs.
 250      * @see getAttributeRun
 251      **/
 252     string getAttributes (in long offset,
 253                           out long startOffset, out long endOffset);
 254       /**
 255        * Deprecated in favor of getDefaultAttributeSet.
 256        * @returns the attributes which apply to the entire text content, but which were not explicitly
 257        * specified by the content creator.
 258        * @see getDefaultAttributeSet
 259        **/
 260     string getDefaultAttributes ();
 261       /**
 262        * Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular
 263        * character offset in this object's text content.  The coordinate system in which the results are
 264        * reported is specified by coordType.  If an onscreen glyph corresponds to multiple character offsets,
 265        * for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and
 266        * therefore may apply to more than one character offset.
 267        * @param offset the character offset of the character or glyph being queried.
 268        * @param x the minimum horizontal coordinate of the bounding box of the glyph representing
 269        *          the character at \c offset.
 270        * @param y the minimum vertical coordinate of the bounding box of the glyph representing
 271        *          the character at \c offset.
 272        * @param width the horizontal extent of the bounding box of the glyph representing
 273        *          the character at \c offset.
 274        * @param height the vertical extent of the bounding box of the glyph representing
 275        *          the character at \c offset.
 276        * @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels
 277        *                  relative to the upper-left corner of the screen, with the x axis pointing right
 278        *                  and the y axis pointing down.
 279        *                  If 1, the results will be reported relative to the containing toplevel window,
 280        *                  with the x axis pointing right and the y axis pointing down.
 281        **/
 282     void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType);
 283       /**
 284        * Get the offset of the character at a given onscreen coordinate.  The coordinate system used to interpret
 285        * x and y is determined by parameter coordType.
 286        * @param x
 287        * @param y
 288        * @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1,
 289        *                  they are relative to the toplevel window containing this Text object.
 290        * @returns the text offset (as an offset into the character array) of the glyph whose onscreen bounds contain the point x,y, or -1 if the point is outside the bounds of any glyph.
 291        **/
 292     long getOffsetAtPoint (in long x, in long y, in short coordType);
 293       /**
 294        * Obtain the number of separate, contiguous selections in the current Text object.
 295        * Text objects which do not implement selection of discontiguous text regions will always
 296        * return '0' or '1'.  Note that "contiguous" is defined by continuity of the offsets, i.e.
 297        * a text 'selection' is defined by a start/end offset pair.  In the case of bidirectional text,
 298        * this means that a continguous selection may appear visually discontiguous, and vice-versa.
 299        *
 300        * @returns the number of contiguous selections in the current Text object.
 301        **/
 302     long getNSelections ();
 303       /**
 304        * The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection
 305        * which does not exist) is not strictly defined, but should set endOffset equal to startOffset.
 306        **/
 307     void getSelection (in long selectionNum, out long startOffset, out long endOffset);
 308       /**
 309        * The result of calling addSelection on objects which already have one selection present, and which
 310        * do not include STATE_MULTISELECTABLE, is undefined, other than the return value.
 311        * @returns \c True of the selection was successfully added, \c False otherwise. Selection may
 312        * fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the
 313        * object does not support multiple selections and a selection is already defined, or for other reasons
 314        * (for instance if the user does not have permission to copy the text into the relevant selection
 315        * buffer).
 316        **/
 317     boolean addSelection (in long startOffset, in long endOffset);
 318       /**
 319        * Deselect the text contained in the specified selectionNum, if such a selection
 320        * exists, otherwise do nothing.  Removal of a non-existant selectionNum has no effect.
 321        * @returns \c True if the selection was successfully removed, \c False otherwise.
 322        **/
 323     boolean removeSelection (in long selectionNum);
 324       /**
 325        * Modify an existing selection's start or ending offset.
 326        *
 327        * Calling setSelection for a selectionNum that is not already defined has no effect.
 328        * The result of calling setSelection with a selectionNum greater than 0 for objects that
 329        * do not include STATE_MULTISELECTABLE is undefined.
 330        * @param selectionNum indicates which of a set of non-contiguous selections to modify.
 331        * @param startOffset the new starting offset for the selection
 332        * @param endOffset the new ending offset for the selection
 333        * @returns \c True if the selection corresponding to selectionNum is successfully modified,
 334        *             \c False otherwise.
 335        **/
 336     boolean setSelection (in long selectionNum, in long startOffset, in long endOffset);
 337       /**
 338        * Obtain the bounding box which entirely contains a given text range.
 339        * Negative values may be returned for the bounding box parameters in the event
 340        * that all or part of the text range is offscreen or not mapped to the screen.
 341        * @param startOffset the offset of the first character in the specified range.
 342        * @param endOffset the offset of the character immediately after the last
 343        *        character in the specified range.
 344        * @param x an integer parameter which is back-filled with the minimum
 345        *        horizontal coordinate of the resulting bounding box.
 346        * @param y an integer parameter which is back-filled with the minimum
 347        *        vertical coordinate of the resulting bounding box.
 348        * @param width an integer parameter which is back-filled with the
 349        *        horizontal extent of the bounding box.
 350        * @param height an integer parameter which is back-filled with the
 351        *        vertical extent of the bounding box.
 352        * @param coordType If 0, the above coordinates are reported in pixels relative to
 353        *        corner of the screen; if 1, the coordinates are reported relative to the
 354        *        corner of the containing toplevel window.
 355        **/
 356     void    getRangeExtents (in long startOffset, in long endOffset,
 357                              out long x, out long y,
 358                              out long width, out long height, in short coordType);
 359
 360       /**
 361        * Return the text content within a bounding box,
 362        * as a list of Range structures.
 363        * Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the
 364        * bounding box (i.e. which lie partially inside and partially outside it)
 365        * may or may not be included in the ranges returned.
 366        * @note This method may be of particular interest to screen review algorithms.
 367        * @see TEXT_CLIP_TYPE.
 368        * @param x the minimum x ( i.e. leftmost)  coordinate of the bounding box.
 369        * @param y the minimum y coordinate of the bounding box.
 370        * @param width the horizontal size of the bounding box.  The rightmost bound of the bounding box
 371        *        is (x + width);
 372        * @param height the vertical size of the bounding box.  The maximum y value of the bounding box
 373        *        is (y + height);
 374        * @param coordType If 0, the above coordinates are interpreted as pixels relative to
 375        *        corner of the screen; if 1, the coordinates are interpreted as pixels relative to the
 376        *        corner of the containing toplevel window.
 377        * @param xClipType determines whether text which intersects the bounding box in the x direction
 378        *        is included.
 379        * @param yClipType determines whether text which intersects the bounding box in the y direction
 380        *        is included.
 381        **/
 382     RangeList getBoundedRanges (in long x, in long y,
 383                                 in long width, in long height,
 384                                 in short coordType,
 385                                 in TEXT_CLIP_TYPE xClipType,
 386                                 in TEXT_CLIP_TYPE yClipType);
 387
 388     /**
 389      * Query a particular text object for the text attributes defined at a given offset,
 390      * obtaining the start and end of the "attribute run" over which these attributes are currently
 391      * invariant.  Text attributes are those presentational, typographic, or semantic attributes or
 392      * qualitites which apply to a range of text specifyable by starting and ending offsets.
 393      * Attributes relevant to localization should be provided in
 394      * accordance with the w3c "Internationalization and Localization Markup Requirements",
 395      * http://www.w3.org/TR/2005/WD-itsreq-20051122/
 396      * Other text attributes should choose their names and value semantics in accordance with relevant
 397      * standards such as CSS level 2 (http://www.w3.org/TR/1998/REC-CSS2-19980512),
 398      * XHTML 1.0 (http://www.w3.org/TR/2002/REC-xhtml1-20020801), and
 399      * WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/).  Those attributes from the aforementioned
 400      * specifications and recommendations which do not concern typographic, presentational, or
 401      * semantic aspects of text should be exposed via the more general Accessible::getAttributes() API
 402      * (if at all).
 403      *
 404      * For example, CSS attributes which should be exposed on text (either as default attributes, or
 405      * as explicitly-set attributes when non-default values are specified in the content view) include
 406      * the Font attributes (i.e. "css2:font-weight", "css2:font-style"),
 407      * the "css2:color" and "css2:background-color" attributes, and "css2:text-decoration" attribute.
 408      *
 409      * If includeDefaults is TRUE, then this AttributeSet should include the default
 410      * attributes as well as those which are explicitly assigned to the attribute run in question.
 411      * startOffset and endOffset will be back-filled to indicate the start and end of the attribute run
 412      * which contains 'offset' - an attribute run is a contiguous section of text whose attributes are
 413      * homogeneous.
 414      * @param offset the offset of the character whose attributes will be reported.
 415      * @param startOffset backfilled with the starting offset of the character range over which all
 416      *                    text attributes match those of \c offset, i.e. the start of the homogeneous
 417      *                    attribute run including \c offset.
 418      * @param endOffset backfilled with the offset of the first character past the character range over which all
 419      *                    text attributes match those of \c offset, i.e. the character immediately after
 420      *                    the homogeneous attribute run including \c offset.
 421      * @param includeDefaults if False, the call should only return those attributes which are
 422      * explicitly set on the current attribute run, omitting any attributes which are inherited from
 423      * the default values.  See also Text::getDefaultAttributes.
 424      *
 425      * @note Clients seeking annotations or properties of a more general nature, which
 426      * are not specific to the onscreen textual content of objects and cannot logically be applied
 427      * to specific character offset ranges,
 428      * should use Accessible::getAttributes instead.
 429      * The attributes returned by Text::getAttributeRun (with or without 'default attributes'),
 430      * are distinct from the properties/attributes returned by Accessible::getAttributes.
 431      *
 432      * @see Accessible::getAttributes
 433      *
 434      * @returns the AttributeSet defined at offset, optionally including the 'default' attributes.
 435      *
 436      * @since AT-SPI 1.7.0
 437      **/
 438     AttributeSet getAttributeRun (in long offset,
 439                                   out long startOffset,
 440                                   out long endOffset,
 441                                   in boolean includeDefaults);
 442       /**
 443        * Return an ::AttributeSet containing the text attributes which apply to all text in the object
 444        * by virtue of the default settings of the document, view, or user agent; e.g. those
 445        * attributes which are implied rather than explicitly applied to the text object.
 446        * For instance, an object whose entire text content has been explicitly marked as 'bold' will
 447        * report the 'bold' attribute via getAttributeRun(), whereas an object whose text weight is
 448        * inspecified may report the default or implied text weight in the default AttributeSet.
 449        *
 450        * @since AT-SPI 1.7.0
 451        **/
 452     AttributeSet getDefaultAttributeSet ();
 453
 454     /** \cond
 455      * unImplemented:
 456      *
 457      * placeholders for future expansion.
 458      */
 459     void unImplemented ();
 460     void unImplemented2 ();
 461     /** \endcond **/
 462   };
 463 };