## Accessible Objects

Applications support Active Accessibility by exposing their user interface (UI) elements to client applications. These UI elements are presented to clients (accessibility aids) in the form of "accessible objects."

This section provides an overview of the concepts behind accessible objects. The following topics are covered.

- Objects, Children, and Simple Elements
- Object and Child Identifiers
- Supported Interfaces
- Properties for Accessible Objects
- Methods for Accessible Objects
- Enumeration Properties
- Accessible Object Events and Hook Procedures
- Accessible Object Selection and Focus
- Support for Standard Objects

### Objects, Children, and Simple Elements

Throughout this documentation, you'll see the terms "object," "parent," "container," "child," "simple element," and "element" used to refer to various parts of a user interface (UI). These terms seem fairly generic, and you've probably seen them before, used in a number of different ways. In this document, these terms are used to explain whether part of an application's UI supports Active Accessibility, contains other pieces of the UI, and whether or not these smaller pieces also support Active Accessibility. To simplify, in the context of this document, these terms can be defined as follows:

Object
  A user interface element that supports Active Accessibility technology.
Parent or Container
  A user interface element that supports Active Accessibility technology and contains other objects and/or simple elements.
Simple element or Element
  A user interface element that does not support Active Accessibility. This might be because the object simply is "ignorant" of the technology, or that the element's parent assumes the responsibility of providing Active Accessibility features on its behalf.

For an example of using these terms, imagine a toolbar control that contains several buttons. The operating system supports toolbar controls and push buttons as accessible objects. In this case, the toolbar control is the parent object, or container, for the push buttons. The push buttons are also objects but have no children.

In some cases, an object might have children that don't inherently support Active Accessibility—also known as simple elements. To remain "accessible," the parent can create accessible objects with the properties of the child when a client asks for it. This way, the parent saves memory by not keeping extra interfaces around, without sacrificing accessibility. List box items are an example of this. The children (cells) are accessible objects, but the aren't kept around. When the user picks the control, the objects are generated, and then displayed to the user. When the user is done, they are all destroyed.

### Object and Child Identifiers

Active Accessibility identifies user interface elements by using object and child identifiers. These values, by themselves, mean little to a client, and clients aren't expected to decipher them. Rather, clients use these values when calling functions that retrieve the object itself. Active Accessibility provides the AccessibleObjectFromEvent, AccessibleObjectFromWindow, and AccessibleObjectFromPoint functions for this purpose.

The terms "object identifier" and "object ID" refer to a 32-bit value that uniquely identifies an accessible object within an application. Often these values refer to standard top-level objects in a window, like the application menu or scroll bars. Active Accessibility reserves all negative values and zero to use as these standard object identifiers. However, server applications can use any positive, nonzero object ID values to identify other objects they contain.

Child identifiers take one of two forms: a 32-bit integer value or a name string, each uniquely identifying a child within the container's scope. (For simplicity in this document, the term "child ID" refers only to the 32-bit value.) Child identifiers can take strings, object identifiers do not. In effect, child identifiers describe simple elements within an accessible object; that is, they describe elements that don't support Active Accessibility, but are contained by a parent that does. If an object provides information about itself, but not about a child element, it specifies the CHILDID_SELF value, defined as zero in the winable.h header file.

The IAccessible interface provides methods that enable clients to request information about an object or navigate using object and child identifiers. Remember that server applications might support only one of the two child identification methods. For example, if a client calls IAccessible methods by using name strings to identify an object's children but the server supports only 32-bit child IDs, the method will fail and return the E_INVALIDARG error code.

Server applications can use whichever method they choose. However, if a server supports child IDs, it must follow some basic rules. Server applications using child ID values can assign any 32-bit value, so long as they support the IEnumVARIANT interface, which enables clients to logically enumerate child objects regardless of their child IDs. For more information on the IEnumVARIANT interface, see the Win32 SDK. If the server application doesn't support IEnumVARIANT, child ID values must be sequential integers starting with 1.

### Supported Interfaces

All Active Accessibility objects must support the following interfaces.

- The IAccessible interface, which defines the basic functionality. This interface enables clients to retrieve information about object properties, gain selection and focus information, perform hit tests, and navigate between objects.
- The IDispatch interface, which is used to access the same functionality from tools such as Microsoft Visual Basic®. For more information, see IDispatch Interface.

In addition, it is strongly recommended that all container objects support IEnumVARIANT, which allows a client to logically enumerate an object's children. If the server does not support IEnumVARIANT, all child IDs must be sequential integers starting with 1.

### Properties for Accessible Objects

Accessible objects maintain pieces of information, called "properties," that help describe the object's appearance, nature, and purpose.

The IAccessible interface extends methods that enable a client application to retrieve these properties. Using the information that these properties provide, an accessibility aid can determine information valuable to the user, and convey it to the user as needed.

For more information, see Accessible Object Properties.

### Methods for Accessible Objects

Accessible objects contain ways to access information, called "methods," that populate the object's data structures for appearance, nature, and purpose.

The IAccessible interface has methods that enable a client application to access properties of this accessible object.

For more information, see Accessible Object Methods.

### Accessible Object Events and Hook Procedures

Server applications generate event notifications ("WinEvents") whenever they've done something that might be of interest to a client. Client applications don't automatically receive event notifications, they must request them.

Client applications tell the system about the event notifications they want to know about by registering a hook procedure with the SetWinEventHook function. Using this function, the client sets one or more hook functions that the system calls in response to particular events. Hook functions can be located within the client's code body, in a dynamic-link library (DLL) mapped into the client's process, or in a DLL mapped into the server's process. Each of these has benefits and drawbacks. For more information, see About the WinEventProc Callback Function.

The event notification process begins when a server calls the NotifyWinEvent function to inform the system that something of interest is occurring. Active Accessibility checks to see if any client applications have expressed interest in the event, and calls the appropriate hook procedures as necessary. When it is called, a hook procedure in the client can then receive a number of parameters that describe an event and the object that generated it. The hook procedure uses Active Accessibility system functions, like AccessibleObjectFromEvent, to gain access to the object of interest. Once the client retrieves the object, it can retrieve its properties, make selections, or perform other actions appropriate to the event.

### Accessible Object Selection and Focus

Like many elements in Windows applications, accessible objects can be selected and receive keyboard focus. These attributes enable users to interact with application elements, changing values or otherwise manipulating them.

Note that object selection and object focus are two entirely different ideas. The "focused" object is the one object in the entire system that receives keyboard input, while the "selected" object is marked to participate in some type of group operation. Additionally, focused items can be in or out of a selection of items. For example, you can select several items in a list view control in preparation for moving or deleting them all. However, the focus is given only to one object in the system at a time.

Note that menus do not incorporate item selection. When a user highlights menu items, the server must not generate EVENT_OBJECT_SELECTION events or any other selection-related event. Instead, the server should generate an EVENT_OBJECT_FOCUS event specific to the object that is highlighted.

This documentation includes information about accessing selected or focused objects. For more information, see Retrieving the Object with Keyboard Focus and Retrieving Selected Objects and Children.

### Enumeration Properties

All Active Accessibility container objects are strongly recommended to support the IEnumVARIANT interface. This interface extends the following four methods that provide enumeration functionality to the client.

- Clone
- Next
- Reset
- Skip

For a complete description of the IEnumVARIANT interface, see the OLE documentation included in the Win32 SDK.

If a container object supports IEnumVARIANT, it can use any method to assign its child ID values. If it doesn't support IEnumVARIANT, its children must have child ID values that are sequential integers starting with 1.

### Support for Standard Objects

This section provides information describing Active Accessibility's automatic support for common system objects. The following topics are discussed.

- Objects Exposed in a Common Window
- Support for Standard Dialog Manager
- Support for MSHTML

#### Objects Exposed in a Common Window

Active Accessibility automatically provides support for many operating system components.

The following illustration shows a typical window and some of the objects that Active Accessibility automatically exposes.

Additionally, Active Accessibility automatically supports the Standard Dialog Manager dialog boxes and MSHTML. For more information, see Support for Standard Dialog Manager and Support for MSHTML.

#### Support for Standard Dialog Manager

Standard Dialog Manager (SDM) is an internal Microsoft code library that provides applications with a degree of independence from the differences between the Macintosh and Windows operating systems. SDM is primarily used for dialog boxes in the Microsoft Excel and Microsoft Word applications.

SDM presents problems for accessibility aids because it uses nonstandard implementations of dialog boxes. For example, SDM dialog box buttons don't use window handles in the usual sense. You cannot send messages to buttons and buttons aren't contained in the window list. The application using SDM communicates with it through a private interface.

The following illustration shows a sample dialog box from Microsoft Word. While it looks like a regular Windows dialog box using the pagetab control, it is really an SDM dialog box.

#### Support for MSHTML

The Microsoft Internet Explorer 3.0 World Wide Web browser is built on the mshtml.dll component, which is responsible for parsing and displaying HTML. You can also find the MSHTML component in other Web browsers.

Exposing HTML

The following illustration shows a simple HTML page displayed in Internet Explorer 3.0:

This image shows the following elements.

- Images. "Accessibility Support" with the Windows flag logo is an image with the words part of the bitmap. "Download Instructions" and the little icon of a printed page are also images.
- White Space. Blank spaces provided to format the page. They contain no information.
- Text. The main paragraph and the list of instructions are plain text.
- Links. The words "Microsoft and Accessibility" are underlined and act as a link to another page.

Active Accessibility exposes the contents of HTML pages. The parent object in this case is the client area of the browser window. The children are the HTML elements, in the sequence that the HTML was written.

In this case, the first child is the "Accessibility Support" graphic. It exposes a standard Roleproperty of "Graphic". For the Name property it uses the ALT tag, if one is present. The next child of the HTML document is the white space between the graphic and the text. Following that is the first text child containing the first line starting with "Microsoft is committed. . ." Active Accessibility divides the text elements according to the HTML source code. If no breaks exist in the HTML source code, then the largest textual element is a line. Text is exposed with a role of "editable text" and a State property of "read only." The Name property is all the text in the element.

Active Accessibility also exposes the "Microsoft and Accessibility" link with a Role property of "editable text" but with "read only," "focusable", and "linked" as the State. In addition, with a child that is a link, regardless of whether it's an image or text, the Value property contains the link's URL. If the link is focused (by way of the keyboard or a mouse click), then an additional State property, "Focused", is applied. Links also have a DefaultAction property, in this case "Jump".

HTML Forms

Active Accessibility and the MSHTML control also expose all the standard HTML form controls as normal Active Accessibility objects. This means that edit boxes, radio buttons, and other controls are fully accessible when you use Active Accessibility.

© 1997 Microsoft Corporation. All rights reserved. Legal Notices.