Legal Information

[This is preliminary documentation and subject to change.]

Microsoft Active Accessibility

Information in this document is subject to change without notice. Companies, names, and data used in examples are fictitious unless otherwise noted. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation.

Microsoft may have patents or pending patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. The furnishing of this document does not give you the license to these patents, trademarks, copyrights, or other intellectual property rights except as expressly provided in any written license agreement from Microsoft.

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

ActiveX, Microsoft, MS-DOS, Visual Basic, Visual C++, Win32, Windows, and Windows NT are either registered trademarks or trademarks of Microsoft in the United States and/or other countries.

Other product and company names mentioned herein may be the trademarks of their respective owners.


About This Document


About the Reader

This document provides a complete reference to the objects, functions, and other API elements that comprise Microsoft® Active Accessibility. Active Accessibility objects are OLE component objects that conform to the OLE Component Object Model (COM).

To get the most out of this documentation, you should be familiar with the following material.

  • C and C++ programming concepts.
  • OLE programming concepts, including: COM, interface queries, and calling functions.
  • The Win32 application programming interface as presented by the Microsoft Platform Software Development Kit (SDK).


How This Document is Organized

This document is divided into four major sections:

Overview
 | This section provides a high-level overview of Active Accessibility technology. It explains the purpose of the technology, examines its usefulness to developers and users, and lays the conceptual ground-work that comprises the technology, without concentrating on the technical implementation details. Regardless of your background, if you intend to use Active Accessibility, you should read this section first.
C/C++ Developer's Guide
 | This section examines Active Accessibility in a more technical light. It comprehensively presents the technology's key API elements and concepts using terms and examples that will be familiar to the C or C++ application developer. In addition to explaining the technology's key concepts, the C/C++ Developer's Guide contains sections with information pertinent to the two types of Active Accessibility customers: client ("accessibility aid") developers and server developers.
C/C++ Reference
 | This section includes comprehensive reference material for all the API elements that Active Accessibility provides.
Appendix
 | This section briefly examines Active Accessibility from a Visual Basic developer's standpoint. It covers the supported objects, window elements, and user interface controls that are exposed to VB developers.


Overview


What Is Active Accessibility?

Accessibility for people with disabilities (or, simply, "accessibility") refers to software features that enable these users to efficiently use computer applications. Typically, helper applications (called "accessibility aids") or the Microsoft® Windows® operating system provide these features.

Accessibility aids generally perform the following main tasks.

  • Screen reading. These tools for the blind provide audio interpretations of text and other visual elements on the screen.
  • Screen magnification. These tools allow people with low vision to adequately see on-screen information.
  • Input enhancement. These hardware and software tools support users with limited dexterity, enabling them to use different keyboard driver software or different input devices altogether.

Active Accessibility is the umbrella name for the architecture and interface standards that support the integration of accessibility tools with accessibility-aware applications. This subject is quite broad, because there are many forms of disability and many possible application tools intended to assist users with those disabilities.

Active Accessibility provides the fundamental accessibility infrastructure and defines integration standards providing the most value with the least impact on supporting applications.

This technology targets mainstream software developers, accessibility aid vendors, and other interested persons. This document assumes a moderate to high level of knowledge in Microsoft Windows software development. For more information, see Where to Find More Information.


Why Use Active Accessibility?

Currently, there is a third-party market of accessibility aids for the Windows operating system, each aimed at supporting individuals with a particular set of disabilities. These tools fall into two distinct camps: those that replace or modify existing Win32® devices (like the keyboard, mouse, or display driver) and those that integrate with applications to provide greater accessibility (like screen readers or voice-recognition utilities). Active Accessibility targets the problems that these aids face.

Screen access aids for blind or low-vision users provide a prime example: the aid must understand and verbalize anything displayed on the screen. Similarly, voice recognition utilities must identify controllable objects on the screen, recognize the name of each when it is spoken, and then programmatically select the object or manipulate its state.

Before the introduction of Active Accessibility technology, accessibility aid developers had to use cryptic hook mechanisms or hack the operating system in an attempt to gain the information they needed. Generally, they succeeded, but were extremely reliant on implementation details that might change between versions of the operating system.

Using OLE technology, Active Accessibility provides high-performance, reliable tools that enable applications and accessibility aids to work together in helping users with special needs. Active Accessibility provides a comprehensive object model including the interfaces, libraries, and other API elements that eliminate the need for unreliable hacks.


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 Platform 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 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.

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 Platform 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 Role property 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.


Where to Find More Information

Active Accessibility is part of OLE and other ActiveX™ technologies. You can find information about OLE from the following sources.

OLE Programmer's Reference
 | This book describes the component object model (COM), in-place activation, visual edition, structured file storage, and application registration in terms of the APIs and interfaces provided by OLE. Volume One provides a complete reference to OLE (Microsoft Press, ISBN 1-55615-628-6). Volume Two covers OLE Automation and programmable applications (Microsoft Press, ISBN 1-55615-629-4).
Inside OLE 2nd Edition by Kraig Brockschmidt.
 | This book provides a comprehensive tutorial on OLE/COM technology and its implementation. It is an introduction to OLE programming and covers all the basic OLE technologies such as storage, data transfer, OLE Automation, OLE documents and OLE controls. Includes many sample programs on CD-ROM. (Microsoft Press, ISBN 1-55615-843-2)
Inside COM by Dale Rogerson.
 | This book opens up the secrets of COM programming, for the advanced engineer. Includes many sample programs on CD-ROM. (Microsoft Press, ISBN 1-57231-349-8)
OLE Automation Programmer's Reference
 | This book provides procedural and reference information on programmable object model design, describes the IDispatch interface, and covers type libraries and exception handling. (Microsoft Press, ISBN 1-55615-851-3)
Microsoft Developer Network
 | This quarterly subscription service provides a wealth of information on CD-ROM for developers wanting to learn more about Microsoft technologies. MSDN is the official source from Microsoft for comprehensive programming information, development toolkits, and testing platforms. It includes a subscription to Microsoft Developer Network News. Different levels are provided at varying costs. For more information, visit http://www.microsoft.com/msdn/ on the World Wide Web or call (800) 759-5474 (in the United States ).
The Microsoft Network
 | Microsoft maintains large areas on both of these online services for developers to communicate to each other and to work with Microsoft Developer Support engineers.
The Microsoft Windows Guidelines for Accessible Software Design
 | This document provides an in-depth overview of disabilities and introduces techniques for making applications accessible. You can find this document on the Microsoft Developer Network or at the following Web site.

To comment on or get additional information about this documentation, e-mail abletech@microsoft.com/ or visit our Web site at http://www.microsoft.com/enable/


C/C++ Developer's Guide


Introduction to the C/C++ Developer's Guide

This section examines Active Accessibility from a C or C++ application developer's perspective, using familiar programming language terms and C++ style code examples. Additionally, the C/C++ Developer's Guide covers issues specific to client and server developers and provides brief overviews for the SDK's sample applications. The following topics are discussed.

  • Architecture and Key API Elements
  • Developing Applications that Use Active Accessibility
  • Developing Active Accessibility-enabled Applications
  • Sample Applications


Architecture and Key API Elements

This section contains information about the following topics.

  • VARIANT Structure
  • IDispatch Interface
  • IAccessible Interface
  • Accessible Object Properties
  • Accessible Object Methods
  • WinEvents
  • Changes to USER
  • Display Device Interface Redirection
  • Simulating Input


VARIANT Structure

The VARIANT structure carries a wide variety of information used when calling functions through the IDispatch interface. For more information about how Active Accessibility uses the IDispatch interface, see IDispatch Interface. Since so many Active Accessibility API elements use IDispatch, you'll frequently work with VARIANT structures as well.

Essentially, the VARIANT structure is a container for a large union that can carry many types of data. Before using the structure, you must initialize it by calling the VariantInit OLE function.

The value in the first structure member, vt, describes which of the union members is valid. When you receive information in a VARIANT structure, check the vt member to find out which member to look at next. Similarly, when you send information using a VARIANT structure, always set vt to reflect the union member you're using to send the information.

For more information about the VARIANT structure, please refer to OLE Automation documentation.


IDispatch Interface

The IDispatch interface provides the tools that some developers need to work between C/C++ applications and Microsoft Visual Basic® applications. This interface essentially provides an indirect way to expose object methods and properties. The IDispatch method provides information about what methods an object supports, provides identifiers for those methods, and executes them on the caller's behalf if needed.

Many objects built on OLE expose the IDispatch interface to support OLE Automation. Server applications must support the IDispatch interface for this purpose. However, since C/C++ client developers need not interact with VB applications, they should use the IAccessible interface to achieve the best performance. Because most Active Accessibility API functions retrieve objects by way of their IDispatch interface, you'll often need to retrieve an IAccessible interface by calling the object's QueryInterface method and specifying the IID_IAccessible reference identifier as the iid parameter.

Oleacc.h defines the following DISPID values for use with the IDispatch interface.

// PROPERTIES: Hierarchical
#define DISPID_ACC_PARENT                   (-5000)
#define DISPID_ACC_CHILDCOUNT               (-5001)
#define DISPID_ACC_CHILD                    (-5002)

// PROPERTIES:  Descriptional
#define DISPID_ACC_NAME                     (-5003)
#define DISPID_ACC_VALUE                    (-5004)
#define DISPID_ACC_DESCRIPTION              (-5005)
#define DISPID_ACC_ROLE                     (-5006)
#define DISPID_ACC_STATE                    (-5007)
#define DISPID_ACC_HELP                     (-5008)
#define DISPID_ACC_HELPTOPIC                (-5009)
#define DISPID_ACC_KEYBOARDSHORTCUT         (-5010)
#define DISPID_ACC_FOCUS                    (-5011)
#define DISPID_ACC_SELECTION                (-5012)
#define DISPID_ACC_DEFAULTACTION            (-5013)

// METHODS
#define DISPID_ACC_SELECT                   (-5014)
#define DISPID_ACC_LOCATION                 (-5015)
#define DISPID_ACC_NAVIGATE                 (-5016)
#define DISPID_ACC_HITTEST                  (-5017)
#define DISPID_ACC_DODEFAULTACTION          (-5018)

For more information about the IDispatch interface, OLE Automation, and COM, see the references discussed in Where to Find More Information.


IAccessible Interface

The IAccessible interface represents an accessible object. Its methods allow client applications to examine object properties that describe the object, set and retrieve selection states, navigate to other objects, perform hit testing, and invoke an object's default action.

This section describes how you can work with accessible objects using the IAccessible interface. Additionally, this section introduces the concept of object navigation and presents the three navigation methods that the IAccessible interface provides. Information is divided into the following topics.

  • Querying an Object for its Properties
  • Invoking an Object's Default Action
  • Object Navigation


Querying an Object for its Properties

A client application can access all of an object's properties through the IAccessible interface. To retrieve an object property, you must first have the address of the object's IAccessible interface. Then, call the property's corresponding property access method (like IAccessible::get_accName) to retrieve the desired information.

All property access methods can access information for a container object and any simple elements it contains—it is the server's responsibility to maintain property information for simple elements.

For more information about object properties, see Properties for Accessible Objects.


Invoking an Object's Default Action

Applications can invoke an accessible object's default action by calling its IAccessible::accDoDefaultAction method. You can query for an object's DefaultAction property by calling the IAccessible::get_accDefaultAction method.

Effectively, calling accDoDefaultAction causes the object to perform its primary function. For example, calling accDoDefaultAction for a button control would cause the button to be pressed as though the user had clicked it.


Object Navigation

The term "navigation," when used in the context of accessible objects, refers to the process of retrieving the address of another object's IAccessible or IDispatch interface using the methods provided by the current object.

Hierarchical Object Navigation

Often, client applications must move between objects based on their parent-child relationships. For example, an accessibility aid might already have information about a toolbar control, but not yet know anything about the buttons or other controls contained within it.

The IAccessible interface exposes the hierarchical relationships between objects through the IAccessible::get_accParent and IAccessible::get_accChild methods. Using these methods, client applications can navigate from a parent object to its children or vice versa.

Spatial and Logical Object Navigation

Applications can retrieve information about an object that is spatially or logically near the current object by using the IAccessible::accNavigate method. Using this method, a client can navigate to another object based on its location on the screen (spatial) or to the object that logically precedes or follows the current object, as determined by the server (logical). The client application specifies the type and direction to navigate by using navigational constants when calling the method.

The two types of navigation are very different. Spatial navigation is simple in concept; if a client wants the object to the right of the current one, the server retrieves it and gives it to the client. However, since logical relationships between objects are subjective, logical navigation is less straightforward for both the client and server. Generally, these relationships parallel those in keyboard navigation. For example, imagine a typical dialog box that contains a few edit controls, an OK button and a Cancel button. In this case, calling the IAccessible::accNavigate method to move to the next or previous object in the dialog box is analogous to the user pressing tab or shift+tab. That is, when the user presses tab, the system moves focus to the next object, and when the user presses shift+tab, the system moves the focus to the previous object.

When performing spatial navigation, clients must be aware of all floating objects. Because a floating object isn't clipped to its parent, you can't be sure of the hierarchical relationship between two objects near one another on the screen.

The following illustration shows this example of a floating object that isn't clipped to its parent.

Object Navigation Through Hit Testing

Applications can retrieve information about a child object by hit testing a point on the screen. To do this, call the current object's IAccessible::accHitTest method, passing the screen location to be hit tested in x- and y-coordinates. After the call, the pvarChild parameter points to a VARIANT structure that describes the hit test's result. If the call succeeds, the VARIANT structure's ppdispVal member is the address of the child object's IDispatch interface.

If multiple child objects overlap at a specified point, the accHitTest method retrieves the one that visually appears to occupy the space. However, accHitTest does not account for overlapping windows or clipping performed by the parent. Therefore, if a window covers a child object, hit testing the covered point will successfully retrieve the child object, even though it isn't actually visible at that point.

Additionally, the accHitTest method retrieves information about the topmost child object under the specified point. For example, if a child object displays a child of its own at the given point, only the top-level child object's information is returned.

Like any on-screen graphic, accessible objects can vary in shape. This isn't usually a problem, since most on-screen entities are well represented by rectangles. Rectangles can accurately describe most applications and their components: the application window, the menu, dialog boxes, buttons, scroll bars, and other common controls. As a result, accessible objects currently provide location information in terms of rectangles (by way of the IAccessible::accLocation method). If an object isn't shaped like a rectangle, the accLocation method provides the rectangle that contains the object.

Occasionally, rectangles aren't accurate enough. Accessible objects support the IAccessible::accHitTest method to provide access to clients on a pixel-by-pixel basis. This comes in handy when your application is tracking the location of the mouse pointer to gather information. The following illustration shows the relationship between an eccentric object's region and its bounding rectangle.


Accessible Object Properties

Accessible objects maintain several pieces of information, called "properties," that help describe the object's appearance, nature, and purpose. The IAccessible interface extends methods allowing an application to retrieve these properties. The application can examine the properties, determine what is valuable to the user, and convey information to the user as needed.

This section discusses the properties in detail, providing a conceptual overview for each. The following topics are covered.

  • Name Property
  • Role Property
  • State Property
  • Value Property
  • Description Property
  • Focus Property
  • Selection Property
  • DefaultAction Property
  • Location Property
  • Help Property
  • HelpTopic Property
  • KeyboardShortcut Property

You can access each property from C/C++ or Visual Basic® applications. These descriptions examine the properties from a C/C++ perspective.


Name Property

The Name property, retrieved by calling the IAccessible::get_accName method, is a string used by accessibility aids to identify, find, or announce an object for the user. For example, the text on a button control is its name, while the name for a list box or edit control is the text from an associated static text control. Even graphics objects or owner-draw controls that don't display a name should maintain text to provide when queried for the Name property.

It is the server's task to make object names as intuitive as possible. Additionally, the server must make an object's Name property unique relative to any sibling objects in the parent container. This allows accessibility aids (clients) to narrow the object's meaning or purpose more easily.

Navigation within tables presents especially difficult problems for some users. Therefore, server applications should use table cell names that are as descriptive as possible. For example, a server could name a cell by combining the names of the rows and columns it occupies. These can be like "A1," but it is generally more descriptive to use row and column names when available, such as "Tom, February."

Servers, by way of the IAccessible::put_accName method, can allow the client to set an object's name. Servers can choose to assist users by allowing them to assign unique and persistent names for objects. This allows the user to tag objects with names that they use to easily return their focus to the object later. A server must provide its own storage for persistent names. If a server doesn't support the IAccessible::put_accName method, it fails the call by returning S_FALSE.

If an object does not have access to its Name property it should delegate requests to its parent, identifying itself by its child ID. For example, if a client asks an edit control for its name, the edit control will probably delegate the query to its parent, which would return the value of the static text control that labels the edit control. In other cases, the child object might be able to retrieve the text itself. However, the server must be careful to ensure that a parent and child do not each delegate calls to each other.


Role Property

The Role property, retrieved by calling the IAccessible::get_accRole method, describes an object's role. Generally, the Role property describes the object's purpose in terms of its relationship with sibling or child objects. The oleacc.dll dynamic link library supports the role constants defined in the oleacc.h header file. These role constants are symbolic numeric values that identify common object roles. However, servers can provide strings when the standard values do not suffice. Use the GetRoleText method to retrieve these strings.

In many cases, the object's role is obvious; windows have a role of ROLE_SYSTEM_WINDOW and buttons have the ROLE_SYSTEM_PUSHBUTTON role. However, some objects' roles aren't so easy to describe. A folder's large-icon view allows arbitrary arrangement of icons, so its role could be described as ROLE_SYSTEM_GROUPING. Or, a control that provides items in fixed rows and columns could be have the ROLE_SYSTEM_TABLE role.


State Property

The State property, retrieved by calling the IAccessible::get_accState method, describes an object's status at a moment in time. In most cases, the retrieved value is a bitmask containing one or more of the object state constant flag values, but the server can provide a string if none of the predefined flags suffice. Use the GetStateText method to retrieve these strings. The oleacc.dll dynamic-link library supports these object state constants, which are defined in the oleacc.h header file.

Servers can combine the predefined flags with an "alert level" that indicates the importance of the other flags. These are STATE_SYSTEM_ALERT_LOW, STATE_SYSTEM_ALERT_MEDIUM, and STATE_SYSTEM_ALERT_HIGH. A client can use these alert levels to gauge the information's urgency.


Value Property

The Value property, retrieved by calling the IAccessible::get_accValue method, represents visual information contained by the object or conveys hierarchical information. In most cases, the Value property is used to tell the client about what visual information an object contains. For example, the value for an edit control is the text it contains, but a menu item has no value.

In the case of a tree view control, the Value property provides hierarchical information. The tree view control itself has no Value property, but each item within the control has a zero-based value that represents its level within the hierarchy. Top-level items have a value of 0, second-level items have a value of 1, and so on.

Servers, by way of the IAccessible::put_accValue method, can allow the client to set an object's value. This could be useful if a voice input device or other accessibility aid is trying to let the user easily change the value in an object, like an edit control. If a server doesn't support the IAccessible::put_accValue method, it fails the call by returning S_FALSE.


Description Property

An object's Description property, retrieved by calling the IAccessible::get_accDescription method, provides a textual description for an object's visual appearance. The description is primarily used to provide greater context for low-vision or blind users, but can also be used for context searching or other applications.

All objects should have a description, except in cases where the description is obvious or redundant based on the object's Name, Role, State, and Value properties. A button with the word "OK" does not need additional description, but all graphical objects and controls must have some.

For example, imagine a toolbar containing a button that shows a picture of a cactus. The button's properties describe its role, name, purpose, and so on, but the Description property conveys information that is less tangible, like "A button that shows a picture of a cactus."

Not all objects support the Description property; if the call to get_accDescription returns the DISP_E_MEMBERNOTFOUND value, then no object description is available.


Focus Property

An object's Focus property, retrieved by calling the IAccessible::get_accFocus method, allows clients to discover if a particular accessible object and/or child element has the 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 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.

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 currently highlighted. This only applies to a server creating custom menu code or a user interface that appears to the user as a menu. Active Accessibility provides support for the Win32 menu APIs. Menus created via Win32 APIs and resource files will send the correct events and expose MSAA objects.

Implementers: If the object itself has the keyboard focus, return CHILDID_SELF 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.


Selection Property

An object's Selection property, retrieved by calling the IAccessible::get_accSelection method, allows clients to discover which children within an accessible object are selected.

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 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.

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 currently highlighted. This only applies to server creating custom menu code or a user interface that appears to the user as a menu. Active Accessibility provides support for the Win32 menus APIs. Menus created via Win32 APIs and Resource Files will send the correct events and expose MSAA objects.

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.


DefaultAction Property

An object's DefaultAction property, retrieved by calling the IAccessible::get_accDefaultAction method, describes its primary method of manipulation from the user's viewpoint. Do not confuse the DefaultAction property with the object's Value property. Some controls, such as an edit field, might have a value but not a default action. The following list provides some common examples.

  • A selected check box has a default action of "Uncheck" and a value of "Checked."
  • A cleared check box has a default action of "Check" and a value of "Unchecked."
  • A button labeled "Print" has a default action of "Press," with no value.
  • A static text control or an edit control that shows "Printer" has no default action, but would have a value of "Printer."

The DefaultAction property is primarily for use by voice input and blind access utilities. For example, when a blind access utility encounters a custom control that it does not recognize, it can still provide a significant amount of information to the blind user, such as the object's name (like "Speed"), its role (like "Switch"), its default action, if supported (like "Adjust"), and the current value (like "High"). Of course, the client can also use OLE Automation to enumerate all the properties and methods that the object supports, but there could be very many and most can be obscure, so the DefaultAction property provides a simple method of succinctly conveying the operation that the user will most likely use.

Not all objects support the DefaultAction property; if the call to get_accDefaultAction returns the DISP_E_MEMBERNOTFOUND value, then the object has no default action. For example, objects that don't perform actions, like static text, won't have a default action.


Location Property

The Location property, retrieved by calling the IAccessible::accLocation method, can provide information that tells the user about the object's function. For example, the Location property for a toolbar button would be 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. Currently, the only nonvisual objects are sound objects.


Help Property

The Help property, retrieved by calling the IAccessible::get_accHelp method, can provide information that tells the user about the object's function. For example, the Help property for a toolbar button that shows a printer might be, "Prints the current document." This text is not always unique within the user interface; it acts purely to elaborate on the object's purpose and what actions it might perform.

Not all objects support the Help property; if the call to get_accHelp returns the DISP_E_MEMBERNOTFOUND value, then the object does not support this property.


HelpTopic Property

The HelpTopic property, retrieved by calling the IAccessible::get_accHelpTopic method, retrieves details about a Help file that provides information about an object. This is provided in the form of a string that represents the path to the Help file and a value identifying the topic of interest.

The retrieved values can be used with the Win32 WinHelp function to display a help topic associated with the object.

The path name retrieved might be a network path (like "\\network\share\directory\filename.ext") or a Uniform Resource Locator (URL) to an Internet resource (like "http://www.microsoft.com/enable/helpfile.htm").

See the Windows® 95 SDK documentation on parsing paths for more information.


KeyboardShortcut Property

The KeyboardShortcut property, retrieved by calling the IAccessible::get_accKeyboardShortcut method, describes a key or key combination that will activate a given accessible object.

This shortcut key string can describe "shortcut keys" or "access keys." Each is described in the following list.

Term | Description
Shortcut keys | Key combinations that invoke an action. For example, ctrl + o is often used to invoke the Open file common dialog box.
Access keys | Single keys, usually shown underlined in a drop-down menu or dialog box, that invoke an action when pressed. For example, if a user activates an application's File menu, the o key often invokes the Open file common dialog box. Access keys are usually only available when the container (like a menu) has keyboard focus.

The KeyboardShortcut property reflects shortcuts as the key or keys the user must press when the object has keyboard focus. For example, the Print menu command might have both a shortcut key (ctrl+p) and an access key (p). If the user presses ctrl+p while the menu is active, nothing happens, but pressing p invokes the application's Print dialog box. In this case, the KeyboardShortcut property is "P," to reflect what the user must press when the menu is active and has keyboard focus. This "shortcut by focus" type of philosophy is true for all accessible objects.

Active Accessibility describes key combinations using strings that fit a standard format, allowing utilities to parse them. The format is defined as [modifier key +][...] + key-name. For example: "alt+f", "ctrl+alt+4", "win+f1", "backspace", or "ctrl+alt+shift+backspace".

The modifier keys are:

Modifier key | Description
alt | Alternate modifier key
ctrl | Control modifier key
shift | Shift modifier key
win | Windows Logo key
fn | Function key on portable computers

The server never localizes keyboard shortcut strings. If an accessibility aid enunciates keyboard shortcuts to the user, it can parse them into separate key names and substitute localized names. This functionality would be useful, for example, in a blind access utility reading keyboard shortcuts to the user at the user's request.


Accessible Object Methods

Accessible objects maintain several ways to get information from an object, called "methods," that help communicate the object's appearance, nature, and purpose. The IAccessible interface extends methods allowing an application to retrieve this information about the object.

This section discusses the methods in detail, providing a conceptual overview for each. The following topics are covered.

  • IAccessible::accSelect Method
  • IAccessible::accNavigate Method
  • IAccessible::accHitTest Method
  • IAccessible::accDoDefaultAction Method

You can access each property from C/C++ or Visual Basic® applications. These descriptions examine the properties from a C/C++ perspective.


IAccessible::accSelect Method

The Select method, accessed by calling the IAccessible::accSelect method, modifies the selection or moves the keyboard focus according to the specified flags.

This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

This method returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG
S_FALSE


IAccessible::accNavigate Method

The Navigate method, accessed by calling the IAccessible::accNavigate method, retrieves the next or previous sibling or child object in a specified direction.

This method returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG
S_FALSE

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 fail, returning S_FALSE, after the last or first object is found.

Note 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.

Active Accessibility do 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 we create proxies for do not. You might not be able to navigate to all of an object's children, if they have the flag STATE_SYSTEM_INVISIBLE


IAccessible::accHitTest Method

The HitTest method, accessed by calling the IAccessible::accHitTest method, retrieves the IDispatch interface pointer of a child object at a given point on the screen.

This method returns S_OK if successful or a standard COM error code otherwise.

When this method is used in certain situations, additional usage notes apply. For more information, see Object Navigation.

Note 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.


IAccessible::accDoDefaultAction Method

The DoDefaultAction method, accessed by calling the IAccessible::accDoDefaultAction method, performs the object's default action.

This method returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

You can retrieve the object's DefaultAction method 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.


WinEvents

This section contains information about events generated by accessible objects. The following topics are covered.

  • What Are WinEvents?
  • Who Generates Which Events?
  • About the WinEventProc Callback Function
  • About the Client Server Event Process
  • Verify Events
  • WinEvents for Simple Elements
  • Alerts


What Are WinEvents?

Server applications use "WinEvents" to notify clients about specific operations they perform. Accessible objects send these event notifications by using the NotifyWinEvent function. This function essentially tells Active Accessibility that a specific event occurred, which object the event is associated with, and specifies the child element if necessary. When Active Accessibility is notified, it calls any hook procedure functions that were registered for that event.

Client applications register callback hook procedure functions for these events by using the SetWinEventHook function. Applications can set a single hook function for all possible events, or multiple hooks for discrete ranges of events. Once called, the callback function receives several parameters describing an object, as well as an event constant value identifying the event that the specified object generated. Active Accessibility provides several options for callback functions; for more information, see About the WinEventProc Callback Function.

Note WinEvents only notify clients that an event is occurring or has occurred—clients cannot fail them.


Who Generates Which Events?

There are two classes of events, system level and object level, each with a corresponding event constant value. System-level events describe situations affecting all applications in the system, whereas object-level events pertain to situations specific to an object or objects within one application. System-level event values are macro values whose labels begin with EVENT_SYSTEM; object-level event values begin with EVENT_OBJECT.

Server applications and the operating system both generate WinEvents. The operating system generates both system- and object-level events for systemwide notifications about focus changes, activation changes, system alerts, or for events regarding system objects like common controls. Server applications typically generate object-level events regarding the accessible objects they contain, notifying clients about object creation, destruction, selection, or other object-level events. Remember that the server application should minimize sending redundant messages.

In some cases, server applications will send system-level events. For example, when an application displays a message box by calling the MessageBox Win32 function, the system generates the EVENT_SYSTEM_ALERT system-level event. However, if a server application displays an alert box on its own (without calling MessageBox) it should generate an EVENT_SYSTEM_ALERT event on behalf of the custom window.


About the WinEventProc Callback Function

The WinEventProc callback function is the starting point for most client activity. Active Accessibility calls this hook procedure in response to specific ranges of events that server applications generate. You specify which events a hook procedure is called for when you register it with the SetWinEventHook function.

WinEventProc receives seven parameters. The first, hWinEventHook, is an identifier for the hook procedure, and is provided for reference—you won't usually do anything with it. The second parameter, event, is one of the event constants that describes the type of event that occurred. The next three parameters, hwnd, idObject, and idChild, combine to tell you about the window, object, and possible child element that generated the event. The following table provides additional explanation for these three parameters.

Parameter name | Description
hwnd | Handle to the window where the event originated.
idObject | Object identifier of the object associated with the event. This is one of the object constants, and is set to OBJID_WINDOW if the window itself generated the event.
idChild | Identifier of the child element that generated the event. This is CHILDID_SELF if no child element generated the event.

Generally, a client does little more with these three parameters than use them in an object retrieval call, such as the AccessibleObjectFromEvent function. For more information about identifiers, see Object and Child Identifiers.

The remaining two parameters, idEventThread and dwmsEventTime, provide background information about the thread associated with the event and the time the event occurred.

In-context and Out-of-context Hook Procedures

There are two types of hook procedures, in-context and out-of-context. These terms describe the WinEventProc callback function's memory location relative to the server's address space. An in-context hook procedure is located in a dynamic-link library (DLL) that Active Accessibility maps into the server's address space. Similarly, an out-of-context hook procedure is located in the client's address space, whether it's in the code body or in a DLL.

In-context callbacks receive event notifications synchronously from the server, while out-of-context callbacks receive asynchronous event notifications. As a result, in-context callbacks tend to be very fast, since processing occurs in the server's address space, requiring no marshaling across process boundaries. NOTE: For greatest performance, use In-Context Event Notification and access object properties within the same address space of the object. When using in-context callbacks, client developers must ensure that the provided function doesn't use a lot of processor time, since the server must wait for the callback to return before it can continue.

Since out-of-context callbacks aren't mapped into the server's address space, Active Accessibility marshals across process boundaries, making event notifications asynchronous and causing responses noticeably slower than in-context callbacks. Although the event notifications are asynchronous, Active Accessibility assures that the callback function receives all events in the order they were generated.

Multiple Hook Procedures

You can register multiple hooks to respond to various ranges of events. Therefore, the callback function's label doesn't necessarily need to be "WinEventProc"—it can be anything you want, so long as its argument list and return value are identical to the function declaration for the WinEventProc function.


About the Client-Server Event Process

The client-server event process describes the method by which Active Accessibility enables client applications to establish a direct connection to an accessible object in response to events that the object generated. This process is a bit like a matchmaker setting up a date for two people who don't know each other. For example, the matchmaker has a friend who expressed an interest in dating, and the matchmaker knows another friend who might be compatible. The matchmaker tells both people about each other, handles the initial exchange of phone numbers, and then lets the two arrange a first date on their own. In this analogy, Active Accessibility plays the role of the matchmaker, the server application is the friend who wanted a date, and the client application is the potential match.

This general concept holds true for the client-server event process. When it calls the NotifyWinEvent function, the server application tells Active Accessibility about events it has generated. Active Accessibility checks if any client applications have registered a WinEvent hook and sends the event notification to an appropriate callback procedure. If the client application is interested in the event, it can request access to the generating object by using AccessibleObjectFromEvent, or another accessible object retrieval function. This is the beginning of the so-called "exchange of phone numbers" phase.

When the client calls AccessibleObjectFromEvent, Active Accessibility sends the server application a WM_GETOBJECT message. In response to WM_GETOBJECT, the server application returns a value that acts as a one-time reference to the object that generated the event. Active Accessibility uses this reference to retrieve the address of an object interface such as IAccessible or IDispatch, and gives that address to the client application. Once it has an interface address, the client can directly contact the accessible object to manipulate it or retrieve information as needed.


Verifying Events

If your client application uses asynchronous event hooks (when the hook callback function is in your process and not the server's), it is possible that the window associated with an event no longer exists at the time the hook procedure is called. Therefore, you must verify that the window associated with an event still exists before taking any other action related to the event. To ensure that a window still exists, use the Win32 IsWindow function.

For more information about synchronous and asynchronous event hooks, see About the WinEventProc Callback Function.


WinEvents for Simple Elements

Often, simple elements can generate events. Since these elements are not accessible objects and don't support Active Accessibility, they present a special problem for accessibility aids. Therefore, Active Accessibility places the responsibility of supporting the IAccessible interface on the element's parent object. With every event notification, the client application's WinEventProc hook procedure receives a child identifier in the idChild parameter, which specifies the simple element that generated the event. The accessible object that contains the element supports IAccessible on the child element's behalf. To access information about the child element, specify the child identifier in whatever method you call. If no child is associated with the event, idChild is CHILDID_SELF. For more information, see Object and Child Identifiers. All pertinent IAccessible methods accept the pvarChild parameter specifically for the purpose of finding child objects.


Alerts

Server applications generate the EVENT_SYSTEM_ALERT event to notify accessibility aids that a user interface change has occurred that a user might need knowledge of.

Before Active Accessibility, when an application changed an icon's appearance, accessibility aids had to decide whether or not to inform the user, without a clear idea about the information that the application was presenting. Was the information urgent enough that user's work should be interrupted? Was it moderately important information that the user should be informed about without being interrupted? Or, was it low-priority information that the user could choose to accept or ignore based on preference settings? Now, with Active Accessibility, the accessible object conveys urgency by using object state bits that the client can retrieve by calling the IAccessible::get_accState method.

A visual change normally triggers more than one event. For example, an accessible object generates the EVENT_OBJECT_VALUECHANGE event when its value string changes, and can optionally generate an accompanying EVENT_SYSTEM_ALERT event to indicate to the client that some priority level applies to the previous event.

For more information, see Event Constants and Object State Constants.


Changes to USER

Active Accessibility changes some core operating system components. In the case of Windows 95®, user.exe and user32.dll have been replaced with slightly modified versions to support WinEvents and other accessibility enhancements.

Additionally, USER is now sensitive to screen reader applications. When USER notices that the SPI_GETSCREENREADER bit is on, it changes its behavior as follows:

  • Turns off system modal windows. This is the same as Win16 applications running under Windows NT®. Some applications might behave poorly when system modality is turned off and their window loses focus.
  • Disables the CS_SAVEBITS window class style. This style causes the system to save as a bitmap the portion of the screen image obscured by a window. Windows uses the saved bitmap to recreate the screen image when the window is removed. Windows displays the bitmap at its original location and does not send WM_PAINT messages to windows obscured by the window if other screen actions have not invalidated the stored image. Screen readers that use an offscreen model will benefit from this behavior, because WM_PAINT messages will be sent to the underlying windows when a dialog box, menu, or other window class with the CS_SAVEBITS style is hidden or destroyed.
  • A utility that wants to turn on the Screen Reader flag behavior should call the SystemParametersInfo() API and with the SPI_SETSCREENREADER and SPIF_SENDCHANGE parameters. Since multiple accessibility aids might be setting and resetting this flag, an aid that wants it to be turned on should also monitor its value in case it is turned off by another accessibility aid. You can monitor this flag, along with other system values, by looking for a WM_SETTINGCHANGE message in your message loop.


Display Device Interface Redirection

Active Accessibility exposes system graphics events through display device interface (DDI) redirection. This functionality allows applications to intercept graphics events before they affect the display device. Client applications that hook these events can examine or modify stack parameters related to specific DDI calls, failing the calls if they are unwanted.

  • About DDI Redirection
  • Setting a DDI Hook
  • Unhooking A DDI Hook


About DDI Redirection

Client applications can set a DDI hook by using the SetDDIHook function. This function accepts parameters that describe the hook class, the location of the hook procedure, and private data that will be sent to the hook procedure when a DDI function call occurs. All of an application's DDI hook procedures must be written in a 16-bit DLL.

The hook class describes the type of application that owns the DDI hook procedure. Active Accessibility uses this class to determine the order in which it calls the registered hook procedures. Hook classes are defined in winddi.h and are called in the following descending order. This is because each step depends on what the DDI function's screen changes.

Class | Description
DDIHOOK_RECORDER | Screen readers and screen capture utilities.
DDIHOOK_REMOTE | Remoting utilities.
DDIHOOK_FONTS | Font enhancers.
DDIHOOK_MAGNIFIER | Screen magnifiers.

If multiple hooks are registered for a given class, Active Accessibility still uses the preceding order, but sends event notifications within a class to the most recently registered hook procedures first.

When Active Accessibility calls a DDI hook procedure, it receives parameters describing the DDI hook instance, the type of DDI function being called, and the address of a DDI stack structure. DDI stack structures, defined in winddi.h, are the parameters being passed to the specified DDI function as they exist on the stack. The hook procedure can examine these values, change them if necessary, and pass the event by calling the CallNextDDI function and using that return value as its own return. This function returns control to Active Accessibility, which sends event notifications to other registered hook procedures, finally calling the DDI function when all hook procedures have been notified and have passed the call. If a callback procedure changes a stack value, the new value will be reflected by any subsequent DDI hook procedures. If a hook procedure doesn't call CallNextDDI, the DDI function fails and never reaches the display device.


Setting a DDI Hook

You can set a DDI hook procedure by calling the SetDDIHook function. This function accepts five parameters. The first, hdcHook, is unused and must be set to NULL. The second parameter, hModCode, is a handle to the module that contains the hook procedure. This module must be a 16-bit DLL. Use the GetModuleHandle Win32 function to retrieve the module handle. The third parameter, lPrivateData, accepts a 32-bit value that will be passed to the hook procedure when an event occurs. The fourth parameter, hookClass, describes the type of application that the hook procedure belongs to. The last parameter, lpfnDdiHook, is the address of the hook procedure that Active Accessibility calls in response to DDI events.

The SetDDIHook function returns an HDDI value. This value is provided to identify the event hook and acts as the handle accepted when unhooking the event hook. For more information, see Unhooking a DDI Hook.


Unhooking a DDI Hook

When your application no longer needs a DDI hook, you can call the UnhookDDIHook function to remove it. This function accepts a single parameter, hddi, that identifies the event hook that will be removed. This value is returned when the hook was set by calling the SetDDIHook function. For more information, see Setting a DDI Hook.


Simulating Input

Applications can use Active Accessibility's SendInput function to simulate an uninterrupted series of user input events. SendInput provides the same functionality as the mouse_event, keyboard_event, and hardware_event Win32 functions. The SendInput function accepts three parameters. The first parameter, cInputs, indicates the number of input events that will be simulated. The second parameter, rgInputs, is the base address of an array of INPUT structures, each describing a type of input event and additional information about that event. The last parameter, cbSize, accepts the size of the INPUT structure, in bytes.

SendInput works by injecting a series of simulated input events into a device's input stream. The effect is similar to calling the keybd_event or mouse_event Win32 functions repeatedly, except that the application ensures that no other input events intermingle with the simulated events. When the call completes, the return value indicates the number of input events successfully played to the system. If this value is zero, then input was blocked.

The SendInput function does not reset the keyboard's current state. Therefore, if the user has any keys pressed when you call this function, they might interfere with the events that this function generates. If you are concerned about possible interference, check the keyboard's state with the GetAsyncKeyState Win32 function and correct as necessary.


Developing Applications that Use Active Accessibility

This section provides information useful to accessibility aid developers. Information is divided into the following topics.

  • Active Accessibility Clients
  • Setting a WinEvent Hook
  • Getting an Accessible Object Interface Pointer
  • Selecting Child Objects
  • Active Accessibility Client Tutorial
  • Including Active Accessibility with your Accessibility Aids for Client Applications
  • Writing Platform Independent Applications


Active Accessibility Clients

Any application that uses Active Accessibility to gain information about objects is considered a client. Typically, clients are accessibility aids, such as screen readers, screen enlargement utilities for low-vision users, and speech recognition utilities. However, Active Accessibility provides technology useful to many types of applications. For example, testing tools can use Active Accessibility to query the state of applications and objects. Development tools, such as object browsers, might need the run-time information that Active Accessibility provides.

To implement an Active Accessibility client, you must know how to call an accessible object's IDispatch or IAccessible interface methods. For more information on IDispatch, see IDispatch Interface.


Setting a WinEvent Hook

To set a WinEvent hook, you must register a hook procedure by calling the SetWinEventHook function. This function accepts seven parameters that describe the events you want notifications for, the location of the event hook procedure, and other environment variables. The first two parameters, eventMin and eventMax, are event constant values that inclusively declare the lower and upper events you want notifications about. The third parameter, hmodWinEventProc, accepts a handle to the module that contains an in-context hook procedure—this parameter is ignored if the WINEVENT_INCONTEXT flag isn't specified. The fourth parameter, lpfnWinEventProc, is the address of the function that Active Accessibility will call when any of the requested events occurs. The fifth and sixth parameters, idProcess and idThread, are used to identify the specific process and thread to be monitored; setting these to zero indicates that you want to monitor all processes and threads. The last parameter, dwflags, is a bit field that you can use to specify receiving parameters.

The following code fragment, taken from the inspect.cpp file included with this SDK, removes a preexisting event hook or sets a new one. The new hook procedure is called for a specific event (EVENT_OBJECT_FOCUS), is out-of-context, and applies to all threads and processes.

// Set up an event hook.
  hEventHook = SetWinEventHook(EVENT_MIN,         // We want all events
                               EVENT_MAX,
                               GetModuleHandle(NULL),// Use this module
                               WinEventProc,
                               0,        // All processes
                               0,        // All threads
                               WINEVENT_OUTOFCONTEXT);
    // Did we install correctly?

    if (hEventHook)
        return(TRUE);

    // Did not install properly - fail
    return(FALSE);

For more information, see WinEvents and About the WinEventProc Callback Function.


Getting an Accessible Object Interface Pointer

This section contains information about the various ways that Active Accessibility client applications can retrieve interface pointers to accessible objects. The following topics are discussed.

  • Using AccessibleObjectFromEvent
  • Using AccessibleObjectFromPoint
  • Retrieving the Object with Keyboard Focus
  • Retrieving Selected Objects and Children


Using AccessibleObjectFromEvent

Many client applications need to look up information about specific accessible objects that have generated events. Since the IAccessible interface is the "gateway" to accessible objects, clients must have an easy way to associate WinEvents with the IAccessible interface of the object generating the events. Active Accessibility provides the AccessibleObjectFromEvent function specifically for this purpose. Other times, a client might want to access to an object based on its location, or window handle. Active Accessibility provides the AccessibleObjectFromPoint and AccessibleObjectFromWindow functions.

AccessibleObjectFromEvent accepts much of the same information that a client application receives with an event notification. In effect, when a client hook procedure receives an event notification, it can "recycle" most of the parameters it receives with the notification to call the AccessibleObjectFromEvent function and retrieve the generating object's IAccessible interface pointer.

The AccessibleObjectFromEvent function accepts five parameters total. The first three parameters, hwnd, dwId, and dwChildId, receive information taken directly from the WinEventProc callback function. The hwnd parameter receives the callback function's hwnd parameter, the dwId parameter gets the idChild parameter. The remaining two parameters that AccessibleObjectFromEvent accepts will contain the address of an object's IAccessible interface and a status value. The status value, received in the pvarChild parameter, indicates whether the provided interface belongs to the object that generated the event or its parent object. If a parent object is specified, then the server assumes the responsibility of supporting IAccessible for the child object.

AccessibleObjectFromEvent increases an object's reference count, and must have a corresponding Release to lower the reference count. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it quits: As with usual OLE Automation objects, Word will quit and Active Accessibility will CoDisconnect the object so that if anyone tries to access it cross-process after the application quits, OLE will return an error. A reference count on a Active Accessibility object does not reference count the application.


Using AccessibleObjectFromPoint

Accessibility aids can use the AccessibleObjectFromPoint function to retrieve the address of an object's IAccessible interface. This function accepts three parameters that describe a point on the screen, and two output variables used to state the call's result. The first parameter, ptScreen, is a POINT structure that describes the x- and y-coordinates of the on-screen location to be tested. The second parameter, ppacc, is the address of a variable that will contain an IAccessible interface pointer. The last parameter, pvarChild, is the address of a VARIANT structure that will contain a value that describes the call's result. The vt member is always set to VT_I4, which means that the lVal member contains the value you need. Since it's possible that the item at the point you specified was over a simple element, the value in lVal tells you whether the retrieved interface pointer belongs to an object at the specified point, or to a simple element's parent object. If lVal is nonzero, then the function retrieved an interface pointer to a simple element's parent object; if lVal is zero, then the retrieved interface belongs to the object itself.

AccessibleObjectFromPoint increases the an object's reference count, and must have a corresponding Release(); . Even though an object's reference count is greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it quits: As with usual OLE Automation objects, Word will quit and Active Accessibility will CoDisconnect the object so that if anyone tries to access it cross-process after the application quits, OLE will return an error. A reference count on a Active Accessibility object does not reference count the application.

The following code fragment provides an example of how to use the AccessibleObjectFromPoint function.

// For this example, assume that the g_szName variable
// is defined as a global LPTSTR variable.

// Get the current cursor location.
POINT ptCursor
GetCursorPos(&ptCursor);

// Setup variables for interface pointers and return value.
IUnknown*    punk    = NULL;
IAccessible* pOleAcc = NULL;
HRESULT      hr;
VARIANT      varChild;

// See if there is an accessible object under the cursor.
hr = AccessibleObjectFromPoint(ptCursor, &pOleAcc, &varChild);
if (SUCCEDED(hr))
{
    // Query on the object's name.
    BSTR bstrName = NULL;
    hr = pOleAcc->get_accName(varChild, &bstrName);

    // If a name was returned without error,
    // convert it to an OLE Unicode string.
    if (bstrName && SUCCEDED(hr))
    {
        WideCharToMultiByte(CP_ACP, 0, bstrName,-1, g_szName,
            cchName, NULL, NULL);
        SysFreeString(bstrName);
    }
}


Retrieving the Object with Keyboard Focus

By using the IAccessible::get_accFocus method, you can retrieve the child object that has keyboard focus. Keep in mind that only one object in the system at a time can have keyboard focus. This method accepts the address of a single VARIANT structure, which it fills to represent the call's result. After making the call, you can look at the value in the structure's vt member to find the result.

If a child object has keyboard focus, then the vt member is set to VT_I4 or VT_DISPATCH. This value tells you whether to look for information in the form of a child ID or an IDispatch interface pointer, held in the lVal or pdispVal members, respectively. If the object had no children with keyboard focus, the vt member will be VT_EMPTY.

Do not confuse object focus with object selection. For more information, see Accessible Object Selection and Focus and Retrieving Selected Objects and Children. For more information about the VARIANT structure, see VARIANT Structure.


Retrieving Selected Objects and Children

By using the IAccessible::get_accSelection method, you effectively ask an object to retrieve information about any of its currently selected children. This method accepts the address of a single VARIANT structure, which it fills to represent the number of selected objects and indicate the type of information retrieved. After calling get_accSelection, you can use the value in the vt member to determine the call's result.

If one object is selected, then the application sets the vt member to VT_I4 or VT_DISPATCH. This value tells you whether to look for information in the form of a child ID or an IDispatch interface pointer, held in the lVal or pdispVal members, respectively. It is possible that the object you're working with has no children, but is selectable. In this case, vt will be VT_I4 and the lVal member will be CHILDID_SELF.

If multiple objects were selected, getting information about them is a little more complex. The server that handled your get_accSelection call sets the vt member to VT_UNKNOWN and the punkVal member to a valid IUnknown interface pointer. You can call this interface's QueryInterface method to request an IEnumVARIANT interface, which you can use to enumerate the selected objects. The IEnumVARIANT interface provides a method for enumerating a collection of variants, including heterogeneous collections of objects and intrinsic types. It is the server's responsibility to support this interface to allow you to enumerate the selected children. This is the preferred method.

Do not confuse selection with focus. Any or all objects in the system can simultaneously have selected children, but only one can have keyboard focus. For more information, see Accessible Object Selection and Focus and Retrieving the Object with Keyboard Focus.


Selecting Child Objects

Applications call the IAccessible::accSelect method to modify selection or keyboard focus among the child object(s) within the current object. The flags you specify with the call define the operation you want to perform.

The following list describes how you can use IAccessible::accSelect to perform complex selection operations.

To simulate a click:
 | Specify the SELFLAG_TAKEFOCUS flag.
To simulate ctrl + click:
 | To select the target item, specify a combination of the SELFLAG_TAKEFOCUS and SELFLAG_ADDSELECTION flags. Or, to cancel selection of the target item, call the method specifying a combination of the SELFLAG_TAKEFOCUS and SELFLAG_REMOVESELECTION flags.
To simulate shift + click:
 | Call ::accSelect, specifying a combination of the SELFLAG_TAKEFOCUS and SELFLAG_EXTENDSELECTION flags.
To select a range of objects:
 | This requires two calls: in the first, specify SELFLAG_TAKEFOCUS on the starting object; in the second, specify a combination of SELFLAG_EXTENDSELECTION and SELFLAG_TAKEFOCUS on the last object.
To cancel selection of all objects:
 | Specify a combination of SELFLAG_REMOVESELECTION and SELFLAG_TAKEFOCUS.


Active Accessibility Client Tutorial

The Active Accessibility SDK includes a simple client application, called Babble. In addition to Babble's executable file, the SDK includes the sample's source code, header files, and Microsoft® Visual C++® project workspace files. This tutorial sequentially discusses the tasks that Babble performs and, in doing so, presents the basic information you need to develop your own Active Accessibility client application.

The tutorial contains the following steps.

  • About the Babble Sample Application
  • Step 1: Initialize the COM Library
  • Step 2: Set a WinEvent Hook
  • Step 3: Respond to Event Notifications
  • Step 4: Close the COM Library

Additionally, the following topic contains background information.

  • Converting Unicode and ANSI Strings


About the Babble Sample Application

Babble is a simple application that provides information about accessible objects and announces environment changes regarding focus and activation events. Babble combines Active Accessibility technology and the Microsoft Speech SDK to vocalize events and object information to the user. This sample uses both WinEvent and standard keyboard hooks to capture events related to accessible objects and global keyboard events. As a result, the Babble project workspace includes a "Babhook" project for the DLL code to grab all keyboard events.


Step 1: Initialize the COM Library

Before you can start using Active Accessibility's features, you must initialize the Component Object Model (COM) library by calling the CoInitialize OLE function. Babble calls this function before initializing the text to speech engine in its InitTTS application-defined function. InitTTS does several things specific to the speech engine after initializing COM, but the following code fragment illustrates how it calls CoInitialize.

// Attempt to initialize OLE.
if (FAILED(CoInitialize(NULL)))
    return FALSE;

CoInitialize accepts only one parameter, pvReserved, that must always be set to NULL. The function returns a value that indicates success or failure—Babble uses the FAILED macro to test for a failure condition. If the call fails, then COM could not be initialized and application cannot successfully run. FAILED is a macro found in the COM interface.


Step 2: Set a WinEvent Hook

After initializing the COM library, you must set a WinEvent hook by calling the SetWinEventHook function. The Babble application calls this function in its InitMSAA application-defined function. The following code illustrates how to call SetWinEventHook.

BOOL InitMSAA(void) {
  // Set up an event hook.
  hEventHook = SetWinEventHook(EVENT_MIN,         // We want all events
                               EVENT_MAX,
                               GetModuleHandle(NULL),// Use this module
                               WinEventProc,
                               0,        // All processes
                               0,        // All threads
                               WINEVENT_OUTOFCONTEXT);
    // Did we install correctly?
    if (hEventHook)
        return(TRUE);

    // Did not install properly - fail
    return(FALSE);
}

Note InitMSAA specifies the EVENT_MIN and EVENT_MAX event constants. This causes Active Accessibility to notify the hook procedure for all possible events. Additionally, InitMSAA tests the returned hook identifier to determine if the hook was successfully installed. If the return value is non-NULL, then the call succeeded.

For more information, see WinEvents.


Step 3: Respond to Event Notifications

Once a WinEvent hook is successfully in place, your hook procedure will begin receiving event notifications. The following function, taken from the Babble sample application, shows an example of how a hook procedure can receive event notifications and process them.

void CALLBACK WinEventProc(HWINEVENTHOOK hEvent, DWORD event,
    HWND hwndMsg, LONG idObject, LONG idChild, DWORD idThread, DWORD dwmsEventTime)
{
    // What type of event is coming through?
    switch (event) {
        case EVENT_OBJECT_FOCUS:
            // Focus is changing.
            OnFocusChangedEvent(event, hwndMsg,
                                idObject, idChild,
                                dwmsEventTime);
            break;
        }
    return;
}

For simplicity, Babble's WinEventProc function responds only to EVENT_OBJECT_FOCUS events, calling another application-defined function to process them (your client application would probably respond to far more events). When the hook procedure receives an EVENT_OBJECT_FOCUS event, Babble calls the following OnFocusChangedEvent application-defined function to retrieve an interface pointer based on the information Babble received with the notification.

BOOL OnFocusChangedEvent(DWORD event, HWND hwnd,
    LONG idObject, LONG idChild, DWORD dwmsTimeStamp)
{
    VARIANT      varChild;
    IAccessible* pIAcc;
    HRESULT      hr;
    int          cchName = 128;
    TCHAR        tszName[128];
    TCHAR        tszSpeak[1024];

    // Important to init variants
    VariantInit(&varChild);

    hr = AccessibleObjectFromEvent(hwnd, (DWORD)idObject, (DWORD)idChild, &pIAcc, &varChild);

    // Check to see if we got a valid pointer
    if (SUCCEEDED(hr))
    {
        OBJINFO objCurrent;

        objCurrent.hwnd = hwnd;
        objCurrent.plObj = (long*)pIAcc;
        objCurrent.varChild = varChild;

        GetObjectName(&objCurrent, tszName, cchName);

        wsprintf(tszSpeak, "Focus now %s.", tszName);

        SpeakString(tszSpeak);

        if (pIAcc)
             pIAcc->Release();

        return(TRUE);
     }

     // No object was retrieved, so send a failure value.
    return(FALSE);
}

OnFocusChangedEvent uses the AccessibleObjectFromEvent function to retrieve information about the object that generated the event. Note that AccessibleObjectFromEvent doesn't accept an event value. At first this might seem odd, but Babble already knows about what event happened; now it needs information about who generated it. Knowing this, it makes sense that AccessibleObjectFromEvent only needs information about the window, object, and child element associated with the event. Also note that Babble initializes the VARIANT structure it sends with the function call to comply with OLE Automation standards.

When AccessibleObjectFromEvent returns, Babble tests the return value with the SUCCEEDED macro. SUCCEEDED is a macro found in the COM interface. If the call succeeded, it uses Microsoft Speech SDK API elements to vocalize the event, then releases the retrieved interface by calling its IUnknown::Release function. This step is required to meet COM standards.


Step 4: Close the COM Library

When your application no longer needs COM services, use the CoUninitialize OLE function to close the COM library. Closing the COM library is required by COM standards; failing to do so will result in memory leaks. Babble calls CoUninitialize when it closes the text to speech engine in its UnInitTTS application-defined function.


Converting Unicode and ANSI Strings

Active Accessibility uses Unicode strings, as defined by the BSTR data type. If your application does not use Unicode strings, or if you want to convert strings for certain API calls, use the MultiByteToWideChar and WideCharToMultiByte Win32 functions to perform necessary conversion. You can use WideCharToMultiByte to convert a Unicode string to an ANSI string; the MultiByteToWideChar function does the opposite. The Babble sample application uses the WideCharToMultiByte function in several places to perform Unicode to ANSI string conversion. The following application-defined function, from the Babble sources, illustrates how to properly call the function.

DWORD GetObjectName(LPOBJINFO poiObj,LPSTR lpszBuf, int cchBuf)
{
    DWORD dwRetVal;
    BSTR  bszName;
    IAccessible* pIAcc;
    long* pl;

    bszName = NULL;

    // Get the object out of the structure.
    pl = poiObj->plObj;

    pIAcc =(IAccessible*)pl;

    // Get the object's name.
    pIAcc->get_accName(poiObj->varChild, &bszName);

    // Did we get name string?
    if (bszName)
    {
        // Convert the string Unicode to ANSI.
        if (WideCharToMultiByte(CP_ACP, 0,
                            bszName,
                            WC_SEPCHARS, // -1
                            lpszBuf,
                            cchBuf,
                            NULL, NULL))
        {
            SysFreeString(bszName);

            dwRetVal = NO_ERROR;
        }
        else
        {
            dwRetVal = GetLastError();
        }

        return(dwRetVal);
    }

    // Need general failure handling routine
    MessageBeep(MB_ICONEXCLAMATION);

    return(ERROR_INVALID_FUNCTION);
}

For more information about these string conversion functions, see their references in the Platform SDK.


Including Active Accessibility with your Accessibility Aids for Client Applications

You can get Active Accessibility in two forms. The first is this Active Accessibility Software Development Kit (SDK). The Active Accessibility SDK enables developers to create accessibility aids and accessible applications using the Active Accessibility technology. The SDK includes the core components, new dynamic-link libraries (DLLs), sample source code, libraries, header files, sample applications, and documentation. Additionally, the Active Accessibility Redistribution Kit is available. This kit includes the core components and new DLLs, which you can ship with an accessibility aid or accessible application.

If an independent software vendor (ISV) wants to incorporate Active Accessibility in a product, he or she must redistribute the Redistribution Kit. This self-installing package presents no user interface and ensures that the core components are installed correctly.

Typically, an accessibility aid's installation program will execute the Redistribution Kit software as a final step, and then exit. The Redistribution Kit unpacks the various components, performs version checking, registers the IAccessible interface, and restarts the machine to complete the installation.

Note ISVs are not allowed to set up the Active Accessibility components individually. The license agreement provided with the SDK and Redistribution Kit allows Active Accessibility to be distributed only through the Redistribution Kit.

The following table lists the components that comprise the Redistribution Kit.

Component Name | Description
Comctl32.dll | New functionality to support WinEvents
Gdi.exe | New functionality for DDI Redirector
Gdi32.exe | 32-bit version of Gdi.exe
Oleacc.dll | Provides helper functions, marshaling support, and providers for system components
Oleaut32.dll | Newer version than what shipped with Windows 95 to support marshaling of interfaces
Stdole2.tlb | Companion to Oleaut32.dll
User.exe | New functionality for WinEvents and screen reader behavior changes.
User32.dll | 32-bit version of User.exe


Writing Platform Independent Applications

The first release of Microsoft Active Accessibility supports Microsoft Windows 95 only; however, clients and servers might need to run on Windows NT® as well. Active Accessibility introduces new APIs that are not yet available on the Windows NT platform. As a result, instead of relying on import libraries to call new APIs, an MSAA application should use GetProcAddress to dynamically address new USER functions.

For example, an application that wants to use NotifyWinEvent should call GetProcAddress() using the module handle of USER to get the address of the API. If the call is successful, meaning that this version of Windows supports MSAA, then the application can set a flag indicating that it is safe to call NotifyWinEvent. The address received from GetProcAddress() can be stored in a function pointer variable and used throughout the code. See the sample source code for the server application for details.


Developing Active Accessibility-enabled Applications


Active Accessibility Server Tutorial

The Server sample application (Server.exe) was written purposely to be inaccessible. It does, however, expose the Active Accessibility interface to allow a client to operate it. It takes left mouse clicks to select an object from the dialog box's choices of icons. There are no menu choices. If the #define KEYBOARD_SUPPORT is used, then the left and right arrows are enabled, along with the spacebar.

Note: A server application developer should have what parent-child reciprocity : While Parent A's child is Child X (obtained by ::accNavigate NAVDIR_FIRSTCHILD or NAVDIR_LASTCHILD, or ::accChild), and while ::accParent on Child X is Parent B, Parent A is expected to equal Parent B.

Server application developers must remember to eliminate sending redundant messages to client applications, because this is a major performance issue If a control is constantly being updated, a EVENT_OBJECT_VALUECHANGE or EVENT_OBJECT_STATECHANGE should only be sent if the value or state is different that the previous value. For example, if text field repaints every second, the EVENT_OBJECT_VALUECHANGE should only be sent when the actual contents change, not each second.

In addition to Server's executable file, the SDK includes the sample's source code, header files, and Microsoft® Visual C++® project workspace files. This tutorial sequentially discusses the tasks that Server performs and, in doing so, presents the basic information you need to develop your own Active Accessibility server application.

The tutorial contains the following steps.

  • About the Server Sample Application
  • Step 1: Initialize the COM Library
  • Step 2: Handle WM_GETOBJECT Messages
  • Step 3: Close the COM Library

Additionally, the following topic contains background information.

  • Converting Unicode and ANSI Strings


About the Server Sample Application

Server is a simple application that provides information about accessible objects and returns the information as an LRESULT. Server uses Active Accessibility technology. This sample uses only the mouse to select accessible objects.


Step 1: Initialize the COM Library

Before you can start using Active Accessibility's features, you must initialize the Component Object Model (COM) library by calling the OleInitialize(NULL) OLE function. Server calls this function before it can receive WM_GETOBJECT messages.

// Attempt to initialize OLE.
OleInitialize(NULL);


Step 2: Handle WM_GETOBJECT Messages

After initializing the COM library, the server will idle until it has a WM_GETOBJECT message to process. The object, if found, is returned in the LRESULT of the message; otherwise NULL is returned.

MainWndProc(HWND hwnd, UINT uMsg, WPARAM wParam, LPARAM lParam)
{
    switch (uMsg)
    {

        case WM_GETOBJECT:
            if (fShuttingDown)
                return(NULL);

            return(GetObjectPointer(hwnd, wParam, lParam));

}


Step 3: Close the COM Library

When your server no longer needs COM services, use the OleUninitialize(); function to close the COM library. Closing the COM library is required by COM standards; failing to do so will result in memory leaks.

// Attempt to close OLE.
OleUninitialize();


Using Outlines and Lists

The Name property of an OUTLINEITEM is the string displayed, or the name by which an item would be referred. (Or, we could use Value for this...an open issue.)

In an OUTLINE object, indentation levels are represented by making the indented item's children of the item one level higher. Thus, enumerating the children of an OUTLINE object yields only the first-level OUTLINEITEMs. Enumerating the children of a first-level object reveals the second-level objects grouped underneath it. Note that you cannot determine an item's indent level directly, you must walk up the chain of parents until you reach an OUTLINE object.

In some cases an outline might skip one or more levels. In that case an invisible OUTLINEITEM object must be created to represent each level that has no items.

Alternatively, we could state that the accValue (or accName...to be decided) of an outlineitem object is its indentation level. That would remove the need for invisible placeholder objects when indentation levels are skipped. Note, however, that because levels can be skipped, a client cannot assume that the indentation levels alone convey the parent-child relationships. That is, you cannot assume that a third-level item is actually the child of the second-level item that precedes it.

Also note that an OUTLINEITEM can contain objects that are not additional OUTLINEITEMs. For example, the standard Windows tree view control displays a check box (displaying a plus or minus symbol) to the left of each item that has child items. When this is exposed via OLE Accessibility, the checkbox would be a child of the outline item. Any child of an OUTLINEITEM that is not itself an OUTLINEITEM is assumed to be a component of the item itself. (Alternatively, we could recommend that each compound item be a child of a GROUPING object. In that case, children of OUTLINEITEMs would be limited to other OUTLINEITEMs and GROUPINGs. This arrangement makes icons, check boxes and other decorations peers to the outline item rather its children. There seem to be pros and cons to both approaches.)

If a client wishes to enumerate the contents of an outline in top-to-bottom order, it must recurse through the contents of each child in turn. There is no single list of all the items.

LIST objects are a degenerate case of OUTLINE objects. In essence a LIST is an OUTLINE with only one level, and all LISTITEM objects are children of the LIST object. Clients can be much more efficient when dealing with a LIST, because they can enumerate the contents using accChild or accNavigate with NAVDIR_NEXT.

There is no need for recursive code. However, as with OUTLINEITEMs, LISTITEM objects can have children such as check boxes and icons that are actually a part of a complex item's visual presentation.

Clients should also keep in mind that LIST and OUTLINE objects are not limited to conventional, one-dimensional displays with the root at the top. Applications have complete freedom of visual presentation. In fact, an OUTINE object can be displayed much like a flow chart, with items scattered seemingly without pattern. Therefore clients should always rely on the accLocation property of each item rather than assuming a constant direction or visual style.


Related Text Regions

When an object has several regions of text that actually present a single text-stream, such as text broken into multiple columns, it should expose this relationship to accessibility aids through the use of NAVDIR_NEXT and NAVDIR_PREVIOUS ordering. In addition, it should set the STATE_TEXT_CONTINUED attribute on all but the first region, and STATE_TEXT_CONTINUES attribute on all but the final region.


Animated or Moving Objects

The STATE_SYSTEM_ANIMATED flag is used to mark an object whose appearance is changing rapidly or constantly. Blind access utilities can use this flag to avoid notifying the user repeatedly for what is really a single series of visual changes.

A special case of this is marquee text; that is, text that is progressively disclosed as it scrolls across a region. Such objects should be given the attribute of STATE_SYSTEM_ANIMATED. In most cases the object's Value property string should reflect the entire text, even the portion that is not currently visible. If the Value string is changed too frequently, a blind access utility might not be able to convey it usefully to the user.

Example: A window contains a rectangular region in that shows the word "Cool!" moving around in a figure-eight pattern. (This can be implemented using AVI files or through other means.) This object's Role property would be GRAPHIC, its Value property would be the string displayed, and its LOCATION would be the bounding rectangle, and it would have the STATE_SYSTEM_ANIMATED attribute flag set. (STATECHANGE events would also be generated when the object started or ceased animating.) Its Description property should also be something like "The word 'Cool!' is moving about the screen in a figure-eight pattern."


Returning Object Pointers

Child, Focus, and Selection can all return pointers to objects. This is done using a variant structure, and specifying the variant type as VT_DISPATCH.


Table Objects

Tables are potentially very complicated, but are also an extremely important part of accessibility. They are everywhere, and today they are often inaccessible. We expect to define a new object class in the future to handle complex tables, but the current Active Accessibility architecture is sufficient to handle the vast majority of cases.

A table should be represented as an object with role TABLE. It has children with CELL objects, whose name identifies their locations (such as "A1" or "1996"). As noted elsewhere, appropriate names are a very useful part of this process.


Next and Previous Ordering

For objects that have screen locations, NAVDIR_NEXT and NAVDIR_PREVIOUS should traverse them in an order that the user will consider 'reasonable'. In most cases that means in a left-to-right, top-to-bottom ordering (in English-speaking countries), but in other cases it could be based on front-to-back or proximity or even alphabetical ordering, depending on the nature of the container.

For objects that do not have defined screen locations, the order is entirely up the application and clients should make no assumptions about this ordering. It is acceptable for non-visible objects, such as GROUPING objects or objects that are only temporarily hidden, to be interspersed with visible objects.

Next and Previous should always visit all visible child belonging to the parent object. Each child should be visited only once. A voice input or macro utility should be able to implement generic next and previous commands that obey those restrictions and so are "well behaved" from the user's perspective. Certainly a Next command that got you into an infinite loop while only visiting two objects in the container would not meet the user's expectations.

By extension, Next and Previous should not loop around. They should fail when attempting to move before the first object or after the last object.

The order used by Navigate is not necessarily the indexing order used with Child.


Notification Ordering

Order is important: applications should always perform the stages of an alert in the following order:

  1. Adjust the visual presentation of the object (for example, change the icon to red)
  2. Set the alert level state flag for the object (the icon object)
  3. Send any appropriate events related to the appearance change (for example, APPEARANCECHANGE or OBJECTCREATE for the icon object)
  4. Send the ALERTLEVELCHANGE event with a reference to the object that is presenting the alert (for example, the icon object)
  5. When the client receives the ALERTLEVELCHANGE event it should be able to query the alert status of the referenced object immediately.

The same thing is repeated if and when the object is changed to no longer be in the alert state. For example, when the battery indicator icon changes to yellow, its STATE_SYTEM_ALERT_MEDIUM flag is set, and the EVENT_SYSTEM_ALERTLEVELCHANGE message has been sent referencing this icon object. When the indicator changes back to green, its STATE_SYSTEM_ALERT_MEDIUM flag is cleared (so that none of the alert flags are set), and another EVENT_SYSTEM_ALERTLEVELCHANGE message is sent. A client receives this event, checks the icon object's state flags, finds that none are set, and realizes that this notification indicated that the alert level on this object has completed.


Avoiding Race Conditions

It is important to avoid race conditions where a client tries to talk to an object before it is fully initialized or after it is beginning to close down. Active Accessibility containers should not respond to the WM_GETOBJECT message until fully able to respond to requests from the clients. For example, the system will send EVENT_OBJECT_CREATE on the creation of a new window, but before the WM_CREATE message is sent to the window. Since many applications use WM_CREATE to start their initialization process, it would not be wise for the window to respond to the WM_GETOBJECT message until it has processed the WM_CREATE message. Conversely, clients should be aware that the AccessibleObjectFromWindow, AccessibleObjectFromPoint functions might fail if called in response to an EVENT_OBJECT_CREATE. The recommendation is to watch for SHOW and HIDE events rather than CREATE and DESTROY. Objects should be sure to use SHOW and HIDE to bracket their active lifetime.


Sample Applications

This release of Active Accessibility includes sample implementations of Active Accessibility clients and servers. Samples are all written using C++. The following samples are included.

  • Inspect Objects
  • Accessible Event Watcher
  • Snapshot Utility
  • Input Applet
  • DDIHook Applet
  • OACSpy Applet
  • Server Applet
  • Babble Applet
  • VBINSP


Inspect Objects

The Inspect Objects (Inspect.exe) sample hooks global keystroke combinations, even when it is not the active application. The sample has several shortcut keys you can use to activate its various options.

Key combination | Menu command | Action
ctrl+shift+f2 | Get Properties | Retrieves the object properties of the object under the cursor.
ctrl+shift+f3 | Do Default Actions | Invokes the default action of the object under the cursor.
ctrl+shift+f4 | Select | Selects the object under the cursor.
ctrl+shift+f5 | Focus | Sets the keyboard focus to the object under the cursor.
ctrl+shift+f6 | Move to Next | Moves the cursor to the next object in logical order from the one under the cursor.
ctrl+shift+f7 | Move to Previous | Moves the cursor to the previous object in logical order from the one under the cursor.
ctrl+shift+f8 | Move Left | Moves the cursor to the peer object to the left of the one it is over.
ctrl+shift+f9 | Move Above | Moves move the cursor to the peer object above the object it is over.
ctrl+shift+f10 | System Menu | Bring up the system menu.
ctrl+shift+f11 | Move Right | Moves the cursor to the peer object to the right of the one it is over.
ctrl+shift+f12 | Move Below | Moves the cursor to the peer object below the one it is over.

When performing object navigation, the application will produce a beep if no object is available to move to.

Other options for this sample application are accessed through the sample's system menu. The Watch Focus command instructs the sample to follow the keyboard focus; the Watch Caret command tells the sample to follow the caret. When Watch Focus is on, the sample installs an asynchronous focus event hook, and moves the caret to the top left of the object with the focus. This causes Inspect to refresh its properties in about one second.

Something to keep in mind, that Inspect always uses the screen location to navigate from.

When using Office '97, an out-of-context procedure has better performance than an in-context procedure does. An in-context hook procedure is located in a dynamic-link library (DLL) that Active Accessibility maps into the server's address space. Similarly, an out-of-context hook procedure is located in the client's address space, whether it's in the code body or in a DLL.


Accessible Event Watcher

The simple Accessible Event Watcher (Accevent.exe) application logs the following types of events as they occur within the system.

Event Type | Event Name
Creation or Destruction | EVENT_OBJECT_CREATE, EVENT_OBJECT_DESTROY
Location | EVENT_OBJECT_REORDER, EVENT_OBJECT_PARENTCHANGE, EVENT_OBJECT_LOCATIONCHANGE
State | EVENT_OBJECT_STATECHANGE, EVENT_OBJECT_SHOW, EVENT_OBJECT_HIDE
Focus or Selection | EVENT_OBJECT_FOCUS, EVENT_OBJECT_SELECTION, EVENT_OBJECT_SELECTIONADD, EVENT_OBJECT_SELECTIONREMOVE, EVENT_OBJECT_SELECTIONWITHIN
Description | EVENT_OBJECT_NAMECHANGE, EVENT_OBJECT_VALUECHANGE, EVENT_OBJECT_DESCRIPTIONCHANGE
Other | EVENT_OBJECT_HELPCHANGE, EVENT_OBJECT_DEFACTIONCHANGE, and others
Caret | For caret object events
Cursor | For cursor object events
Mode | For modality events (like EVENT_SYSTEM_MOVESIZESTART, EVENT_SYSTEM_MOVESIZEEND, and others)

Warning Do not use this sample while the OACSpy application is spying on event notifications. If both applications are active, they will log each other's events, generating events in the process. This causes an endless loop.


Snapshot Utility

The Snapshot utility (Snapshot.exe) enables you to pick a top-level window, and then dumps recursively in outline fashion all the accessible objects within that window. It has an option to skip invisible objects. It will also enable you to save the outline to a file in text format, with tabs used for indenting.


Input Applet

The dialog box-based Input applet (Input.exe) exercises the various input APIs.


DDIHook Applet

The DDIHook sample program (DDIHook.exe) shows how to get DDI information. The actual callback is called in a 16-bit DLL, that passes the information up to a 32-bit component, that saves the DDI information in a text file.


OACSpy Applet

With the OACSpy applet (OACSpy.exe), you can verify that a 32-bit application supports Active Accessibility in Windows 95 (previously known as OleACcessibility).

OACSpy verifies that an application supports WM_GETOBJECT and NotifyWinEvent.

Follow these steps to use OACSpy to test selection change and notifications:

  1. Run OACSpy.exe.
  2. Activate the Spy menu and choose the Selection Notification command to display the Selection Notification dialog box.
  3. OACSpy displays detailed Active Accessibility information given any keyboard, focus, selection, or other notifications that the active application generates (even those that the system creates on the application's behalf).

Follow these steps to check if an application is responding correctly to the WM_GETOBJECT message:

  1. Activate the Spy menu and choose the Windows command to invoke the Windows dialog box.
  2. When the list of open windows appears, choose the one of interest to see its child windows.
  3. Any window that supports the WM_GETOBJECT message has "OAC" as its class. The second list box shows details about the window. Additionally, you can place the cursor over any object outside OACSpy, and the OAC information under the cursor will be displayed.

Warning Do not use this sample to spy on event notifications while the Accevent.exe application is running and active. If both applications are active, they will log each other's events, generating events in the process. This causes an endless loop.


Server Applet

The Server sample application (Server.exe) was written purposely to be inaccessible. It does, however, expose the Active Accessibility interface to allow a client to operate it. It takes left mouse clicks to select an object from the dialog box's choices of icons. It has no menus.


Babble Applet

Babble is a sample Active Accessibility client that uses the Microsoft Speech API to speak the properties of an object. Babble requires an SAPI-compliant speech engine, which is not provided as part of the Microsoft Active Accessibility SDK, in order to speak. Babble will compile and run, but it is not considered a complete applet. It is provided as sample source code only.


VBINSP

This sample is written using Microsoft Visual Basic version 4.0. It performs a function similar to the Inspect Objects sample. Instead of waiting for the mouse to stop moving, this sample uses a timer to constantly query the object under the mouse. The VBINSP.BAS code module can be reused in other Visual Basic projects.


C/C++ Reference


IAccessible

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.

Navigation and Hierarchy | IAccessible::accNavigate
 | IAccessible::get_accChild
 | IAccessible::get_accParent
Property Access | IAccessible::accLocation
 | IAccessible::get_accChildCount
 | IAccessible::get_accDefaultAction
 | IAccessible::get_accDescription
 | IAccessible::get_accHelp
 | IAccessible::get_accHelpTopic
 | IAccessible::get_accKeyboardShortcut
 | IAccessible::get_accName
 | IAccessible::get_accRole
 | IAccessible::get_accState
 | IAccessible::get_accValue
 | IAccessible::put_accName
 | IAccessible::put_accValue
Selection and Focus | IAccessible::accSelect
 | IAccessible::get_accFocus
 | IAccessible::get_accSelection
Miscellaneous | IAccessible::accHitTest
 | IAccessible::accDoDefaultAction


IAccessible::accDoDefaultAction

Performs the object's default action.

HRESULT accDoDefaultAction(
  VARIANT varChild
);

Parameters

varChild
[in] Value identifying the child whose default action will be invoked. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

Remarks

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.


IAccessible::accHitTest

Retrieves the child object at a given point on the screen.

HRESULT accHitTest(
  long xLeft,
  long yTop,
  VARIANT *pvarChild
);

Parameters

xLeft and yTop
[in] Screen coordinates of the point to be hit tested.
pvarChild
[out, retval] Address of a VARIANT structure that will contain information describing the child object at the point specified by the xLeft and yTop parameters, if any. If the specified point exists outside the current object's boundaries, the VARIANT structure's vt member is VT_EMPTY. If the point exists within the current object but not within a child object, the vt member is VT_I4 and the lVal member is CHILDID_SELF. Otherwise, the vt member is VT_DISPATCH and the child object's IDispatch interface pointer is set in the pdispVal member.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Remarks

When this method is used in certain situations, additional usage notes apply. For more information, see Object Navigation.

Note 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


IAccessible::accLocation

Retrieves the object's current screen location (if the object was placed on the screen) and optionally, the child element.

HRESULT accLocation(
  long *pxLeft,
  long *pyTop,
  long *pcxWidth,
  long *pcyHeight,
  VARIANT varChild
);

Parameters

pxLeft and pyTop
[out] Specifies the x- and y-coordinates of the upper left boundary of the object's location.
pcxWidth and pcyHeight
[out] Value specifying the object's width and height, in pixels.
varChild
[in] Value identifying the child whose location will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

Remarks

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 Implementers: This method must not fail for visual objects. The only nonvisual objects are sound objects.


IAccessible::accNavigate

Retrieves the next or previous sibling or child object in a specified direction.

HRESULT accNavigate(
  long navDir,
  VARIANT varStartFromChildOrSelf,
  VARIANT *pvarEndUpAt
);

Parameters

navDir
[in] Value specifying the direction in which to move. This direction can be in spatial order (such as left or right) or navigational order (such as next or previous). This value is one of the Navigation Constants.
varStartFromChildOrSelf
[in] VARIANT structure that specifies the type of navigation desired. If the vt member is VT_EMPTY, the method retrieves a sibling object. If the vt member is VT_I4 and the lVal member is CHILDID_SELF, the method retrieves a child object.
pvarEndUpAt
[out, retval] Address of a VARIANT structure that will contain information about the destination object. If the vt member is VT_DISPATCH, then the pdispVal member is the address of the destination object's IDispatch interface. If the vt member is VT_I4, then the lVal member is the object ID. If vt is VT_EMPTY, then the call failed.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG
S_FALSE

Remarks

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 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


IAccessible::accSelect

Modifies the selection or moves the keyboard focus according to the specified flags.

HRESULT accSelect(
  long flagsSelect,
  VARIANT varChild
);

Parameters

flagsSelect
[in] Value specifying how to change the current selection. This parameter can be a combination of the values from the SELFLAG enumerated type.
varChild
[in] Value identifying the child that will be selected. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG
S_FALSE

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.


IAccessible::get_accChild

Retrieves an IDispatch interface address of the child object that has the given child ID or name.

HRESULT get_accChild(
  VARIANT varChild,
  IDispatch** ppdispChild
);

Parameters

varChild
[in] VARIANT structure that identifies the child to be retrieved. This parameter can be the child ID value (provided by the object) or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
ppdispChild
[out, retval] Address of a pointer variable that will contain the address of the child object's IDispatch interface.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise. The S_FALSE return value indicates that no child object is available.

Note 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.

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.

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, Child Identifiers


IAccessible::get_accChildCount

Retrieves the number of children belonging to the current object.

HRESULT get_accChildCount(
  long* pcountChildren
);

Parameters

pcountChildren
[out, retval] Address of a variable that will contain the number of child objects belonging to this object. The children can be separate objects or child elements. If the object has no children, this value will be zero.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Note 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.

Remarks

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.


IAccessible::get_accDefaultAction

Retrieves a string containing a localized sentence that describes the object's default action.

HRESULT get_accDefaultAction(
  VARIANT varChild,
  BSTR* pszDefaultAction
);

Parameters

varChild
[in] VARIANT structure that identifies the child whose default action will be retrieved. This parameter can contain the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
pszDefaultAction
[out, retval] Address of a BSTR variable that will contain a string describing the default action for this object, or NULL if this object has no default action.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

Remarks

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


IAccessible::get_accDescription

Retrieves a string containing a sentence that describes the current object.

HRESULT get_accDescription(
  VARIANT varChild,
  BSTR* pszDescription
);

Parameters

varChild
[in] Value identifying the child whose description will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
pszDescription
[out, retval] Address of a BSTR variable that will contain the string describing the specified object.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

Remarks

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.


IAccessible::get_accFocus

Retrieves the child object that currently has the keyboard focus.

HRESULT get_accFocus(
  VARIANT *pvarChild
);

Parameters

pvarChild
[out, retval] Address of a VARIANT structure that will contain information about the retrieved child. If the current object does not contain an object that has keyboard focus, then the vt member is VT_EMPTY. If vt is VT_DISPATCH, then the pdispVal member is the address of the child object's IDispatch interface. If vt is VT_I4, then the lVal member is the child ID.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Remarks

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, Focus, IDispatch Interface


IAccessible::get_accHelp

Retrieves an object's Help property string.

HRESULT get_accHelp(
  VARIANT varChild,
  BSTR *pszHelp
);

Parameters

varChild
[in] VARIANT structure that identifies the child whose default action will be retrieved. This parameter can contain the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszHelp
[out, retval] Address of a BSTR variable that will contain the Help property string for the specified object, or NULL if no Help string is available.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

Remarks

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


IAccessible::get_accHelpTopic

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.

HRESULT get_accHelpTopic(
  BSTR *pszHelpFile,
  VARIANT varChild,
  long *pidTopic
);

Parameters

pszHelpFile
[out] Address of a BSTR variable that will contain a string describing the fully qualified path of the Help file associated with the specified object, if any.
varChild
[in] VARIANT structure identifying the child whose Help information will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pidTopic
[out, retval] Address of a value identifying the Help file topic associated with the object. This value is used as the "context identifier" to the desired topic.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

Note to implementers Do not localize the string returned from this property.

See Also

HelpTopic Property


IAccessible::get_accKeyboardShortcut

Retrieves an object's KeyboardShortcut property.

HRESULT get_accKeyboardShortcut(
  VARIANT varChild,
  BSTR *pszKeyboardShortcut
);

Parameters

varChild
[in] VARIANT structure identifying the child whose keyboard shortcut will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszKeyboardShortcut
[out, retval] Address of a BSTR variable that will contain the keyboard shortcut string, or NULL if no keyboard shortcut is associated with this item.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

Note to implementers Do not localize the string returned from this property.

See Also

VARIANT Structure


IAccessible::get_accName

Retrieves the Name property for this object.

HRESULT get_accName(
  VARIANT varChild,
  BSTR* pszName
);

Parameters

varChild
[in] VARIANT structure identifying the child whose name will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszName
[out, retval] Address of a string containing this object's name.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

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


IAccessible::get_accParent

Retrieves the IDispatch interface of the current object's parent.

HRESULT get_accParent(
  IDispatch** ppdispParent
);

Parameters

ppdispParent
[out, retval] Address of a variable that will contain the parent object's IDispatch interface. The variable will be set to NULL if no parent exists or the child cannot access its parent.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Note 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


IAccessible::get_accRole

Retrieves the object's Role property.

HRESULT get_accRole(
  VARIANT varChild,
  VARIANT *pvarRole
);

Parameters

varChild
[in] VARIANT structure that identifies the child whose role will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pvarRole
[out, retval] Address of a VARIANT structure that will contain a role constant or a string describing the object's role. If the vt member is VT_I4 , then the lVal member contains the standard role constant. If vt is VT_BSTR, then the bstrVal member contains the description string.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

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.

Remarks

Do not localize the string returned from this property.

See Also

VARIANT Structure


IAccessible::get_accSelection

Retrieves the selected children of this object.

HRESULT get_accSelection(
  VARIANT *pvarChildren
);

Parameters

pvarChildren
[out, retval] Address of a VARIANT structure that will contain information about the child object or objects. The vt member will be set to one of the following values, indicating the call's result.
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.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

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


IAccessible::get_accState

Retrieves the current state of the object or child item.

HRESULT get_accState(
  VARIANT varChild,
  VARIANT *pvarState
);

Parameters

varChild
[in] VARIANT structure identifying the child whose state will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pvarState
[out, retval] VARIANT structure that will contain information describing the object's state. If the vt member is VT_I4, then the lVal member is one or more of the object state constants. If vt is VT_BSTR, then the bstrVal member contains a string describing the object's state.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise.

Note to implementers Localize the string returned from this property.

Remarks

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


IAccessible::get_accValue

Retrieves the object's Value property.

HRESULT get_accValue(
  VARIANT varChild,
  BSTR* pszValue
);

Parameters

varChild
[in] VARIANT structure identifying the child whose value will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
pszValue
[out, retval] Address of a variable that will contain a localized string containing the object's current value.

Return Values

Returns S_OK if successful or one of the following values or a standard COM error code otherwise.

DISP_E_MEMBERNOTFOUND
E_INVALIDARG

See Also

IAccessible::put_accValue


IAccessible::put_accName

Sets the Name property for this object.

HRESULT put_accName(
  VARIANT varChild,
  BSTR szName
);

Parameters

varChild
[in] Value identifying the child whose name will be set. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1").
szName
[in] String that specifies the name to be associated with this item.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise. If the object does not support setting names, the method returns S_FALSE.

See Also

IAccessible::get_accName


IAccessible::put_accValue

Sets the value of the object's Value property for the current item.

HRESULT put_accValue(
  VARIANT varChild,
  BSTR szValue
);

Parameters

varChild
[in] VARIANT structure identifying the child whose state will be retrieved. This parameter can be the child ID value (provided by the object), CHILDID_SELF for the object itself, or a string identifying the child (such as "A1"). The caller must initialize the structure's vt member to indicate which union member is valid prior to the call.
szValue
[in] String containing the value to assign to the object.

Return Values

Returns S_OK if successful or E_INVALIDARG or another standard COM error code otherwise. If the object does not support setting values, the method returns S_FALSE.

See Also

VARIANT Structure, IAccessible::get_accValue


Callback Functions

This section contains information about the following callback functions used with Active Accessibility.

  • DDIHookProc
  • WinEventProc


DDIHookProc

Application-defined callback function called by GDI when a display device interface (DDI) function is called. This is a function prototype for conceptual presentation; actual callback functions in your code would accept the same parameters and return a DWORD value, but need not have an identical label.

DWORD CALLBACK DDIHookProc(
  HDDI hddi,
  LONG lPrivateData,
  DDITYPE ddiType,
  LPDDIPARAMS lpDDIStruct
);

Parameters

hddi
Handle to a DDI hook function.
lPrivateData
A 32-bit value associated with this callback function. You set this value in the previous call to the SetDDIHook function.
ddiType
DDI function type value identifying the DDI function being called. This parameter can be one of the following values. For information on the functions and structures identified by this parameter, see the Windows 95 Device Driver Kit (DDK).
Value | Meaning
DDI_BITBLT | The DDI function being called is BitBlt and the lpDDIStruct parameter specifies the address of a BITBLT_DDIPARAMS structure.
DDI_BITMAPBITS | The DDI function being called is BitmapBits and lpDDIStruct specifies the address of a BITMAPBITS_DDIPARAMS structure.
DDI_COLORINFO | The DDI function being called is ColorInfo and lpDDIStruct specifies the address of a COLORINFO_DDIPARAMS structure.
DDI_CONTROL | The DDI function being called is Control and lpDDIStruct specifies the address of a CONTROL_DDIPARAMS structure.
DDI_CREATEDIBITMAP | The DDI function being called is CreateDIBitmap and lpDDIStruct specifies the address of a CREATEDIBITMAP_DDIPARAMS structure.
DDI_DEVICEBITMAP | The DDI function being called is DeviceBitmap and lpDDIStruct specifies the address of a DEVICEBITMAP_DDIPARAMS structure.
DDI_DEVICEMODE | The DDI function being called is DeviceMode and lpDDIStruct specifies the address of a DEVICEMODE_DDIPARAMS structure.
DDI_DIBBLT | The DDI function being called is DeviceBitmapBits and lpDDIStruct specifies the address of a DIBBLT_DDIPARAMS structure.
DDI_DIBTODEVICE | The DDI function being called is SetDIBitsToDevice and lpDDIStruct specifies the address of a DIBTODEVICE_DDIPARAMS structure.
DDI_DISABLE | The DDI function being called is Disable and lpDDIStruct specifies the address of a DISABLE_DDIPARAMS structure.
DDI_ENABLE | The DDI function being called is Enable and lpDDIStruct specifies the address of an ENABLE_DDIPARAMS structure.
DDI_ENUMDEVICEFONTS | The DDI function being called is EnumDFonts and lpDDIStruct specifies the address of an ENUMDEVICEFONTS_DDIPARAMS structure.
DDI_ENUMOBJECTS | The DDI function being called is EnumObj and lpDDIStruct specifies the address of an ENUMOBJECTS_DDIPARAMS structure.
DDI_EXTTEXTOUT | The DDI function being called is ExtTextOut and lpDDIStruct specifies the address of an EXTTEXTOUT_DDIPARAMS structure.
DDI_FASTBORDER | The DDI function being called is FastBorder and lpDDIStruct specifies the address of a FASTBORDER_DDIPARAMS structure.
DDI_GETCHARWIDTH | The DDI function being called is GetCharWidth and lpDDIStruct specifies the address of a GETCHARWIDTH_DDIPARAMS structure.
DDI_GETPALETTE | The DDI function being called is GetPalette and lpDDIStruct specifies the address of a GETSETPALETTE_DDIPARAMS structure.
DDI_GETPALETTETRANSLATE | The DDI function being called is GetPalTrans and lpDDIStruct specifies the address of a GETSETPALETTETRANSLATE_DDIPARAMS structure.
DDI_OUTPUT | The DDI function being called is Output and lpDDIStruct specifies the address of an OUTPUT_DDIPARAMS structure.
DDI_PIXEL | The DDI function being called is Pixel and lpDDIStruct specifies the address of a PIXEL_DDIPARAMS structure.
DDI_REALIZEOBJECT | The DDI function being called is RealizeObject and lpDDIStruct specifies the address of a REALIZEOBJECT_DDIPARAMS structure.
DDI_SCANLEFTRIGHT | The DDI function being called is ScanLR and lpDDIStruct specifies the address of a SCANLEFTRIGHT_DDIPARAMS structure.
DDI_SELECTBITMAP | The DDI function being called is SelectBitmap and lpDDIStruct specifies the address of a SELECTBITMAP_DDIPARAMS structure.
DDI_SETATTRIBUTE | The DDI function being called is SetAttribute and lpDDIStruct specifies the address of a SETATTRIBUTE_DDIPARAMS structure.
DDI_SETPALETTE | The DDI function being called is SetPalette and lpDDIStruct specifies the address of a GETSETPALETTE_DDIPARAMS structure
DDI_SETPALETTETRANSLATE | The DDI function being called is SetPalTrans and lpDDIStruct specifies the address of a GETSETPALETTETRANSLATE_DDIPARAMS structure.
DDI_STRETCHBLT | The DDI function being called is StretchBlt and lpDDIStruct specifies the address of a STRETCHBLT_DDIPARAMS structure.
DDI_STRETCHDIBITS | The DDI function being called is StretchDIBits and lpDDIStruct specifies the address of a STRETCHDIBITS_DDIPARAMS structure.
DDI_STRINGBLT | The DDI function being called is StrBlt and lpDDIStruct specifies the address of a STRINGBLT_DDIPARAMS structure.
DDI_UPDATECOLORS | The DDI function being called is UpdateColors and lpDDIStruct specifies the address of an UPDATECOLORS_DDIPARAMS structure.

lpDDIStruct
Address of a DDI stack function structure, as defined in the winddi.h header file. This address exists within the stack; the structure is provided to allow applications to easily modify values if needed.

Note You must write this callback procedure in a 16-bit DLL.

Return Values

Returns a DWORD value specific to the DDI call being made. The CallNextDDI function generates this value.


WinEventProc

Application-defined callback function called by USER in response to events generated by an accessible object. This is a function prototype for conceptual presentation; actual callback functions in your code would accept the same parameters and return a VOID, but need not have an identical label.

VOID CALLBACK WinEventProc(
  HWINEVENTHOOK hWinEventHook,
  DWORD event,
  HWND hwnd,
  LONG idObject,
  LONG idChild,
  DWORD dwEventThread,
  DWORD dwmsEventTime
);

Parameters

hWinEventHook
Handle to an event hook. This value is specific to each instance of a WinEventProc function.
event
Value specifying the event that occurred. This value will be one of the event constants.
hwnd
Handle to the window generating the event, or NULL if no window is associated with the event.
idObject
Value identifying the top-level object associated with the event. This will be one of the object identifier constants or a custom object ID. If this value is OBJID_WINDOW, then the object is the window itself.
idChild
ID of the child element triggering the event, or CHILDID_SELF if the event is for the object itself.
dwEventThread
ID of the thread generating the event. This value is provided for background information only.
dwmsEventTime
Value specifying the time of the event, in milliseconds.

Remarks

An Active Accessibility client requests specific types of event notifications by calling the SetWinEventHook function.

You can create multiple callback functions to handle different events. For more information, see About the WinEventProc Callback Function.

See Also

WINEVENTPROC, SetWinEventHook


New System Functions

This section contains information about the following new system functions supported by user.exe, user32.dll, oleacc.dll, and GDI.

User.exe and user32.dll now expose the following new functions.

  • BlockInput
  • GetGUIThreadInfo
  • GetWindowModuleFileName
  • NotifyWinEvent
  • SendInput
  • SetWinEventHook
  • UnhookWinEvent

The oleacc.dll library provides several helper functions that allow clients to discover Active Accessibility objects based on screen coordinates or window handles. Other functions facilitate communication with objects and marshaling across process boundaries. Oleacc.dll now supports the following new functions.

  • AccessibleChildren
  • AccessibleObjectFromEvent
  • AccessibleObjectFromPoint
  • AccessibleObjectFromWindow
  • CreateStdAccessibleObject
  • GetRoleText
  • GetStateText
  • LresultFromObject
  • ObjectFromLresult
  • WindowFromAccessibleObject

The core Windows 95 components gdi32.dll and gdi.exe have been modified to provide DDI redirection through the following new functions.

  • CallNextDDI
  • SetDDIHook
  • UnhookDDIHook


AccessibleChildren

Retrieves the child ID or IDispatch interface for a range of child objects within an accessible container object.

STDAPI AccessibleChildren(
  IAccessible* paccContainer,
  LONG iChildStart,
  LONG cChildren,
  VARIANT* rgvarChildren,
  LONG* pcObtained
);

Parameters

paccContainer
Address of the container object's IAccessible interface.
iChildStart
Value specifying the zero-based index of the first child to be retrieved.
cChildren
Count of how many children to retrieve. An application can call the IAccessible::get_accChildCount method to retrieve the current count.
rgvarChildren
Base address of an array of VARIANT structures to be filled by the function. If the vt member of an element is VT_I4, then the lVal member for that element is the child object's ID. If vt is VT_DISPATCH, then the pdispVal member is the address of the child object's IDispatch interface. The vt member can also be a string if the object supports returning strings as child identifiers.
pcObtained
Address of a variable that will contain a value indicating the number of array elements filled.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

The second parameter passed to this function is an index, not a child ID.

The caller must call the Release method for any IDispatch interfaces retrieved by this function and free the array when it is no longer needed.

See Also

VARIANT Structure, IDispatch Interface


AccessibleObjectFromEvent

Retrieves the address of the IAccessible interface for an object that generated a given event.

STDAPI AccessibleObjectFromEvent(
  HWND hwnd,
  DWORD dwId,
  DWORD dwChildId,
  IAccessible** ppacc,
  VARIANT* pvarChild
);

Parameters

hwnd
Handle to the window that generated the event.
dwId
Object ID. This value can be one of the standard object identifier constants or a custom object ID.
dwChildId
ID of the child element that triggered the event, or CHILDID_SELF if the object itself triggered the event.
ppacc
Address of a variable that will contain the address of the child object's IAccessible interface if the child is an accessible object. If not, this is the address of the IAccessible interface of the child's parent object. See the description for the pvarChild parameter for information about which interface is returned.
pvarChild
Address of a VARIANT structure that will contain information describing the call's result. The vt member will always be set to VT_I4. If the lVal member is set to zero, then the IAccessible interface pointer at ppacc belongs to the child object specified in dwChildId. Otherwise, ppacc is the address of the IAccessible interface of the child's parent object.

Return Values

Returns S_OK if successful or a standard COM error code otherwise. When the idObject parameter identifies a system object, oleacc.dll checks for a valid idChild value. However, if the object identified by the idObject parameter is not a system object, the server is responsible for returning failure when the idChild parameter is invalid.

Clients call this function to retrieve a specific child object that generated an event. The client uses the parameters sent to its WinEventProc callback function to fill this function's parameters.

Remarks

This function retrieves the lowest-level accessible object that is associated with an event. If the child that generated the event is not an accessible object (that is, does not support IAccessible), then the function returns that child's parent. The parent is assumed to support the functionality extended by the IAccessible interface on the child's behalf.

This function increases an object's reference count, and must have a corresponding call to Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Microsoft® Word does with its objects when it shuts down: As with standard OLE Automation objects, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count in the application.

See Also

AccessibleObjectFromPoint, AccessibleObjectFromWindow, WinEventProc, VARIANT Structure


AccessibleObjectFromPoint

Retrieves the address of the IAccessible interface accessible object at a specified point on the screen.

STDAPI AccessibleObjectFromPoint(
  POINT ptScreen,
  IAccessible** ppacc,
  VARIANT* pvarChild
);

Parameters

ptScreen
Win32 POINT structure describing the point to be examined, in screen coordinates.
ppacc
Address of a variable that will contain the address of the object's IAccessible interface.
pvarChild
Address of a VARIANT structure that will contain information describing the call's result. The vt member is always VT_I4. If the lVal member is set to zero, then the IAccessible interface pointer at ppacc belongs to the child object at the specified point. Otherwise, ppacc is the address of the IAccessible interface of the child's parent object.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Remarks

This function retrieves the lowest-level accessible object at a given point. If the child at the point is not an accessible object (that is, does not support IAccessible), then the function returns that child's parent. The parent is assumed to support the functionality extended by the IAccessible interface on the child's behalf.

This function increases an object's reference count, and must have a corresponding Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it shuts down: As with a standard OLE Automation object, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count in the application.

See Also

AccessibleObjectFromEvent, AccessibleObjectFromWindow, WinEventProc, VARIANT Structure


AccessibleObjectFromWindow

Retrieves the address of a specified interface for a given object.

STDAPI AccessibleObjectFromWindow(
  HWND hwnd,
  DWORD dwId,
  REFIID riid,
  void **ppvObject
);

Parameters

hwnd
Handle to the window whose object interface pointer will be retrieved, or NULL to retrieve information about the mouse pointer (cursor).
dwId
Object ID. This value can be one of the standard object identifier constants or a custom object ID.
riid
Reference identifier of the interface being requested. If the requested interface is not supported, the call will fail and the function will return E_NOINTERFACE.
ppvObject
Address of a variable that will contain the address of the specified interface if the call succeeds.

Return Values

Returns S_OK if successful or another standard COM error code otherwise.

Remarks

Clients can call this function to retrieve addresses of an object's IAccessible, IDispatch, IEnumVARIANT, IUnknown, or other supported interface. If the requested interface is not supported, the function returns E_NOINTERFACE.

In some cases, this function might create and return a pseudo-object as a wrapper for windows that do not provide accessible objects themselves.

This function increases an object's reference count, and must have a corresponding Release. Even though an object has a reference count greater than zero, that object can still be destroyed, and clients are not guaranteed that getting properties from or calling methods on an object will succeed. This is what Word does with its objects when it shuts down: As with a standard OLE Automation object, Word will quit and CoDisconnect the object so that if anyone tries to access it cross-process after the quit, OLE will return an error. A reference count on a OLE Automation object does not affect the reference count of the application.

See Also

AccessibleObjectFromEvent, AccessibleObjectFromPoint, WinEventProc, IDispatch Interface


BlockInput

Blocks keyboard and mouse events from reaching the raw input thread, and therefore from all applications.

BOOL BlockInput(
  BOOL fBlock
);

Parmeters

fBlock
Flag value specifying the call's purpose. If this value is TRUE, hardware input events are blocked until the function is called again by the same thread with a FALSE parameter.

Return Values

Returns TRUE if successful or FALSE if input is already blocked.

Remarks

This function will not interfere with the asynchronous keyboard input state table. This means that calls to the SendInput function while input is blocked will change the asynchronous keyboard input state table.

There are three situations where blocked input will become unblocked:

  1. The thread that blocked input unexpectedly exits without calling BlockInput with fBlock set to FALSE. In this case USER cleans up properly and re-enables input.
  2. The system displays the Close Program/Fault dialog box. This can occur if the thread faults or if the user presses ctrl+alt+delete.
  3. The system invokes the Hard System Error modal message box.

In all cases, USER must unblock software-blocked input. Since system-critical dialog boxes are system modal, in the latter case, the thread owning the block will not resume execution until the user closes the dialog box.


CallNextDDI

Calls the next display device interface (DDI) hook process.

WINDDIAPI DWORD WINAPI CallNextDDI(
  HDDI hddi,
  DDITYPE ddiType,
  LPDDIPARAMS lpDdiParams
);

Parameters

hddi
Handle to the current DDI hook as received in the hddi parameter of the DDIHookProc callback function.
ddiType
DDI hook type identifier as received in the ddiType parameter of the DDIHookProc callback function.
lpDdiParams
Address of the function stack structure for this DDI function as received in the lpDdiParams parameter of the DDIHookProc callback function.

Return Values

Returns a DWORD value that is the result of the DDI call that was made.

Remarks

An application calls this function in the body of a DDI hook callback function to pass control on to the next DDI hook callback function, if any. If this callback procedure modified any stack structure members prior to calling CallNextDDI, the new values will remain changed for the next callback function. If the callback procedure doesn't call this function, then the DDI function halts, never reaching the display.


CreateStdAccessibleObject

Creates a default implementation of an accessible object for a given standard object.

STDAPI CreateStdAccessibleObject(
  HWND hwnd,
  LONG idObject,
  REFIID riidInterface,
  void **ppvObject
);

Parameters

hwnd
Handle to the window containing the object specified by the idObject parameter.
idObject
Object ID. This value must be one of the object identifier constants.
riidInterface
Reference identifier of the interface being requested. If the requested interface is not supported, the call will fail and the function will return E_NOINTERFACE.
ppvObject
Address of a variable that will contain the address of the specified interface if the call succeeds.

Return Values

Returns S_OK if successful or a standard COM error code otherwise.

Remarks

This function is used only by server applications, not clients.

All standard objects support the IAccessible, IDispatch, IEnumVARIANT and IUnknown interfaces.

See Also

IDispatch Interface


GetGUIThreadInfo

Retrieves information about the active window or a specified graphical user interface (GUI) thread.

BOOL WINAPI GetGUIThreadInfo(
  DWORD idThread,
  LPGUITHREADINFO lpgui
);

Parameters

idThread
Value identifying the thread for which information is being retrieved. An application can retrieve this value by calling the GetWindowThreadProcessId Win32 function. Or, if you specify NULL for this parameter, the function returns information for the foreground thread.
lpgui
Address of a GUITHREADINFO structure that will contain information describing the thread. Before making the call, the cbSize member must be initialized in the program to the size of the GUITHREADINFO structure, in bytes.

Return Values

Returns TRUE if successful or FALSE otherwise.

Remarks

This function succeeds even if the active window is not owned by the caller's process. If the specified thread does not exist or have an input queue, the function will fail.

This function is useful for retrieving out-of-context information about a thread. The information retrieved is the same as if an application retrieved the information for itself using the Win32 functions GetFocus, GetCapture, and so on.


GetRoleText

Retrieves the localized string based on a specified standard role value.

UINT GetRoleText(
  DWORD dwRole,
  LPTSTR lpszRole,
  UINT cchRoleMax
);

Parameters

dwRole
Object role value for which the appropriate string will be retrieved. This value must be one of the object role constants.
lpszRole
Address of a buffer that will contain the role text string. If this parameter is NULL, the function retrieves the role string's length, not including the null character.
cchRoleMax
Size of the buffer at the address specified by lpszRole. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

Return Values

Returns a UINT value that represents the number of characters copied to the string. If lpszRole is NULL, then the return value represents the string's length, not including the null character.

Remarks

If the lpszRole parameter is not a valid pointer, the function returns zero and sets an ERROR_INVALID_PARAMETER error value. Applications can retrieve this error value with the GetLastError Win32 function.

Calling this function with lpszRole set to NULL is analogous to querying for the length of the role text string. You can use the return value from such a call to dynamically allocate the memory needed to hold the string. The following code fragment illustrates this concept.

UINT   iRoleLength;
LPTSTR lpszRoleString;

// Find out how long the role text string is.
iRoleLength = GetRoleText(ROLE_SYSTEM_MENUITEM, NULL, 0);

// Allocate memory for the string. Add one byte to
// length we got in the previous call to make room
// for the null character.
lpszRoleString = GlobalAllocPtr(GMEM_FIXED, iRoleLength+1);

// Get the string.
GetRoleText(ROLE_SYSTEM_MENUITEM,
            lpszRoleString, iRoleLength +1);


GetStateText

Retrieves the localized standard adjective string for a single standard state bit.

UINT GetStateText(
  DWORD dwStateBit,
  LPTSTR lpszStateBit,
  UINT cchStateBitMax
);

Parameters

dwStateBit
Object state value for which the appropriate state text will be retrieved. This value must be only one of the object state constants.
lpszStateBit
Address of a buffer that will contain the state text string. If this parameter is NULL, the function retrieves the role string's length, not including the null character.
cchStateBitMax
Size of the buffer at the address specified by the lpszStateBit parameter. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

Return Values

Returns the number of characters copied to the string. If the lpszStateBit parameter is NULL, then the return value is the string's length, not including the null character.

Remarks

This function accepts only one bit at a time, not a bitmask.

If the lpszRole parameter is not a valid pointer, the function returns zero and sets an ERROR_INVALID_PARAMETER error value. Applications can retrieve this error value with the GetLastError Win32 function.

Calling this function with lpszStateBit set to NULL is analogous to querying for the length of the state text string. You can use the return value from such a call to dynamically allocate the memory needed to hold the string. The following code fragment illustrates this concept.

UINT   iLength;
LPTSTR lpszString;

// Find out how long the string is.
iLength = GetStateText(STATE_SYSTEM_FOCUSED, NULL, 0);

// Allocate memory for the string. Add one byte to
// length we got in the previous call to make room
// for the null character.
lpszString = GlobalAllocPtr(GMEM_FIXED, iLength + 1);

// Get the string.
GetStateText(STATE_SYSTEM_FOCUSED, lpszString, iLength + 1);


GetWindowModuleFileName

Retrieves the full path and file name of the module associated with the given window handle.

UINT WINAPI GetWindowModuleFileName(
  HWND hwnd,
  LPTSTR lpszFileName,
  UINT cchFileNameMax
);

Parameters

hwnd
Handle to the window whose module file name will be retrieved.
lpszFileName
Address of a string variable that will contain the executable file's path and file name.
cchFileNameMax
Value specifying the maximum number of characters to copy into the buffer at lpszFileName.

Return Values

Returns a value representing the total number of characters copied into the buffer.


LresultFromObject

Generates a reference to an accessible object, in the form of an LRESULT value.

LRESULT LresultFromObject(
  REFIID riid,
  WPARAM wParam,
  LPUNKNOWN punk
);

Parameters

riid
Reference identifier of the interface that USER will provide to the client.
wParam
Value as provided in the wParam parameter received with the associated WM_GETOBJECT message.
punk
Address of the IUnknown interface for the object whose reference is being generated.

Return Values

Returns a positive object reference if successful or one of the following error codes otherwise.

E_INVALIDARG | One or more arguments are invalid.
E_NOINTERFACE | The punk parameter does not support the interface riid parameter.
E_OUTOFMEMORY | Insufficient memory to store the object reference.
E_UNEXPECTED | An unexpected error occurred.

Remarks

This function can return other values, identical to those returned by the CoMarshalInterface OLE function.

Active Accessibility server applications use this function to retrieve a return value while processing the WM_GETOBJECT message. This function is called only by Active Accessibility server applications, not clients.

The riid parameter identifies the interface that will be provided and allows oleacc.dll to optimize marshaling between the client and the server. That is, if a given interface has already been provided for an object, oleacc.dll will optimize the process by using the existing interface rather than creating another one in shared memory.

A value returned from LresultFromObject can be passed to ObjectFromLresult only once; if it is passed subsequent times the error result will be returned from this function.

Since this function creates a weak reference (MSHLFLAGS_TABLEWEAK) to an object, the object's table is not affected.


NotifyWinEvent

Signals the system and accessibility aids that a predefined event occurred.

void WINAPI NotifyWinEvent(
  DWORD event,
  HWND hwnd,
  LONG idObject,
  LONG idChild
);

Parameters

event
Value specifying the event that occurred. This value must be one of the event constants defined in the winable.h header file.
hwnd
Handle to the window generating the event.
idObject
Value identifying the object that generated the event. This value can be one of the predefined object constants or a custom object ID value.
idChild
Value identifying the child of the object specified in idObject that is generating the event. This value is CHILDID_SELF if the object itself is generating the event.

Remarks

An Active Accessibility server application calls this method to notify the system and accessibility aids that a predefined event occurred within the application. This allows accessibility aids to communicate directly with the server object using IAccessible interface methods.

There is no significant performance penalty for calling this function when no clients of the events are present. The system does not perform any thunking for context switches. Server application developers can call this method with their own events without fear of overhead.


ObjectFromLresult

Retrieves a requested interface pointer for an accessible object based on a previously generated object reference.

STDAPI ObjectFromLresult(
  LRESULT lResult,
  REFIID riid,
  WPARAM wParam,
  void** ppvObject
);

Parameters

lResult
A 32-bit value returned by a previous successful call to the LresultFromObject function.
riid
Reference identifier of the interface to be retrieved.
wParam
Additional information as provided in the associated wParam parameter of the WM_GETOBJECT message.
ppvObject
Location, in screen coordinates, of the interface pointer to return.

Return Values

Returns S_OK if successful or one of the following COM error codes otherwise.

E_INVALIDARG | One or more arguments are invalid. Most commonly, this occurs when the lResult parameter specified is not a value obtained by a call to LresultFromObject, or when lResult is a value used on a previous call to ObjectFromLresult.
E_NOINTERFACE | The object does not support the interface specified by the riid parameter.
E_UNEXPECTED | An unexpected error occurred.

This function can return other values, identical to those returned by the CoUnMarshalInterface OLE function.

Returns an interface pointer to an object given a 32-bit LRESULT value returned by a previous call to LresultFromObject on the same computer. You can pass a value returned by LresultFromObject to ObjectFromLresult only once; if it is passed subsequent times, the function fails and returns an error value.

Note Active Accessibility servers or clients can't use this function. Only oleacc.dll can use this function, which is documented only for informational purposes.


SendInput

Simulates a series of mouse, keyboard, or other user input events without interruption.

UINT SendInput(
  UINT cInputs,
  LPINPUT pInputs,
  INT cbSize
);

Parameters

cInputs
Count of INPUT structures in the array at cInputs.
pInputs
Base address of an array INPUT structures. Each element describes a single simulated event.
cbSize
Size of the INPUT structure, in bytes.

Return Values

Returns a value representing the number of INPUT structures played back to USER. If this value equals the cInputs parameter, then the function completed successfully. If this value equals zero, then input was already blocked by another thread.

Remarks

This function does not reset the keyboard's current state. Therefore, if the user has any keys pressed when you call this function, they might interfere with the events that this function generates. If you are concerned about possible interference, check the keyboard's state with the GetAsyncKeyState Win32 function and correct as necessary.

See Also

Simulating Input


SetDDIHook

Sets a hook into the DDI stream.

WINDDIAPI HDDI WINAPI SetDDIHook(
  HDC hdcHook,
  HMODULE hModCode,
  LONG lPrivateData,
  UINT hookClass,
  DDIHOOKPROC lpfnDdiHook
);

Parameters

hdcHook
Reserved for future use. This parameter must be NULL.
hModCode
Handle to the 16-bit DLL module containing the callback function at the address specified by the lpfnDdiHook parameter.
lPrivateData
A 32-bit value will be passed to the callback function specified by the lpfnDdiHook parameter.
hookClass
DDI hook class value. This value can be one of the following:
DDIHOOK_FONTS | Font enhancers.
DDIHOOK_MAGNIFIER | Screen magnifiers.
DDIHOOK_RECORDER | Screen readers and screen capture utilities.
DDIHOOK_REMOTE | Remoting utilities.

lpfnDdiHook
Address of a callback function that matches the return value and argument list of the DDIHookProc function declaration. The winable.h header file defines the DDIHOOKPROC data type for declaring variables that match this declaration. GDI calls this function when specific DDI functions have been called.

Return Values

Returns an HDDI value identifying this DDI hook instance if successful, or zero otherwise. Your application should save the return value to use with the UnhookDDIHook function.

Remarks

The hook class determines the order in which DDI callbacks are called. The actual display device is always the last called. See the winddi.h file in the INC16 directory for more information on what GDI passes to the callback function.

Note The callback procedure specified by the lpfnDdiHook parameter must be written into a 16-bit dynamic-link library (DLL).

See Also

Setting a DDI Hook, Unhooking a DDI Hook


SetWinEventHook

Sets an event hook for a range of events.

HWINEVENTHOOK WINAPI SetWinEventHook(
  UINT eventMin,
  UINT eventMax,
  HMODULE hmodWinEventProc,
  WINEVENTPROC lpfnWinEventProc,
  DWORD idProcess,
  DWORD idThread,
  UINT dwflags
);

Parameters

eventMin
Event constant describing the lowest event value in the range. This parameter can be EVENT_MIN to indicate the lowest possible event value.
eventMax
Event constant describing the highest event value in the range. This parameter can be EVENT_MAX to indicate the highest possible event value.
hmodWinEventProc
Handle to the dynamic-link library (DLL) containing the callback function at lpfnWinEventProc, if the WINEVENT_INCONTEXT flag is specified in the dwFlags parameter. If the callback function is not located in a DLL or the WINEVENT_OUTOFCONTEXT flag is specified, this parameter is ignored.
lpfnWinEventProc
Address of a callback function that matches the return value and argument list of the WinEventProc function declaration. The winable.h header file defines the WINEVENTPROC data type for declaring variables that match the WinEventProc declaration. USER calls this function when a server posts an event that falls within the range specified by the eventMin and eventMax parameters.
idProcess
ID of the process to be monitored, or zero for all processes.
idThread
ID of the thread with which the callback function will be associated. If this parameter is zero, the hook procedure is associated with all existing threads.
dwflags
Flag values specifying one or more receiving options. This parameter can contain one or more of the following values. The default value is WINEVENT_OUTOFCONTEXT.
WINEVENT_INCONTEXT
USER sends event notifications to the callback function as they occur. In this case, the DLL containing the callback function is mapped into the address space of the process generating the event. The callback function must be in a DLL to use this option.
WINEVENT_OUTOFCONTEXT
USER sends event notifications that are queued before sending them to the callback function. Queuing is required because the callback function is not mapped into the address space of the process generating the event. Although this method is asynchronous, events are guaranteed to be in sequential order.
WINEVENT_SKIPOWNPROCESS
Prevents any threads in the caller's process from receiving their own notifications. This flag does not prevent threads from generating events.
WINEVENT_SKIPOWNTHREAD
Prevents the thread that is processing notifications from receiving any events it might have generated itself. This flag does not prevent the thread from generating events.

Return Values

Returns an HWINEVENTHOOK value that identifies this event hook instance if successful, or zero otherwise. Your application should save this return value to use with the UnhookWinEvent function.

Remarks

This function allows you to specify not only which events you want, but also the process and thread in which you want to look for those events. This is useful when you want to work only with certain applications or just the system.

If the idProcess parameter is nonzero and idThread is zero, this function will hook all threads in that process. If the idProcess parameter is zero and idThread is nonzero, this function will hook only the thread specified by idThread. If both are zero, the function will hook in all threads and processes.

To monitor a noncontiguous range of events, call this method twice, specifying the same callback function in the lpfnWinEventProc parameter each time.

The client thread calling SetWinEventHook must be a thread that has a message loop, sometimes known as a "GUI thread."

See Also

About the WinEventProc Callback Function.


UnhookDDIHook

Removes a DDI hook created by a previous call to the SetDDIHook function.

WINDDIAPI BOOL WINAPI UnhookDDIHook(
  HDDI hddi
);

Parameters

hddi
Handle to this DDI hook. The previous SetDDIHook function call returned this value.

Return Values

Returns TRUE if successful or FALSE if the hddi parameter is invalid.

See Also

Unhooking a DDI Hook,Setting a DDI Hook


UnhookWinEvent

Removes an event hook created by a previous call to SetWinEventHook.

BOOL WINAPI UnhookWinEvent(
  HWINEVENTHOOK hWinEventHook
);

Parameters

hWinEventHook
Handle to the event hook that was returned in the previous call to SetWinEventHook.

Return Values

Returns TRUE if successful or FALSE otherwise.

Three common errors will cause this function to fail:

  1. The hWinEventHook parameter is NULL or invalid.
  2. The event hook specified by hWinEventHook was already removed.
  3. UnhookWinEvent is called from a different thread than the original call to SetWinEventHook

Remarks

This function removes the event hook specified by hWinEventHook, preventing the accompanying callback function from receiving further notifications. Clients should call this function when event notification is no longer needed or if the client's thread is ending for any reason.

Ensure that you call this function from the same thread that installed the event hook. USER will not allow threads to remove event hooks that they do not own.

If WINEVENT_INCONTEXT is specified when installing this event hook, winable.h will attempt to unload the corresponding DLL from all processes that loaded it. Although unloading might not occur immediately, the callback function will not be called after UnhookWinEvent returns.


WindowFromAccessibleObject

Retrieves the window handle that corresponds to a given instance of an IAccessible interface.

STDAPI WindowFromAccessibleObject(
  IAccessible* pacc,
  HWND* phwnd
);

Parameters

pacc
Address of an IAccessible interface.
phwnd
Address of a variable that will contain a handle to the window that contains the specified object, if any. If this value is NULL after the call, the object was not contained within a window (like the mouse pointer).

Return Values

Returns S_OK if successful or a standard COM error code otherwise. This function returns E_INVALIDARG if the pacc parameter is NULL.

See Also

AccessibleObjectFromWindow


Event Constants

The following table lists all the events generated by Active Accessibility server applications, in ascending numeric order. The EVENT_MIN and EVENT_MAX values represent the lowest and highest possible event values, respectively.

For more information about events, see WinEvents.

EVENT_SYSTEM_SOUND | A sound is being played. | Notes
EVENT_SYSTEM_ALERT | An alert was generated. | Notes
EVENT_SYSTEM_FOREGROUND | The foreground window is changing. | Notes
EVENT_SYSTEM_MENUSTART | An application is entering a modal menu loop. | Notes
EVENT_SYSTEM_MENUEND | An application is exiting a modal menu loop. | Notes
EVENT_SYSTEM_MENUPOPUPSTART | A pop-up menu is being displayed. | Notes
EVENT_SYSTEM_MENUPOPUPEND | A pop-up menu is being removed. | Notes
EVENT_SYSTEM_CAPTURESTART | A window received mouse capture. |
EVENT_SYSTEM_CAPTUREEND | A window lost mouse capture. |
EVENT_SYSTEM_MOVESIZESTART | A window entered a modal move or size loop. |
EVENT_SYSTEM_MOVESIZEEND | A window exited a modal move or size loop. |
EVENT_SYSTEM_CONTEXTHELPSTART | A window entered context-sensitive Help mode. |
EVENT_SYSTEM_CONTEXTHELPEND | A window exited context-sensitive Help mode. |
EVENT_SYSTEM_DRAGDROPSTART | An application is about to enter drag-and-drop mode. | Notes
EVENT_SYSTEM_DRAGDROPEND | An application is about to exit drag-and-drop mode. | Notes
EVENT_SYSTEM_DIALOGSTART | A dialog box was displayed. | Notes
EVENT_SYSTEM_DIALOGEND | A dialog box was removed. | Notes
EVENT_SYSTEM_SCROLLINGSTART | A scroll bar is being tracked. | Notes
EVENT_SYSTEM_SCROLLINGEND | A scroll bar is no longer being tracked. | Notes
EVENT_SYSTEM_SWITCHSTART | The user pressed alt+tab. | Notes
EVENT_SYSTEM_SWITCHEND | The user released alt+tab. | Notes
EVENT_SYSTEM_MINIMIZESTART | A window object is about to be minimized or maximized. |
EVENT_SYSTEM_MINIMIZEEND | A window object was minimized or maximized. |
EVENT_OBJECT_CREATE | An object was created. | Notes
EVENT_OBJECT_DESTROY | An object was destroyed. | Notes
EVENT_OBJECT_SHOW | An object is being shown. | Notes
EVENT_OBJECT_HIDE | An object is being hidden. | Notes
EVENT_OBJECT_REORDER | A container object's children are changing their z-order placements. | Notes
EVENT_OBJECT_FOCUS | An object is receiving keyboard focus. | Notes
EVENT_OBJECT_SELECTION | An object selection change occurred. | Notes
EVENT_OBJECT_SELECTIONADD | An object was added to the selection. | Notes
EVENT_OBJECT_SELECTIONREMOVE | An object was removed from the selection. | Notes
EVENT_OBJECT_SELECTIONWITHIN | Numerous selection changes occurred within a container. | Notes
EVENT_OBJECT_STATECHANGE | An object's state changed. | Notes
EVENT_OBJECT_LOCATIONCHANGE | An object is changing location, shape, or size. | Notes
EVENT_OBJECT_NAMECHANGE | An object's Name property changed. |
EVENT_OBJECT_DESCRIPTIONCHANGE | An object's Description property changed. |
EVENT_OBJECT_VALUECHANGE | An object's Value property changed. |
EVENT_OBJECT_PARENTCHANGE | An object has a new parent object. |
EVENT_OBJECT_HELPCHANGE | An object's Help property changed. |
EVENT_OBJECT_DEFACTIONCHANGE | An object's DefaultAction property changed. |
EVENT_OBJECT_ACCELERATORCHANGE | An object's KeyboardShortcut property changed. |


EVENT_SYSTEM_SOUND Notes

The system generates this event when a system sound (for menus, and so on) is played. The system will generate this event even if no sound is audible (for example, lack of a sound file to play, no sound card, and so on).

For this event, the WinEventProc callback function will receive the OBJID_SOUND value as the idObject parameter.


EVENT_SYSTEM_ALERT Notes

Message boxes generate this event when they are displayed.


EVENT_SYSTEM_FOREGROUND Notes

The system generates this event even if the foreground window is changing to another window in the same thread.

For this event, the WinEventProc callback function's hwnd parameter is the handle to the window that is now in the foreground, and the idObject parameter is OBJID_WINDOW. The idChild parameter is CHILDID_SELF.


EVENT_SYSTEM_MENUSTART Notes

For this event, the WinEventProc callback function's hwnd, idObject, and idChild parameters refer to the control with the menu bar or the control activating the context menu.

The hwnd parameter is the handle to the top-level window related to the event. The idObject parameter will be OBJID_MENU or OBJID_SYSMENU for a menu, or OBJID_WINDOW for a pop-up menu. The idChild parameter will be CHILDID_SELF.


EVENT_SYSTEM_MENUEND Notes

For this event, the WinEventProc callback function's hwnd, idObject, and idChild parameters refer to the control with the menu bar or the control activating the context menu.

The hwnd parameter is the handle to the top-level window related to the event. The idObject parameter will be OBJID_MENU or OBJID_SYSMENU for a menu, or OBJID_WINDOW for a pop-up menu. The idChild parameter will be CHILDID_SELF.


EVENT_SYSTEM_MENUPOPUPSTART Notes

For this event, the WinEventProc callback function's hwnd, idObject, and idChild parameters refer to the new pop-up menu being displayed, not the parent item. You can retrieve the parent or pop-up menu by calling the IAccessible::get_accParent method.

When an application displays a pop-up menu, the client will receive an EVENT_SYSTEM_MENUSTART event followed almost immediately by this event.


EVENT_SYSTEM_MENUPOPUPEND Notes

When a pop-up menu disappears, the client will receive this message followed almost immediately by the EVENT_SYSTEM_MENUEND event.


EVENT_SYSTEM_DRAGDROPSTART Notes

Applications that support drag-and-drop operations must send this event; the system does not.


EVENT_SYSTEM_DRAGDROPEND Notes

Applications that support drag-and-drop operations must send this event; the system does not.


EVENT_SYSTEM_DIALOGSTART Notes

Applications must send this event after the dialog box is completely initialized and visible.


EVENT_SYSTEM_DIALOGEND Notes

Applications must send this event just before the dialog box is removed from the screen.


EVENT_SYSTEM_SCROLLINGSTART Notes

This event applies to scroll bars contained in windows and top-level scroll bar controls. Top-level scroll bar controls are identified by the OBJID_HSCROLL and OBJID_VSCROLL object ID values.


EVENT_SYSTEM_SCROLLINGEND Notes

This event applies to scroll bars contained in windows and top-level scroll bar controls. Top-level scroll bar controls are identified by the OBJID_HSCROLL and OBJID_VSCROLL object ID values.


EVENT_SYSTEM_SWITCHSTART Notes

For this event notification, the hwnd parameter of the WinEventProc callback function identifies the window that the user is switching to.

If only one application is running when the user presses alt+tab, the client application can receive an EVENT_SYSTEM_SWITCHEND event without a corresponding EVENT_SYSTEM_SWITCHSTART event.


EVENT_SYSTEM_SWITCHEND Notes

For this event notification, the hwnd parameter of the WinEventProc callback function identifies the window that the user switched to.

If only one application is running when the user presses alt+tab, the client application can receive this event without a corresponding EVENT_SYSTEM_SWITCHSTART event.


EVENT_OBJECT_CREATE Notes

In the case of window objects only, both the parent and the child send this event. The child window sends the event when created, and the parent sends it after creation is complete. Note that the child window is responsible for sending this event before the parent.

If the client is using synchronous callbacks, it should not attempt to retrieve the parent object (by using IAccessible::get_accParent) until after control is yielded to the operating system.


EVENT_OBJECT_DESTROY Notes

In the case of window objects only, both the parent and the child send this event. The child window sends the event when it is destroyed, and the parent sends it after destruction is complete. Note that the child window is responsible for sending this event before the parent. It is assumed that all the children of an object are destroyed when the parent is destroyed. This event is also sent when an application is shutting down.

Calling IAccessible properties at this point can cause a crash—in particular, when the call references a DLL that is unloaded first. Calling the IAccessible::get_accName method is a good example. It eventually calls SysAllocString, a Win32 API call. exported by oleaut32.dll. If oleaut32.dll is unloaded first, it crashes. Therefore, upon receiving the EVENT_OBJECT_DESTROY, call these properties only for visible windows. Only invisible windows are dangerous because some of them are destroyed after a majority of the system has already been destroyed. To get the name of the invisible window, try using GetWindowText, a Win32 API call.


EVENT_OBJECT_SHOW Notes

When a parent object is being shown, all child objects are, of course, visible on the screen. Therefore, server applications must not send this event for the child objects.


EVENT_OBJECT_HIDE Notes

When a parent object is being hidden, all child objects are, of course, no longer visible on the screen. They still have the same "visible" status, but are not truly visible. Therefore, server applications must not send this event for the child objects.


EVENT_OBJECT_REORDER Notes

The object referred to in the hwnd and idObject parameters of the WinEventProc callback function identify the parent container object in which z-ordering is occurring. This is because if one child changes its z-order, all of them must change.


EVENT_OBJECT_FOCUS Notes

The parameters received in the WinEventProc callback function describe the object that is receiving the keyboard focus.

There is only one focused child item in a parent. The focused child is the object that receives keystrokes at a given moment. Hence, server applications must only send this notification describing where the new focus is going. That is, a new item that gets the focus implies that the old one is losing it.

Do not confuse object focus with object selection. For more information, see Accessible Object Selection and Focus.


EVENT_OBJECT_SELECTION Notes

Server applications send this notification when the item being selected is within the same container as the last selected object.

The hwnd and idObject parameters of the WinEventProc callback function describe the container, and the idChild parameter identifies the object that is selected. The idChild parameter can be OBJID_WINDOW if the selected child is a window that also contains objects.

Do not confuse object selection with object focus. For more information, see Accessible Object Selection and Focus.


EVENT_OBJECT_SELECTIONADD Notes

Server applications send this notification when an object or objects have been added to the selection within a container. This is appropriate when the number of newly selected items is very small.

The hwnd and idObject parameters of the WinEventProc callback function describe the container, and the idChild parameter is the child that was added to the selection.

Do not confuse object selection with object focus. For more information, see Accessible Object Selection and Focus.


EVENT_OBJECT_SELECTIONREMOVE Notes

Server applications send this notification when an object or objects have been removed from the selection within a container. Like the EVENT_OBJECT_SELECTIONADD event, this is appropriate when the number of newly selected items is very small.

The hwnd and idObject parameters of the WinEventProc callback function describe the container, and the idChild parameter identifies the child that was added to the selection.

Do not confuse object selection with object focus. For more information, see Accessible Object Selection and Focus.


EVENT_OBJECT_SELECTIONWITHIN Notes

A server application sends this notification when the selected items within a control have changed substantially. Effectively, this notification informs the client that many selection changes have occurred (instead of sending several EVENT_OBJECT_SELECTIONADD or EVENT_OBJECT_SELECTIONREMOVE events). The client can query for the selected items by calling the container object's IAccessible::get_accSelection method and enumerating the selected items.

For this event notification, the hwnd and idObject parameters of the WinEventProc callback function describe the container in which the changes occurred.

Do not confuse object selection with object focus. For more information, see Accessible Object Selection and Focus.


EVENT_OBJECT_STATECHANGE Notes

A state change can occur when a button object has been pressed or released, when an object is being enabled or disabled, or whatever else is pertinent for a given object. USER sends these events on behalf of standard controls, like push buttons and check boxes.

For this event notification, the idChild parameter of the WinEventProc callback function identifies the child object whose state changed.


EVENT_OBJECT_LOCATIONCHANGE Notes

This event is generated in response to the topmost level object that has changed, not for any children it might contain. For example, if the user resizes a top-level window, USER generates this notification for the window, but not for the menu bar, title bar, scroll bars, or other objects that are also changing.

USER generates this event for windows that are changing. It does not do this for every nonfloating child window when the parent moves. However, if an application explicitly resizes child windows as a result of being sized, USER will generate multiple events for the resized children. Additionally, USER generates this event for two nonwindow system objects: the system caret and the cursor.

For this event notification, the idChild parameter of the WinEventProc callback function identifies the child object that changed.


Structures

This section contains information on the following new structures used with Active Accessibility.

  • GUITHREADINFO
  • HARDWAREINPUT
  • INPUT
  • KEYBDINPUT
  • MOUSEINPUT


GUITHREADINFO

Carries information about a GUI thread.

typedef struct tagGUITHREADINFO {
    DWORD   cbSize;
    DWORD   flags;
    HWND    hwndActive;
    HWND    hwndFocus;
    HWND    hwndCapture;
    HWND    hwndMenuOwner;
    HWND    hwndMoveSize;
    HWND    hwndCaret;
    RECT    rcCaret;
} GUITHREADINFO, FAR * LPGUITHREADINFO;

Members

cbSize
Size of this structure, in bytes.
flags
Bitmask value. This member contains a combination of the following flags that, if set, indicate that the corresponding condition is true for the specified thread.
GUI_CARETBLINKING | Represents the caret's blink state. This bit is set if the caret is visible.
GUI_INMENU | Represents the thread's menu state. This bit is set if the thread is in menu mode.
GUI_INMOVESIZE | Represents the thread's move state. This bit is set if the thread is in a move or size loop.
GUI_POPUPMENUMODE | Represents the thread's pop-up menu state. This bit is set if the thread has an active pop-up menu.
GUI_SYSTEMMENUMODE | Represents the thread's system menu state. This bit is set if the thread is in a system menu mode.

hwndActive
Handle to the active window within the thread.
hwndFocus
Handle to the window that has keyboard focus.
hwndCapture
Handle to the window that has mouse capture.
hwndMenuOwner
Handle to the window that owns any active menus.
hwndMoveSize
Handle to the window in a move or size loop.
hwndCaret
Handle to the window that is displaying the caret.
rcCaret
RECT structure that describes the caret's bounding rectangle, in client coordinates, relative to the window specified by the hwndCaret member.

Remarks

This structure is used with the GetGUIThreadInfo function to retrieve information about the active window or a specified GUI thread.


HARDWAREINPUT

Contains information about a simulated message generated by an input device.

typedef struct tagHARDWAREINPUT {
    DWORD   uMsg;
    WORD    ParamL;
    WORD    ParamH;
    DWORD   dwExtraInfo;
} HARDWAREINPUT, FAR* LPHARDWAREINPUT;

Members

uMsg
Value specifying the message associated with the hardware input event.
ParamL
Low-order word of the lParam parameter for the message.
ParamH
High-order word of the lParam parameter for the message.
dwExtraInfo
A 32-bit value to be associated with the event. An application calls the GetMessageExtraInfo Win32 function to obtain this extra information.

Remarks

This structure is contained by the INPUT structure and used with the SendInput function.

See Also

Simulating Input


INPUT

Carries information describing simulated mouse, keyboard, or other user input.

typedef struct tagINPUT {
    DWORD   type;
    union {
        MOUSEINPUT      mi;
        KEYBDINPUT      ki;
        HARDWAREINPUT   hi;
    };
} INPUT, FAR* LPINPUT;

Members

type
Flag value indicating the type of device information this structure carries. This member is one of the following values.
INPUT_HARDWARE | The hi union member is valid.
INPUT_KEYBOARD | The ki union member is valid.
INPUT_MOUSE | The mi union member is valid.

mi
MOUSEINPUT structure that contains information about simulated mouse input.
ki
KEYBDINPUT structure that contains information about simulated keyboard input.
hi
HARDWAREINPUT structure that contains information about a simulated input device message.

Remarks

This structure is used with the SendInput sample application.

This structure contains information identical to that used in the parameter list for a call to the keybd_event, mouse_event, or hardware_event functions.

See Also

Simulating Input


KEYBDINPUT

Contains information about a simulated keyboard event.

typedef struct tagKEYBDINPUT {
    WORD    wVk;
    WORD    wScan;
    DWORD   dwFlags;
    DWORD   time;
    DWORD   dwExtraInfo;
} KEYBDINPUT, *PKEYBDINPUT, FAR* LPKEYBDINPUT;

Members

wVk
Value specifying the virtual key code. This value must be between 1 and 254, inclusive. The winuser.h header file provides macro definitions (VK_*) for each value.
wScan
Value specifying the hardware scan code for the key.
dwFlags
Bitmask value containing bit flags that specify various aspects of a keystroke. These bits can be any combination of the following values.
KEYEVENTF_EXTENDEDKEY | If specified, the scan code was preceded by a prefix byte that has the value 0xE0 (224).
KEYEVENTF_KEYUP | If specified, the key is being released. If not specified, the key is being pressed.

time
Value indicating the time stamp for the event, in milliseconds.
dwExtraInfo
A 32-bit value to be associated with the keystroke. An application calls the Win32 GetMessageExtraInfo function to obtain this extra information.

Remarks

This structure is contained by the INPUT structure and used with the SendInput function.

See Also

Simulating Input


MOUSEINPUT

Carries information about a simulated mouse event.

typedef struct tagMOUSEINPUT {
    LONG    dx;
    LONG    dy;
    DWORD   mouseData;
    DWORD   dwFlags;
    DWORD   dwExtraInfo;
} MOUSEINPUT, FAR* LPMOUSEINPUT;

Members

dx and dy
Absolute or relative mouse movement on the x-axis and y-axis, in pixels.

Depending on the flags specified in the dwFlags member of the associated SendInput function call, these members indicate either an absolute position or an amount of movement since the last mouse event occurred. If the MOUSEEVENTF_ABSOLUTE bit is set in the dwFlags member, then these are absolute positions; otherwise they are relative movement values.

mouseData
Value indicating mouse wheel movement. This member is valid only if the dwFlags member contains the MOUSEEVENTF_WHEEL value. If so, then mouseData specifies the amount of wheel movement. A positive value indicates that the wheel was rotated forward, away from the user; a negative value indicates that the wheel was rotated backward, toward the user. One wheel click is defined as WHEEL_DELTA, which is 120.

If the dwFlags member does not contain MOUSEEVENTF_WHEEL, then you must set mouseData to zero.

dwFlags
Bitmask value that can contain a combination of the following values.
MOUSEEVENTF_ABSOLUTE | Specifies that the dx and dy members contain normalized absolute coordinates. If the flag is not set, the dx and dy members contain relative data: the change in position since the last reported position. This flag can be set, or not set, regardless of what kind of mouse or other pointing device, if any, is connected to the system.
MOUSEEVENTF_LEFTDOWN | Specifies that the left button was pressed.
MOUSEEVENTF_LEFTUP | Specifies that the left button was released.
MOUSEEVENTF_MIDDLEDOWN | Specifies that the middle button was pressed.
MOUSEEVENTF_MIDDLEUP | Specifies that the middle button was released.
MOUSEEVENTF_MOVE | Specifies that movement occurred.
MOUSEEVENTF_RIGHTDOWN | Specifies that the right button was pressed.
MOUSEEVENTF_RIGHTUP | Specifies that the right button was released.
MOUSEEVENTF_WHEEL | Windows NT only: Specifies that the wheel was moved, if the mouse has a wheel. The amount of movement is specified in mouseData.

dwExtraInfo
A 32-bit value to be associated with the mouse event. An application can call the GetMessageExtraInfo Win32 function to retrieve this extra information.

Remarks

This structure is contained by the INPUT structure and used with the SendInput function.

See Also

Simulating Input


Window Messages

This section contains information on the following window message used by Active Accessibility API elements.

  • WM_GETOBJECT


WM_GETOBJECT

The oleacc.dll dynamic link library sends this message to an Active Accessibility server application to retrieve information about an accessible object it contains.

wParam = (WPARAM)(DWORD) dwFlags;
lParam = (LPARAM)(DWORD) dwObjId;

Parameters

dwFlags
Flag values providing additional information about the message. This value is passed to the LresultFromObject function, as the wParam parameter.
dwObjId
Object identifier. This value can be one of the object identifier constants or a custom object identifier.

Return Values

Returns a value specifying the object's reference, a request for a standard object, or a COM error code otherwise. To return an object reference, use the LresultFromObject function. To request a standard accessible object, return zero. To fail the message, return a COM error code.

Remarks

Oleacc.dll generates this message to retrieve object information in response to AccessibleObjectFromEvent, AccessibleObjectFromWindow or AccessibleObjectFromPoint function calls.

Applications should never send this message directly. It is sent only by oleacc.dll in response to AccessibleObjectFromPoint, AccessibleObjectFromEvent or AccessibleObjectFromWindow calls. However, server components must understand and handle it.


Simple Types

This section contains information about the following simple types defined for use with Active Accessibility.

  • DDIHOOKPROC
  • DDITYPE
  • HDDI
  • HWINEVENTHOOK
  • LPDDIPARAMS
  • WINEVENTPROC


DDIHOOKPROC

The DDIHOOKPROC type defines a variable that points to a valid DDI hook callback procedure. The winddi.h header file uses the following definition.

typedef DWORD (CALLBACK* DDIHOOKPROC)(HDDI, LONG, DDITYPE, LPDDIPARAMS);

Remarks

For more information, see DDIHookProc.


DDITYPE

The DDITYPE type defines a variable describing a specific DDI function call. The winddi.h header file uses the following definition.

typedef UINT    DDITYPE;

Remarks

This data type is used with the CallNextDDI function and the DDIHookProc callback function.


HDDI

The HDDI type defines a 32-bit variable that identifies a DDI hook. The winddi.h header file uses the following definition.

typedef struct tagDDI FAR* HDDI;

Remarks

This data type is used with the CallNextDDI, SetDDIHook, and UnhookDDIHook functions.


HWINEVENTHOOK

The HWINEVENTHOOK type defines a 32-bit variable that identifies a window event hook. The winable.h header file uses the following definition.

typedef DWORD HWINEVENTHOOK

Remarks

This data type is used with the WinEventProc, SetWinEventHook, and UnhookWinEvent functions.


LPDDIPARAMS

The LPDDIPARAMS type defines a variable that contains the address of one of the DDI parameter structures. The DDI parameters structures are included in the winddi.h header file, which defines LPDDIPARAMS as follows:

typedef LPVOID  LPDDIPARAMS;

Remarks

This data type is used with CallNextDDI function and the DDIHookProc callback function.


WINEVENTPROC

The WINEVENTPROC type defines a variable that conforms to the WinEventProc callback function declaration. The winable.h header file uses the following definition.

typedef VOID (CALLBACK* WINEVENTPROC)(
    HWINEVENTHOOK  hWinEventHook,
    DWORD          event,
    HWND           hwnd,
    LONG           idObject,
    LONG           idChild,
    DWORD          idEventThread,
    DWORD          dwmsEventTime);

Remarks

For more information, see WinEventProc.


Constants and Enumerated Types

This section contains information on the following constants and enumerated types used with Active Accessibility.

  • Object Identifiers
  • Object Roles
  • Object State Constants
  • Navigation Constants
  • Return Values
  • SELFLAG


Object Identifiers

The oleacc.dll dynamic-link library recognizes and provides the following standard object identifiers (defined in winable.h). The system reserves zero and all negative values for standard objects.

Clients will receive and use these values to identify parts of a window. Servers use these values to identify the corresponding parts of a window, but must provide positive values to identify any other objects they employ within an application.

OBJID_ALERT
 | Refers to an alert associated with a window or application.
OBJID_CARET
 | Refers to the text insertion bar (caret) in the window.
OBJID_CLIENT
 | Refers to the window's client area. In most cases, the operating system controls the frame elements and the client object contains all elements that the application controls. List boxes use OBJID_CLIENT for item notifications.
OBJID_CURSOR
 | Refers to the mouse pointer. There is only one mouse pointer in the system and it is not a child of any window.
OBJID_HSCROLL
 | Refers to the window's horizontal scroll bar.
OBJID_MENU
 | Refers to the window's menu bar.
OBJID_SIZEGRIP
 | Refers to the window's size grip, an optional frame component located at the lower right corner of the window frame.
OBJID_SOUND
 | Refers to a sound object. Sound objects do not have screen locations or children, but do have name and state attributes. They are children of the application playing the sound.
OBJID_SYSMENU
 | Refers to the window's system menu.
OBJID_TITLEBAR
 | Refers to the window's title bar.
OBJID_VSCROLL
 | Refers to the window's vertical scroll bar.
OBJID_WINDOW
 | Refers to the window itself rather than a child object.


Object Roles

The following values (defined in oleacc.h) describe the role of objects within an application.

ROLE_SYSTEM_ALERT
 | This is an alert object. This role should be used only for objects that embody an alert but are not associated with another object such as a graphic, text, or sound.
ROLE_SYSTEM_APPLICATION
 | This object appears to the user as a main window for an application.
ROLE_SYSTEM_BORDER
 | This object is a window border; because of implementation constraints, the entire border is represented by a single object, rather than by separate objects for each side.
ROLE_SYSTEM_BUTTONDROPDOWN
 | This object is a button that drops down a list of items.
ROLE_SYSTEM_BUTTONDROPDOWNGRID
 | This object is a button that drops down a grid.
ROLE_SYSTEM_BUTTONMENU
 | This object is a button that drops down a menu.
ROLE_SYSTEM_CARET
 | This is the system object for the caret.
ROLE_SYSTEM_CELL
 | This object is a cell within a table.
ROLE_SYSTEM_CHARACTER
 | This object is a social interaction character or agent.
ROLE_SYSTEM_CHART
 | This object is a graphical image used to represent data.
ROLE_SYSTEM_CHECKBUTTON
 | This object appears to the user to function as a check box control; that is, an option that can be turned on or off independently of other options.
ROLE_SYSTEM_CLIENT
 | This object is a window's client area.
ROLE_SYSTEM_COLUMN
 | This object is a column of cells within a table.
ROLE_SYSTEM_COLUMNHEADER
 | This object appears to the user to function as a column header, providing a visual label for a column in a table, and might allow the user to select or adjust values for the entire column.
ROLE_SYSTEM_COMBOBOX
 | This object appears to the user to function as a combo box; that is, a text box with an associated list box, which can be dropped, or not.
ROLE_SYSTEM_CURSOR
 | This is the system object for the mouse pointer.
ROLE_SYSTEM_DIAL
 | This object appears to the user as a dial or knob. This can be a read-only object as well, showing a value like a speedometer.
ROLE_SYSTEM_DIALOG
 | This object appears to the user to function as a dialog box or message box.
ROLE_SYSTEM_DOCUMENT
 | This object appears to the user as a document window. A document window is always contained within an application window. This applies only to multiple-document interface (MDI) windows and refers to the object that contains the MDI title bar, and so on.
ROLE_SYSTEM_DROPLIST
 | This object appears to the user to function as a drop-down list box; that is, it shows one item and allows the user to display and select another from a list of alternative values.
ROLE_SYSTEM_GRAPHIC
 | This object appears to the user as a picture.
ROLE_SYSTEM_GRIP
 | This object is a mouse pointer target that, when activated, causes something to happen for as long as the target is activated. For example, in Windows 95, the user can click and drag around a sizing grip in the lower-right corner of each window, thus resizing the window.
ROLE_SYSTEM_GROUPING
 | This object logically groups other objects. There might or might not be a parent-child relationship between the grouping object and the objects it contains.
ROLE_SYSTEM_HELP
 | This is an object that displays Help in the form of a ToolTip, quick tip or Help balloon.
ROLE_SYSTEM_HOTKEYFIELD
 | This object appears to the user to function as a hot-key field; that is, it allows the user to enter a combination or sequence of keystrokes, which are then described by the hot-key field.
ROLE_SYSTEM_LINK
 | This object is a link to something else. This object might look like text or a graphic, but acts like a button.
ROLE_SYSTEM_LIST
 | This object appears to the user to function as a list box, allowing the user to choose between one or more choices.
ROLE_SYSTEM_LISTITEM
 | This object functions as an item in a list box or the list portion of a combo box, drop-down list box, or drop-down combo box.
ROLE_SYSTEM_MENUBAR
 | This is the menu "bar" usually located under the title bar.
ROLE_SYSTEM_MENUITEM
 | This object appears to the user to function as a menu item; that is, an entry in a menu that the user can choose to carry out a command, select an option, or display another menu. (Functionally, a menu item can be equivalent to a push button, radio button, check box, or menu.)
ROLE_SYSTEM_MENUPOPUP
 | This object appears to the user to function as a menu; that is, a window that can appear or disappear depending on some user action, and which displays a list of choices.
ROLE_SYSTEM_OUTLINE
 | This object appears to the user to function as an outline or tree structure, possibly allowing the user to expand and collapse branches.
ROLE_SYSTEM_OUTLINEITEM
 | This object is an item in an outline or tree.
ROLE_SYSTEM_PAGETAB
 | This object appears to the user to function as a page tab. Normally the only child of a pagetab control is a ROLE_SYSTEM_GROUPING object that contains the contents of the associated page.
ROLE_SYSTEM_PANE
 | This object appears to the user to act as a pane within a frame or document window. These objects are areas of a window that have separate contents from other areas of the window. Additionally, users can navigate between panes and within the contents of the current pane, but cannot magically navigate between items in different panes. Thus, panes represent a level of grouping lower than frame windows or documents, but above individual controls. Typically the user navigates between panes by pressing TAB, f6, or ctrl+tab, depending on the context.
ROLE_SYSTEM_PROGRESSBAR
 | This object appears to the user to function as a progress bar, dynamically showing the user the percent complete of an operation in progress. This control usually takes no user input.
ROLE_SYSTEM_PUSHBUTTON
 | This object appears to the user to function as a push button control.
ROLE_SYSTEM_RADIOBUTTON
 | This object appears to the user to function as an option button (also called a radio button); that is, one of a group of mutually exclusive options. All objects sharing a single parent that have this attribute are assumed to be part of single mutually exclusive group; You can use ROLE_SYSTEM_GROUPING objects to divide them into separate groups when necessary.
ROLE_SYSTEM_ROW
 | This object is a row of cells within a table.
ROLE_SYSTEM_ROWHEADER
 | This object appears to the user to function as a row header, providing a visual label for a table row, and might allow the user to select or adjust values for the entire row.
ROLE_SYSTEM_SCROLLBAR
 | This object is a vertical or horizontal scroll bar, either part of the client area or used in a control.
ROLE_SYSTEM_SEPARATOR
 | This is any object used to visually divide a space into two regions, such as a separator menu item or a bar dividing split panes within a window.
ROLE_SYSTEM_SLIDER
 | This object appears to the user to function as a slider, allowing the user to adjust a setting in given increments between given minimum and maximum values.
ROLE_SYSTEM_SOUND
 | This object is a system sound, associated with various system events.
ROLE_SYSTEM_SPINBUTTON
 | This object appears to the user to function as a spin box; that is, a control that allows the user to select next and previous (or "higher" and "lower") values from a list of appropriate values. The value can be displayed in a separate control ("buddy control") associated with the spin box.
ROLE_SYSTEM_STATICTEXT
 | This object appears to the user as static text. You cannot modify or select static text.
ROLE_SYSTEM_STATUSBAR
 | This object appears to the user to function as a status bar; that is, an area that displays information about the current operation, state of the application, or selected object. The status bar can have multiple fields, and can show different sets of one or more values.
ROLE_SYSTEM_TABLE
 | This object is a table containing rows and columns of cells, and optionally row headers and column headers.
ROLE_SYSTEM_TEXT
 | This object appears to the user as text that can be selected. It can be editable or read-only.
ROLE_SYSTEM_TITLEBAR
 | This object is a title or caption bar for the application.
ROLE_SYSTEM_TOOLBAR
 | This object appears to the user to function as a toolbar; that is, a grouping of controls that remains visible on the screen or within a window.
ROLE_SYSTEM_WINDOW
 | This object is the window frame, which usually consists of child objects such as a title bar, client, and so on.


Object State Constants

The following values (defined in oleacc.h) describe the states of objects within an application.

STATE_SYSTEM_ALERT_HIGH
 | It is important that this information be conveyed to the user immediately. For example, a battery level indicator reaching a critical level conveys truly urgent information, so a blind access utility should announce this information immediately, and a screen magnification program should scroll the screen so that this indicator is in view. This is also appropriate for any prompt or operation that must be completed before the user can continue.
STATE_SYSTEM_ALERT_LOW
 | This information is of low priority, so the user need not be immediately informed that it occurred; this can be a user option provided by the accessibility aid. For example, when Microsoft Word changes the appearance of the TipWizard button on its toolbar to indicate that it has a hint for the user, some users might want to know about this but others might not. Another example is helpful information that appears on an application's status bar when the user is in the middle of an operation.
STATE_SYSTEM_ALERT_MEDIUM
 | The user should be informed that this information is available, but the informational content need not be conveyed immediately. For example, when a battery level indicator reaches a low level, it should generate a medium-level alert. Blind access utilities could then generate a sound to let the user know that important information is available, without actually interrupting the user's work. The user could then query the alert information at his or her leisure.
STATE_SYSTEM_ANIMATED
 | Object's appearance is changing rapidly or constantly. (This alert should not be used if the object's location alone is changing.)
STATE_SYSTEM_BUSY
 | Control cannot accept input at this time.
STATE_SYSTEM_CHECKED
 | Object's check box is selected.
STATE_SYSTEM_COLLAPSED
 | Objects within this object that have the ROLE_SYSTEM_OUTLINEITEM role are hidden.
STATE_SYSTEM_DEFAULT
 | Default button or menu item.
STATE_SYSTEM_EXPANDED
 | Objects within this object that have the ROLE_SYSTEM_OUTLINEITEM role are displayed.
STATE_SYSTEM_EXTSELECTABLE
 | Object can extend its selection using SELFLAG_EXTENDSELECTION in the IAccessible::accSelect method.
STATE_SYSTEM_FLOATING
 | Object is not clipped to the boundary of its parent object, and is not assumed to move automatically when the parent moves. An event must be sent whenever the object changes location in screen coordinates; if an object does not have this attribute, an event must be triggered only when it moves relative to its parent.
STATE_SYSTEM_FOCUSABLE
 | Object can accept the input focus.
STATE_SYSTEM_FOCUSED
 | Item is focused. Do not confuse object focus with object selection. For more information, see Accessible Object Selection and Focus
STATE_SYSTEM_HOTTRACKED
 | Item is hot-tracked by the mouse, meaning that it has a special appearance used to indicate the mouse pointer is located over it.
STATE_SYSTEM_INVISIBLE
 | Object is hidden or invisible. This attribute is used for objects which currently not visible. Object which are never visible should be set as STATE_SYSTEM_OFFSCREEN. This state only reflects the items which are known to be invisible by the application. An object can be considered visible - the STATE_SYSTEM_INVISIBLE flag is not set - and yet be obscured by another application and not be visible to the user. For example, a object that appears in the main window of an application might be obsurced by a dialog. This object is considered visible. However, a list of files names in a list box might contain several hundred names, but only a few are visible to the user. The rest are clipped by the parent and should have STATE_SYSTEM_INVISIBLE set.
STATE_SYSTEM_MARQUEED
 | Scrolling or moving text.
STATE_SYSTEM_MIXED
 | Three-state check box or toolbar button.
STATE_SYSTEM_MULTISELECTABLE
 | Object can accept multiple selected items (that is, SELFLAG_ADDSELECTION for the IAccessible::accSelect method is valid).
STATE_SYSTEM_OFFSCREEN
 | This object has no on-screen representation. A sound or alert object would have this state.
STATE_SYSTEM_PRESSED
 | Item is pressed.
STATE_SYSTEM_READONLY
 | Item is read-only.
STATE_SYSTEM_SELECTABLE
 | Object can accept selection.
STATE_SYSTEM_SELECTED
 | Item is currently selected.
STATE_SYSTEM_SELFVOICING
 | Object or child can use Text To Speech (TTS) to voice itself. A speech-based accessibility aid would be advised not to announce information when this object is focused. This would be very frequent, and would be very distracting. However, when the focus is not on this object and it is referenced, the accessibility aid can provide information about the object for screen review purposes.
STATE_SYSTEM_UNAVAILABLE
 | Object is unavailable.


Navigation Constants

The following values (defined in oleacc.h) indicate physical or logical directions when navigating from one location or object to another by using the IAccessible::accNavigate method.

NAVDIR_DOWN
 | Locations or objects physically below the current one.
NAVDIR_FIRSTCHILD
 | Go to the first child of this object.
NAVDIR_LASTCHILD
 | Go to the last child of this object.
NAVDIR_LEFT
 | Locations or objects physically to the left of the current one.
NAVDIR_NEXT
 | The next logical location or object, generally a "sibling" to the current object. This ordering should be the navigational order, although in some cases it can represent logical relationships. It should always seem reasonable to the user. It is not necessarily the indexing order used with child. For example, in a dialog box, the tab key takes you to the next logical control, although this can be represented in any number of different physical directions.
NAVDIR_PREVIOUS
 | The previous logical location or object. This ordering should be the navigational order, although in some cases it can represent logical relationships. It should always seem reasonable to the user. It is not necessarily the indexing order used with child. In a dialog box, the shift+tab key combination takes you to the previous logical control, although this might be in any number of physical directions visually on the screen. For example, in vertical toolbars, logically the previous button is often the button physically above (NAVDIR_UP) the current one, whereas in horizontal toolbars, logically the previous button is generally the button physically to the left (NAVDIR_LEFT) of the current one.
NAVDIR_RIGHT
 | Locations or objects physically to the right of the current one.
NAVDIR_UP
 | Locations or objects physically above the current one.


Return Values

This table lists the values that all the IAccessible interface methods can return.

DISP_E_MEMBERNOTFOUND
 | The current object does not support the requested property or action. For example, a push button returns this value if you request its Value property, since it has none.
E_INVALIDARG
 | One or more arguments was invalid. This error can occur when the caller attempts to identify a child object using an identifier that the server doesn't support (child ID when the server uses strings, or vice versa). This error can also result when a client attempts to identify a child object within an object that has no children.
E_FAIL
 | An unknown or generic error occurred.
E_NOTIMPL
 | The method is not implemented. This value can occur when a client calls a method that isn't yet supported in that operating system.
E_OUTOFMEMORY
 | The method was unable to allocate memory required to complete an operation crucial to its success.
S_FALSE
 | The method succeeded in part. This can happen when the method itself succeeded, but the requested information isn't available. For example, this return value will result if you call the IAccessible::accHitTest method to retrieve a child object at a given point and the specified point is not within the parent object.
S_OK
 | The method succeeded.

Like all COM error codes, you can use the SUCCEEDED and FAILED macros to test the HRESULT return values that Active Accessibility API elements return. Although these macros provide a simple way to test for a method's overall success or failure, always check the output parameters that you pass with a method call. For example, when one of a method's output parameters is a pointer, you can get a successful return value (such as S_FALSE) but still receive a NULL pointer in an output parameter.


SELFLAG

Describes how an accessible object will become selected or take focus. These values are used with the IAccessible::accSelect method.

typedef enum tagSELFLAG
{
    SELFLAG_NONE            = 0,
    SELFLAG_TAKEFOCUS       = 1,
    SELFLAG_TAKESELECTION   = 2,
    SELFLAG_EXTENDSELECTION = 4,
    SELFLAG_ADDSELECTION    = 8,
    SELFLAG_REMOVESELECTION = 16
} SELFLAG;

Members

SELFLAG_NONE
Used only to test for argument validity.
SELFLAG_TAKEFOCUS
The object will take the input focus and become the selection anchor. This value does not alter the selection unless specified by other flags, so it is useful when altering the input focus without changing the selection itself (that is, moving the focus by pressing the arrow keys while holding down the ctrl key in File Manager or a Windows 95® folder, or maneuvering the input-focus cell in a multicell selection within a spreadsheet application such as Microsoft Excel).

To select a range of objects and put the focus on the last object: This requires two calls: in the first, specify the SELFLAG_TAKEFOCUS on the starting object; in the second, specify a combination of the SELFLAG_EXTENDSELECTION and SELFLAG_TAKEFOCUS on the last object.

SELFLAG_TAKESELECTION
The object becomes the only selected object in the container. Valid flag combinations are:
NONE
TAKE FOCUS
TAKE SELECTION
ADD SELECTION
REMOVE SELECTION
EXTEND SELECTION
TAKE FOCUS and TAKE SELECTION
TAKE FOCUS and ADD SELECTION
TAKE FOCUS and REMOVE SELECTION
TAKE FOCUS and EXTEND SELECTION
ADD SELECTION and EXTEND SELECTION
REMOVE SELECTION and EXTEND SELECTION
TAKE FOCUS, ADD SELECTION, and EXTEND SELECTION
TAKE FOCUS, REMOVE SELECTION, and EXTEND SELECTION

Invalid flag combinations are:
ADDSELECTION and REMOVESELECTION
ADDSELECTION and TAKESELECTION
REMOVESELECTION and TAKESELECTION
EXTENDSELECTION and TAKESELECTION

SELFLAG_EXTENDSELECTION
The current selection will be logically extended to include this object. If specified with SELFLAG_ADDSELECTION, all objects logically between the current anchor and the selection become selected. If specified with SELFLAG_REMOVESELECTION, the selection of those objects is canceled. If neither SELFLAG_ADDSELECTION nor SELFLAG_REMOVESELECTION are specified, all objects logically between the current anchor and the selection take on the anchor object's selection state. That is, the objects are added to or removed from the selection depending on the state of the object at the selection anchor (that is, adding or removing items by pressing shift+click or shift+space selection in File Manager, a Windows 95 folder, or an extended-selection list box).
SELFLAG_ADDSELECTION
Not valid with SELFLAG_REMOVESELECTION. The current object will be added individually to the current selection, possibly resulting in a disjoint selection (that is, adding or removing items by pressing ctrl+click or ctrl+space selection of an unselected object in a multiselect list box or in the Windows Explorer).
SELFLAG_REMOVESELECTION
Not valid with SELFLAG_ADDSELECTION. The current object will be removed individually from the current selection, and might result in a noncontiguous selection (that is, adding or removing items by pressing ctrl+click or ctrl+space selection of a selected object in a multiselect list box or in the Windows Explorer).


VB Developer's Guide and Reference


VB Developer's Reference

This section contains general reference information about Active Accessibility for Visual Basic developers. The following topics are discussed.

  • Visual Basic Method Notes
  • Visual Basic Sample: VBinsp


Visual Basic Method Notes

This section contains important notes that detail differences between the accessible object methods when called from Visual Basic versus C or C++.

  • accName
  • accValue


Visual Basic Method Notes: accName

The Object Description Language (ODL) file, oleacc.odl, contains information that differs between the VB and C/C++ implementations. Oleacc.odl contains the following definition for the property-setting version of the function.

[hidden, propput, id(DISPID_ACC_NAME)]
    HRESULT accName(
        [in, optional] VARIANT varChild,
        [in] BSTR szName);

Although the varChild parameter is listed as optional in the ODL file and the object browser, you must include it when calling the property setting version of accName.


Visual Basic Method Notes: accValue

The Object Description Language (ODL) file, oleacc.odl, contains information that differs between the VB and C/C++ implementations. Oleacc.odl contains the following definition for the property-setting version of the function.

[hidden, propput, id(DISPID_ACC_VALUE)]
    HRESULT accValue(
        [in, optional] VARIANT varChild,
        [in] BSTR szValue);

Although the varChild parameter is listed as optional in the ODL file and the object browser, you must include it when calling the property setting version of accValue.


Visual Basic Sample: VBinsp

Currently, the Active Accessibility SDK includes one example of a Visual Basic application that incorporates Active Accessibility technology, called "VBinsp."

This application is very similar to the Inspect.exe C/C++ sample application, and provides a simple illustration of how a VB4 can incorporate Active Accessibility technology. The sample reports most of the Accessible information exposed by the object currently under the mouse pointer.

The VBinsp sample code incorporates a timer control that it uses to determine the time increments between each query. On every timer tick, the code queries the object under the pointer and displays the results in a Visual Basic form. In the SDK, VBinsp is not an executable file. Rather, it is a set of VB source code found in the samples directory.


Appendix


Appendix A - IAccessible DISPIDs

A DISPID allows the implementation of IDispatch lookup the various methods and properties of a dual interface.

// PROPERTIES: Hierarchical
#define DISPID_ACC_PARENT                   (-5000)
#define DISPID_ACC_CHILDCOUNT               (-5001)
#define DISPID_ACC_CHILD                    (-5002)

// PROPERTIES:  Descriptional
#define DISPID_ACC_NAME                     (-5003)
#define DISPID_ACC_VALUE                    (-5004)
#define DISPID_ACC_DESCRIPTION              (-5005)
#define DISPID_ACC_ROLE                     (-5006)
#define DISPID_ACC_STATE                    (-5007)
#define DISPID_ACC_HELP                     (-5008)
#define DISPID_ACC_HELPTOPIC                (-5009)
#define DISPID_ACC_KEYBOARDSHORTCUT         (-5010)
#define DISPID_ACC_FOCUS                    (-5011)
#define DISPID_ACC_SELECTION                (-5012)
#define DISPID_ACC_DEFAULTACTION            (-5013)

// METHODS
#define DISPID_ACC_SELECT                   (-5014)
#define DISPID_ACC_LOCATION                 (-5015)
#define DISPID_ACC_NAVIGATE                 (-5016)
#define DISPID_ACC_HITTEST                  (-5017)
#define DISPID_ACC_DODEFAULTACTION          (-5018)


Appendix B - Variant Types

Data Type | Member | VARTYPE
unsigned char | bVal | VT_UI1
short | iVal | VT_I2
long | lVal | VT_I4
float | fltVal | VT_R4
double | dblVal | VT_R8
VARIANT_BOOL | bool | VT_BOOL
SCODE | scode | VT_ERROR
CY | cyVal | VT_CY
DATE | date | VT_DATE
BSTR | bstrVal | VT_BSTR
LPUNKNOWN | punkVal | VT_UNKNOWN
LPDISPATCH | pdispVal | VT_DISPATCH
SAFEARRAY * | parray | VT_ARRAY|*
unsigned char * | pbVal | VT_BYREF|VT_UI1
short * | piVal | VT_BYREF|VT_I2
long * | plVal | VT_BYREF|VT_I4
float * | pfltVal | VT_BYREF|VT_R4
double * | pdblVal | VT_BYREF|VT_R8
VARIANT_BOOL * | pbool | VT_BYREF|VT_BOOL
SCODE * | pscode | VT_BYREF|VT_ERROR
CY * | pcyVal | VT_BYREF|VT_CY
DATE * | pdate | VT_BYREF|VT_DATE
BSTR * | pbstrVal | VT_BYREF|VT_BSTR
LPUNKNOWN * | ppunkVal | VT_BYREF|VT_UNKNOWN
LPDISPATCH * | ppdispVal | VT_BYREF|VT_DISPATCH
SAFEARRAY ** | pparray | VT_BYREF|VT_ARRAY|*
VARIANT * | pvarVal | VT_BYREF|VT_VARIANT

In addition to the tag and arm, the VARIANTARG contains additional reserved members to properly align the arm on 8-byte boundaries (to support efficient copying of 8-byte doubles); these members (along with any unused bytes in the arm) must be properly initialized with the VariantInit API. Once initialized, the tag and arm of each VARIANTARG are assigned the proper values. It is important to note that arguments are stored in the array in right to-left order. The DISPPARAMS structure bundles the VARIANTARG array with an array of DISPIDs that correspond to the names of each argument.

typedef struct tagDISPPARAMS {
// Array of arguments
    VARIANTARG FAR* rgvarg;
// DISPIDS of named arguments
    DISPID FAR* rgdispidNamedArgs;
// Number of arguments
    unsigned int cArgs;
// Number of named arguments
    unsigned int cNamedArgs;
} DISPPARAMS;


Appendix C - Supported Objects

Active Accessibility provides support for many common components within the system. For more information about these objects, see Support for Standard Objects.


Appendix D - Window Elements

Information for this section is not completely available at the time of this beta release of the Active Accessibility SDK, but will be provided for future releases.

MDI Client Windows

  • Description
  • Properties and Methods
  • Events

Menus

  • Description
  • Properties and Methods
  • Events

Size Grip

  • Description

    The size grip is located in the lower left corner of a window. Mouse users can click and drag the size grip to resize the window.

  • Properties and Methods

    Description

    HitTest

    Location

    Name

    Navigation

    Role

    State

  • Events

Title Bar

  • Description

    Windows can have titles bars drawn by the operating system. Dialog boxes and top-level application windows are usually drawn with a title bar. The title bar contains text identifying the window. Sometimes buttons are placed on the title bar to give the user control over the window state.

  • Properties and Methods

    DefaultAction

    Description

    DoDefaultAction

    HitText

    Location

    Name

    Navigate

    Role

    State

    Value

  • Events


Appendix E - User Interface Controls

These controls are provided by the system and COMCTL32 and are used throughout Windows 95 and applications written for it.

Note This refers only to controls exposed by COMCTL32.DLL, not 16-bit controls. At present Active Accessibility does not support the 16-bit versions (mainly status bar and toolbar). Also, keep in mind that edits, statics, titlebars, buttons, (may be others) have a limit of 4096 bytes of text they will return.

Animation

  • Properties and Methods
  • Events

Button

  • Properties and Methods

    DefaultAction is "Press"

    DoDefaultAction presses the button as if a user clicked on it.

  • Events

Check Boxes

  • Properties and Methods

    DefaultAction is "Check" if unchecked, "Uncheck" if checked

    DoDefaultAction checks or unchecks the check box

ComboBox

  • Properties and Methods

    DefaultAction is "Drop down" if combo list is hidden, or "Pop up" if shown.

    DoDefaultAction shows or hides the list

  • Events

Edit

  • Properties and Methods
  • Events

Header

  • Properties and Methods
  • Events
    • CREATE when header is added
    • DESTROY when header is removed
    • REORDER when the columns are rearranged

HotKey

  • Properties and Methods
  • Events
    • VALUECHANGE when the hot key changes

ListBox

  • Properties and Methods
  • Events

ListView

  • Properties and Methods
  • Events
    • CREATE when item added
    • DESTROY when item deleted
    • FOCUS when the item with the caret changes
    • NAMECHANGE when the name of an item is changed
    • SELECTION when one item is selected
    • SELECTIONADD for multiselect list view controls (when another item is added to the selection).
    • SELECTIONREMOVE for multiselect list views when an item is deselected

    Notes

    • OWNERDRAW list views might not give you back item text.
    • On the CREATE for some list view items, you might get no text (but it will show up later), because of the LPSTR_CALLBACK option, there's no way to know when this happens.
    • Most applications add in toolbar buttons groups at a time, in which case you'll see REORDER instead of a ton of creates. But VB and MFC do it one at a time, so we do generate a CREATE in that case.

ProgressBar

  • Properties and Methods
  • Events
    • VALUECHANGE when the position changes

Radio Buttons

  • Properties and Methods

    DoDefaultAction selects the radio button, deselecting the others in a group.

Note

This works only when the radio buttons have the BS_AUTORADIOBUTTON style set.

RichEdit

  • Properties and Methods
  • Events

ScrollBar

  • Properties and Methods
  • Events

Slider

  • Properties and Methods
  • Event
    • VALUECHANGE when the thumb moves

Spin Buttons

  • Properties and Methods
  • Events
    • STATECHANGE when a button is pressed, released
    • VALUECHANGE when the position in the buddy changes

Static

  • Properties and Methods
  • Events

StatusBar

  • Events
    • NAMECHANGE when the contents of a status bar slot change

TabControl

  • Properties and Methods

    DefaultAction is "Switch"

    DoDefaultAction selects the tab

  • Events
    • CREATE when a tab is added to the list
    • DESTROY when a tab is removed from the list
    • FOCUS/SELECTION when the currently active tab changes

Toolbar

  • Properties and Methods
  • Events
    • CREATE or REORDER when one or several buttons are added
    • DESTROY when a button is removed
    • STATECHANGE for the buttons when pressed, released, enabled, disabled

    Please Note : the problem with toolbars is that they aren't supposed to have children who are windows. They don't even support it very well as a hack. What someone designing an app with a toolbar has to do if they want a real window on it is to scoot all the buttons (the "real" children of the toolbar) over to the right, and then place their window. So Active Accessibility does a similar hack. When you are doing Next or Previous, it checks if you started at a child that has an HWNDID. If so, it gives back the first child (if doing NEXT) or the toolbar itself (if PREVIOUS).

    Also, if you start at the toolbar itself and are going next, it will check if there is a child window, and if so, return an IDispatch to the window in the VARIANT. If you start at the first "real" child and go previous, it will do the same thing - check for a child window and return an IDispatch to it if it is there.

    This is a major limitation in that this will only work for toolbars that have 0 or 1 children that are windows themselves.

ToolTips

  • Properties and Methods

    Name

    Role

    Value

  • Events

TreeView

  • Properties and Methods
  • Events
    • CREATE when item added
    • DESTROY when item deleted
    • FOCUS when caret changes
    • NAMECHANGE when item renamed
    • SELECTION when selected item changes
    • STATECHANGE when item expanded or collapsed
  • Notes
    • The role of the tree view is ROLE_SYSTEM_OUTLINE; the items' roles are ROLE_SYSTEM_OUTLINEITEM.
    • All items, regardless of their position in the hierarchy, are peer children of the tree view
    • The value of an item is the "indent level". So, for example, the value of the "Desktop" item would be zero because it is the root.
    • A tool can use the value to figure out which items are logically grouped under another. If you have an item, ask for the next one. If that next one's value is <= the value of the start item, you are done. If the item has a value of one greater than the start, it must be a logical item directly underneath. In other words, the value is the indent level.
    • Items that are expandable and collapsible are the only ones with default action. If an item is expanded, the default action is to collapse it. If an item is collapsed, the default action is to expand it


Appendix F - Other System Elements

Alt Tab Window

  • Description

    The Alt Tab window is what appears when the user presses the alt and tab keys together. It displays a dialog-link window with a series of icons displayed in one or more rows. Each icon represents a running application.

  • Properties and Methods

    DefaultAction is "Switch"

    DoDefaultAction switches to the application referenced by the item

  • Events

    Normal window and focus events are sent with this object

Carets

  • Description

    Carets are the insertion point in editable text. Carets are owned by applications, but the operating system is aware of them. Not all applications use the system-provided caret APIs, opting instead to draw and redraw the caret themselves. In such cases, Active Accessibility can't provide information.

  • Properties and Methods

    HitTest

    Location

    Name

    Role

    State

  • Events
    • CREATE/DESTROY
    • LOCATIONCHANGE when moved
    • STATECHANGE when shown or hidden.

Owner Drawn Menus

  • Such as the Windows 95 Start menu and right-click shortcut menus.

System Tray


Appendix G - Standard Dialog Manager Support

Active Accessibility provides complete support for Standard Dialog Manager dialog box controls. For more information, see Support for Standard Dialog Manager.


Appendix H - Mshtml.dll Support

Active Accessibility supports HTML through the mshtml.dll dynamic-link library included with the Microsoft Internet Explorer 3.0 World Wide Web browser and other software packages. For more information, see Support for MSHTML.

Exposed Objects

  • Images

    Text

    Links

    White Space

    Client-side Image Maps

  • Events

    The MSHTML control allows the user to press the tab key to move to focusable elements on the page. MSHTML sends out the appropriate EVENT_OBJECT_FOCUS event. An Active Accessibility client can use AccessibleObjectFromEvent to get information about the child element that was focused.


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.