Skip to content

Commit

Permalink
Version 1.2.1 (2011-01-21).
Browse files Browse the repository at this point in the history
  • Loading branch information
@jcsteh
jcsteh committed May 10, 2011
1 parent 710b268 commit 51ad09d
Show file tree
Hide file tree
Showing 18 changed files with 327 additions and 113 deletions.
70 changes: 39 additions & 31 deletions api/Accessible2.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,7 @@
IAccessibleHyperlink\n
IAccessibleImage\n
IAccessibleRelation\n
IAccessibleTable [deprecated]\n
IAccessibleTable [Deprecated]\n
IAccessibleTable2\n
IAccessibleTableCell\n
IAccessibleText\n
Expand Down Expand Up @@ -196,19 +196,20 @@
String: What are the rules for BSTR allocation and deallocation?</a>

@subsection _arrayConsideration Special Consideration when using Arrays
There are several methods which return arrays. It is considered a best practice
for the client to allocate and free the arrays. This can be done for
IAccessible2::relations and IAccessibleRelation::targets. However, due to the
coding of the IDL for the remaining methods which return arrays, the server must
allocate the array and the client must free the array when no longer needed.
These methods are IAccessible2::extendedStates, IAccessible2::localizedExtendedStates,
IAccessibleAction::keyBinding, IAccessibleTable::selectedChildren,
IAccessibleTable::selectedColumns, and IAccessibleTable::selectedRows. For those
methods, the server must allocate both the top level array and any storage
associated with it, e.g. for BSTRs. The client must use CoTaskMemFree to free
the array and any BSTRs must be freed with SysFreeString.
There are several methods which return arrays. In the case of IAccessible2::relations
and IAccessibleRelation::targets the client must allocate and free the arrays.

For the remaining methods which return arrays, the server must allocate the array
and the client must free the array when no longer needed. These methods are
IAccessible2::extendedStates, IAccessible2::localizedExtendedStates,
IAccessibleAction::keyBinding, IAccessibleTable2::selectedCells,
IAccessibleTable2::selectedColumns, and IAccessibleTable2::selectedRows. For
those methods, the server must allocate both the top level array and any storage
associated with it, e.g. for BSTRs. The server must allocate the arrays with
CoTaskMemAlloc and any BSTRs with SysAllocString. The client must use CoTaskMemFree
to free the array and any BSTRs must be freed with SysFreeString.

Also, the IDL for those methods includes an extraneous [in] parameter for the
Also, the IDL for those six methods includes an extraneous [in] parameter for the
caller to specify the max size of the array. This parameter will be ignored by
the COM server.

Expand Down Expand Up @@ -255,13 +256,11 @@
}
@endcode

@section _changingInterfaces Changing between Accessible Interfaces
Note that developers must always implement MSAA's IAccessible and, if needed, some
of the interfaces in the set of IAccessible2 interfaces. Although the IAccessible2
IDL is currently coded such that IAccessible2 is a subclass of MSAA's IAccessible,
none of MSAA's IAccessible methods are overridden or extended. In order to allow
future removal of the inheritance, Assistive Technologies (ATs) should not rely on
that inheritance.
@section _changingInterfaces Changing between Accessible Interfaces
Note that developers must always implement MSAA's IAccessible and, if needed, some
of the interfaces in the set of IAccessible2 interfaces. Although the IAccessible2
IDL is coded such that IAccessible2 is a subclass of MSAA's IAccessible, none of
MSAA's IAccessible methods are redefined by IAccessible2.

QueryService must be used to switch from a reference to an MSAA IAccessible interface
to another interface. This has been
Expand Down Expand Up @@ -356,13 +355,15 @@ typedef struct IA2Locale {
BSTR variant; ///< Application specific variant of the locale
} IA2Locale;

/** This interface must always be provided for objects that support some
/** @brief This interface exposes the primary set of information about an
IAccessible2 enabled accessible object.

This interface must always be provided for objects that support some
portion of the collection of the %IAccessible2 interfaces.

Please refer to @ref _changingInterfaces "Changing between Accessible Interfaces"
for special considerations related to use of the MSAA IAccessible interface and
the set of %IAccessible2 interfaces.

*/
[object, uuid(E89F726E-C4F4-4c19-BB19-B647D7FA8478)]
interface IAccessible2 : IAccessible
Expand All @@ -382,7 +383,7 @@ interface IAccessible2 : IAccessible
0 based
@param [out] relation
@retval S_OK
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT relation
(
Expand Down Expand Up @@ -470,16 +471,19 @@ interface IAccessible2 : IAccessible
1 based, 0 indicates that this value is not applicable
@param [out] positionInGroup
1 based, 0 indicates that this value is not applicable. This is an index
into the objects in the current group, not an index into all the objects
at the same group level.
into the objects in the current group, not an index into all the objects
at the same group level.
@retval S_OK if at least one value is valid
@retval S_FALSE if no values are valid
@retval S_FALSE if no values are valid, [out] values are 0s
@note This method is meant to describe the nature of an object's containment
structure. This is normally not implemented on a combo box to describe the nature
structure. It's exposed by trees, tree grids, nested lists, nested menus,
but not headings, which uses the level object attribute. It is also exposed
by radio buttons (with groupLevel == 0).
@note This is normally not implemented on a combo box to describe the nature
of its contents. Normally an AT will get that information from its child list
object. However, in some cases when combo boxes are not able to be structured
such that the list is a child of the combo box, this method is implemented
on the combo box itself. ATs can use this interface if a child list is not found.
object. However, in some cases when non-edit combo boxes are not able to be structured
such that the list is a child of the combo box, this method is implemented on
the combo box itself. ATs can use this interface if a child list is not found.
*/
[propget] HRESULT groupPosition
(
Expand Down Expand Up @@ -606,7 +610,11 @@ interface IAccessible2 : IAccessible
One means of implementing this would be to create a factory with a 32 bit number
generator and a reuse pool. The number generator would emit numbers starting
at 1. Each time an object's life cycle ended, its number would be saved into a
resuse pool. The number generator would be used whenever the reuse pool was empty.
reuse pool. The number generator would be used whenever the reuse pool was empty.

Another way to create a unique ID is to generate it from a pointer value, e.g. an
object's address. That would be unique because no two active objects can use the
same allocated memory space.

@param [out] uniqueID
@retval S_OK
Expand Down
11 changes: 6 additions & 5 deletions api/AccessibleAction.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,6 +97,7 @@ interface IAccessibleAction : IUnknown
0 based index specifying the action to perform. If it lies outside
the valid range no action is performed.
@retval S_OK
@retval S_FALSE if action could not be performed
@retval E_INVALIDARG if bad [in] passed
*/
HRESULT doAction
Expand All @@ -112,7 +113,7 @@ interface IAccessibleAction : IUnknown
The returned value is a localized string of the specified action.
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT description
(
Expand Down Expand Up @@ -151,8 +152,8 @@ interface IAccessibleAction : IUnknown
@param [out] nBindings
The number of key bindings returned; the size of the returned array.
@retval S_OK
@retval S_FALSE if there are no relations, [out] values are NULL and 0 respectively
@retval E_INVALIDARG if bad [in] passed, [out] values are NULL and 0 respectively
@retval S_FALSE if there are no key bindings, [out] values are NULL and 0 respectively
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT keyBinding
(
Expand All @@ -168,7 +169,7 @@ interface IAccessibleAction : IUnknown
@param [out] name
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT name
(
Expand All @@ -182,7 +183,7 @@ interface IAccessibleAction : IUnknown
@param [out] localizedName
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT localizedName
(
Expand Down
6 changes: 6 additions & 0 deletions api/AccessibleApplication.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,9 @@ interface IAccessibleApplication : IUnknown

/** @brief Returns the application version.
@param [out] version
The version string must not contain levels when it is know beforehand that
this information will never require a change in a client's behavior.
For example, use "3.6.0" rather than "3.6.0.v201005131500".
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
*/
Expand All @@ -103,6 +106,9 @@ interface IAccessibleApplication : IUnknown

/** @brief Returns the toolkit/bridge version.
@param [out] version
The version string must not contain levels when it is know beforehand that
this information will never require a change in a client's behavior.
For example, use "3.6.0" rather than "3.6.0.v201005131500".
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
*/
Expand Down
55 changes: 42 additions & 13 deletions api/AccessibleEditableText.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -81,8 +81,8 @@ interface IAccessibleEditableText : IUnknown

/** @brief Copies the text range into the clipboard.

The specified text between the two given indices is copied into the
system clipboard.
The selection is set to the specified offsets and then selection is copied into
the system clipboard.

@param [in] startOffset
Start index of the text to moved into the clipboard.
Expand All @@ -92,6 +92,10 @@ interface IAccessibleEditableText : IUnknown
The valid range is 0..length.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
@note Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
*/
HRESULT copyText
(
Expand All @@ -112,6 +116,10 @@ interface IAccessibleEditableText : IUnknown
The valid range is 0..length.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
@note Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
*/
HRESULT deleteText
(
Expand All @@ -127,6 +135,10 @@ interface IAccessibleEditableText : IUnknown
@param [in] offset
Index at which to insert the text.
The valid range is 0..length.
Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
@param [in] text
Text that is inserted.
@retval S_OK
Expand All @@ -140,8 +152,8 @@ interface IAccessibleEditableText : IUnknown

/** @brief Deletes a range of text and copies it to the clipboard.

The text between the two given indices is deleted from the text
represented by this object and copied to the clipboard.
The selection is set to the specified offsets, the selection is then copied into
the system clipboard, and then the selection is deleted.

@param [in] startOffset
Start index of the text to be deleted.
Expand All @@ -151,24 +163,33 @@ interface IAccessibleEditableText : IUnknown
The valid range is 0..length.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
@note Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
*/
HRESULT cutText
(
[in] long startOffset,
[in] long endOffset
);

/** @brief Pastes text from the clipboard.
/** @brief Pastes content from the clipboard.

The text in the system clipboard is pasted into the text represented
by this object at the given index. This method is similar to the
IAccessibleEditableText::insertText method. If the index is not valid
the system clipboard text is not inserted.

Any existing selection is removed, the clipboard content is then pasted into
this object's text at the given offset. This method is similar to the insertText
method. If the index is not valid the system clipboard content is not inserted. The
behavior is the same as when Ctrl+V is used, i.e. the pasted contents are not
necessarily plain text.

@param [in] offset
Index at which to insert the text from the system clipboard into
Index at which to insert the content from the system clipboard into
the text represented by this object.
The valid range is 0..length.
Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
*/
Expand All @@ -189,12 +210,16 @@ interface IAccessibleEditableText : IUnknown
Start index of the text to be replaced.
The valid range is 0..length.
@param [in] endOffset
Start index of the text to be replaced.
End index of the text to be replaced.
The valid range is 0..length.
@param [in] text
The Text that replaces the text between the given indices.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
@note Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
*/
HRESULT replaceText
(
Expand All @@ -212,13 +237,17 @@ interface IAccessibleEditableText : IUnknown
Start index of the text whose attributes are modified.
The valid range is 0..length.
@param [in] endOffset
Start index of the text whose attributes are modified.
End index of the text whose attributes are modified.
The valid range is 0..length.
@param [in] attributes
Set of attributes that replaces the old list of attributes of
the specified text portion.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed
@note Refer to @ref _specialOffsets
"Special Offsets for use in the IAccessibleText and IAccessibleEditableText Methods"
for information about special offsets that can be used in %IAccessibleEditableText
methods.
*/
HRESULT setAttributes
(
Expand Down
2 changes: 1 addition & 1 deletion api/AccessibleEventId.idl → api/AccessibleEventID.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,7 @@ enum IA2EventID {
*/
IA2_EVENT_ACTION_CHANGED = 0x101,

/** The active descendant of a component has changed.
/** <b>Deprecated.</b> The active descendant of a component has changed.

Note: This event constant is misspelled and thus is deprecated and will be
removed in a later version. Please use the correctly spelled version which
Expand Down
15 changes: 7 additions & 8 deletions api/AccessibleHyperlink.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -111,8 +111,7 @@ interface IAccessibleHyperlink : IAccessibleAction
an IUnknown VARIANT for IAccessibleImage. See the section about
@ref _variants "VARIANTs" for additional information.
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT anchor
(
Expand All @@ -133,8 +132,7 @@ interface IAccessibleHyperlink : IAccessibleAction
activated when the link is activated. See the section about
@ref _variants "VARIANTs" for additional information.
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT anchorTarget
(
Expand Down Expand Up @@ -174,12 +172,13 @@ interface IAccessibleHyperlink : IAccessibleAction
This has also been used to indicate whether or not the URI of the anchorTarget
is malformed.

Note: This method is not being used, is deprecated, and should not be implemented or
used. It is likely that this method will be removed in a later version of the IDL.

@param [out] valid
If false, one or more of the object's links are invalid.
If true, all of the object's links are valid.
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is FALSE
@retval S_FALSE if there is nothing to return, [out] value is FALSE
@note This method is not being used, is deprecated, and should not be implemented or
used. It is likely that this method will be removed in a later version of the IDL.
*/
[propget] HRESULT valid
(
Expand Down
4 changes: 2 additions & 2 deletions api/AccessibleHypertext.idl
View file
Original file line number Diff line number Diff line change
Expand Up @@ -91,7 +91,7 @@ interface IAccessibleHypertext : IAccessibleText
of links minus one, a reference to the specified hyperlink object is returned.
If the index is invalid then a NULL pointer is returned.
@retval S_OK
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT hyperlink
(
Expand All @@ -112,7 +112,7 @@ interface IAccessibleHypertext : IAccessibleText
character index, or -1 if charIndex is not on a link.
@retval S_OK
@retval S_FALSE if there is nothing to return, [out] value is -1
@retval E_INVALIDARG if bad [in] passed, [out] value is NULL
@retval E_INVALIDARG if bad [in] passed
*/
[propget] HRESULT hyperlinkIndex
(
Expand Down
Loading

0 comments on commit 51ad09d

Please sign in to comment.