mirror of
https://gitlab.winehq.org/wine/wine-gecko.git
synced 2024-09-13 09:24:08 -07:00
470 lines
17 KiB
Plaintext
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
|
|
);
|
|
|
|
}
|