gecko-dev/other-licenses/ia2/AccessibleText.idl

470 lines
17 KiB
Plaintext

/*************************************************************************
*
* File Name (AccessibleText.idl)
*
* IAccessible2 IDL Specification
*
* Copyright (c) IBM Corp. 2007
* Copyright (c) Sun Microsystems, Inc. 2000, 2006
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License version 2.1, as published by the Free Software Foundation; either
* version 2.1 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
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02110-1301 USA
*
************************************************************************/
import "objidl.idl";
import "oaidl.idl";
import "oleacc.idl";
import "IA2CommonTypes.idl";
/// A structure containing a substring and the start and end offsets in the enclosing string.
typedef struct {
BSTR text; ///< A copy of a segment of text taken from an enclosing paragraph.
long start; ///< Index of the first character of the segment in the enclosing text.
long end; ///< Index of the character following the last character of the segment in the enclosing text.
} IA2TextSegment;
/** @brief Defines values to specify a text boundary type.
If one of these is not implemented, such as IA2_TEXT_BOUNDARY_SENTENCE, S_FALSE is returned.
*/
enum IA2TextBoundaryType {
IA2_TEXT_BOUNDARY_CHAR, ///< =0,
IA2_TEXT_BOUNDARY_WORD, ///< Range is from start of one word to the start of another word.
IA2_TEXT_BOUNDARY_SENTENCE, ///< Range is from start of one sentence to the start of another sentence.
IA2_TEXT_BOUNDARY_PARAGRAPH, ///< Range is from start of one paragraph to the start of another paragraph.
IA2_TEXT_BOUNDARY_LINE, /**< Range is from start of one line to the start of another line. This
often means that an end-of-line character will appear at the end of
the range. However in the case of some apps an end-of-line character
indicates the end of a paragraph and the lines composing the paragraph,
other than the last line, do not contain an end of line character. */
IA2_TEXT_BOUNDARY_ALL ///< Using this value will cause all text to be returned.
};
/** @brief This interface gives read-only access to text.
The IAccessibleText interface should be implemented by all components
that present textual information on the display like buttons,
text entry fields, or text portions of the document window. The interface
provides access to the text's content, attributes, and spatial location.
However, text can not be modified with this interface. That is the task
of the IAccessibleEditableText interface.
The text length, i.e. the number of characters in the text, is
returned by IAccessibleText::nCharacters. All methods that operate
on particular characters (e.g. IAccessibleText::textAtOffset) use character
indices from 0 to length-1. All methods that operate on character positions
(e.g. IAccessibleText::text) use indices from 0 to length.
Please note that accessible text does not necessarily support selection.
In this case it should behave as if there where no selection. An empty
selection is used for example to express the current cursor position.
*/
[object, uuid(24FD2FFB-3AAD-4a08-8335-A3AD89C0FB4B)]
interface IAccessibleText : IUnknown
{
/** @brief Adds a text selection
@param [in] startOffset
Starting offset ( 0-based).
@param [in] endOffset
Offset of first character after new selection (0-based).
*/
HRESULT addSelection
(
[in] long startOffset,
[in] long endOffset
);
/** @brief Returns text attributes.
@param [in] offset
Text offset (0-based).
@param [out] startOffset
Start of requested text range (0-based)
@param [out] endOffset
First character after requested text range (0-based)
@param [out] textAttributes
A string of attributes describing the text.
*/
[propget] HRESULT attributes
(
[in] long offset,
[out] long *startOffset,
[out] long *endOffset,
[out, retval] BSTR *textAttributes
);
/** @brief Returns the position of the caret.
The caret is the position between two characters. Its position/offset
is that of the character to the right of it.
@param [out] offset
The returned offset is relative to the text represented by this object.
*/
[propget] HRESULT caretOffset
(
[out, retval] long *offset
);
/** @brief Returns the bounding box of the specified position.
The virtual character after the last character of the represented
text, i.e. the one at position length is a special case. It represents the
current input position and will therefore typically be queried by AT more
often than other positions. Because it does not represent an existing character
its bounding box is defined in relation to preceding characters. It should be
roughly equivalent to the bounding box of some character when inserted at the
end of the text. Its height typically being the maximal height of all the
characters in the text or the height of the preceding character, its width being
at least one pixel so that the bounding box is not degenerate.
Note that the index 'length' is not always valid. Whether it is or not is
implementation dependent. It typically is when text is editable or otherwise
when on the screen the caret can be placed behind the text. You can be sure
that the index is valid after you have received a ::IA2_EVENT_TEXT_CARET_MOVED
event for this index.
@param [in] offset
Index of the character for which to return its bounding box. The valid range
is 0..length.
@param [in] coordType
Specifies if the coordinates are relative to the screen or to the parent window.
@param [out] x
X coordinate of the bounding box of the referenced character.
@param [out] y
Y coordinate of the bounding box of the referenced character.
@param [out] width
Width of the bounding box of the referenced character.
@param [out] height
Height of the bounding box of the referenced character.
*/
[propget] HRESULT characterExtents
(
[in] long offset,
[in] enum IA2CoordinateType coordType,
[out] long *x,
[out] long *y,
[out] long *width,
[out, retval] long *height
);
/** @brief Returns the number of active non-contiguous selections
@param [out] nSelections
*/
[propget] HRESULT nSelections
(
[out, retval] long *nSelections
);
/** @brief Returns the text position for the specified screen position.
Given a point return the zero-based index of the character under that
point. The same functionality could be achieved by using the bounding
boxes for each character as returned by IAccessibleText::characterExtents.
The method IAccessibleText::offsetAtPoint, however, can be implemented
more efficiently.
@param [in] x
The position's x value for which to look up the index of the character that
is rendered on to the display at that point.
@param [in] y
The position's y value for which to look up the index of the character that
is rendered on to the display at that point.
@param [in] coordType
Screen coordinates or window coordinates.
@param [out] offset
Index of the character under the given point or -1 if the point
is invalid or there is no character under the point.
*/
[propget] HRESULT offsetAtPoint
(
[in] long x,
[in] long y,
[in] enum IA2CoordinateType coordType,
[out, retval] long *offset
);
/** @brief Returns the character offsets of N-th active text selection
@param [in] selectionIndex
Index of selection (0-based).
@param [out] startOffset
0 based offset of first selected character
@param [out] endOffset
0 based offset of one past the last selected character.
*/
[propget] HRESULT selection
(
[in] long selectionIndex, ///< index of selection (0-based)
[out] long *startOffset,
[out, retval] long *endOffset
);
/** @brief Returns the substring between the two given indices.
The substring starts with the character at startOffset (inclusive) and up to
the character at endOffset (exclusive), if startOffset is less or equal
endOffste. If endOffset is lower than startOffset, the result is the same
as a call with the two arguments being exchanged.
The whole text can be requested by passing the indices zero and
IAccessibleText::nCharacters. If both indices have the same value, an empty
string is returned.
@param [in] startOffset
Index of the first character to include in the returned string. The valid range
is 0..length.
@param [in] endOffset
Index of the last character to exclude in the returned string. The valid range
is 0..length.
@param [out] text
Returns the substring starting with the character at startOffset (inclusive)
and up to the character at endOffset (exclusive), if startOffset is less than
or equal to endOffset.
Note: returned string may be longer than endOffset-startOffset bytes if text
contains multi-byte characters.
*/
[propget] HRESULT text
(
[in] long startOffset,
[in] long endOffset,
[out, retval] BSTR *text
);
/** @brief Returns a text portion before the given position.
Returns the substring of the specified text type that is located before the
given character and does not include it. The result of this method should be
same as a result for IAccessibleText::textAtOffset with a suitably decreased
index value.
For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
word that is closest to and located before offset is returned.
If the index is valid, but no suitable word (or other text type) is found, an
empty text segment is returned.
@param [in] offset
Index of the character for which to return the text part before it. The index
character will not be part of the returned string. The valid range is 0..length.
@param [in] boundaryType
The type of the text portion to return. See ::IA2TextBoundaryType for the
complete list.
@param [out] startOffset
0 based offset of first character.
@param [out] endOffset
0 based offset of one past the last character.
@param [out] text
Returns the requested text portion. This portion may be empty or invalid when
no appropriate text portion is found or text type is invalid.
*/
[propget] HRESULT textBeforeOffset
(
[in] long offset,
[in] enum IA2TextBoundaryType boundaryType,
[out] long *startOffset,
[out] long *endOffset,
[out, retval] BSTR *text
);
/** @brief Returns a text portion after the given position.
Returns the substring of the specified text type that is located after the
given character and does not include it. The result of this method should be
same as a result for IAccessibleText::textAtOffset with a suitably decreased
index value.
For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
word that is closest to and located before offset is returned.
If the index is valid, but no suitable word (or other text type) is found, an
empty text segment is returned.
@param [in] offset
Index of the character for which to return the text part before it. The index
character will not be part of the returned string. The valid range is 0..length.
@param [in] boundaryType
The type of the text portion to return. See ::IA2TextBoundaryType for the complete
list.
@param [out] startOffset
0 based offset of first character.
@param [out] endOffset
0 based offset of one past the last character.
@param [out] text
Returns the requested text portion. This portion may be empty or invalid when
no appropriate text portion is found or text type is invalid.
*/
[propget] HRESULT textAfterOffset
(
[in] long offset,
[in] enum IA2TextBoundaryType boundaryType,
[out] long *startOffset,
[out] long *endOffset,
[out, retval] BSTR *text
);
/** @brief Returns a text portion that spans the given position.
Returns the substring of the specified text type that the specified offset. The
result of this method should be same as a result for
IAccessibleText::textAtOffset with a suitably decreased index value.
For example, if text type is ::IA2_TEXT_BOUNDARY_WORD, then the complete
word that is closest to and located before offset is returned.
If the index is valid, but no suitable word (or other text type) is found, an
empty text segment is returned.
@param [in] offset
Index of the character for which to return the text part before it. The index
character will not be part of the returned string. The valid range is 0..length.
@param [in] boundaryType
The type of the text portion to return. See ::IA2TextBoundaryType for the complete
list.
@param [out] startOffset
0 based offset of first character.
@param [out] endOffset
0 based offset of one past the last character.
@param [out] text
Returns the requested text portion. This portion may be empty or invalid when
no appropriate text portion is found or text type is invalid.
*/
[propget] HRESULT textAtOffset
(
[in] long offset,
[in] enum IA2TextBoundaryType boundaryType,
[out] long *startOffset,
[out] long *endOffset,
[out, retval] BSTR *text
);
/** @brief Unselects a range of text.
@param [in] selectionIndex
Index of selection to remove (0-based).
*/
HRESULT removeSelection
(
[in] long selectionIndex
);
/** @brief Sets the position of the caret.
The caret is the position between two characters. Its position/offset
is that of the character to the right of it.
Setting the caret position may or may not alter the current selection. A
change of the selection is notified to the accessibility event listeners with
an ::IA2_EVENT_TEXT_SELECTION_CHANGED event.
When the new caret position differs from the old one (which, of course, is the
standard case) this is notified to the accessibility event listeners with an
::IA2_EVENT_TEXT_CARET_MOVED event.
@param [in] offset
The new index of the caret. This caret is actually placed to the left side of
the character with that index. An index of 0 places the caret so that the next
insertion goes before the first character. An index of IAccessibleText::nCharacters
leads to insertion after the last character.
*/
HRESULT setCaretOffset
(
[in] long offset
);
/** @brief Changes the bounds of an existing selection.
@param [in] selectionIndex
Index of selection to change (0-based)
@param [in] startOffset
New starting offset (0-based)
@param [in] endOffset
New ending offset (0-based) - the offset of the character just past the last character of the selection.
*/
HRESULT setSelection
(
[in] long selectionIndex,
[in] long startOffset,
[in] long endOffset
);
/** @brief Returns total number of characters.
Note: This may be different than the total number of bytes required to store the
text, if the text contains multi-byte characters.
@param [out] nCharacters
*/
[propget] HRESULT nCharacters
(
[out, retval] long *nCharacters
);
/** @brief Makes a specific part of string visible on screen.
@param [in] startIndex
0-based character offset.
@param [in] endIndex
0-based character offset - the offset of the character just past the last character of the string.
@param [in] scrollType
Defines where the object should be placed on the screen.
*/
HRESULT scrollSubstringTo
(
[in] long startIndex,
[in] long endIndex,
[in] enum IA2ScrollType scrollType
);
/** @brief Moves the top left of a substring to a specified location.
Note: S_FALSE is returned if the object is already at the specified location.
@param [in] startIndex
0-based character offset.
@param [in] endIndex
0-based character offset - the offset of the character just past the last character of the string.
@param [in] coordinateType
Specifies whether the coordinates are relative to the screen or the parent object.
@param [in] x
Defines the x coordinate.
@param [in] y
Defines the y coordinate.
*/
HRESULT scrollSubstringToPoint
(
[in] long startIndex,
[in] long endIndex,
[in] enum IA2CoordinateType coordinateType,
[in] long x,
[in] long y
);
/** @brief Returns any inserted text.
Provided for use by the ::IA2_EVENT_TEXT_INSERTED and ::IA2_EVENT_TEXT_UPDATED
event handlers.
@param [out] newText
The text that was just inserted.
*/
[propget] HRESULT newText
(
[out, retval] IA2TextSegment *newText
);
/** @brief Returns any removed text.
Provided for use by the IA2_EVENT_TEXT_REMOVED/UPDATED event handlers.
@param [out] oldText
The text that was just removed.
*/
[propget] HRESULT oldText
(
[out, retval] IA2TextSegment *oldText
);
}