The IAccessible interface is the heart of Active Accessibility. Applications provide this Component Object Model (COM) interface on behalf of user interface elements.
The IAccessible interface methods can be organized into the following groups.
HRESULT accDoDefaultAction(VARIANT varChild);
Performs the object's default action.
You can retrieve the object's DefaultAction property by using the IAccessible::get_accDefaultAction method.
Only controls that perform actions support IAccessible::accDoDefaultAction. Some controls, like edit fields, can have a primary value but not a primary action.
In most cases, the client could also perform this action using standard OLE Automation, as well as carry out any nondefault actions supported by the object. However, this method provides an easy way to identify and perform an object's most commonly used function. Also, with the information provided by the IAccessible::get_accDefaultAction method, you can describe the action to the user even if the application does not ship an OLE Automation type library.
HRESULT accHitTest(long xLeft, long yTop, VARIANT * pvarChild);
Retrieves the child object at a given point on the screen.
When this method is used in certain situations, additional usage notes apply. For more information, see Object Navigation.
Note to implementers: This method must not fail for visual objects. Instead, set the vt member of the VARIANT structure to VT_EMPTY. Currently, the only nonvisual objects are sound objects.
See also VARIANT Structure, IDispatch Interface
HRESULT accLocation(long * pxLeft, long * pyTop, long * pcxWidth, long * pcyHeight, VARIANT varChild);
Retrieves the object's current screen location (if the object was placed on the screen) and optionally, the child element.
This method retrieves the object's bounding rectangle. If the object is a region, then this method returns the biggest rectangle encompassing the entire region.
Note to implementers: This method must not fail for visual objects. The only nonvisual objects are sound objects.
HRESULT accNavigate(long navDir, VARIANT varStartFromChildOrSelf, VARIANT * pvarEndUpAt);
Retrieves the next or previous sibling or child object in a specified direction.
This method retrieves only objects that have a defined screen location. However, the object might be currently clipped or obscured by another object. This method does not change selection or focus. To change focus to or select an object, use the IAccessible::accSelect method. For more information see, Object Navigation.
The NAVDIR_NEXT and NAVDIR_PREVIOUS values will not cause looping. The method will return S_FALSE, after the last or first object is found.
Note to implementers: If the current object does not have any knowledge of peer objects, it should ask its parent object to perform the navigation. If the current object does not have any knowledge of its parent, it should return S_FALSE. Client applications using accNavigate should be aware that the return value they get back may not have been provided by the object itself. For example, if a client asks Object A to navigate to the next object (Object B), Object A may ask its parent to do the navigation. In that case, the client must direct any future queries about Object B (i.e. accLocation) to the parent of Object A (by calling ObjectA.get_accParent) or to Object B itself (by calling ObjectA.get_accParent() and then ParentObject.get_accChild(ChildB). The client will be able to tell that this is necessary if: * The accNavigate call started with the varStart VARIANT set to type = VT_I4 and lVal = CHILDID_SELF (0). * The VARIANT filled in by the accNavigate call (pvarEndUpAt) also has type = VT_I4.
Active Accessibility does not always support navigation to invisible children. Remember that it is OK for an object to support the IAccessible::accNavigate and IAccessible::get_accChild methods for children that are invisible, but that clients cannot expect this. In the section where the proxies are implemented, that menus, menu items, and menu popups allow navigation to invisible children, but that other objects that Active Accessibility proxies may not. You might not be able to navigate to all of an object's children, if they have the flag STATE_SYSTEM_INVISIBLE.
See also VARIANT Structure, IDispatch Interface
HRESULT accSelect(long flagsSelect, VARIANT varChild);
Modifies the selection or moves the keyboard focus according to the specified flags.
If the selection can't be placed at the requested location, the server fails the call and returns S_FALSE.
Applications can use this method to perform complex selection operations. For more information, see Selecting Child Objects.
HRESULT get_accChild(VARIANT varChild, IDispatch** ppdispChild);
Retrieves an IDispatch interface address of the child object that has the given child ID or name.
Note that the IDispatch interface returned must be released when the client is finished using it. This can be done by calling the Release() member. Failure to do so will keep the object in memory, causing memory leaks.
This is the only IAccessible method that fails if the application cannot create an OLE object for the child element being referenced.
Note to implementers: If a container object does not support the IEnumVARIANT interface, its child ID numbers must be sequential positive integers starting with 1. If the object supports IEnumVARIANT, then it can use any method to assign its child ID numbers.
Note to implementers: If a VT_EMPTY is passed in, then an E_INVALIDARG can be returned, while get_accName and get_accRole get passed with VT_EMPTY, the application will get back valid results.
See also IAccessible::get_accParent, Object Navigation, VARIANT Structure, IDispatch Interface, Object and Child Identifiers
HRESULT get_accChildCount(long* pcountChildren);
Retrieves the number of children belonging to the current object.
Note that the IDispatch interface returned must be released when the client is finished using it. This can be done by calling the Release() member. Failure to do so will keep the object in memory, causing memory leaks.
The number of children in an object can change. An application should watch for EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY events generated by the current object to keep track of possible child count updates.
The children of this object might or might not be objects themselves.
Note to implementers: This method must not fail if no child objects exist. Instead, return S_OK and set the variable at pcountChildren to zero.
HRESULT get_accDefaultAction(VARIANT varChild, BSTR* pszDefaultAction);
Retrieves a string containing a localized sentence that describes the object's default action.
The retrieved string describes the action that is performed on an object, not what the object does as a result. That is, a toolbar button that prints a document would have a default action of "Press" rather than "Prints the current document." Also, do not confuse an object's default action with its value. For more information, see DefaultAction Property.
Only controls that perform actions support this method.
Note to implementers: Localize the string returned from this property.
See also VARIANT Structure
HRESULT get_accDescription(VARIANT varChild, BSTR* pszDescription);
Retrieves a string containing a sentence that describes the current object.
The object description conveys the object's visual appearance to the user. Visual information is key for graphical objects, like toolbar buttons or images. However, the vendor ultimately determines the level of detail provided. For more information about this property, see Description Property.
Note to implementers: Localize this property.
HRESULT get_accFocus(VARIANT * pvarChild);
Retrieves the child object that currently has the keyboard focus.
Only one object or item within a container can have the focus at any one time. The object with the keyboard focus is not necessarily the selected object.
Note to implementers: If the object itself has the keyboard focus, return zero as a VT_I4 type. If a child is an accessible object and has the focus, return the address of its IDispatch interface (a VT_DISPATCH type). Or, if a child has the focus but isn't an accessible object, return the child ID to the child as a VT_I4 type.
See also Accessible Object Selection and Focus, IDispatch Interface
HRESULT get_accHelp(VARIANT varChild, BSTR * pszHelp);
Retrieves an object's Help property string.
An object's Help property is represented in the form of a string that provides some helpful text to associate with the specified object. You can use this helpful text to provide a description of what the object does; contrast this with the Description property, which describes what an object looks like.
Note to implementers: Objects need not support both the IAccessible::get_accHelp and IAccessible::get_accHelpTopic functions, but should support at least one. That is, if they can easily return a string they should support get_accHelp, otherwise they should support get_accHelpTopic. If both are supported, the object need not yield identical information.
Localize this property.
Developers of both servers and clients should be aware that getting information from a Help file might be expensive in terms of time and memory.
See also VARIANT Structure
HRESULT get_accHelpTopic(BSTR * pszHelpFile, VARIANT varChild, long * pidTopic);
Retrieves the full path of the Help file associated with the specified object, as well as the address of the appropriate topic within that file.
Note to implementers: Do not localize the string returned from this property.
See also HelpTopic Property
HRESULT get_accKeyboardShortcut(VARIANT varChild, BSTR * pszKeyboardShortcut);
Retrieves an object's KeyboardShortcut property.
Note to implementers: Do not localize the string returned from this property.
See also VARIANT Structure
HRESULT get_accName(VARIANT varChild, BSTR* pszName);
Retrieves the Name property for this object.
Note to implementers: If you are using menu or button text for the Name property, strip any ampersands (&) marking keyboard access keys; the information they convey can be provided to the client in response to IAccessible::get_accKeyboardShortcut calls.
Do not localize the string returned from this property.
See also IAccessible::put_accName, VARIANT Structure
HRESULT get_accParent(IDispatch** ppdispParent);
Retrieves the IDispatch interface of the current object's parent.
Note that the IDispatch interface returned must be released when the client is finished using it. This can be done by calling the Release() member. Failure to do so will keep the object in memory, causing memory leaks.
Note to implementers: This method must not fail if no parent object exists. Instead, return S_FALSE and set the variable at ppdispParent to NULL.
See also IAccessible::get_accChild, Object Navigation, IDispatch Interface
HRESULT get_accRole(VARIANT varChild, VARIANT * pvarRole);
Retrieves the object's Role property.
Note to implementers: This method must not fail if no role text exists. Instead, return S_OK and set the vt member of the VARIANT structure at pvarRole to VT_EMPTY. All objects should have a role and role text.
Do not localize the string returned from this property.
See also VARIANT Structure
HRESULT get_accSelection(VARIANT * pvarChildren);
Retrieves the selected children of this object.
VT_DISPATCH | One child was selected and the address of its IDispatch interface is set in the pdispVal member. |
VT_EMPTY | No objects were selected. |
VT_I4 | One object was selected. The child ID is set in the lVal member. If lVal is CHILDID_SELF, then the object itself had no children but was selected. |
VT_UNKNOWN | Multiple objects were selected and the punkVal member contains the address of the IUnknown interface. The client can query this interface for the IEnumVARIANT interface, which it can use to enumerate the selected objects. |
Note to implementers: If the object has no children, but is itself selected, set the vt member to VT_I4 and lVal to CHILDID_SELF. If no child is selected, set vt to VT_EMPTY. If multiple children are selected, set vt to VT_UNKNOWN and punkVal to the IUnknown interface pointer of an object that can be used to enumerate the child objects. This object must support the IEnumVARIANT interface.
See also Retrieving Selected Objects and Children, VARIANT Structure, IDispatch Interface
HRESULT get_accState(VARIANT varChild, VARIANT * pvarState);
Retrieves the current state of the object or child item.
Note to implementers: Localize the string returned from this property.
It is recommended that you avoid using a string to identify the child; because if the object uses strings, it prevents the use of the default states. It is not recommended that you use this string functionality.
See also State Property, VARIANT Structure
HRESULT get_accValue(VARIANT varChild, BSTR* pszValue);
Retrieves the object's Value property.
See also IAccessible::put_accValue
HRESULT put_accName(VARIANT varChild, BSTR szName);
Sets the Name property for this object.
See also IAccessible::get_accName
HRESULT put_accValue(VARIANT varChild, BSTR szValue);
Sets the value of the object's Value property for the current item.
See also VARIANT Structure, IAccessible::get_accValue
© 1997 Microsoft Corporation. All rights reserved. Legal Notices.