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_BOUNDARY_WORD_START,
- TEXT_BOUNDARY_WORD_END,
- TEXT_BOUNDARY_SENTENCE_START,
- TEXT_BOUNDARY_SENTENCE_END,
- TEXT_BOUNDARY_LINE_START,
- TEXT_BOUNDARY_LINE_END
+ 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);
- void getCharacterExtents (in long offset, out long x, out long y, out long length, out long width, in short coordType);
+ /**
+ * 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.
+ *
+ * @since AT-SPI 1.7.0
+ **/
+ AttributeSet getDefaultAttributeSet ();
+
+ /** \cond
* unImplemented:
*
* placeholders for future expansion.
*/
void unImplemented ();
void unImplemented2 ();
- void unImplemented3 ();
- void unImplemented4 ();
- void unImplemented7 ();
- void unImplemented8 ();
+ /** \endcond **/
};
};
projects / platform / core / uifw / at-spi2-atk.git / blobdiff