* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Library General Public
* License as published by the Free Software Foundation; either
* version 2 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Library General Public License for more details.
*
* You should have received a copy of the GNU Library General Public
* License along with this library; if not, write to the
* Free Software Foundation, Inc., 59 Temple Place - Suite 330,
* Boston, MA 02111-1307, USA.
*/
module Accessibility {
/**
* Specifies the boundary conditions determining a run of text as returned from
* getTextAtOffset, getTextAfterOffset, and getTextBeforeOffset.
*/
enum TEXT_BOUNDARY_TYPE {
TEXT_BOUNDARY_CHAR,/**< Text is bounded by this character only.
* Start and end offsets differ by one, by definition, for this value.
*/
TEXT_BOUNDARY_WORD_START,/**< Boundary condition is start of a word; i.e. range is from start of
* one word to the start of another word.
*/
TEXT_BOUNDARY_WORD_END,/**< Boundary condition is the end of a word; i.e. range is from
* the end of one word to the end of another.
* @note some locales may not distinguish between words and
* characters or glyphs, in particular those locales which use
* wholly or partially ideographic character sets. In these cases,
* characters may be returned in lieu of multi-character substrings.
*/
TEXT_BOUNDARY_SENTENCE_START,/**< Boundary condition is start of a sentence, as determined
* by the application.
* @note Some locales or character sets may not include explicit sentence
* delimiters, so this boundary type can not always be honored.
* Some locales will return lines of text instead of grammatical sentences.
*/
TEXT_BOUNDARY_SENTENCE_END,/**< Boundary condition is end of a sentence, as determined by the application,
* including the sentence-delimiting character, for instance '.'
* @note Some locales or character sets may not include explicit sentence
* delimiters, so this boundary type can not always be honored.
* Some locales will return lines of text instead of grammatical sentences.
*/
TEXT_BOUNDARY_LINE_START,/**< Boundary condition is the start of a line; i.e. range is
* from start of one line to the start of another. This generally
* means that an end-of-line character will appear at the end of the range.
*/
TEXT_BOUNDARY_LINE_END /**< Boundary condition is the end of a line; i.e. range is
* from start of one line to the start of another. This generally
* means that an end-of-line character will be the first character of the range.
*/
};
/**
* TEXT_CLIP_TYPE:
* CLIP_MIN means text clipped by min coordinate is omitted,
* CLIP_MAX clips text interescted by the max coord, and CLIP_BOTH
* will retain only text falling fully within the min/max bounds.
*
**/
enum TEXT_CLIP_TYPE {
TEXT_CLIP_NONE,
TEXT_CLIP_MIN,/**< characters/glyphs clipped by the minimum coordinate are omitted */
TEXT_CLIP_MAX,/**< characters/glyphs which intersect the maximum coordinate are omitted */
TEXT_CLIP_BOTH /**< only glyphs falling entirely within the region bounded by min and max are retained. */
};
/**
* The text interface should be implemented by objects which place textual information onscreen as character
* strings or glyphs. The text interface allows access to textual content, including display attributes and
* semantic hints associated with runs of text, and access to bounding box information for glyphs and substrings.
* It also allows portions of textual content to be selected, if the object's StateSet includes
* STATE_SELECTABLE_TEXT.
*
* In some cases a Text object may have, as its content, an empty string. In particular this can
* occur in the case of Hypertext objects which do not display explicitly textual information onscreen,
* as Hypertext is derived from the Text interface. @see Hypertext.
*
* Typographic and semantic attributes of onscreen textual content, for instance typeface, weight,
* language, and such qualities as 'emphasis' or 'blockquote', are represented as text attributes.
* Contiguous sequences of characters over which these attributes are unchanged are referred to as
* "attribute runs", and are available via Text::getAttributeRun. Where possible, implementing clients
* will report textual attributes which are the same over the entire text object, for instance those
* inherited from a default or document-scope style, via getDefaultAttributes instead of reporting them
* explicitly for each character. Therefore, for any span of text, the attributes in effect are the union
* of the set returned by Text::getDefaultAttributes, and the set returned at a particular character
* offset via Text::getAttributeRun.
*
* @note Events that may be emitted by instances of Text include:
* \li \c "object:text-attributes-changed" The attributes of a range of text, or the range over
* which attributes apply, has changed.
* \li \c "object:text-changed" The text content of this object has changed.
* \li \c "object:text-bounds-changed" The character bounds of a text object have changed,
* for instance in response to a reformatting or reflow operation.
* \li \c "object:text-caret-moved" The character offset of the text caret (visible or notional) within
* this object has changed. Events of this type may also be generated when an onscreen
* text caret appears or disappears.
* \li \c "object:text-selection-changed" The range or number of text selections within this text object
* has changed.
*
* @note In some cases, objects which are not onscreen may implement Text, but if such objects
* implement Component, their potential visibility should be examined (via comparison with STATE_VISIBLE
* and STATE_SHOWING) before exposing them to the user. Objects which implement Text but not Component
* may be encountered in special-purpose interfaces or as special ¨accessibility¨ extensions to visual
* interfaces to allow non-graphical access to application features. These instances should be considered
* the exception, rather than the rule.
*/
interface Text : Bonobo::Unknown {
/** A structure used to define a continguous range of text, including its
* (unattributed) textual content.
**/
struct Range {
long startOffset;
long endOffset;
string content;
any data;
};
typedef sequence<Range> RangeList;
/** The total current number of characters in the Text object,
* including whitespace and non-spacing characters.
**/
readonly attribute long characterCount;
/** The current offset of the text caret in the Text object.
* This caret may be virtual, e.g. non-visual and notional-only, but if an
* onscreen representation of the caret position is visible, it will correspond to this offset.
* The caret offset is given as a character offset, as opposed to a byte offset into
* a text buffer or a column offset.
**/
readonly attribute long caretOffset;
/**
* Obtain all or part of the onscreen textual content of a Text object. If endOffset is specified as
* "-1", then this method will return the entire onscreen textual contents of the Text object.
* @note 'onscreen' in this context means "potentially onscreen", this method does not perform any sort
* of coordinate visibility clipping or window-stack-ordering clipping. The text thus reported
* corresponds to the text which would be presented onscreen if the object implementing the Text interface
* were entirely unobscured.
* @returns the textual content of the current Text object beginning startOffset (inclusive)
* up to but not including the character at endOffset.
**/
string getText (in long startOffset, in long endOffset);
/** Programmatically move the text caret (visible or virtual, as above) to a given position.
* @param offset a long int indicating the desired character offset. Not all implementations of
* Text will honor setCaretOffset requests, so the return value below should be checked by the client.
* @returns \c TRUE if the request was carried out, or \c FALSE if the caret could not be moved to
* the requested position.
**/
boolean setCaretOffset (in long offset);
/**
* Obtain a subset of the text content of an object which entirely precedes \c offset,
* delimited by character, word, line, or sentence boundaries as specified by \c type. The
* starting and ending offsets of the resulting substring are returned in \c startOffset
* and \c endOffset. By definition, if such a substring exists, \c endOffset is less than or
* equal to \c offset.
* @param offset the offset from which the substring search begins.
* @param type the text-boundary delimiter which determines whether the returned text constitures
* a character, word, line, or sentence (and possibly attendant whitespace),
* and whether the start or ending of such a substring forms the boundary condition.
* @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
* @param endOffset back-filled with the offset of the character immediately following the resulting
* substring, if one exists.
* @see TEXT_BOUNDARY_TYPE
* @returns a string which is a substring of the text content of the object, delimited by the
* specified boundary condition.
*/
string getTextBeforeOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
/**
* Obtain a subset of the text content of an object which includes the specified \c offset,
* delimited by character, word, line, or sentence boundaries as specified by \c type. The
* starting and ending offsets of the resulting substring are returned in \c startOffset
* and \c endOffset.
* @param offset the offset from which the substring search begins, and which must
* lie within the returned substring.
* @param type the text-boundary delimiter which determines whether the returned text constitures
* a character, word, line, or sentence (and possibly attendant whitespace),
* and whether the start or ending of such a substring forms the boundary condition.
* @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
* @param endOffset back-filled with the offset of the character immediately following the resulting
* substring, if one exists.
* @see TEXT_BOUNDARY_TYPE
* @returns a string which is a substring of the text content of the object, delimited by the
* specified boundary condition.
*/
string getTextAtOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
/**
* Obtain a subset of the text content of an object which entirely follows \c offset,
* delimited by character, word, line, or sentence boundaries as specified by \c type. The
* starting and ending offsets of the resulting substring are returned in \c startOffset
* and \c endOffset. By definition, if such a substring exists, \c startOffset must be greater than
* \c offset.
* @param offset the offset from which the substring search begins, and which must
* lie before the returned substring.
* @param type the text-boundary delimiter which determines whether the returned text constitures
* a character, word, line, or sentence (and possibly attendant whitespace),
* and whether the start or ending of such a substring forms the boundary condition.
* @param startOffset back-filled with the starting offset of the resulting substring, if one exists.
* @param endOffset back-filled with the offset of the character immediately following the resulting
* substring, if one exists.
* @see TEXT_BOUNDARY_TYPE
* @returns a string which is a substring of the text content of the object, delimited by the
* specified boundary condition.
*/
string getTextAfterOffset (in long offset, in TEXT_BOUNDARY_TYPE type,
out long startOffset, out long endOffset);
/**
* @returns an unsigned long integer whose value corresponds to the UCS-4 representation of the
* character at the specified text offset, or 0 if offset is out of range.
*/
unsigned long getCharacterAtOffset (in long offset); /* long instead of wchar,
* to allow unicode chars > 16 bits
*/
/**
* Get the string value of a named attribute at a given offset, if defined.
* @param offset the offset of the character for which the attribute run is to be obtained.
* @param attributeName the name of the attribute for which the value is to be returned, if defined.
* @param startOffset back-filled with the offset of the first character in the attribute run
* containing the character at \c offset.
* @param endOffset back-filled with the offset of the first character past the end of the
* attribute run containing the character at \c offset.
* @param defined back-filled with \c True if the attributeName has a defined value at \c offset,
* \c False otherwise.
* @returns the value of attribute (name-value pair) corresponding to "name", if defined.
**/
string getAttributeValue (in long offset, in string attributeName,
out long startOffset,
out long endOffset,
out boolean defined);
/**
* getAttributes is deprecated in favor of getAttributeRun.
* @returns the attributes at offset, as a semicolon-delimited set of colon-delimited name-value pairs.
* @see getAttributeRun
**/
string getAttributes (in long offset,
out long startOffset, out long endOffset);
/**
* Deprecated in favor of getDefaultAttributeSet.
* @returns the attributes which apply to the entire text content, but which were not explicitly
* specified by the content creator.
* @see getDefaultAttributeSet
**/
string getDefaultAttributes ();
/**
* Obtain a the bounding box, as x, y, width, and height, of the character or glyph at a particular
* character offset in this object's text content. The coordinate system in which the results are
* reported is specified by coordType. If an onscreen glyph corresponds to multiple character offsets,
* for instance if the glyph is a ligature, the bounding box reported will include the entire glyph and
* therefore may apply to more than one character offset.
* @param offset the character offset of the character or glyph being queried.
* @param x the minimum horizontal coordinate of the bounding box of the glyph representing
* the character at \c offset.
* @param y the minimum vertical coordinate of the bounding box of the glyph representing
* the character at \c offset.
* @param width the horizontal extent of the bounding box of the glyph representing
* the character at \c offset.
* @param height the vertical extent of the bounding box of the glyph representing
* the character at \c offset.
* @param coordType If 0, the results will be reported in screen coordinates, i.e. in pixels
* relative to the upper-left corner of the screen, with the x axis pointing right
* and the y axis pointing down.
* If 1, the results will be reported relative to the containing toplevel window,
* with the x axis pointing right and the y axis pointing down.
**/
void getCharacterExtents (in long offset, out long x, out long y, out long width, out long height, in short coordType);
/**
* Get the offset of the character at a given onscreen coordinate. The coordinate system used to interpret
* x and y is determined by parameter coordType.
* @param x
* @param y
* @param coordType if 0, the input coordinates are interpreted relative to the entire screen, if 1,
* they are relative to the toplevel window containing this Text object.
* @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.
**/
long getOffsetAtPoint (in long x, in long y, in short coordType);
/**
* Obtain the number of separate, contiguous selections in the current Text object.
* Text objects which do not implement selection of discontiguous text regions will always
* return '0' or '1'. Note that "contiguous" is defined by continuity of the offsets, i.e.
* a text 'selection' is defined by a start/end offset pair. In the case of bidirectional text,
* this means that a continguous selection may appear visually discontiguous, and vice-versa.
*
* @returns the number of contiguous selections in the current Text object.
**/
long getNSelections ();
/**
* The result of calling getSelection with an out-of-range selectionNum (i.e. for a selection
* which does not exist) is not strictly defined, but should set endOffset equal to startOffset.
**/
void getSelection (in long selectionNum, out long startOffset, out long endOffset);
/**
* The result of calling addSelection on objects which already have one selection present, and which
* do not include STATE_MULTISELECTABLE, is undefined, other than the return value.
* @returns \c True of the selection was successfully added, \c False otherwise. Selection may
* fail if the object does not support selection of text (see STATE_SELECTABLE_TEXT), if the
* object does not support multiple selections and a selection is already defined, or for other reasons
* (for instance if the user does not have permission to copy the text into the relevant selection
* buffer).
**/
boolean addSelection (in long startOffset, in long endOffset);
/**
* Deselect the text contained in the specified selectionNum, if such a selection
* exists, otherwise do nothing. Removal of a non-existant selectionNum has no effect.
* @returns \c True if the selection was successfully removed, \c False otherwise.
**/
boolean removeSelection (in long selectionNum);
/**
* Modify an existing selection's start or ending offset.
*
* Calling setSelection for a selectionNum that is not already defined has no effect.
* The result of calling setSelection with a selectionNum greater than 0 for objects that
* do not include STATE_MULTISELECTABLE is undefined.
* @param selectionNum indicates which of a set of non-contiguous selections to modify.
* @param startOffset the new starting offset for the selection
* @param endOffset the new ending offset for the selection
* @returns \c True if the selection corresponding to selectionNum is successfully modified,
* \c False otherwise.
**/
boolean setSelection (in long selectionNum, in long startOffset, in long endOffset);
/**
* Obtain the bounding box which entirely contains a given text range.
* Negative values may be returned for the bounding box parameters in the event
* that all or part of the text range is offscreen or not mapped to the screen.
* @param startOffset the offset of the first character in the specified range.
* @param endOffset the offset of the character immediately after the last
* character in the specified range.
* @param x an integer parameter which is back-filled with the minimum
* horizontal coordinate of the resulting bounding box.
* @param y an integer parameter which is back-filled with the minimum
* vertical coordinate of the resulting bounding box.
* @param width an integer parameter which is back-filled with the
* horizontal extent of the bounding box.
* @param height an integer parameter which is back-filled with the
* vertical extent of the bounding box.
* @param coordType If 0, the above coordinates are reported in pixels relative to
* corner of the screen; if 1, the coordinates are reported relative to the
* corner of the containing toplevel window.
**/
void getRangeExtents (in long startOffset, in long endOffset,
out long x, out long y,
out long width, out long height, in short coordType);
/**
* Return the text content within a bounding box,
* as a list of Range structures.
* Depending on the TEXT_CLIP_TYPE parameters, glyphs which are clipped by the
* bounding box (i.e. which lie partially inside and partially outside it)
* may or may not be included in the ranges returned.
* @note This method may be of particular interest to screen review algorithms.
* @see TEXT_CLIP_TYPE.
* @param x the minimum x ( i.e. leftmost) coordinate of the bounding box.
* @param y the minimum y coordinate of the bounding box.
* @param width the horizontal size of the bounding box. The rightmost bound of the bounding box
* is (x + width);
* @param height the vertical size of the bounding box. The maximum y value of the bounding box
* is (y + height);
* @param coordType If 0, the above coordinates are interpreted as pixels relative to
* corner of the screen; if 1, the coordinates are interpreted as pixels relative to the
* corner of the containing toplevel window.
* @param xClipType determines whether text which intersects the bounding box in the x direction
* is included.
* @param yClipType determines whether text which intersects the bounding box in the y direction
* is included.
**/
RangeList getBoundedRanges (in long x, in long y,
in long width, in long height,
in short coordType,
in TEXT_CLIP_TYPE xClipType,
in TEXT_CLIP_TYPE yClipType);
/**
* Query a particular text object for the text attributes defined at a given offset,
* obtaining the start and end of the "attribute run" over which these attributes are currently
* invariant. Text attributes are those presentational, typographic, or semantic attributes or
* qualitites which apply to a range of text specifyable by starting and ending offsets.
* Attributes relevant to localization should be provided in
* accordance with the w3c "Internationalization and Localization Markup Requirements",
* http://www.w3.org/TR/2005/WD-itsreq-20051122/
* Other text attributes should choose their names and value semantics in accordance with relevant
* standards such as CSS level 2 (http://www.w3.org/TR/1998/REC-CSS2-19980512),
* XHTML 1.0 (http://www.w3.org/TR/2002/REC-xhtml1-20020801), and
* WICD (http://www.w3.org/TR/2005/WD-WICD-20051121/). Those attributes from the aforementioned
* specifications and recommendations which do not concern typographic, presentational, or
* semantic aspects of text should be exposed via the more general Accessible::getAttributes() API
* (if at all).
*
* For example, CSS attributes which should be exposed on text (either as default attributes, or
* as explicitly-set attributes when non-default values are specified in the content view) include
* the Font attributes (i.e. "css2:font-weight", "css2:font-style"),
* the "css2:color" and "css2:background-color" attributes, and "css2:text-decoration" attribute.
*
* If includeDefaults is TRUE, then this AttributeSet should include the default
* attributes as well as those which are explicitly assigned to the attribute run in question.
* startOffset and endOffset will be back-filled to indicate the start and end of the attribute run
* which contains 'offset' - an attribute run is a contiguous section of text whose attributes are
* homogeneous.
* @param offset the offset of the character whose attributes will be reported.
* @param startOffset backfilled with the starting offset of the character range over which all
* text attributes match those of \c offset, i.e. the start of the homogeneous
* attribute run including \c offset.
* @param endOffset backfilled with the offset of the first character past the character range over which all
* text attributes match those of \c offset, i.e. the character immediately after
* the homogeneous attribute run including \c offset.
* @param includeDefaults if False, the call should only return those attributes which are
* explicitly set on the current attribute run, omitting any attributes which are inherited from
* the default values. See also Text::getDefaultAttributes.
*
* @note Clients seeking annotations or properties of a more general nature, which
* are not specific to the onscreen textual content of objects and cannot logically be applied
* to specific character offset ranges,
* should use Accessible::getAttributes instead.
* The attributes returned by Text::getAttributeRun (with or without 'default attributes'),
* are distinct from the properties/attributes returned by Accessible::getAttributes.
*
* @see Accessible::getAttributes
*
* @returns the AttributeSet defined at offset, optionally including the 'default' attributes.
*
* @since AT-SPI 1.7.0
**/
AttributeSet getAttributeRun (in long offset,
out long startOffset,
out long endOffset,
in boolean includeDefaults);
/**
* Return an ::AttributeSet containing the text attributes which apply to all text in the object
* by virtue of the default settings of the document, view, or user agent; e.g. those
* attributes which are implied rather than explicitly applied to the text object.
* For instance, an object whose entire text content has been explicitly marked as 'bold' will
* report the 'bold' attribute via getAttributeRun(), whereas an object whose text weight is
* inspecified may report the default or implied text weight in the default AttributeSet.
