Windows Accessibility Features

[This is preliminary documentation and subject to change.]

The Win32 API provides a set of accessibility features that make it easier for persons with disabilities to use computers. This overview describes the provided accessibility features and the Win32 functions and structures for controlling these features.

For information about other accessibility features, see About the Active Accessibility SDK.

Microsoft Platform SDK, February 2001 Edition.
This content last built on Wednesday, February 07, 2001.


About Windows Accessibility Features

There are two categories of accessibility features that correspond to the settings available to users through the Accessibility Options Control Panel application:

  • Accessibility parameters. When set, these parameters indicate that applications should change their default behavior. Applications can check the state of an accessibility parameter to determine whether the user wants special behavior that can be provided in an application-specific manner. For example, the ShowSounds parameter indicates that an application that typically uses sound to convey important information should also provide the information visually.
  • Built-in accessibility features. These features are built into the system or provided as an extension to the system. They affect how the user provides keyboard and mouse input to the computer. When enabled, their functionality is available regardless of which applications are running. An example is a keyboard filter that makes it easier for users with movement impairments to type key combinations such as CTRL+ALT+DEL.

Each accessibility parameter and each built-in accessibility feature corresponds to a system parameter that can be set or queried with the SystemParametersInfo function.


Accessibility Parameters

The system maintains a set of accessibility parameters that indicate whether the user has special needs or preferences that require applications to change their default behavior. The user controls the state of these parameters, typically using the Accessibility Options Control Panel application. Control Panel applications or other programs that allow the user to customize the environment can use the SystemParametersInfo function to set the accessibility parameters.

If a user changes these parameters, the Control Panel sends the WM_SETTINGCHANGE message. Applications should respond to this message and use SystemParametersInfo to determine the state of the accessibility parameters. When an accessibility parameter is enabled, the application should modify its user interface, if necessary, to accommodate the user's preferences.

Win32 supports the following accessibility parameters.

Parameter | Description
High contrast | Indicates that applications should provide high contrast between foreground and background visuals.
Keyboard Preference | Indicates that applications should display keyboard interfaces that would otherwise be hidden.
Screen Reader | Indicates that applications should provide textual information in situations where it would otherwise present the information graphically.
ShowSounds | Indicates that applications should also provide a visual alert or cue when it uses sound to convey important information.


High Contrast Parameter

The high contrast parameter indicates whether the user wants a high contrast between the colors used for foreground and background visuals.

The user controls the setting of the high contrast parameter by using the Accessibility Control Panel application or another application for customizing the environment. Applications use the SPI_GETHIGHCONTRAST and SPI_SETHIGHCONTRAST flags with the SystemParametersInfo function to get and set the high contrast parameter.

During initialization and when processing WM_SYSCOLORCHANGE messages, applications should determine the state of the high contrast parameter. To make this determination, applications should call SystemParametersInfo with the SPI_GETHIGHCONTRAST flag to obtain a HIGHCONTRAST structure. If the dwFlags member of the HIGHCONTRAST structure has the HCF_HIGHCONTRASTON bit set, then the high contrast feature is enabled, and applications should do the following:

  • Map all colors to a single pair of foreground and background colors. Use the GetSysColor function to determine the appropriate foreground and background colors, using either a combination of COLOR_WINDOWTEXT and COLOR_WINDOW or a combination of COLOR_BTNTEXT and COLOR_BTNFACE. The GetSysColor function returns the colors selected by the user through the Control Panel.
  • Omit any bitmapped images that would typically be displayed behind text. Such images are visually distracting to a user who needs high contrast.
  • Images that would typically be drawn in multiple colors should be drawn using the foreground and background colors selected for text.


Keyboard Preference Parameter

The keyboard preference parameter indicates that the user relies on the keyboard instead of the mouse, so applications should display keyboard interfaces that would otherwise be hidden.

The user controls the setting of the keyboard preference parameter by using the Accessibility Control Panel application or another application for customizing the environment. Applications use the SPI_GETKEYBOARDPREF and SPI_SETKEYBOARDPREF flags with the SystemParametersInfo function to get and set the keyboard preference parameter.

Additionally, on Windows 2000, users can set a parameter that indicates whether menu access keys are always underlined. Applications use the SPI_GETMENUUNDERLINES and SPI_SETMENUUNDERLINES flags with the SystemParametersInfo function to get and set the menu underlines parameter.

When an application receives a WM_SETTINGCHANGE message for either the keyboard preference or menu underline parameter, it is recommended that the application call SystemParametersInfo to update the information for both parameters.

Note that SPI_GETMENUUNDERLINES is the same as SPI_GETKEYBOARDCUES, and SPI_SETMENUUNDERLINES is the same as SPI_SETKEYBOARDCUES.


Screen Reader Parameter

The screen reader parameter indicates whether an application should provide textual information in situations where it would otherwise present the information graphically.

This parameter is typically set by accessibility aids such as screen readers. Applications use the SPI_GETSCREENREADER and SPI_SETSCREENREADER flags with the SystemParametersInfo function to get and set the screen reader parameter.


ShowSounds Parameter

The ShowSounds parameter indicates whether the user wants applications to present all important information in visual form.

The user controls the setting of the ShowSounds parameter by using the Accessibility Options Control Panel application or another application for customizing the environment. Applications use the SPI_GETSHOWSOUNDS and SPI_SETSHOWSOUNDS flags with the SystemParametersInfo function to get and set the ShowSounds parameter. Alternatively, applications can use the SM_SHOWSOUNDS flag with the GetSystemMetrics function to determine the state of the ShowSounds parameter.

Determining the state of the ShowSounds parameter is necessary only for applications that would typically present important information by sound alone. Applications should provide ShowSounds support if they use sounds in either of the following ways:

  • To convey information that is important to the operation of the application.
  • To alert the user that important information is being presented visually. If this is the case, even though the information is presented visually, the sound has the additional function of attracting the attention of the user.

Appropriate visual feedback forms can make the software much more functional for users who cannot rely on sound alone. The design of the visual feedback is application specific and depends on the information that will be presented to the user. For example, to attract the user's attention when new electronic mail arrives, the application might flash its window or even flash the entire screen. If the application typically makes sound to indicate that the user is trying to perform an illegal operation, it could also display an appropriate message on its status line or use the MessageBox function to display a specific error message. If the application is typically designed to play sound bites that carry meaning, such as digitized speech, it could also display a caption window with the same text.

Redundant use of audible and visual alerts has been shown to increase the usability of software applications. The ShowSounds parameter is a request for visual feedback, but its use does not restrict an application to presenting information visually. Users should be able to request visual feedback regardless of whether they also want audible feedback.


Built-in Accessibility Features

The built-in accessibility features are extensions to the operating system. These features affect the behavior of the system regardless of which applications are running.

Win32 supports the following built-in accessibility features.

Feature | Description
AccessTimeout | Enables a user to specify a timeout interval after which system-wide accessibility features are automatically disabled. The AccessTimeout feature is intended for computers that are shared by several users with different preferences. Each individual can use hot keys or the Control Panel to enable preferred features. The accessibility time-out period is the length of time that must pass without keyboard and mouse input before the operating system automatically turns off accessibility features. The accessibility features affected by the timeout are FilterKeys, MouseKeys, StickyKeys, and ToggleKeys, and high contrast. The ACCESSTIMEOUT structure defines the parameters for this feature.
FilterKeys | Enables control of keyboard properties, such as the amount of time before a keystroke is accepted as input and the amount of time before a keystroke begins to repeat. The FilterKeys feature also provides sound feedback when a key is pressed and when it is accepted as input. The FILTERKEYS structure defines the parameters for this feature.
MouseKeys | Enables the user to control the mouse pointer using the numeric keypad. The MOUSEKEYS structure defines the parameters for this feature.
SerialKeys | Enables the user to provide input using an alternate input device attached to the computer's serial port. This feature is designed for users who are unable to use the computer's standard keyboard and mouse. The SERIALKEYS structure defines the parameters for this feature.
SoundSentry | Displays a visual signal when a sound is generated by a Win32-based application or an MS-DOS application running in a window. The SOUNDSENTRY structure defines the parameters for this feature, including the address of the SoundSentryProc callback function.
StickyKeys | Enables the user to type key combinations, such as CTRL+ALT+DEL, in sequence rather than at the same time. The STICKYKEYS structure defines the parameters for this feature.
ToggleKeys | Provides sound feedback when the user turns on or off the CAPS LOCK, NUM LOCK, or SCROLL LOCK keys. The TOGGLEKEYS structure defines the parameters for this feature.

The SystemParametersInfo function provides the programming interface to the built-in accessibility features. This function is useful in Control Panel applications or other programs that allow the user to customize the environment. The SystemParametersInfo function can perform the following tasks:

  • Query the system to determine the availability and current state of a specified built-in accessibility feature.
  • Enable a feature and specify parameters that control its behavior.
  • Disable a feature.
  • Enable a hot key that allows the user to enable or disable a feature.

For each of the built-in features, Win32 defines a structure that applications use with SystemParametersInfo to query or set the parameters of the feature.

An application can use SystemParametersInfo to enable or disable a feature directly. For some of the features, SystemParametersInfo can enable a hot key or key combination so the user can toggle the state of a feature. There are no hot keys for the SerialKeys or SoundSentry features, or for the ShowSounds parameter. The following accessibility features have hot keys.

Feature | Description
FilterKeys | Hold down the RIGHT SHIFT key for eight seconds to toggle the FilterKeys feature on or off. Holding down the RIGHT SHIFT key for 12 seconds enables FilterKeys using the most conservative values for FILTERKEYS.iBounceMSec. Holding down the RIGHT SHIFT key for 16 seconds enables FilterKeys using the most conservative values for FILTERKEYS.iWaitMSec.
MouseKeys | Press LEFT ALT + LEFT SHIFT + NUM LOCK.
StickyKeys | Press the SHIFT key 5 times.
ToggleKeys | Hold down the NUM LOCK key for 5 seconds.
High contrast mode | Press LEFT ALT + LEFT SHIFT + PRINT SCREEN.


Using Windows Accessibility Features

  • Checking the state of an accessibility parameter
  • Enabling a built-in accessibility feature


Checking the State of an Accessibility Parameter

The following code fragment uses the GetSystemMetrics function to check the ShowSounds parameter. If GetSystemMetrics returns TRUE, the application should present all important information in visual form.

BOOL fShowSounds;
fShowSounds = GetSystemMetrics(SM_SHOWSOUNDS);


Enabling a Built-in Accessibility Feature

The following code fragment uses the SystemParametersInfo function to enable the FilterKeys feature:

FILTERKEYS fk;
BOOL bSuccess;

// Fill in the members of the FILTERKEYS structure.

fk.cbSize = sizeof(FILTERKEYS);
fk.dwFlags = (FKF_FILTERKEYSON | FKF_HOTKEYACTIVE |
                       FKF_AVAILABLE | FKF_HOTKEYSOUND | FKF_CLICKON);
fk.iWaitMSec = 1000;
fk.iDelayMSec = 1000;
fk.iRepeatMSec = 500;
fk.iBounceMSec = 0;

// Call SystemParametersInfo with the SPI_SETFILTERKEYS flag.

bSuccess = SystemParametersInfo(SPI_SETFILTERKEYS, 0, (LPVOID) &fk, 0);


Windows Accessibility Features Reference

The following elements are used with accessibility features.

  • Accessibility Functions
  • Accessibility Structures


Accessibility Functions

Use the following functions to implement accessibility features:

SoundSentryProc
SystemParametersInfo


SoundSentryProc

The SoundSentryProc function is an application-specific callback function that produces a customized visual signal when the SoundSentry accessibility feature is on and a Win32-based application (or an application running in a window) generates a sound through the computer's built-in speaker.

LRESULT CALLBACK SoundSentryProc(
  DWORD dwMillisec,  // duration of visual signal
  DWORD fdwEffect    // effect-type flag
);

Parameters

dwMillisec
Specifies the duration, in milliseconds, of the visual signal that is displayed when a Win32-based application (or an application running in a window) generates a sound.
fdwEffect
Specifies the type of visual signal to display. Currently, this value must always be SSWF_CUSTOM.

Return Values

If the visual signal was or will be displayed correctly, the return value is TRUE. If the signal is asynchronous and the status is not available when the function is called, it should return TRUE.

If an error prevented the signal from being displayed, the return value is FALSE. To get extended error information, call GetLastError.

Remarks

The SoundSentryProc function must be defined in a 32-bit DLL, and the DLL must export a function with the name SoundSentryProc.

The SoundSentryProc function is called only after an application or library calls the SystemParametersInfo function, specifying the SPI_SETSOUNDSENTRY value and the address of a SOUNDSENTRY structure whose iWindowsEffect member is set to SSWF_CUSTOM.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Functions, SOUNDSENTRY, SystemParametersInfo


Accessibility Structures

Use the following structures to implement accessibility features:

ACCESSTIMEOUT
FILTERKEYS
HIGHCONTRAST
MOUSEKEYS
SERIALKEYS
SOUNDSENTRY
STICKYKEYS
TOGGLEKEYS


ACCESSTIMEOUT

The ACCESSTIMEOUT structure contains information about the time-out period associated with the Win32 accessibility features. The accessibility time-out period is the length of time that must pass without keyboard and mouse input before the operating system automatically turns off accessibility features. The accessibility time-out is designed for computers that are shared by several users so that options selected by one user do not inconvenience a subsequent user.

The accessibility features affected by the time-out are the FilterKeys features (SlowKeys, BounceKeys, and RepeatKeys), MouseKeys, ToggleKeys, and StickyKeys. The accessibility time-out also affects the high contrast mode setting.

typedef struct tagACCESSTIMEOUT {
    UINT   cbSize;
    DWORD  dwFlags;
    DWORD  iTimeOutMSec;
} ACCESSTIMEOUT, *LPACCESSTIMEOUT;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
A set of bit flags that specify properties of the time-out behavior for accessibility features. The following values are defined.
Value | Meaning
ATF_ONOFFFEEDBACK | If this flag is set, the operating system plays a descending siren sound when the time-out period elapses and the accessibility features are turned off.
ATF_TIMEOUTON | If this flag is set, a time-out period has been set for accessibility features. If this flag is not set, the features will not time out even though a time-out period is specified.

iTimeOutMSec
Specifies the time-out period, in milliseconds.

Remarks

Use an ACCESSTIMEOUT structure when calling the SystemParametersInfo function with the uiAction parameter set to the SPI_GETACCESSTIMEOUT or SPI_SETACCESSTIMEOUT value. When using SPI_GETACCESSTIMEOUT, you must specify the cbSize member of the ACCESSTIMEOUT structure; the SystemParametersInfo function fills in the remaining members. Specify all structure members when using the SPI_SETACCESSTIMEOUT value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


FILTERKEYS

The FILTERKEYS structure contains information about the FilterKeys accessibility feature, which allow a user with disabilities to set the keyboard repeat rate (RepeatKeys), acceptance delay (SlowKeys), and bounce rate (BounceKeys).

typedef struct tagFILTERKEYS {
    UINT   cbSize;
    DWORD  dwFlags;
    DWORD  iWaitMSec;
    DWORD  iDelayMSec;
    DWORD  iRepeatMSec;
    DWORD  iBounceMSec;
} FILTERKEYS *LPFILTERKEYS;

Members

cbSize
Specifies the structure size, in bytes.
dwFlags
A set of bit flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:
Value | Meaning
FKF_AVAILABLE | The FilterKeys features are available.
FKF_CLICKON | The computer makes a click sound when a key is pressed or accepted. If SlowKeys is on, a click is generated when the key is pressed and again when the keystroke is accepted.
FKF_FILTERKEYSON | The FilterKeys features are on.
FKF_HOTKEYACTIVE | The user can turn the FilterKeys feature on and off by holding down the RIGHT SHIFT key for eight seconds.
FKF_HOTKEYSOUND | If this flag is set, the computer plays a siren sound when the user turns the FilterKeys feature on or off by using the hot key.
FKF_CONFIRMHOTKEY | Windows 95/98, Windows 2000: A confirmation dialog box appears when the FilterKeys features are activated by using the hot key.
FKF_INDICATOR | Windows 95/98, Windows 2000: A visual indicator is displayed when the FilterKeys features are on.

iWaitMSec
Specifies the length of time, in milliseconds, that the user must hold down a key before it is accepted by the computer.
iDelayMSec
Specifies the length of time, in milliseconds, that the user must hold down a key before it begins to repeat.
iRepeatMSec
Specifies the length of time, in milliseconds, between each repetition of the keystroke.
iBounceMSec
Specifies the amount of time, in milliseconds, that must elapse after releasing a key before the computer will accept a subsequent press of the same key.

Remarks

Use a FILTERKEYS structure when calling the SystemParametersInfo function with the uiAction parameter set to the SPI_GETFILTERKEYS or SPI_SETFILTERKEYS value. When using SPI_GETFILTERKEYS, you must specify the cbSize member of the FILTERKEYS structure; the SystemParametersInfo function fills the remaining members. Specify all structure members when using the SPI_SETFILTERKEYS value.

At least one of the iDelayMSec and iBounceMSec members must be zero; they cannot both be nonzero at the same time.

If iBounceMSec is nonzero, the BounceKeys feature is on and the SlowKeys feature is off (the iDelayMSec value is ignored). If iBounceMSec is zero, the BounceKeys feature is off.

If iDelayMSec is nonzero and iBounceMSec is zero, the SlowKeys feature is on; otherwise, it is off.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


HIGHCONTRAST

The HIGHCONTRAST structure contains information about the high contrast accessibility feature, which sets the appearance scheme of the user interface for maximum visibility for a visually-impaired user, and advises applications to comply with this appearance scheme.

typedef struct tagHIGHCONTRAST {
    UINT    cbSize;
    DWORD   dwFlags;
    LPTSTR  lpszDefaultScheme;
} HIGHCONTRAST, *LPHIGHCONTRAST;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
Specifies a combination of the following values:
Value | Meaning
HCF_AVAILABLE | The high contrast feature is available.
HCF_CONFIRMHOTKEY | A confirmation dialog appears when the high contrast feature is activated by using the hot key.
HCF_HIGHCONTRASTON | The high contrast feature is on.
HCF_HOTKEYACTIVE | The user can turn the high contrast feature on and off by simultaneously pressing the left ALT, left SHIFT, and PRINT SCREEN keys.
HCF_HOTKEYAVAILABLE | The hot key associated with the high contrast feature can be enabled. An application can retrieve this value, but cannot set it.
HCF_HOTKEYSOUND | A siren is played when the user turns the high contrast feature on or off by using the hot key.
HCF_INDICATOR | A visual indicator is displayed when the high contrast feature is on. This value is not currently used and is ignored.

lpszDefaultScheme
Points to a string that contains the name of the color scheme that will be set to the default scheme.

Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETHIGHCONTRAST or SPI_SETHIGHCONTRAST value. When using SPI_GETHIGHCONTRAST, an application must specify the cbSize member of the HIGHCONTRAST structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETHIGHCONTRAST value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


MOUSEKEYS

The MOUSEKEYS structure contains information about the MouseKeys accessibility feature. When the MouseKeys feature is active, the user can use the numeric keypad to control the mouse pointer, and to click, double-click, drag, and drop. By pressing NUMLOCK, the user can toggle the numeric keypad between mouse control mode and normal operation.

typedef struct _MOUSEKEYS {
    DWORD  cbSize;
    DWORD  dwFlags;
    DWORD  iMaxSpeed;
    DWORD  iTimeToMaxSpeed;
    DWORD  iCtrlSpeed;
    DWORD  dwReserved1;
    DWORD  dwReserved2;
} MOUSEKEYS, *LPMOUSEKEYS;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
A set of bit-flags that specify properties of the FilterKeys feature. The following bit-flag values are defined:
Value | Meaning
MKF_AVAILABLE | If this flag is set, the MouseKeys feature is available.
MKF_CONFIRMHOTKEY | Windows 95/98, Windows 2000: A confirmation dialog box appears when the MouseKeys feature is activated by using the hot key.
MKF_HOTKEYACTIVE | If this flag is set, the user can turn the MouseKeys feature on and off by using the hot key, which is LEFT ALT+LEFT SHIFT+NUM LOCK.
MKF_HOTKEYSOUND | If this flag is set, the system plays a siren sound when the user turns the MouseKeys feature on or off by using the hot key.
MKF_INDICATOR | Windows 95/98, Windows 2000: A visual indicator is displayed when the MouseKeys feature is on.
MKF_MOUSEKEYSON | If this flag is set, the MouseKeys feature is on.
MKF_MODIFIERS | Windows 95/98, Windows 2000: The CTRL key increases cursor speed by the value specified by the iCtrlSpeed member, and the SHIFT key causes the cursor to delay briefly after moving a single pixel, allowing fine positioning of the cursor. If this value is not specified, the CTRL and SHIFT keys are ignored while the user moves the mouse cursor using the arrow keys.
MKF_MOUSEMODE | Windows 98, Windows 2000: The system is processing numeric keypad input as mouse commands.
MKF_REPLACENUMBERS | Windows 95/98, Windows 2000: The numeric keypad moves the mouse when the NUM LOCK key is on. If this flag is not specified, the numeric keypad moves the mouse cursor when the NUM LOCK key is off.
MKF_LEFTBUTTONSEL | Windows 98, Windows 2000: The user has selected the left button for mouse-button actions.
MKF_RIGHTBUTTONSEL | Windows 98, Windows 2000: The user has selected the right button for mouse-button actions.
MKF_LEFTBUTTONDOWN | Windows 98, Windows 2000: The left button is in the "down" state.
MKF_RIGHTBUTTONDOWN | Windows 98, Windows 2000: The right button is in the "down" state.

iMaxSpeed
Specifies the maximum speed the mouse cursor attains when an arrow key is held down.

Windows 95/98: Range checking is not performed.

Windows NT/2000: Valid values are from 10 to 360.

iTimeToMaxSpeed
Specifies the length of time, in milliseconds, that it takes for the mouse cursor to reach maximum speed when an arrow key is held down. Valid values are from 1000 to 5000.
iCtrlSpeed
Specifies the multiplier to apply to the mouse cursor speed when the user holds down the CTRL key while using the arrow keys to move the cursor. this value is ignored if MKF_MODIFIERS is not set.
dwReserved1
This member is reserved for future use. It must be set to zero.
dwReserved2
This member is reserved for future use. It must be set to zero.

Remarks

An application uses a MOUSEKEYS structure when calling the SystemParametersInfo function with the uiAction parameter set to the SPI_GETMOUSEKEYS or SPI_SETMOUSEKEYS value. When using SPI_GETMOUSEKEYS, an application must specify the cbSize member of the MOUSEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETMOUSEKEYS value.

If you call SystemParametersInfo with the SPI_SETMOUSEKEYS value, the following flags are ignored:

MKF_LEFTBUTTONDOWN
MKF_LEFTBUTTONSEL
MKF_MOUSEMODE
MKF_RIGHTBUTTONDOWN
MKF_RIGHTBUTTONSEL

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


SERIALKEYS

The SERIALKEYS structure contains information about the SerialKeys accessibility feature, which interprets data from a communication aid attached to a serial port as commands causing the system to simulate keyboard and mouse input.

typedef struct tagSERIALKEYS {
    UINT  cbSize;
    DWORD dwFlags;
    LPSTR lpszActivePort;
    LPSTR lpszPort;
    UINT  iBaudRate;
    UINT  iPortState;
    UINT  iActive;
} SERIALKEYS, *LPSERIALKEYS;

Members

cbSize
Specifies the structure size, in bytes.
dwFlags
Specifies a combination of the following values:
Value | Meaning
SERKF_AVAILABLE | The SerialKeys feature is available.
SERKF_INDICATOR | A visual indicator is displayed when the SerialKeys feature is on. This value is not currently used and is ignored.
SERKF_SERIALKEYSON | The SerialKeys feature is on.

lpszActivePort
Points to a string that contains the name of the serial port that receives input from the communication aid when the SerialKeys feature is on. If no port is being used, this member is NULL. If this member is "Auto", the system watches all unused serial ports for input from communication aids.
lpszPort
Reserved; must be NULL.
iBaudRate
Specifies the baud rate setting for the serial port specified by the lpszActivePort member. This member should be set to one of the CBR_ values defined in the SDK header file winbase.h. If lpszActivePort is NULL, this member is zero.
iPortState
Specifies the state of the port specified by the lpszActivePort member. If lpszActivePort is NULL, iPortState is zero; otherwise, it is one of the following values:
Value | Meaning
0 | All input on this port is ignored by the SerialKeys feature.
1 | Input on this port is watched for SerialKeys activation sequences when no other application has the port open.
2 | All input on this port is treated as SerialKeys commands.

iActive
Specifies the active port.

Remarks

An application uses this structure when calling the SystemParametersInfo function with the SPI_GETSERIALKEYS or SPI_SETSERIALKEYS value. When using SPI_GETSERIALKEYS, an application must specify the cbSize, lpszActivePort, and lpszPort members of the SERIALKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SPI_SETSERIALKEYS value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.51 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


SOUNDSENTRY

The SOUNDSENTRY structure contains information about the SoundSentry accessibility feature. When the SoundSentry feature is on, the computer displays a visual indication only when a sound is generated.

Windows 95/98: The visual indication is displayed when a sound is generated through the computer's internal speaker.

Windows NT/2000: The visual indication is displayed when a sound is generated through either the multimedia sound services or through the computer's speaker.

typedef struct tagSOUNDSENTRY {
    UINT   cbSize;
    DWORD  dwFlags;
    DWORD  iFSTextEffect;
    DWORD  iFSTextEffectMSec;
    DWORD  iFSTextEffectColorBits;
    DWORD  iFSGrafEffect;
    DWORD  iFSGrafEffectMSec;
    DWORD  iFSGrafEffectColor;
    DWORD  iWindowsEffect;
    DWORD  iWindowsEffectMSec;
    LPTSTR lpszWindowsEffectDLL;
    DWORD iWindowsEffectOrdinal;
} SOUNDSENTRY, *LPSOUNDSENTRY;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
A set of bit flags that specify properties of the SoundSentry feature. The following bit-flag values are defined:
Value | Meaning
SSF_AVAILABLE | If this flag is set, the SoundSentry feature is available.
SSF_INDICATOR | This flag is not implemented.
SSF_SOUNDSENTRYON | If this flag is set, the SoundSentry feature is on.

iFSTextEffect
Windows 95/98: Specifies the visual signal to present when a text-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:
Value | Meaning
SSTF_BORDER | Flash the screen border (that is, the overscan area), which is unavailable on some displays.
SSTF_CHARS | Flash characters in the corner of the screen.
SSTF_DISPLAY | Flash the entire display.
SSTF_NONE | No visual signal.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iFSTextEffectMSec
Windows 95/98: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, text-mode application generates a sound.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iFSTextEffectColorBits
Windows 95/98: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, text-mode application generates a sound.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iFSGrafEffect
Windows 95/98: Specifies the visual signal to present when a graphics-mode application generates a sound while running in a full-screen virtual machine. This member can be one of the following values:
Value | Meaning
SSGF_DISPLAY | No visual signal.
SSGF_NONE | Flash the entire display.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iFSGrafEffectMSec
Windows 95/98: Specifies the duration, in milliseconds, of the visual signal that is displayed when a full-screen, graphics-mode application generates a sound.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iFSGrafEffectColor
Windows 95/98: Specifies the RGB value of the color to be used when displaying the visual signal shown when a full-screen, graphics-mode application generates a sound.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

iWindowsEffect
Specifies the visual signal to display when a sound is generated by a Windows-based application or an MS-DOS application running in a window. This member can be one of the following values:
Value | Meaning
SSWF_CUSTOM | Call the SoundSentryProc routine exported by the DLL specified by the iFSWindowsEffectDLL member.
SSWF_DISPLAY | Flash the entire display.
SSWF_NONE | No visual signal.
SSWF_TITLE | Flash the title bar of the active window.
SSWF_WINDOW | Flash the active window.

iWindowsEffectMSec
Windows 95/98: Specifies the duration, in milliseconds, of the visual signal that is displayed when a Win32-based application (or an application running in a window) generates a sound.

Windows NT/2000: This member is reserved for future use. It must be set to zero.

lpszWindowsEffectDLL
Points to the buffer that contains the name of the DLL that contains a SoundSentryProc callback function. The length of the name must not exceed the value of MAX_PATH. This member is NULL if no DLL is used. When retrieving information about the SoundSentry feature, the size of the buffer must be equal to, or larger than, the value of MAX_PATH.
iWindowsEffectOrdinal
This member is reserved for future use. It must be set to zero.

Remarks

An application uses a SOUNDSENTRY structure when calling the SystemParametersInfo function with the uiAction parameter set to SPI_GETSOUNDSENTRY or SPI_SETSOUNDSENTRY. When using SPI_GETSOUNDSENTRY, an application must specify the cbSize member of the SOUNDSENTRY structure; the SystemParametersInfo function fills the remaining members. An application must specify the cbSize, dwFlags, and iWindowsEffect members when using the SPI_SETSOUNDSENTRY value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.1 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SoundSentryProc, SystemParametersInfo


STICKYKEYS

The STICKYKEYS structure contains information about the StickyKeys accessibility feature. When the StickyKeys feature is on, the user can press a modifier key (SHIFT, CTRL, or ALT) and then another key in sequence rather than at the same time, to enter shifted (modified) characters and other key combinations. Pressing a modifier key once latches the key down until the user presses a non-modifier key or clicks a mouse button. Pressing a modifier key twice locks the key until the user presses the key a third time.

typedef struct tagSTICKYKEYS {
    DWORD  cbSize;
    DWORD  dwFlags;
} STICKYKEYS, *LPSTICKYKEYS;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
A set of bit-flags that specify properties of the StickyKeys feature. The following bit-flag values are defined:
Value | Meaning
SKF_AUDIBLEFEEDBACK | If this flag is set, the system plays a sound when the user latches, locks, or releases modifier keys using the StickyKeys feature.
SKF_AVAILABLE | If this flag is set, the StickyKeys feature is available.
SKF_CONFIRMHOTKEY | Windows 95/98, Windows 2000: A confirmation dialog appears when the StickyKeys feature is activated by using the hot key.
SKF_HOTKEYACTIVE | If this flag is set, the user can turn the StickyKeys feature on and off by pressing the SHIFT key five times.
SKF_HOTKEYSOUND | If this flag is set, the system plays a siren sound when the user turns the StickyKeys feature on or off by using the hot key.
SKF_INDICATOR | Windows 95/98, Windows 2000: A visual indicator should be displayed when the StickyKeys feature is on.
SKF_STICKYKEYSON | If this flag is set, the StickyKeys feature is on.
SKF_TRISTATE | If this flag is set, pressing a modifier key twice in a row locks down the key until the user presses it a third time.
SKF_TWOKEYSOFF | If this flag is set, releasing a modifier key that has been pressed in combination with any other key turns off the StickyKeys feature.
SKF_LALTLATCHED | Windows 98, Windows 2000: The left ALT key is latched.
SKF_LCTLLATCHED | Windows 98, Windows 2000: The left CTRL key is latched.
SKF_LSHIFTLATCHED | Windows 98, Windows 2000: The left SHIFT key is latched.
SKF_RALTLATCHED | Windows 98, Windows 2000: The right ALT key is latched.
SKF_RCTLLATCHED | Windows 98, Windows 2000: The right CTRL key is latched.
SKF_RSHIFTLATCHED | Windows 98, Windows 2000: The right SHIFT key is latched.
SKF_LALTLOCKED | Windows 98, Windows 2000: The left ALT key is locked.
SKF_LCTLLOCKED | Windows 98, Windows 2000: The left CTRL key is locked.
SKF_LSHIFTLOCKED | Windows 98, Windows 2000: The left SHIFT key is locked.
SKF_RALTLOCKED | Windows 98, Windows 2000: The right ALT key is locked.
SKF_RCTLLOCKED | Windows 98, Windows 2000: The right CTRL key is locked.
SKF_RSHIFTLOCKED | Windows 98, Windows 2000: The right SHIFT key is locked.
SKF_LWINLATCHED | Windows 98, Windows 2000: The left Windows key is latched.
SKF_RWINLATCHED | Windows 98, Windows 2000: The right Windows key is latched.
SKF_LWINLOCKED | Windows 98, Windows 2000: The left Windows key is locked.
SKF_RWINLOCKED | Windows 98, Windows 2000: The right Windows key is locked.

Remarks

An application uses a STICKYKEYS structure when calling the SystemParametersInfo function with the uiAction parameter set to SPI_GETSTICKYKEYS or SPI_SETSTICKYKEYS. When using SPI_GETSTICKYKEYS, you must specify the cbSize member of the STICKYKEYS structure; the SystemParametersInfo function fills the remaining members. You must specify all structure members when using the SPI_SETSTICKYKEYS value.

If you call SystemParametersInfo with the SPI_SETSTICKYKEYS value, the following flags are ignored:

SKF_LALTLATCHED
SKF_LCTLLATCHED
SKF_LSHIFTLATCHED
SKF_RALTLATCHED
SKF_RCTLLATCHED
SKF_RSHIFTLATCHED
SKF_LALTLOCKED
SKF_LCTLLOCKED
SKF_LSHIFTLOCKED
SKF_RALTLOCKED
SKF_RCTLLOCKED
SKF_RSHIFTLOCKED

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


TOGGLEKEYS

The TOGGLEKEYS structure contains information about the ToggleKeys accessibility feature. When the ToggleKeys feature is on, the computer emits a high-pitched tone whenever the user turns on the CAPS LOCK, NUM LOCK, or SCROLL LOCK key, and a low-pitched tone whenever the user turns off one of those keys.

typedef struct tagTOGGLEKEYS {
    DWORD  cbSize;
    DWORD  dwFlags;
} TOGGLEKEYS, *LPTOGGLEKEYS;

Members

cbSize
Specifies the size, in bytes, of this structure.
dwFlags
A set of bit flags that specify properties of the ToggleKeys feature. The following bit flag values are defined:
Value | Meaning
TKF_AVAILABLE | If this flag is set, the ToggleKeys feature is available.
TKF_CONFIRMHOTKEY | Windows 95/98, Windows 2000: A confirmation dialog box appears when the ToggleKeys feature is activated by using the hot key.
TKF_HOTKEYACTIVE | If this flag is set, the user can turn the ToggleKeys feature on and off by holding down the NUM LOCK key for eight seconds.
TKF_HOTKEYSOUND | If this flag is set, the system plays a siren sound when the user turns the ToggleKeys feature on or off by using the hot key.
TKF_INDICATOR | This flag is not implemented.
TKF_TOGGLEKEYSON | If this flag is set, the ToggleKeys feature is on.

Remarks

An application uses a TOGGLEKEYS structure when calling the SystemParametersInfo function with the uiAction parameter set to SPI_GETTOGGLEKEYS or SPI_SETTOGGLEKEYS. When using SPI_GETTOGGLEKEYS, an application must specify the cbSize member of the TOGGLEKEYS structure; the SystemParametersInfo function fills the remaining members. An application must specify all structure members when using the SETTOGGLEKEYS value.

Requirements

Windows NT/2000 or later: Requires Windows NT 3.5 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

Accessibility Structures, SystemParametersInfo


Microsoft Active Accessibility

Version 2.0

Purpose

Microsoft® Active Accessibility® is a COM-based technology that improves the way accessibility aids work with applications running on Microsoft Windows®. It provides dynamic-link libraries that are incorporated into the operating system as well as a COM interface and application programming elements that provide reliable methods for exposing information about user interface elements.

Where Applicable

By using Active Accessibility and following accessible design practices, developers can make applications running on Windows more accessible to many people with vision, hearing, or motion disabilities.

Developer Audience

Active Accessibility is designed primarily for C ,C++, and Microsoft Visual Basic® developers. In general, developers need a moderate level of understanding about COM objects and interfaces as well as about Unicode.

Run-time Requirements

Active Accessibility is supported on Windows 98, Microsoft Windows NT® 4 with Service Pack 6, and Whistler Beta 2.

See Also

Microsoft Accessibility Web site

Microsoft Active Accessibility 2.0 Beta 2 Release Notes

Overview

General information about Microsoft Active Accessibility.

Reference

Documentation of Active Accessibility C/C++ reference.

Feedback

Make error reports and feature requests directly to Microsoft.


Legal Information

Microsoft Active Accessibility

Information in this document is subject to change without notice. The example companies, organizations, products, people, and events depicted herein are fictitious. No association with any real company, organization, product, person, or event is intended or should be inferred. Complying with all applicable copyright laws is the responsibility of the user. Without limiting the rights under copyright, no part of this document may be reproduced, stored in or introduced into a retrieval system, or transmitted in any form or by any means (electronic, mechanical, photocopying, recording, or otherwise), or for any purpose, without the express written permission of Microsoft Corporation.

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

©1997-2001 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, Active Accessibility, ActiveX, Microsoft Press, MSDN, Visual Basic, Visual C++, and Win 32 are either registered trademarks or trademarks of Microsoft Corporation in the U.S.A. and/or other countries.

The names of actual companies and products mentioned herein may be the trademarks of their respective owners.


Release Notes for Microsoft® Active Accessibility® Version 2.0 Beta 2

Copyright © 1994-2001 by the Microsoft Corporation. All Rights Reserved


New Features in Microsoft Active Accessibility Version 2.0 Beta 2

Microsoft Active Accessibility (MSAA) 2.0 provides Dynamic Annotation and Text Services features.

Dynamic Annotation allows developers to overwrite one property in an IAccessible interface pointer without having to provide new values for the remaining properties. The IAccessible interface pointer retains the values for the remaining properties so developers do not have to provide new ones.

MSAA Text Services provides a way to navigate through large bodies of text programmatically using a COM interface, ITextStoreAnchor. ITextStoreAnchor communicates text style information, such as whether the text is bold or italic, or if an item is in bulleted list. MSAA Text Services provides features in applications such as Microsoft Word.

For more information about the new features provided in MSAA 2.0, see the topic "What's New in Active Accessibility 2.0" in the MSAA documentation.


Platform Support

This beta 2 release of MSAA supports Microsoft Windows® 98, Microsoft Windows NT® 4 with Service Pack 6 or later, and Whistler Beta 2.


International Support

With the release of MSAA 2.0, Active Accessibility supports 28 Windows languages.

The Redistribution Kit installs the localized Active Accessibility files on all language versions of Microsoft Windows 98, Windows NT 4 SP6, and Whistler Beta 2. Tools that are included with MSAA 2.0 Beta 2 are only available in English.


Known Issues

The following are known issues with MSAA 2.0 Beta 2. The status of each issue is indicated where known.

Operating Systems Not Supported in the Beta 2 Release

This beta 2 release of MSAA 2.0 does not currently support Windows 2000 or Windows Me.

Operating Systems Supported by the Beta 2 Redistribution Kit

The beta redistribution kit (RDK) that accompanies MSAA 2.0 Beta 2 supports Windows NT 4 SP6 and Windows 98. If you upgrade your operating system or apply a service pack after installing MSAA 2.0 Beta 2, you must reinstall the beta RDK.

If you wish to repair or remove Active Accessibility 2.0 Beta 2, from Control Panel, double-click Add/Remove Programs, select Microsoft Active Accessibility 2.0 Beta, and then click Change/Remove. Note that this method completely removes Active Accessibility and does not revert to a previous version.

Multiple Document Interface Support for OLEACC

In this beta 2 release of MSAA 2.0, OLEACC accurately reports the IAccessible properties for the Minimize, Maximize, and Close icons. These icons are used on multiple document interfaces

Document Services Not Currently Implemented for RichEdit

In this beta 2 release of MSAA 2.0, Document Services is not currently working for RichEdit. When text is changed, such as when a character is added or deleted, Document Services does not send an OnTextChange event.

MSAA Tools Not Currently Available for 64-Bit Operating Systems

This beta 2 release of MSAA 2.0 includes the following tools: Inspect Objects, Accessible Event Watcher, and Accessible Explorer. For this beta version, these tools are not available for 64-bit operating systems.


About the Active Accessibility SDK

The Microsoft® Active Accessibility® Software Development Kit (SDK) is intended for software developers who wish to incorporate Active Accessibility into their products.

The SDK contains dynamic-link libraries (DLLs), documentation, sample source code, and tools to test Active Accessibility in both client and server applications. Clients are programs such as accessibility aids and testing tools that use Active Accessibility to obtain information about user interface elements, and servers are programs that provide information about their user interface elements.

The following topics provide information about the major components of the SDK:

  • About the Redistribution Kit
  • About This Documentation


About the Redistribution Kit

The Microsoft® Active Accessibility® Redistribution Kit (RDK) version 2.0 contains all of the core system files needed to incorporate Active Accessibility technology into client and server applications.

The RDK installs Active Accessibility 2.0 and also will upgrade previous versions of Active Accessibility to version 2.0. The RDK supports Microsoft Windows® 98, Microsoft Windows NT® version 4.0 with Service Pack 6 or later, and Whistler Beta 2.

For information about obtaining updated versions of the RDK, see the Microsoft Accessibility Web site at www.microsoft.com/enable. Additional information about the RDK is contained in the Active Accessibility 2.0 Release Notes, which are available with the Active Accessibility SDK or through the Microsoft Accessibility Web site.

The following topics provide more information about the RDK and the platforms supported by Active Accessibility:

  • Overview of the RDK
  • Platforms Supported by Active Accessibility
  • RDK Installation Details


Overview of the RDK

Active Accessibility client developers must include the RDK with their product and ensure that it executes during their product's installation. During the install process, setup.exe unpacks the various components, performs version checking as it updates system files, registers the IAccessible and ITextStore interfaces in the system registry, and in some cases may need to restart the computer to complete the installation. Because the computer may need to be rebooted, RDK installation should be launched at the end of the client product installation.

The RDK installs the following files to the system folder.

Component | Description
Oleacc.dll | Primary Active Accessibility file. Provides helper functions, marshaling support, and exposes system components
Oleaccrc.dll | Contains localized string resources
Msaatext.dll | Contains document support

NOTE Independent software vendors are not allowed to install the Active Accessibility components individually. The license agreements provided with the SDK and RDK allow Active Accessibility to be distributed only through the RDK.


Platforms Supported by Active Accessibility

Active Accessibility is available in some form for most versions of Windows. The following provides information about the platforms that Active Accessibility supports.

Windows 95
You can use Active Accessibility RDK version 1.3 to install Active Accessibility version 1.3. This RDK is available at www.microsoft.com/enable.
Windows 98
The initial release of Windows 98 included Active Accessibility version 1.1; All language versions of Windows 98 are supported. The Active Accessibility 2.0 RDK can be run to upgrade Active Accessibility to the new version.
Windows NT 4.0
Beginning with Service Pack 6 (SP6), full Active Accessibility support is built into Windows NT 4.0. The Active Accessibility 2.0 RDK can be run to upgrade Active Accessibility to the new version.
Windows 2000
Windows 2000 includes Active Accessibility version 1.3. Currently you are not able to use the Active Accessibility RDK version 2.0 to upgrade Active Accessibility to the new version.
Windows Me
Windows Me includes Active Accessibility version 1.3. Currently you are not able to use the Active Accessibility RDK version 2.0 to upgrade Active Accessibility to the new version.
Windows 3.1
Not supported.
Windows CE
Not supported.

Additional information about the platforms supported by Active Accessibility is contained in the Active Accessibility 2.0 Release Notes, which are available in the Active Accessibility SDK or through the Microsoft Accessibility Web site www.microsoft.com/enable.


RDK Installation Details

To start the installation, run the setup.exe file. You will be asked to accept the license agreement and optionally provide your username and organization. If you are running a program that is using Active Accessibility, you will be asked to close it. If you choose not to close the program, after the installation you will be told to restart your system.

If you wish to repair or remove Active Accessibility 2.0 Beta 2, from Control Panel, double-click Add/Remove Programs, select Microsoft Active Accessibility 2.0 Beta, and then click Change/Remove. Note that this method completely removes Active Accessibility and does not revert to a previous version.


About This Documentation

This documentation is for accessibility aid developers and application developers who want to make their products more accessible. It describes the objects, functions, and other application programming interface (API) elements that make up Microsoft® Active Accessibility®.

To get the most out of this documentation, you should have a moderate to high level of knowledge in Microsoft Windows® software development and be familiar with the following:

  • C and C++ programming concepts
  • Component Object Model (COM) objects and interfaces
  • The Microsoft Win32® API as presented by the Microsoft Platform Software Development Kit (SDK)

For more information about the above topics, see Where to Find More Information.

For information about this documentation, see the following:

Documentation Map

Documentation Conventions


Documentation Map

The information in this documentation is organized to meet the needs of developers new to, as well as those familiar with Active Accessibility. The major sections of the documentation are described below:

NOTE In this documentation, clients are accessibility aids and other applications that use Active Accessibility to obtain information about user interface elements. Servers are applications that use Active Accessibility to provide information about their user interface elements.

What's New in Active Accessibility 2.0
Provides updated information for readers who are already familiar with Active Accessibility.
Background
Provides background information for readers unfamiliar with accessibility issues.
Technical Overview of Active Accessibility
Provides an overview of Active Accessibility and general guidelines for Active Accessibility client and server developers.
Active Accessibility C/C++ Developer's Guide
Presents in-depth information about the key Active Accessibility application programming interface (API) elements and concepts. Uses terms and examples familiar to C or C++ developers.
Active Accessibility C/C++ Reference
Provides a comprehensive reference for all the Active Accessibility APIs, data types, data structures, and messages.
Notes for Visual Basic Developers
Provides information about Active Accessibility for developers programming in Microsoft® Visual Basic®.
Active Accessibility Appendixes
Provides additional reference material for Active Accessibility client and server developers.


Documentation Conventions

This SDK uses the following typographic conventions.

Convention | Meaning
Bold text | Indicates a function name, data type, object, interface, or other fixed element. Is in uppercase and lowercase text.
Italic text | Indicates a placeholder, parameter, or variable, for example, pvarEndUpAt. Function parameters in API reference material are italicized to indicate that any variable name is used. In addition, the first mention of important terms are italicized to highlight their definitions.
UPPERCASE TEXT | Indicates a constant or structure, for example, VARIANT. Is in bold or Roman text.
Monospace text
 Indicates source code examples.

Also, the interface syntax in this SDK follows the variable-naming convention known as Hungarian notation, in which variables are prefixed with lowercase letters to indicate their data type. For example, pszString is a pointer to a zero-terminated string.


Where to Find More Information

You can find information about COM programming concepts and other topics from the following sources:

The Microsoft Windows Guidelines for Accessible Software Design
Describes how to design and produce computer software that accommodates users with disabilities. Available on the Microsoft Developer Network (MSDN®) or through the Accessibility Web site at www.microsoft.com/enable.
Understanding ActiveX and OLE by David Chappell
Provides an introduction and overview of COM and Microsoft ActiveX®. Suitable for both developers and technical managers. (Microsoft Press®, ISBN 1-57231-216-5)
Essential COM by Don Box
Covers the motivation for the design of COM and its distributed aspects. Shows how COM works. Coverage of the core concepts of distributed COM include detailed descriptions of COM theory and remote servers. Offers a thorough explanation of COM's basic vocabulary. (Addison Wesley ISBN 0-201-63446-5)
Advanced Microsoft Visual Basic 6.0, 2nd Edition by The Mandelbrot Set International, Ltd.
Contains a chapter that discusses Microsoft Active Accessibility. The chapter provides sample code that demonstrates how to use key Active Accessibility APIs. The book also covers other development issues, including: designing distributed business objects, client/server development, and Internet/intranet programming and integration. (Microsoft Press, ISBN 1-57231-893-7)
Inside OLE 2nd Edition by Kraig Brockschmidt.
Provides a comprehensive tutorial about OLE/COM technology and its implementation. Introduces COM programming and covers all the basic COM technologies such as storage, data transfer, Automation, compound documents, and OLE controls (now called ActiveX controls). Includes many sample programs on CD-ROM. Available in its entirety on the MSDN. (Microsoft Press, ISBN 1-55615-843-2)
Inside COM by Dale Rogerson.
Discloses 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
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
The Microsoft Developer Network (MSDN) is Microsoft's broad program for providing developers with the tools, technologies, and information they need. The MSDN includes:
  • MSDN Online—Microsoft's home page for developers.
  • MSDN Online Membership—A free online program that gives developers access to additional content.
  • The MSDN Subscription Program—A CD-ROM subscription program that offers a range of products such as the MSDN Library which includes programming-related documentation for Microsoft products, technical articles, and sample code. Includes a subscription to the Microsoft Developer Network News newsletter.

For more information, see the MSDN Web site at msdn.microsoft.com, or in the United States call (800) 759-5474.

The Active Accessibility Newsgroups
Microsoft provides a number of Internet newsgroups as a forum for anyone to discuss accessibility topics. To participate in these discussions, you must have an Internet news reader, such as Microsoft Internet Mail and News. Adjust the options in your news reader to use msnews.microsoft.com as your news server.
  • General Accessibility Issues (microsoft.public.enable.issues) provides a forum for general accessibility discussions about Microsoft products and services.
  • Accessibility Development Issues (microsoft.public.enable.developer) provides a forum for general development questions dealing with accessibility.

To comment on or get additional information about this documentation, e-mail enable@microsoft.com or visit the Microsoft Accessibility Web site at www.microsoft.com/enable.


What's New in Active Accessibility 2.0

Microsoft® Active Accessibility® version 2.0 has several updates and changes reflected in the SDK documentation.

Active Accessibility now fully supports Unicode, and supports all 27 languages for Windows.

The changes in Active Accessibility are described in detail within their appropriate sections in the documentation and are summarized below.

The following table describes the changes.

Feature | Change
Dynamic Annotation | The Dynamic Annotation Application Programming Interface (API) is an extension to MSAA that allows developers to customize existing IAccessible support without having to use error-prone subclassing or wrapping techniques. This mechanism also allows developers to pass hints or other useful information to the OLEACC proxies. For more information, see Dynamic Annotation API.
Text Services | MSAA Text Services provides a way to navigate through large bodies of text programmatically using a COM interface, ITextStoreAnchor. ITextStoreAnchor communicates text style information, such as whether the text is bold or italic, or if an item is in a bulleted list. MSAA Text Services provides these features in applications such as Microsoft Word.
The Inspect Object tool | Preliminary documentation is available in a compiled help file (.chm). The name of the file is Inspecto.chm. Currently, this documentation is not available from within the tool.
The Accessible Event Watcher tool | Preliminary documentation is available in a compiled help file (.chm). The name of the file is Accevent.chm. Currently, this documentation is not available from within the tool.
The Accessible Explorer tool | Preliminary documentation is available in a compiled help file (.chm). The name of the file is Explorer.chm. Currently, this documentation is not available from within the tool.


Background

This section discusses accessibility aids and the challenges client developers face when dealing with the event-driven graphical user interfaces (GUIs) of applications running on Microsoft® Windows® operating systems. If you are already familiar with accessibility issues, you can skip ahead to Technical Overview of Active Accessibility to learn how Microsoft Active Accessibility® works.

The following topics introduce you to accessibility issues and general information about Active Accessibility:

  • What Is Accessibility?
  • Types of Accessibility Aids
  • What Information Do Aids Need?
  • Why Active Accessibility Is Needed
  • Benefits of Active Accessibility


What Is Accessibility?

Many people with vision, hearing, or motion disabilities are unable to use mainstream applications running on Microsoft Windows operating systems without the assistance of accessibility aids. Accessibility aids allow people with these disabilities to gain or improve their access to the computing world.

By following accessible design practices and using Active Accessibility, developers can make applications more accessible. Additionally, the Windows operating systems incorporate many features and enhancements designed to increase the accessibility of computers.


Types of Accessibility Aids

Accessibility aids for Microsoft Windows operating systems fall into two categories:

  • Aids that replace or modify existing Microsoft Win32® devices, such as the keyboard, mouse, or display driver.
  • Aids that integrate with applications, such as screen readers or voice-input utilities.

Microsoft Active Accessibility currently targets problems that aids in the latter group face. Some common accessibility aids that use Active Accessibility include:

  • Screen review utilities, which provide alternative, nonvisual interpretations such as synthesized speech or Braille displays that have refresh capabilities, of text and other visual elements on the screen.
  • Screen enlargement utilities, which allow users with low vision to see on-screen information adequately.
  • Voice input utilities, which provide an alternative input mechanism for users who have difficulty typing or using a mouse.

These aids are described in more detail in the topics that follow. For more information about other kinds of accessibility aids, see the Microsoft Accessibility Web site at www.microsoft.com/enable.


Screen Review Utilities

People who are blind use computers with the aid of screen review utilities, also called blind access utilities or screen readers. A screen review utility makes the information displayed on the screen available through alternative, nonvisual methods, such as synthesized speech or a refreshable Braille display.

Most screen review utilities assign a user-friendly name to each graphical object on the screen. The utility also tracks what a user is doing at all times to describe what is happening on the screen. Some information is read to the user automatically when the screen changes, and other information is provided when the user requests it.

Screen review utilities build an "off-screen model" of all operations that draw information to the screen. This model is a database of objects on the screen and includes their properties and their spatial relationships.

Screen review utilities often use configuration files, also called set files or profiles, which provide the utilities with information about particular applications.


Screen Enlargement Utilities

A screen enlarger, also called a screen magnifier or large print program, is a utility that enables a user to magnify the contents of the computer screen.

Many utilities provide a floating window that enlarges a portion of the computer screen. With the mouse or keyboard commands, users can move the window to see different areas of the screen. An enlarger tracks where a user is working so the active area is automatically in view.


Voice Input Utilities

People with motion disabilities often use a voice input utility, also called a speech recognition program, to control the computer with their voice instead of the mouse or keyboard. This kind of utility is also used to help boost the productivity of people who do not have disabilities.

Like a screen review utility, a voice input utility identifies objects on the screen that can be manipulated and provides appropriate names for them so that users can activate and manipulate the objects.


What Information Do Aids Need?

In general, accessibility aids have to identify and interpret various types of visual information. They also return information about screen changes—for example, when a control becomes grayed or when a text string changes. Accessibility aids require information about the following:

  • Application user interfaces—the controls, toolbars, menus, dialog boxes, and so forth that appear in the application's user interface.
  • Document contents—the text and graphics that compose the document, including information about items such as annotations or images.
  • Document structure—how the document content is organized into paragraphs, sections, table cells, columns, and so forth, and the identity of those elements.

Together these items make up the user interface elements: those things that the application displays to users to supply information or get input.


Why Active Accessibility Is Needed

A few years ago much of the information accessibility aids needed was not available in Microsoft® Windows® or Windows-based applications. Accessibility aid developers used unsupported and unreliable techniques to gain information about user interface elements.

Their techniques relied on implementation details specific to each application and each version of Windows. Consequently, accessibility aid developers had problems migrating their aids to new platforms such as Microsoft Windows NT® version 4.0. They also had difficulty with upgrades, foreign-language versions, and applications with which the aids were not originally tested.

Microsoft Active Accessibility® is a technology that alleviates many of these development problems. It also helps other applications, such as automated testing utilities, which need this same type of information about user interfaces.


Benefits of Active Accessibility

First released in May 1997, Microsoft® Active Accessibility® addresses the coordination and communication problems that accessibility aid developers face when trying to program aids to work with a variety of applications and/or operating systems.

In general, Active Accessibility helps developers by:

  • Providing dynamic-link libraries (DLLs) that are incorporated into the operating system.
  • Making available a Component Object Model (COM) interface and application programming interface (API) elements that help replace the unreliable and less portable techniques developers had to use in the past.
  • Providing the framework for applications and operating systems to cooperate with accessibility aids.
  • Providing methods for exposing information about custom controls.
  • Exposing information about most system-provided user interface elements such as list boxes and buttons.
  • Providing a mechanism for accessibility aids to be notified when the screen changes.
  • Giving accessibility aids data about user interface elements that previously had not been available.

Active Accessibility provides the means for accessibility aids to get meaningful information about user interface elements and a means for applications to expose that information. In the process, it allows server application developers to innovate more freely on their user interfaces without sacrificing compatibility with accessibility aids.

For additional information about Active Accessibility, see the Microsoft Accessibility Web site at www.microsoft.com/enable.


Technical Overview of Active Accessibility

Microsoft® Active Accessibility® improves the way accessibility aids work with applications running on Microsoft Windows®.

Active Accessibility is based on the Component Object Model (COM), which was developed by Microsoft and is an industry standard that defines a common way for applications and operating systems to communicate. Active Accessibility provides dynamic-link libraries (DLLs) that are incorporated into the operating system as well as a COM interface and application programming interface (API) elements that provide reliable methods for exposing information about user interface elements.

The following topics introduce key Active Accessibility components and describe how developers use them:

  • How Clients and Servers Use Active Accessibility
  • COM Objects Represent User Interface Elements
  • Relationships Among Objects
  • APIs Retrieve Objects
  • WinEvents Notify Changes
  • Summary of the Client-Server Event Process
  • Guidelines for Servers
  • Guidelines for Clients
  • What You Need to Know About COM and Unicode


How Clients and Servers Use Active Accessibility

Microsoft® Active Accessibility® is designed to help accessibility aids, called clients, interact with standard and custom user interface (UI) elements of other applications and the operating system. These other applications, called servers, use Active Accessibility to provide information to clients about their UI elements.

For example, to enable a user to select commands verbally from a word processor's custom toolbar, a speech recognition program needs to get information about that toolbar. The word processor would therefore need to make that information available. Active Accessibility provides the means for the word processor to expose information about its custom toolbar and for the speech recognition program to get that information. In the following example, the speech recognition program is the client and the word processor is the server.

Using Active Accessibility, client applications:

  • Query for information—for example, about a user interface element at a particular location.
  • Receive notifications when information changes—for example, when a control becomes grayed or when a text string changes.
  • Carry out actions that affect user interface or document contents—for example, push a push button, drop down a menu, choose a menu command, and so forth.

Using Active Accessibility, server applications:

  • Provide information about their custom user interface objects and the contents of their client window.
  • Send notifications when their user interface changes.


COM Objects Represent User Interface Elements

With Microsoft® Active Accessibility®, user interface (UI) elements are exposed to clients as COM objects. These accessible objects maintain pieces of information, called properties, which describe the object's name, screen location, and other information needed by accessibility aids. Accessible objects also provide methods that clients call to cause the object to perform some action.

Accessible objects are implemented using Active Accessibility's COM-based IAccessible interface. The IAccessible methods and properties enable client applications to get information about UI elements needed by users.

NOTE to Microsoft Visual Basic Developers Applications written in Microsoft Visual Basic® are Active Accessibility clients. They do not provide information about their custom user interface elements, because they do not implement IAccessible or any COM interface

This documentation uses the C/C++ names for the IAccessible properties; however, the Visual Basic names are similar. For example, the IAccessible::get_accName property would be called accName in a Visual Basic application.

For more information, see the following:

Servers Expose Custom User Interface Elements

Active Accessibility Exposes System-Provided User Interface Elements


Servers Expose Custom User Interface Elements

Server developers design accessible objects based on their application's user interface (UI). Because Active Accessibility exposes system-provided user interface elements, such as list boxes, menus, and trackbar controls, server application developers only need to implement the IAccessible interface for the following kinds of custom user interface elements:

  • Custom controls created by registering an application-defined window class.
  • Custom controls drawn directly on the screen and do not have an associated HWND.
  • Custom controls such as Microsoft ActiveX® and Java controls.
  • The content in the application's client window.

Owner-drawn controls and menus are accessible as long as application developers follow the guidelines discussed in Shortcuts for Exposing Custom User Interface Elements. If these guidelines are followed, then developers do not need to implement the IAccessible interface for owner-drawn controls and menus.

In most cases, superclassed and subclassed controls are accessible because the basic functionality of the control is handled by the system. However, if a superclassed or subclassed control significantly modifies the behavior of the system-provided control on which it is based, then developers must implement the IAccessible interface. For more information, see Exposing Controls Based on System Controls.

If an application uses only system-provided user interface elements, then it does not implement IAccessible, except for its client window. For example, an application that includes a text editor, not implemented using an edit control, exposes lines of text as accessible objects. Note that Active Accessibility automatically exposes the text in edit and rich edit controls, but it is exposed as a single string of text in the Value property of the control.


Dual Interface Provides Alternative Access

Server developers must provide the standard COM interface IDispatch for their accessible objects. The IDispatch interface allows client applications written in Microsoft Visual Basic and various scripting languages to use the methods and properties exposed by IAccessible. Accessible objects have a dual interface, which provides access to the object indirectly through IDispatch::Invoke or directly with IAccessible.

To comply with the COM specification, the IAccessible methods retrieve other accessible objects through the IDispatch interface. Clients written in C/C++ call the object's IDispatch::QueryInterface method with the IID_IAccessible reference identifier to get a pointer to the IAccessible interface. To use the IAccessible methods indirectly, C/C++ clients use IDispatch::Invoke. For improved performance, use IAccessible to use the object directly.

For a list of the dispatch IDs (DISPIDs) that IDispatch uses to identify the IAccessible methods and properties, see Appendix C: IAccessible DISPIDs.


Active Accessibility Exposes System-Provided User Interface Elements

Active Accessibility provides support for most predefined and common controls. The following illustration shows a typical window and some of the system-provided user interface elements that Active Accessibility exposes, such as title bars, menus, combo boxes, toolbar controls, tree view controls, status bars, size grips, list view controls, and scroll bars.

Screenshot of the Exploring - My Computer window, showing the All Folders pane and the Contents of "My Computer' pane. Includes nine callouts: Title Bar, Menu, Combo Box Control, Tool Bar Control, Tree View Control, Status Bar, List View Control, Scroll Bar Control, and Size Grip.

Active Accessibility exposes system-provided user interface elements to server applications without the requirement to implement the IAccessible interface. Any application that contains these elements automatically inherits their accessibility.

For a list of the controls and other system-provided user interface elements that Active Accessibility supports, see Appendix A: Supported User Interface Elements Reference.

In addition to system-provided objects, Active Accessibility provides support for Standard Dialog Manager, which is used by some Microsoft applications. For more information, see Appendix B: Standard Dialog Manager Support.


Relationships Among Objects

Depending on its user interface design, server developers may implement the IAccessible interface for all UI elements or only for parent objects (also called containers). If the children do not implement IAccessible, the parent object must provide information about them. Clients use the IAccessible methods and properties to get information about an object or an object's children.

All parent objects and children that implement the IAccessible interface are called accessible objects. Children that are not accessible objects and that are exposed by their parents are called child elements or simple elements.

With the IAccessible interface, Microsoft® Active Accessibility® provides properties and methods that inform clients how UI elements are related to each other within the UI hierarchy. For example, IAccessible::get_accParent returns an interface pointer to an accessible object's parent, and IAccessible::accNavigate provides a means for clients to get information about other objects within a container.

The following provides more information about making children accessible:

  • Identifying Children


Identifying Children

Server application developers can provide child identifiers for clients to get information about an children of an object. A child ID is a positive 32-bit integer value that uniquely identifies the child within the scope of the parent.

Because most of the IAccessible methods and properties take child IDs as parameters, both client and server developers need to know the following about child IDs:

  • How Servers Implement Child IDs
  • How Clients Obtain Child IDs
  • How Child IDs Are Used in Parameters


How Servers Implement Child IDs

While server developers can assign child IDs to both simple elements and accessible objects, the recommended approach is to support the standard COM interface IEnumVARIANT in every accessible object that has children.

If server developers implement IEnumVARIANT, they must:

  • Enumerate all children, both simple elements and accessible objects. Provide child IDs for all simple elements and provide the IDispatch interface to each accessible object.
  • Allocate space for each VARIANT structure. Note that it is the responsibility of the client to free the memory used for the VARIANTs. Clients also call IUnknown::Release on any IDispatch interface that is returned.
  • For accessible objects, set the vt field of the VARIANT structure to VT_IDISPATCH. The pdispVal field must contain a pointer to the IDispatch interface.
  • For simple elements, the child ID is any 32-bit positive integer. Note that zero and negative integers are reserved by Active Accessibility. Set the VARIANT's vt member to VT_I4 and the lVal member to the child ID.

If server developers do not support IEnumVARIANT, they must assign child IDs and number the children in each object sequentially starting with one.

For more information about IEnumVARIANT, see the Platform SDK documentation.

It is recommended that clients use the Active Accessibility API AccessibleChildren rather than call the server's IEnumVARIANT interface directly.


How Clients Obtain Child IDs

Clients get an object's child ID in several ways:

  • Call AccessibleChildren, which passes back an array of VARIANTs.
  • Query the object to see if it supports the IEnumVARIANT interface and if it does, enumerate its children, which is what AccessibleChildren does.
  • Collect the child IDs within your WinEventProc when the server generates an event, by calling NotifyWinEvent.
  • Collect the child IDs by calling the parent object's IAccessible::accNavigate method.

Note It is the responsibility of the client to free the memory used for the VARIANTs. Clients also must call IUnknown::Release on any IDispatch interface that is returned.


How Child IDs Are Used in Parameters

Many of the Active Accessibility functions and most of the IAccessible properties take a VARIANT input parameter. For most of the IAccessible properties, this parameter allows client developers to specify whether they want information about the object itself or about one of the object's simple elements.

Active Accessibility provides the constant CHILDID_SELF to indicate that information is needed about the object itself. To obtain information about a simple element, client developers specify its child ID in the VARIANT.

When initializing a VARIANT parameter, be sure to specify VT_I4 in the vt member in addition to specifying the child ID value (or CHILDID_SELF) in the lVal member.

For example, to get the name of an object, and not one of the object's child elements, call IAccessible::get_accName, and initialize the first parameter with CHILDID_SELF in the lVal member and VT_I4 in the vt member.

Several IAccessible properties and methods have a VARIANT output parameter that contain a child ID or an IDispatch interface pointer to a child object. It is recommended that servers return an IDispatch interface if the child is an accessible object. However, if a child ID is returned, clients must determine whether the child is an accessible object or a simple element that is exposed through the parent object. To make this determination, clients must call the parent object's IAccessible::get_accChild passing it the child ID.

The exception to the above rule is when a child ID is returned by the IAccessible::accHitTest method. Servers must return an IDispatch interface if the child is an accessible object. If a child ID is returned by IAccessible::accHitTest, the child is a simple element.

Before using a VARIANT, you must initialize it by calling the VariantInit COM function. When finished with the structure, clear it before the memory that contains the VARIANT is freed by calling VariantClear.

Note Do not confuse child identifiers with object identifiers, which are Active Accessibility categories used to identify parts of a window.


APIs Retrieve Objects

Microsoft® Active Accessibility® provides application programming interfaces (APIs) such as AccessibleObjectFromWindow and AccessibleObjectFromPoint that allow clients to retrieve accessible objects. These functions return either an IDispatch or IAccessible interface pointer through which clients get information about the accessible object.

When a client calls AccessibleObjectFromWindow or any of the other AccessibleObjectFromX APIs that retrieve an interface to an object, Active Accessibility sends the WM_GETOBJECT window message to the applicable window procedure within the appropriate application. To provide information to clients, servers must respond to the WM_GETOBJECT message.


How WM_GETOBJECT Works

Active Accessibility sends the WM_GETOBJECT message to the appropriate server application when a client calls one of the AccessibleObjectFromX APIs. The following describes the various scenarios that occur:

  • If the window or control that receives WM_GETOBJECT implements IAccessible, the window returns a reference to the IAccessible interface using the API LresultFromObject. Active Accessibility, in conjunction with the COM library, performs the appropriate marshaling and passes the interface pointer from the server back to the client.
  • If the window that receives the message does not implement IAccessible, it should return zero.
  • If the window does not handle the WM_GETOBJECT message, the Microsoft Win32® API DefWindowProc returns zero.

Even if the server returns zero, Active Accessibility still provides the client with information about the object. For most system-provided objects such as list boxes and buttons, Active Accessibility provides complete information, but for other objects, the information is limited. Active Accessibility returns an IAccessible interface pointer that the client uses to get information about the object.


WinEvents Notify Changes

Microsoft® Active Accessibility® provides a mechanism called WinEvents that allows the operating system and servers to notify clients when an accessible object changes. There are numerous conditions in which a server notifies a client of a change. Each event constant defined by Active Accessibility describes a condition about which clients is notified.

WinEvents can signal:

  • When an object is created or destroyed.
  • When an object receives or loses focus.
  • When an object's state or location changes.

Client applications do not receive event notifications automatically; they must specify which events they want to receive by calling SetWinEventHook. With SetWinEventHook, a client specifies the notification events and sets a hook function to handle the specified events. Clients call SetWinEventHook more than once to register different hook functions or to set additional events about which a previously registered hook function is notified.

Hook functions are 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 methods has advantages and disadvantages. For more information, see In-Context and Out-of-Context Hook Functions.

To notify the system of an event occurrence, servers call NotifyWinEvent. Active Accessibility checks whether any client applications have set hook functions for the event and calls the appropriate hook functions as necessary.

When the client's hook function is called, it receives a number of parameters that describe the event and the object that generates the event. To gain access to the object that generates the event, the hook function calls AccessibleObjectFromEvent.

Note If no events are hooked by clients, the performance impact on servers for calling NotifyWinEvent is negligible.

Servers call NotifyWinEvent for changes only in their accessible objects; they do not call NotifyWinEvent for changes in system-provided user interface elements.


Summary of the Client-Server Event Process

The client-server event process is the method the Microsoft® Active Accessibility® establishes a connection through the client applications to an accessible object in response to events that the object generates. The process has six steps:

  1. A server calls NotifyWinEvent to notify Active Accessibility about changes to its user interface elements.
  2. Active Accessibility checks whether any client applications have registered a WinEvent hook function using SetWinEventHookand sends the event notification to the registered callback procedure.
  3. If the client handles the event, it requests access to the object that generates the event by using AccessibleObjectFromEvent, or other accessible object retrieval functions.
  4. In response to the function call, Active Accessibility sends the server application a WM_GETOBJECT message.
  5. In response to WM_GETOBJECT, the server application returns a value to Active Accessibility that acts as a one-time reference to the object that generates the event.
  6. 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.

Once the client has an interface address, the client calls the IAccessible properties and methods of the accessible object to retrieve information.


Guidelines for Servers

For Microsoft® Active Accessibility® to work as designed, servers must provide accessibility information to clients. Active Accessibility server developers should observe the following guidelines:

  • Make your application more accessible by following the guidelines in The Microsoft Windows Guidelines for Accessible Software Design. This document is available on the Microsoft Accessibility Web site at www.microsoft.com/enable.
  • Create accessible objects by implementing the IAccessible properties and methods for your custom user interface elements and for your application's client. Be sure to provide a dual interface that support both IAccessible and IDispatch so that clients written in Microsoft Visual Basic® and various scripting languages get information about the objects.
  • Call NotifyWinEvent to notify clients of user interface changes.
  • Handle WM_GETOBJECT to provide access to your accessible objects.

To qualify to use the Microsoft Windows logo, the logo program requires applications to support a number of accessibility features. For more information, see the Microsoft Accessibility Web site at www.microsoft.com/enable.

For suggestions and guidelines when designing your accessible objects, see Developer's Guide for Active Accessibility Servers.


Guidelines for Clients

Clients use the following functionality in Microsoft® Active Accessibility® to get information about the contents of computer screens:

  • To get an IAccessible interface to objects, call AccessibleObjectFromWindow, AccessibleObjectFromPoint, or AccessibleObjectFromEvent.
  • To examine and manipulate accessible objects use the IAccessible properties and methods.
  • To receive WinEvents call SetWinEventHook to register a WinEvent callback function for those events that are relevant to the client application.


What You Need to Know About COM and Unicode

Because Microsoft® Active Accessibility® is based on COM, developers need a moderate level of understanding about COM objects and interfaces. Client and server developers need to know how to initialize the COM library. Server developers need to understand how to design classes that implement the IAccessible interface and how to create accessible objects.

Developers also need a moderate level of understanding about Unicode to use many of the Active Accessibility functions that return strings.

To use Active Accessibility effectively, at a minimum developers need to know about the following COM and Unicode functions, structures, data types, and interfaces.

Functions | OleInitialize CoInitialize VariantInit and VariantClear MultiByteToWideChar and WideCharToMultiByte SysAllocString and SysFreeString
Structures and Data Types | VARIANT HRESULT BSTR
COM Interfaces | IUnknown IDispatch IEnumVARIANT

Limited information about some of these items is provided in this documentation. For a description of standard COM parameter attributes [in], [out], [in/out], and [out, retval], see Definitions of Parameter Attributes. To learn more about COM and Unicode, see Where to Find More Information.


VARIANT Structure

Most of the Active Accessibility functions and the IAccessible properties and methods take a VARIANT structure as a parameter. Essentially, the VARIANT structure is a container for a large union that carries many types of data.

The value in the first member of the structure, vt, describes which of the union members is valid. Although the VARIANT structure supports many different data types, the only types used in Active Accessibility are the following.

vt Value | Corresponding value member name
VT_I4 | lVal
VT_DISPATCH | pdispVal
VT_BSTR | bstrVal
VT_EMPTY | none

When you receive information in a VARIANT structure, check the vt member to find out which member contains valid data. Similarly, when you send information using a VARIANT structure, always set vt to reflect the union member you're using to send the information.

Before using the structure, initialize it by calling the VariantInit COM function. When finished with the structure, clear it before the memory that contains the VARIANT is freed by calling VariantClear.

For more information about the VARIANT structure, refer to the Automation documentation in the Platform SDK.


IDispatch Interface

The IDispatch interface was initially designed to support Automation. It provides a late-bound mechanism to access and retrieve information about an object's methods and properties. Server developers must implement both the IDispatch and IAccessible interfaces for their accessible objects; that is, they must provide a dual interface.

In addition to the methods inherited from IUnknown, servers developers must implement the following methods within the class definition of each object that is exposed:

  • GetTypeInfoCount—Returns the number of type descriptions for the object. For objects that support IDispatch, the type information count is always one.
  • GetTypeInfo—Retrieves a description of the object's programmable interface.
  • GetIDsOfNames—Maps the name of a method or property to a DISPID, which is later used to invoke the method or property.
  • Invoke—Calls one of the object's methods, or gets or sets one of its properties.

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


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 Microsoft® Win32® functions to perform the necessary conversion.

Use WideCharToMultiByte to convert a Unicode string to an ANSI string. The MultiByteToWideChar function converts an ANSI string to a Unicode string.

The following application-defined function from the Babble sample, which is included with this SDK, illustrates how to properly call WideCharToMultiByte.

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


Active Accessibility C/C++ Developer's Guide

This section provides information about how Microsoft® Active Accessibility® works from the perspective of a C or C++ application developer. It covers issues specific to client and server developers and provides overviews of the SDK's sample applications.

Note that clients are accessibility aids and other applications that use Active Accessibility to obtain information about user interface elements. Servers are applications that use Active Accessibility to provide information about their user interface elements.

The following topics are covered:

  • IAccessible Interface
  • WinEvents
  • Calling Active Accessibility APIs
  • Developer's Guide for Active Accessibility Clients
  • Developer's Guide for Active Accessibility Servers
  • Sample Programs and Testing Tools


IAccessible Interface

The IAccessible interface is a collection of the most common attributes and behaviors of a wide range of user interface (UI) elements. Some of the IAccessible properties are not applicable to every kind of user interface element. Also, the implementation of IAccessible varies from application to application.

Although the parameters and return values for the IAccessible properties and methods are fully specified, how a client should use a property, or how a server should implement a property is sometimes subject to interpretation.

This section provides suggestions, guidelines, and examples to help clients obtain information about UI elements and to help servers provide appropriate information. The following topics are covered:

  • Content of Descriptive Properties
  • Selection and Focus Properties and Methods
  • Object Navigation Properties and Methods


Content of Descriptive Properties

The IAccessible interface provides descriptive properties, which describe various aspects of an object. Some of these properties are content specific; other properties have content consisting of descriptive text that is provided by the server. The type of information for each property varies depending on the object.

The following topics describe information that clients obtain from these properties. They also provide suggestions for servers in choosing the content. The topics are:

  • Name Property
  • Role Property
  • State Property
  • Value Property
  • Description Property
  • Help Property
  • HelpTopic Property
  • KeyboardShortcut Property
  • DefaultAction Property

When designing accessible objects, server developers should also refer to the following topics:

  • Choosing Which Properties To Support
  • Choosing the Content for Descriptive Properties

For information about the parameters and return values of these properties, see the IAccessible section of the Active Accessibility C/C++ Reference.


Name Property

The Name property is a string used by clients to identify, find, or announce an object for the user. All objects support the Name property. 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 graphic objects that do not display a name provide text when queried for the Name property.

The Name property is retrieved by calling IAccessible::get_accName.

Selecting Names

An object's name should be intuitive so that users understand the object's meaning or purpose. Also, the Name property should be unique relative to any sibling objects in the parent.

Navigation within tables presents especially difficult problems for some users. Therefore, server developers should make table cell names as descriptive as possible. For example, a cell name could be created by combining the names of the row and column it occupies, such as "A1." However, it is generally better to use more descriptive names, such as "Nancy, February."

Delegating Requests

If an object does not have access to its Name property, it delegates requests to its parent, identifying itself by its child ID. For example, if a client calls an edit control's Name property, the edit control delegates the query to its parent, which returns the value of the static text control that labels the edit control.


Role Property

The Role property describes an object's user interface element. All objects support the Role property.

In many cases, the object's role is obvious. For example, windows have the ROLE_SYSTEM_WINDOW role and push buttons have the ROLE_SYSTEM_PUSHBUTTON role.

The Role property is retrieved by calling IAccessible::get_accRole.

Identifying an Object's Role

Active Accessibility provides role constants, defined in oleacc.h, that identify common object roles. It is recommended that server developers use these predefined role values. However, servers provide their own localized strings if the predefined values do not suffice. If a predefined role constant is returned, clients use the GetRoleText function to retrieve a localized string that describes the role.

For animation controls such as the animation control displayed when copying files use ROLE_SYSTEM_ANIMATION. Graphics that are occasionally animated, but not always, are described as ROLE_SYSTEM_GRAPHIC with the State property set to STATE_SYSTEM_ANIMATED.

Note that some roles are not easy to describe. For example, 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 have the ROLE_SYSTEM_TABLE role.


State Property

The State property describes an object's status at a moment in time. All objects support the State property.

The State property is retrieved by calling IAccessible::get_accState.

Active Accessibility provides object state constants, defined in oleacc.h, that are combined to identify an object's state. It is recommended that server developers use these predefined state values. However, servers provide their own localized strings if the predefined values do not suffice. If predefined state values are returned, clients use GetStateText to retrieve a localized string that describes the state.

Graphics that are occasionally animated should have the State property set to STATE_SYSTEM_ANIMATED and the Role property set to ROLE_SYSTEM_GRAPHIC.

Using Alert Levels

Server developers can combine the predefined state flags with an alert level that indicates the importance of the other flags. The alert levels are:

  • STATE_SYSTEM_ALERT_LOW
  • STATE_SYSTEM_ALERT_MEDIUM
  • STATE_SYSTEM_ALERT_HIGH

To determine when to notify users, clients can use these alert levels to gauge the information's urgency. For more information, see Alerts.


Value Property

The Value property represents visual information contained by the object. Not all objects support the Value property.

The Value property is retrieved by calling IAccessible::get_accValue.

The Value property tells the client about the visual information contained in an object. For example, the value for an edit control is the text it contains, but a menu item has no value.

Providing Hierarchical Information

The Value property provides hierarchical information in cases such as a tree view control. Although the parent object in the tree view control does not provide information in the Value property, each item within the control has a zero-based value that represents its level within the hierarchy. Top-level items have a value of zero, second-level items have a value of one, and so on.


Description Property

An object's Description property provides a textual description about an object's visual appearance. The description is primarily used to provide greater context for low-vision or blind users, but is also used for context searching or other applications.

The Description property is retrieved by calling IAccessible::get_accDescription,

When to Support the Description Property

Servers support the Description property if the description is not obvious, or if it is redundant based on the object's Name, Role, State, and Value properties. For example, a button with "OK" does not need additional information, but a button that shows a picture of a cactus would. The Name, Role and Help properties for the cactus button describe its purpose, but the Description property conveys information that is less tangible. For example, "A button that shows a picture of a cactus."


Help Property

The Help property provides information that tells the user about the function of an object.

The Help property is retrieved by calling IAccessible::get_accHelp.

This property contains balloon-style information, as is found in ToolTips, that is used either to describe what the object does or how to use it. For example, the Help property for a toolbar button that shows a printer might be, "Prints the current document."

The text for the Help property does not have to be unique within the user interface.

When to Support the Help Property

Servers do not support the Help property if other properties provide sufficient information about the object's purpose and what actions the object performs. Accessible objects that expose system-provided controls do not support the Help property.


HelpTopic Property

The HelpTopic property obtains details used with the Microsoft Win32® WinHelp function to display a Help topic associated with the object. Not all objects support this property.

The HelpTopic property is retrieved by calling the IAccessible::get_accHelpTopic.


KeyboardShortcut Property

The KeyboardShortcut property describes a key or key combination that activates a specified accessible object.

The KeyboardShortcut property is retrieved by calling IAccessible::get_accKeyboardShortcut.

The retrieved string describes a shortcut key, also called a keyboard accelerator or an access key, also called a mnemonic. An access key is an underlined character in the text of a menu, menu item, or the label of a control such as a push button.

The retrieved string must contain the name of the key along with the modifier key or keys. The string must be in the following format so that clients can easily parse it: [[modifier key]+[...]+] key name.

Examples include ALT+F, CTRL+ALT+4, WIN+F1, CTRL+ALT+SHIFT+BACKSPACE, or simply BACKSPACE.

Modifier keys are listed in the following table.

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

Do not localize keyboard shortcut strings.

Handling Objects That Have Both Key Types

If an object has both a shortcut key and an access key, the KeyboardShortcut property returns the access key. The access key is the one a user would press when the object or the object's parent has the keyboard focus. For example, the Print menu item might have both a shortcut key (CTRL+P) and an access key (P). If a user presses CTRL+P while the menu is active, nothing happens. But if a user presses P while the menu is active, it 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 has the keyboard focus.


DefaultAction Property

An object's DefaultAction property describes the object's primary method of manipulation from the user's viewpoint. An object's DefaultAction property should be a verb or a short verb phrase.

The DefaultAction property is retrieved by calling IAccessible::get_accDefaultAction.

To perform an object's default action, clients call IAccessible::accDoDefaultAction.

Not all objects have default actions, and some objects have a default action that is related to its Value property, such as in the following 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 has a value of "Printer."


Selection and Focus Properties and Methods

Like many elements in applications running on Microsoft Windows® operating systems, accessible objects select and receive keyboard focus. These attributes enable users to interact with application elements, change values or otherwise manipulate them.

There are some key differences between object selection and object focus:

  • A focused object is the one object in the entire operating system that receives keyboard input. The object with the keyboard focus is either the active window or a child object of the active window.
  • A selected object is marked to participate in some type of group operation.

For example, a user can select several items in a list view control, but the focus is given only to one object in the system at a time. Note that focused items are in or out of a selection of items.

Clients determine whether a particular accessible object or child element has the focus by calling IAccessible::get_accFocus. Clients determine whether an object is selected or which children within an accessible object are selected by calling IAccessible::get_accSelection . For objects such as list views in which more than one child is selected, the parent object must support the IEnumVARIANT interface, which allows clients to enumerate the selected children.

Events Triggered in Menus

Microsoft Active Accessibility exposes standard menus created with the Microsoft Win32 menu APIs and resource files. To be consistent with standard menus, servers with custom menus trigger EVENT_OBJECT_FOCUS, not EVENT_OBJECT_SELECTION when a user highlights menu items.

NOTE Active Accessibility does not support the selection of the text contained in edit and rich edit controls because the text is exposed as a single string in the Value property for these controls.


Selecting Child Objects

Clients call the IAccessible::accSelect method to modify selection or keyboard focus among the children in an object. The SELFLAG values specified with the call define the operation to perform.

If IAccessible::accSelect is called with the SELFLAG_TAKEFOCUS flag on a child object that has an HWND, the flag takes effect only if the object's parent has the focus.

Performing Complex Selection Operations

The following describes which SELFLAG values to specify when calling IAccessible::accSelect to perform complex selection operations.

To simulate a click

  • SELFLAG_TAKEFOCUS | SELFLAG_TAKESELECTION

To select a target item by simulating CTRL + click

  • SELFLAG_TAKEFOCUS | SELFLAG_ADDSELECTION

To cancel selection of a target item by simulating CTRL + click

  • SELFLAG_TAKEFOCUS | SELFLAG_REMOVESELECTION

To simulate SHIFT + click

  • SELFLAG_TAKEFOCUS | SELFLAG_EXTENDSELECTION

To select a range of objects and put focus on the last object

  1. Specify SELFLAG_TAKEFOCUS on the starting object to set the selection anchor.
  2. Call IAccessible::accSelect again and specify SELFLAG_EXTENDSELECTION | SELFLAG_TAKEFOCUS on the last object.

To deselect all objects

  1. Specify SELFLAG_TAKESELECTION on any object. This flag deselects all selected objects except the one just selected.
  2. Call IAccessible::accSelect again and specify SELFLAG_REMOVESELECTION on the remaining object.


Object Navigation Properties and Methods

Clients navigate from one object to another using methods such as IAccessible::accNavigate and IAccessible::accHitTest. These methods allow clients to retrieve either a child ID or the address of another object's IAccessible interface. Navigation allows clients to explore how objects are related to each other. Note that navigating to another object does not change the selection of focus.

The IAccessible interface provides properties and methods that support the following kinds of navigation:

  • Hierarchical Navigation
  • Spatial and Logical Navigation
  • Navigation Through Hit Testing and Screen Location


Hierarchical Navigation

Often clients must move between objects based on their parent-child relationships. For example, a client might already have information about a toolbar control, but not have information about the buttons contained within it.

The IAccessible interface exposes the hierarchical relationships between objects. Clients can navigate from a parent object to its children or from a child object to its parent by calling IAccessible::get_accParent and IAccessible::get_accChild.


Spatial and Logical Navigation

Clients retrieve information about an object that is spatially or logically near another object within the same container by calling IAccessible::accNavigate and specifying one of the navigation constants.

With spatial navigation clients navigate to an object based on its location on the screen. Clients navigate up, down, left, or right from the current object to obtain information about another object within the same container.

With logical navigation clients navigate to the object that logically precedes or follows another object, as determined by the server. Clients navigate to all of an object's children in two ways:

  • Start the navigation with NAVDIR_FIRSTCHILD and then repeatedly call the method with NAVDIR_NEXT.
  • Start the navigation with NAVDIR_LASTCHILD and repeatedly call the method with NAVDIR_PREV.

Whichever direction, the navigation visits each visible child that belongs to the parent object. Additionally, each child is visited only once, and the navigation does not loop around. That is, the method fails if a client attempts to navigate before the first object or after the last object.

Spatial and logical navigation are related. For example, in a horizontal toolbar, calling the method with NAVDIR_RIGHT should produce the same results as calling the method with NAVDIR_NEXT.

The starting object of the navigation is either the object itself or one of the object's children, except when either NAVDIR_FIRSTCHILD or NAVDIR_LASTCHILD is specified; in this case, the navigation must start from the object itself.

If a client navigates from an accessible object to a sibling user interface element, or the lVal member of varStart is CHILDID_SELF and the specified flag in navDir is any navigation flag except NAVDIR_FIRSTCHILD or NAVDIR_LASTCHILD, the result in pvarEnd is either a child ID or an IDispatch interface. If pvarEnd contains a child ID, to navigate from this user interface element or to obtain more information about it, clients must first obtain a pointer to the parent's IAccessible interface. To obtain the parent object, clients call the IAccessible::get_accParent property of the sibling object or the starting object of the navigation.

Note that clients must know all floating objects, by calling the Win32 API EnumChildWindows. Because a floating object is not clipped to its parent, clients do not have information about the hierarchical relationship between two objects near one another on the screen.

The following is an example of a floating object that is not clipped to its parent.

Screenshot of the Open window layered above a larger Microsoft Developer Studio window.

Establishing the Order in Logical Navigation

In logical navigation, the developers who design the objects establish the relationships between them. Logical navigation is more subjective than spatial navigation. Also, the order in logical navigation is not the same as the order used with child IDs.

For objects that have screen locations, server developers should establish the navigation order in the way that most users would consider logical. In English-speaking countries, for instance, this means a left-to-right, top-to-bottom ordering.

Logical navigation order must parallel keyboard navigation order. For example, a dialog box contains OK and Cancel push buttons and a few edit controls. A client that calls IAccessible::accNavigate to navigate to the next or previous object in that dialog box moves in the same order as a user pressing TAB or SHIFT+TAB to move the focus between items.

For objects that do not have defined screen locations, the logical order is decided by server developers, and client developers should make no assumptions about it. For instance, it is acceptable for non-visible objects, such as objects that are only temporarily hidden, to be interspersed with visible objects.


Navigation Through Hit Testing and Screen Location

To locate an object's children or to determine how large an object is, clients can hit test points on the screen. Two methods are available:

  • IAccessible::accHitTest
  • IAccessible::accLocation

Using IAccessible::accHitTest

To identify whether a point is within an object, within its child, or neither, clients call the IAccessible::accHitTest method of the parent object, passing the screen coordinates of the point to be hit tested. The following describes some typical scenarios:

  • If the object's children overlap at a specified point, IAccessible::accHitTest retrieves the topmost child that visually appears to occupy the space.
  • If a window covers a child, or if the child is clipped by the parent, hit testing the covered point retrieves the child even though it is not visible.
  • If the child found at the specified point is an accessible object, as opposed to a child element, the method returns the child's IDispatch interface.

Using IAccessible::accLocation

To get the screen location of an object or one of the object's children, clients call IAccessible::accLocation. This method returns the coordinates of the specified object's bounding rectangle. If the object is not shaped like a rectangle, the method returns the coordinates of the smallest rectangle that encompasses the entire object.

The following illustration shows the relationship between a non-rectangular object's region and its bounding rectangle.

Illustration showing the relationship between a nonrectangular object's region and its bounding rectangle.

Note IAccessible::accHitTest is more precise than IAccessible::accLocation because it enables clients to determine the location of objects on a pixel-by-pixel basis rather than with bounding rectangles. This precision is useful, for example, when an application is tracking the location of the mouse pointer to gather information.


WinEvents

Microsoft Active Accessibility provides a mechanism called WinEvents that allows servers and the operating system to notify clients when an accessible object changes in some manner.

This section provides suggestions, guidelines, and examples to help clients in handling WinEvents, as well as to help servers determine the conditions in which they trigger a WinEvent, and which WinEvent triggers. The following topics are covered:

  • What Are WinEvents?
  • System Level and Object Level Events
  • Registering a Hook Function
  • In-Context and Out-of-Context Hook Functions
  • In-Context Hook Functions Precautions
  • WinEvents for Simple Elements
  • Alerts

For an overview of the event notification process, see WinEvents Notify Changes.


What are WinEvents?

Server applications and the operating system use WinEvents to notify clients that an accessible object changes in some manner. Servers call the NotifyWinEvent function whenever they notify clients that an event has occurred.

This function identifies the event that has occurred, as well as the window the object is in, and with which object the event is associated. If a child element changes, the parent object calls NotifyWinEvent and specifies the child ID of the child element.

Servers call NotifyWinEvent to announce the event to the system after the event has occurred. They must never notify the system of an event before the event occurs.

To be notified of events, clients register callback hook functions by using SetWinEventHook. Clients set a single hook function for all possible events, or multiple hook functions for discrete ranges of events.

When Active Accessibility is notified of an event, it calls any hook functions that were registered for that event, passing along the parameters from NotifyWinEvent.


System Level and Object Level Events

There are two classes of events, system level and object level, each with a corresponding event constant value:

  • Event constants that begin with EVENT_SYSTEM identify system level events. These events describe situations affecting all applications in the system.
  • Event constants that begin with EVENT_OBJECT identify object level events. These events pertain to situations specific to objects within one application.

Both classes of events are generated by the operating system and server applications. The operating system generates system level and object level events for:

  • System-wide notifications about focus changes.
  • Activation changes.
  • Events regarding system-provided objects, such as common controls.

Server applications generate system level events for:

  • Alerts.
  • Custom objects that replicate system objects, such as custom menus and scroll bars.

Server applications typically generate object level events for:

  • Changes to the accessible objects they contain, such as object creation, destruction, and selection.

Although the system generates object level events for window objects, servers must also send object-level events for every accessible object contained in a window. For example, if a server application registers an application-defined window class to create a custom control, the system generates object-level events for the window that contains the custom control, but the server generates object-level events for the accessible object that provides information about the control.

Servers only generate object level events for the custom controls for which they implement the IAccessible interface. For more information, see Servers Expose Custom User Interface Elements.


Registering a Hook Function

An application-defined hook function is typical of other Microsoft Windows operating system callback functions. An application selects any name for the hook function, but it must take the same parameters and return value as specified in WinEventProc Callback Function.

The parameters that the hook function receives tell the client about the window, object, and possible child element that generated the event. A client uses these parameters in an object retrieval call, such as AccessibleObjectFromEvent.

Clients specify which events a hook function is called for when registering the hook function with SetWinEventHook. Clients call SetWinEventHook more than once to register different hook functions or to set additional events about which a previously registered hook function is notified.


In-Context and Out-of-Context Hook Functions

When registering a hook function with SetWinEventHook, clients specify whether the hook function is in-context or out-of-context. These terms describe the memory location of the hook function relative to the server's address space.

The following provides detailed information:

  • In-Context Hook Functions
  • In-Context Hook Functions Precautions
  • Out-of-Context Hook Functions


In-Context Hook Functions

The following outlines key aspects of in-context hook functions:

  • Must be located in a dynamic-link library (DLL) that the system maps into the server's address space.
  • Shares the address space with the server.
  • When the server triggers an event, the system calls a hook function without marshaling, (packaging and sending interface parameters across process boundaries).
  • Tends to be very fast and receives event notifications synchronously, because there is no marshaling.


In-Context Hook Functions Precautions

For performance reasons, client developers register in-context hook functions. However, because these hook functions are mapped into the server's address space, client and server developers must take precautions to ensure that the event processing goes smoothly.

Precautions for Client Developers

Client developers should be aware of the following:

  • In-context hook functions do not use a lot of processor time because the hook function must return before the server application continues.
  • After an event is triggered, it is possible that the window associated with an event no longer exists by the time the hook function is called. Clients 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, clients use the Microsoft Win32 IsWindow function.
  • If the DLL in which the hook function is defined links to another DLL, client developers must ensure that the system locates the other DLL to load it. If linking implicitly (using .def files and imports), the additional DLL must be in either the Windows or Windows\System directory. If linking explicitly (using LoadLibrary), the full-path to the directory in which the additional DLL resides must be specified in the call to LoadLibrary.
  • In-context hook functions cause a stack overflow when the DLL that contains the hook function is loaded into a 16-bit application. This problem happens because 16-bit applications use a fixed stack size that is not large enough to accommodate the chain of system function calls that result in a call to the hook function.

Invalid Interface Pointers

When a client calls AccessibleObjectFromEvent within an in-context hook function, the IAccessible interface pointer that is returned points directly to code in the server's address space. If the client calls an interface property using this pointer, the COM library is not involved with marshaling (packaging and sending interface parameters across process boundaries) or unmarshaling (unpackaging parameters that have been sent across process boundaries) and does not detect if an object is destroyed.

If the client calls an interface property to an object that is destroyed, unless the server detects this situation, the invalid interface pointer causes a General Protection fault in the server's address space.

To protect against invalid interface pointers, servers create proxy objects that wrap accessible objects and that monitor the life span of accessible objects. For instance, when a client calls an IAccessible property to get information about an object, the proxy checks whether the accessible object is still available, and if so, the proxy forwards the client's request to the accessible object. If the accessible object is destroyed, the proxy returns an error to the client.


Out-of-Context Hook Functions

The following outlines the key aspects of out-of-context hook functions.

  • Out-of-context hook functions are located in the client's address space, whether it's in the code body or in a DLL.
  • Out-of-context hook functions are not mapped into the server's address space.
  • When an event is triggered, the parameters for the hook function are marshaled across process boundaries.
  • Out-of-context hook functions are noticeably slower than in-context hook functions, because of marshaling.
  • The system queues the event notifications so that they arrive asynchronously (because of the time required to perform marshaling).

Although the event notifications are asynchronous, Active Accessibility assures that the callback function receives all events in the order in which they are generated.

The USER component of the operating system allocates memory for events that are handled by out-of-context hook functions, and the memory is freed when the hook functions return. If a hook function does not process events quickly enough, USER resources are lowered, eventually resulting in a fault or extremely slow response times. These problems may occur if:

  • Events are fired very rapidly.
  • A slow computer is used.
  • The hook function takes a long time to process events.


Guarding Against Reentrancy in Hook Functions

When a hook function processes an event, additional events are triggered, and the hook function is reentered before the processing for the original event is finished. The problem with reentrancy in hook functions is that events are completed out of sequence unless the hook function handles this situation.

For example, a hook function in a screen reader program is processing the event EVENT_OBJECT_VALUECHANGE for an edit control. If, while processing the first value change event, the hook function is reentered to process a subsequent value change event, it completes the second event before the first event. This situation results in the screen reader conveying inaccurate information to the user.

Because event processing is interrupted, additional events are triggered any time the hook function calls an API that causes the owning thread's message queue to get checked. This happens when any of the following are called within the hook function:

  • The Win32 APIs SendMessage, GetMessage, PeekMessage, DialogBox, or MessageBox.
  • The Active Accessibility APIs AccessibleObjectFromEvent, AccessibleObjectFromWindow, AccessibleObjectFromPoint.
  • An IAccessible or other COM property or method that crosses process boundaries.

Because hook functions call AccessibleObjectFromEvent and IAccessible properties and methods, it is not possible to prevent reentrancy. The only solution is for client developers to add code in the hook function that detects reentrancy and take appropriate action if the hook function is reentered.

The file inspect.cpp in the Inspect Objects sample demonstrates how to guard against reentrancy. The Inspect Objects hook function, NotifyProc, uses a global BOOL to detect reentrancy. NotifyProc sets the variable to TRUE right before it begins processing an event and sets it to FALSE when the processing is complete.

When the hook function is called, NotifyProc check the variable, and if it is TRUE, instead of processing the event, NotifyProc saves the event data and sets a flag to indicate that an event has been stored. When the processing for the original event is done, NotifyProc checks this flag, and if it is set, indicating that there is a saved event, NotifyProc processes the event. This takes place within a loop because it is possible that more callbacks can occur while processing the saved event.


WinEvents for Simple Elements

Often, simple elements generate events. Because these elements are not accessible objects and do not support Active Accessibility, they present a special problem for clients. Active Accessibility places the responsibility of support for the IAccessible interface on the element's parent object. For information about accessible objects and simple elements, see Relationships Among Objects.

With every event notification, the client's WinEventProc callback function receives an identifier in the idChild parameter that specifies whether an object or one of the object's child elements generated the event. If idChild is a child ID, then the accessible object that contains the element supports IAccessible on the child element's behalf. Clients use the IAccessible methods and properties to obtain information about an object or an object's children.


Alerts

Server applications generate the EVENT_SYSTEM_ALERT event whenever a user interface change occurs about which a user needs to know. In addition to triggering EVENT_SYSTEM_ALERT, the server sets the alert level in the object's state bits to convey the level of urgency to the client.

To determine when the user is notified, clients call IAccessible::get_accState to get the object's state information.

Applications always perform the stages of an alert in a specified order.

To perform the stages of an alert

  1. Adjust the visual presentation of the object. For example, change an icon to red.
  2. Set the alert level state flag for the object to either STATE_SYSTEM_ALERT_LOW, STATE_SYSTEM_ALERT_MEDIUM, or STATE_SYSTEM_ALERT_HIGH.
  3. Send any appropriate events related to the appearance change. For example, EVENT_OBJECT_DESCRIPTIONCHANGE.
  4. Send the EVENT_SYSTEM_ALERT event.
  5. When the client receives the EVENT_SYSTEM_ALERT event, it immediately calls IAccessible::get_accState to obtain the alert state flags of the referenced object.

The same process is repeated until the object is no longer 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_ALERT message is sent and references 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_ALERT message is sent. A client receives this event, checks the icon object's state flags and finds that none of the alert flags are set, which indicates that the alert for this object is over.

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

Although the appropriate events are generated when a change occurs, server developers should minimize sending redundant events.


Dynamic Annotation API

The Dynamic Annotation Application Programming Interface (API) is an extension to MSAA that allows developers to customize existing IAccessible support without having to use error-prone subclassing or wrapping techniques. This mechanism also allows developers to pass hints or other useful information to the OLEACC proxies.

Dynamic Annotation is typically used to correct or amend an inaccurate instance of an IAccessible object exposed by an existing OLEACC proxy. For example, you can use it to override the Name and Role properties provided by the default proxy; and to supply Description and Help properties (which may not be provided by the default proxy).


Background Information

Currently, you can customize an existing IAccessible implementation using subclassing and wrapping techniques. However, these techniques are tedious and error-prone. In fact, the majority of the code written to override one or two properties is concerned with implementing subclassing and wrapping; only a small fraction carries out the real task of overriding information.

Dynamic Annotation improves the situation by providing similar capabilities without requiring you to write subclassing or wrapping code. Instead, you can focus on providing code that supplies the correct information.

Dynamic Annotation also provides a standard way to provide hints or extra information to the OLEACC proxies.


Using Dynamic Annotation

The following section explains how to use Dynamic Annotation to perform the following tasks:

  • Override a property specifying a value
  • Override a property specifying a callback

It also contains information about the properties that Dynamic Annotation supports.


Override a property specifying a value

To override a property that specifies a value

  1. Obtain an IAccessible interface pointer to the accessible element that is to be annotated.
  2. Call QueryInterface on the accessible element to get an IAccIdentity pointer.
  3. Call GetIdentityString() on the IAccIdentity pointer to obtain a string that uniquely identifies the accessible element which is to be annotated.
  4. Use CoCreate to create the IAccPropServices object.
  5. Call IAccPropServices::SetPropValue, passing the identity string, a GUID indicating the property to be overridden, and a VARIANT containing the new value of the property. This annotates the value.
  6. Release interface pointers and free memory.

If you know in advance that the accessible element being annotated is HWND-based and the corresponding hwnd/idObject/idChild values, you can generate an identity string using IAccPropServices::ComposeHwndIdentityString(), avoiding the need to obtain the IAccessible interface pointer and call QueryInterface for IAccIdentity. Alternatively, you can call the SetHwndPropValue method, which takes a hwnd/idObject/idChild in place of an identity string.

For a list of properties that can be annotated using this procedure, see Properties supported when specifying a value.


Properties supported when specifying a value

The following properties can be annotated when specifying a value (where value must be of the noted type):

Property | Type
PROPID_ACC_NAME | VT_BSTR
PROPID_ACC_DESCRIPTION | VT_BSTR
PROPID_ACC_ROLE | VT_I4
PROPID_ACC_STATE | VT_I4
PROPID_ACC_HELP | VT_BSTR
PROPID_ACC_KEYBOARDSHORTCUT | VT_BSTR
PROPID_ACC_DEFAULTACTION | VT_BSTR
PROPID_ACC_VALUEMAP | VT_BSTR
PROPID_ACC_ROLEMAP | VT_BSTR
PROPID_ACC_STATEMAP | VT_BSTR


Override a property specifying a callback

To override a property that specifies a callback

  1. Obtain an IAccessible interface pointer to the accessible element that is to be annotated.
  2. Call QueryInterface on the accessible element to get an IAccIdentity pointer.
  3. Call GetIdentityString() on the IAccIdentity pointer to obtain a string that uniquely identifies the accessible element which is to be annotated.
  4. Use CoCreate to create the IAccPropServices object.
  5. Create a COM object that implements IAccPropServer.
  6. Call IAccPropServices::SetPropServer, passing the identity string, a GUID indicating the property to be overridden, and a pointer to the IAccPropServer callback object.
  7. Release interface pointers and free memory.

When a client requests that property of that accessible element, the callback object will be called, and the value it returns will be returned to the client.

As when specifying a value, the annotator can alternatively use the IAccPropServices::ComposeHwndIdentityString method to obtain an identity string; or it can use the IAccPropServices::SetHwndPropServer method and specify the hwnd/idObject/idChild instead of an identity string.

When using either SetPropServer or SetHwndPropServer on a container object, the annotator can optionally specify that the overriding information should also apply to all element children of that container.

The annotator can explicitly clear the annotation at any time by using IAccPropServices::ClearProp(). This is usually not required, as the annotation service will automatically clean up and release annotation information when the accessible element being annotated disappears.

For a list of properties that can be annotated using this procedure, see Properties supported when specifying a callback.


Properties supported when specifying a callback

When specifying a callback, the following properties can be annotated (currently these properties cannot be annotated directly by specifying a value):

Property | Type
PROPID_ACC_NAME | VT_BSTR
PROPID_ACC_DESCRIPTION | VT_BSTR
PROPID_ACC_ROLE | VT_I4
PROPID_ACC_STATE | VT_I4
PROPID_ACC_HELP | VT_BSTR
PROPID_ACC_KEYBOARDSHORTCUT | VT_BSTR
PROPID_ACC_DEFAULTACTION | VT_BSTR
PROPID_ACC_VALUEMAP | VT_BSTR
PROPID_ACC_ROLEMAP | VT_BSTR
PROPID_ACC_STATEMAP | VT_BSTR
PROPID_ACC_FOCUS | VT_DISPATCH VT_I4
PROPID_ACC_SELECTION | VT_DISPATCH VT_I4 VT_UNKNOWN
PROPID_ACC_PARENT | VT_DISPATCH
PROPID_ACC_NAV_UP | VT_DISPATCH VT_I4
PROPID_ACC_NAV_DOWN | VT_DISPATCH VT_I4
PROPID_ACC_NAV_LEFT | VT_DISPATCH VT_I4
PROPID_ACC_NAV_RIGHT | VT_DISPATCH VT_I4
PROPID_ACC_NAV_PREV | VT_DISPATCH VT_I4
PROPID_ACC_NAV_NEXT | VT_DISPATCH VT_I4
PROPID_ACC_NAV_FIRSTCHILD | VT_DISPATCH VT_I4
PROPID_ACC_NAV_LASTCHILD | VT_DISPATCH VT_I4


Read the property of an annotated object

MSAA clients can use the existing OLEACC APIs and IAccessible methods to access the properties of an annotated object. Clients do not have to perform any additional tasks to take advantage of annotation.

Currently only the above properties are supported. Specifying a property other than those mentioned above in one of the annotation methods will result in an E_INVALIDARG error return.

Interface IAccIdentity is implemented by all OLEACC proxies.


Issues and Limitations

Before using Dynamic Annotation, you should consider the following issues and limitations:

  • Scope and longevity of identity strings
  • Multiple annotations on a single accessible element
  • Annotation properties that have corresponding WinEvents
  • Interaction with WinEvents
  • Native IAccessible support
  • In-process support


Scope and longevity of identity string

An identity string identifies a particular instance of a UI element. Multiple instances of an accessible element will have different identity strings; therefore it is typically not useful to persist an identity string.


Multiple annotations on a single accessible element

Currently only one annotation is supported per property on an accessible element. Successive annotations on a property of an object replace and overwrite earlier annotations of that property.


Annotation properties that have corresponding WinEvents

Be careful when overriding properties that change frequently, particularly those that are examined by clients as a result of a WinEvent (such as State, Value, and, for some controls, the Name properties).

In many cases, especially for USER and ComCtl controls, the WinEvent signaling a property change is sent before the owner of the control is notified (typically via WM_NOTIFY). Updating the property using SetPropValue() in the WM_NOTIFY handler will be too late; clients using in-context hooking will already have accessed the old value.

You can handle these types of properties by using callback server objects (using SetPropServer); however, the server cannot use any state that is updated in the WM_NOTIFY handler, because that handler will not yet have been called. For example, instead of using a cached 'current value' variable that is updated in the WM_NOTIFY handler and which will be out-of-date, the IAccPropServer::GetPropValue callback object should send a message directly to the control to get its true current value and use that to generate the required property.


Interaction with WinEvents

The Annotation run time will not send WinEvents; it is the annotator's responsibility to send appropriate events, when necessary. If you need to send WinEvents, be sure to send them after the annotation has taken place.

For example, if you use IAccPropServices::SetPropValue to set the Name property of an element, send an EVENT_OBJECT_NAMECHANGE event for that object after SetPropValue returns.

However, if the annotator uses IAccPropServices::SetPropValue to set the ValueMap for a slider, no events are required, since setting the ValueMap does not change the slider's value.


Native IAccessible support

OLEACC implements IAccIdentity on behalf of 'OBJID_CLIENT' IAccessible interface pointers and their immediate simple element children. An 'OBJID_CLIENT' IAccessible interface pointer is returned when WM_GETOBJECT with lParam = OBJID_CLIENT is sent to an hWnd, and which represents the client area of the window or the control as a whole. The parent of such an IAccessible will typically have a role of ROLE_SYSTEM_WINDOW and is the IAccessible object returned when WM_GETOBJECT with lParam = OBJID_WINDOW is sent to an hWnd.

These IAccessible interface pointers typically occur where an OLEACC proxy is subclassed; or where a simple custom control (such as container IAccessible plus one level of simple element children) provides a native IAccessible implementation.

More complicated native IAccessible implementations—such as where a hierarchy of IAccessibles exists or where custom idObjects are used—must implement IAccIdentity themselves.

However, this would require adding methods to IAccPropServices to allow such implementations to hook into the identity string namespace without clashing with other strings. Support for this does not currently exist.


In-Process Support

The current implementation of Dynamic Annotation is entirely in-process; and consequently allows only UI elements to be annotated by the process that owns those UI elements. It is not possible for one process to annotate the UI elements of another process.

Note that this only affects the act of setting an annotation; it does not interfere with the ability of clients to access the properties (annotated or otherwise) of UI elements in other processes.


Calling Active Accessibility APIs

Microsoft Active Accessibility provides application programming interface (APIs) for both clients and servers. Most are implemented in the Active Accessibility dynamic link library, oleacc.dll, but NotifyWinEvent, SetWinEventHook, and UnhookWinEvent are implemented in user32.dll, which is a core component of the Microsoft Windows operating system.

Computers running Microsoft Windows 95 or Microsoft Windows NT® version 4.0 do not have oleacc.dll and the correct version of user32.dll installed because Active Accessibility was incorporated in stages into succeeding versions of Windows. As a result, applications that run on these platforms explicitly link to oleacc.dll at runtime using the Microsoft Win32 API LoadLibrary instead of relying on import libraries.

Server applications use the Win32 API GetProcAddress to retrieve the address of an Active Accessibility function and then make the call through a function pointer. If calling a function that was implemented in oleacc.dll, server applications use the handle returned from LoadLibrary in the call to GetProcAddress. If calling a function defined in user32.dll, server applications call GetModuleHandle specifying "USER32" and use the returned module handle in the call to GetProcAddress.

For example, if an application uses NotifyWinEvent, it calls GetProcAddress using the module handle of user32.dll to get the address of the API. If the call is successful, meaning that this version of Windows supports Active Accessibility, then the application sets a flag that indicates that it is safe to call NotifyWinEvent. The address received from GetProcAddress is stored in a function pointer variable and used throughout the code.


Developer's Guide for Active Accessibility Clients

This section is for client developers who use Microsoft Active Accessibility to obtain information about user interface elements. The following topics are discussed:

  • Getting an Accessible Object Interface Pointer
  • Checking IAccessible Return Values
  • Setting a WinEvent Hook
  • Active Accessibility Client Tutorial


Getting an Accessible Object Interface Pointer

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

  • Using AccessibleObjectFromEvent
  • Using AccessibleObjectFromPoint

It is possible that servers return distinct interface pointers for the same user interface element each time any of the AccessibleObjectFromX is called. To determine if two interface pointers point to the same user interface element, client developers must compare IAccessible properties of the object; comparing pointers do not work.


Using AccessibleObjectFromEvent

Many clients look up information about specific accessible objects that generate events. Because 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.

Note Clients with in-context hook functions must call the Microsoft Win32 API IsWindow before calling AccessibleObjectFromEvent.

AccessibleObjectFromEvent accepts much of the same information that a client's hook function receives. When a client hook function receives an event notification, it "recycles" most of the parameters it receives with the notification to call AccessibleObjectFromEvent.

AccessibleObjectFromEvent retrieves either the IAccessible interface pointer of the user interface element that generated the event or the interface pointer of the element's parent object. If the parent object's interface pointer is returned, clients call the parent's properties and methods to obtain information about the child element that generated the event.


Using AccessibleObjectFromPoint

To retrieve the address of an object's IAccessible interface at a specified point on the screen, clients use the AccessibleObjectFromPoint function.

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.
IAccessible* pAcc = NULL;
HRESULT      hr;
VARIANT      varChild;

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

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


Checking IAccessible Return Values

Client developers must not use the COM macros SUCCEEDED and FAILED to test IAccessible return values because values other than S_OK are considered a success. For example, a method returns S_FALSE, which is considered a success by the SUCCEEDED macro, but still receive a NULL pointer in an output parameter. Only a return value equal to S_OK is considered successful.

Client developers must guard against the possibility that some servers return error codes other than the documented values. To be safe, clients must ensure that all the output parameters contain valid information. Clients must check output parameters to ensure that:

  • All pointers are non-NULL.
  • The vt member of any VARIANT structure is not equal to VT_EMPTY.


Setting a WinEvent Hook

To set a WinEvent hook, client developers must register a hook procedure by calling the SetWinEventHook function. This function allows clients to specify the events to receive, and the process and thread in which those events are generated. This is useful when client developers want to work with certain applications or just the system.

Additionally, the function's parameters describe whether the client is registering an in-context or out-of-context hook function.

The following code fragment, taken from the Inspect Objects sample 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,             // Get 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);
else // Did not install properly - fail
    return(FALSE);


Active Accessibility Client Tutorial

The Active Accessibility SDK includes a sample 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 discusses the tasks that Babble performs and presents the basic information to develop an Active Accessibility client application.

The tutorial contains the following:

  • 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


About the Babble Sample Application

Babble is a simple application that provides information about accessible objects and announces focus and activation events. Babble combines Active Accessibility technology and the Microsoft Speech SDK to vocalize events and object information to the user.

Babble uses both WinEvent and standard keyboard hooks to capture events related to accessible objects and global keyboard events. The Babble project workspace includes a "BabHook" project for the DLL code that grabs all keyboard events.

To build the Babble project, have the SAPI (Speech API) SDK installed on your machine. Additionally, define the environment variable SPEECHDK to point to the SAPI SDK installation. If you do not have the SAPI SDK installed on your machine, download it from www.microsoft.com/iit/.


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 COM 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 COM.
if (FAILED(CoInitialize(NULL)))
    return FALSE;

CoInitialize accepts only one parameter, pvReserved, which 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 is not initialized and the application cannot successfully run. FAILED is a macro found in winerror.h.


Step 2: Set a WinEvent Hook

After initializing the COM library, set a WinEvent hook by calling the SetWinEventHook function. The Babble application calls SetWinEventHook 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,             // Get 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);
else // 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 begins to receive event notifications. The following function, taken from the Babble sample application, shows an example of how a hook procedure receives event notifications and processes 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 only responds to EVENT_OBJECT_FOCUS events, calling another application-defined function to process them. The client application responds to far more events.

When the hook procedure receives an EVENT_OBJECT_FOCUS event, Babble calls the 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 received 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);
}

To retrieve information about the object that generated the event, OnFocusChangedEvent uses the AccessibleObjectFromEvent function.

Note that Babble initializes the VARIANT structure it sends with the function call to comply with Automation standards.

When AccessibleObjectFromEvent returns, Babble tests the return value with the SUCCEEDED macro, which is found in winerror.h. 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 the application no longer requires COM services, use the CoUninitialize COM function to close the COM library. Closing the COM library is required by COM standards; failing to do so results in memory leaks. Babble calls CoUninitialize when it closes the text-to-speech engine in its UnInitTTS application-defined function.


Developer's Guide for Active Accessibility Servers

This section provides information useful to server developers who use Microsoft Active Accessibility to expose information about their application's user interface elements. The following topics are discussed:

  • Creating Proxy Objects
  • IAccessible Design Considerations
  • How to Handle WM_GETOBJECT
  • Shortcuts for Exposing Custom User Interface Elements


Creating Proxy Objects

In addition to designing classes that implement the IAccessible properties and methods, server developers may also need to design proxy objects that monitor the life span of accessible objects. If an accessible object in an application is available the entire time the application is running, then you do not need to create a proxy object. If it is possible to destroy the accessible object while the application remains running, then servers must create a proxy object.

The following topics are discussed in this section:

  • What Are Proxy Objects?
  • Why Proxy Objects Are Needed
  • Design Considerations of Proxy Objects


What Are Proxy Objects?

A proxy object acts as an intermediary between the client and an accessible object. The purpose of the proxy object is to monitor the life span of the accessible object and to forward calls to the accessible object only if it is not destroyed.

When a client calls an IAccessible property to get information about an object, the proxy object must check whether the accessible object is still available. If it is, the proxy object forwards the client's request to the accessible object. If the accessible object is destroyed, for example, when a dialog box with custom controls is closed, the proxy object returns an error. To indicate that the object has been destroyed, it is recommended that servers return the error code CO_E_OBJECTNOTCONNECTED because this error is returned by COM after a server calls CoDisconnectObject.

The proxy object is transparent to the client. When the client calls AccessibleObjectFromEvent or any of the AccessibleObjectFromX APIs, it receives back a pointer to an IAccessible interface. However, when the client uses this pointer to call any of the IAccessible properties or methods, the code that is executed is actually within the proxy object.


Why Proxy Objects Are Needed

With other COM objects, the COM library itself serves as a proxy because the client and the object run in separate address spaces. When a client calls an interface property, the COM library performs the appropriate marshaling and unmarshaling. Because the COM library is in the middle, it detects when a server calls CoDisconnectObject and returns an error code if the client calls an interface property after the object is destroyed.

With accessible objects, when a client sets an in-context hook function, the DLL in which the client's hook function is implemented is loaded into the server's address space. In this case, when the client calls AccessibleObjectFromEvent from within the hook function, the interface pointer that is returned points directly to code in the server's address space. When the client calls an interface property using this pointer, the COM library is not involved with marshaling or unmarshaling and cannot detect if an object is destroyed. Therefore, the server must detect this situation and return an error code to the client.


Design Considerations of Proxy Objects

Proxy and accessible object design depends on the design of the server user interface (UI) elements. But no matter what the design is, a UI element must notify its proxy object right before it is destroyed so that the proxy object handles calls from clients appropriately.

Some design possibilities are:

  • The code that implements the IAccessible interface could be placed in the same module as the code that implements the user interface element if the user interface code is easily extensible. In this case, the proxy is "lightweight" in the sense that all it does is monitor the life span of the accessible object, forward calls to the accessible object, and return the results.
  • The code that implements IAccessible could be placed in the same module as the code that implements the proxy object. In this case, the accessible object uses internal functions to obtain information about the UI element.


IAccessible Design Considerations

Server developers have a great deal of freedom in designing their classes based on the IAccessibleinterface that exposes information about their application's user-interface. Server developers must make decisions about:

  • Choosing When to Create Accessible Objects
  • Choosing Which Properties To Support
  • Choosing the Content for Descriptive Properties
  • Setting Properties for Animated or Moving Objects


Choosing When to Create Accessible Objects

Server developers can create all the accessible objects within a container when the container is created, or they can create the accessible objects dynamically.

For example, imagine a dialog box with several custom controls. A server creates accessible objects for all of the custom controls when the dialog box is displayed. However, if one of the controls is a custom combo box, the server waits until a user selects it to create accessible objects for the items that the combo box contains.

By having the parent create accessible objects dynamically, applications use less memory than if all the possible accessible objects were created ahead of time.


Choosing Which Properties To Support

The IAccessible properties provide a way for server developers to describe a wide variety of user interface elements. But not all of the properties are applicable for every kind of user interface element. Additionally, some properties provide descriptive information that is useful but not essential.

Servers must support the following properties and methods for every object:

  • Name
  • Role
  • State
  • Location and IAccessible::accHitTest
  • Parent and IAccessible::accNavigate

The following properties and method must be supported if they are applicable to the object.

  • KeyboardShortcut
  • DefaultAction and IAccessible::accDoDefaultAction method
  • Value

The following properties method must be supported if the object has children.

  • Child and ChildCount
  • Focus, Selection, and IAccessible::accSelect

The following properties are optional, but they provide useful descriptive information about the object. The Description property is implemented to describe bitmaps and other images.

  • Description
  • Help
  • HelpTopic


Choosing the Content for Descriptive Properties

While the content of some properties is specific, the content for other properties consists of descriptive text that is left to the server developer to provide. Additionally, the type of information for each property varies depending on the object. The following table provides suggestions to help choose the content of these descriptive properties.

Property | Content Suggestion
Name | A label that briefly describes and identifies the object within its container, such as the text in a push button, the name of a menu item, or a label displayed next to an edit control.
DefaultAction | The default interaction with the object. The string returned by this property is either a single verb, such as "Press" for a toolbar button, or a short phrase that begins with a verb.
Value | Information contained in the object, such as the text in an edit control or the filename of an HTML link. The contents of the Value property can change, whereas the contents of the Name property do not change.
Description | Describes what the object looks like.
Help | ToolTip or balloon-style information used either to describe what the object does or how to use it.
HelpTopic | A context identifier of a WinHelp topic that documents the object.

Use one of the predefined object role values for the Role property and the appropriate combination of object state constants for the State property.

The content of the properties for custom controls must match the content of the properties for the system-provided controls that the custom controls emulate. See Appendix A: Supported User Interface Elements Reference for information about the properties supported by system-provided controls.


Setting Properties for Animated or Moving Objects

For animation controls, such as the animation control displayed when copying files, use ROLE_SYSTEM_ANIMATION. Graphics that are occasionally animated, but not always, are described as ROLE_SYSTEM_GRAPHIC with the State property set to STATE_SYSTEM_ANIMATED.

Use the STATE_SYSTEM_ANIMATED flag to mark an object whose appearance changes rapidly. Clients use this flag to avoid notifying users repeatedly for what is really a single series of visual changes.

An example of this is "marquee" text, disclosed progressively as it scrolls across the screen. Such objects are given the attribute of STATE_SYSTEM_ANIMATED. In most cases the object's Value property string reflects the entire text, even the portion not currently visible. Changing the Value string frequently to correspond to the text currently visible is not recommended because it results in far too many EVENT_OBJECT_STATECHANGE events that do not convey useful information.

For example, in a window that contains a rectangular region that shows the word "Yes!" moving around in a figure-eight pattern, the Role property is ROLE_SYSTEM_GRAPHIC, its Value property is the string displayed, its Location property is the bounding rectangle around the text, and it has the STATE_SYSTEM_ANIMATED attribute flag set. Its Description property is "The word 'Yes!' is moving around the screen in a figure-eight pattern." The server generates only EVENT_OBJECT_STATE_CHANGE events when the object starts or ceases animation.


How to Handle WM_GETOBJECT

How a server application responds to WM_GETOBJECT depends on the design of its accessible objects. Whatever the design, servers must pass a pointer to the interface for the accessible object that corresponds to LresultFromObject, which generates a reference to the accessible object. Active Accessibility, in conjunction with the COM library, performs the appropriate marshaling and passes the interface pointer from the server back to the client.

LresultFromObject increments the object's reference count. If a new object or a new interface to an existing object is created each time WM_GETOBJECT is received, servers must call the object's Release method to decrement the reference count back to one. Doing so allows the object to destroy itself when the client calls Release on the object.

The most typical ways in which a server handles WM_GETOBJECT are:

  • Create New Accessible Objects
  • Reuse Existing Pointers to Objects
  • Create New Interfaces to the Same Object

Note In this section as in the rest of the documentation, when a pointer to an IAccessible interface is discussed, this pointer may actually be a pointer to a proxy object that wraps the IAccessible interface. For more information about proxy objects, see Creating Proxy Objects.

For an overview of WM_GETOBJECT, see How WM_GETOBJECT Works.


Create New Accessible Objects

Servers create a new accessible object in response to each WM_GETOBJECT. In the pseudo-code below, CreateNewAccObj is an application-defined function that creates a new accessible object using an internal user interface data structure. Because a new object is created each time WM_GETOBJECT arrives for this object, the object's reference count decrements back to one.

case WM_GETOBJECT:
   if (lParam == OBJID_CLIENT)
   {
      IAccessible *pAcc = CreateNewAccObj(&UI_Data); // Ref count is 1
      LRESULT lAcc = LresultFromObject(pAcc); // Increments ref count
      pAcc->Release(); // Decrement ref count back to 1
      return lAcc;
   }
   break;  // Fall through to DefWindowProc


Reuse Existing Pointers to Objects

Servers respond to WM_GETOBJECT using the same IAccessible interface pointer each time. In the pseudo-code below, m_pAcc is a data member of the application-defined class that implements IAccessible. Because the pointer to the object is reused on subsequent WM_GETOBJECT messages, the object's reference count does not decrement by calling the object's Release method before the object returns. The reference count on this object is decremented by clients when they no longer require access to the object.

Applications store pointers to accessible objects when the life span of the object is the same as the life span of the window that the object is in or the life span of the application. If this is not the case, the reference count of the object adjusts when the object is first created as in the pseudo-code below, and the object is not destroyed until its reference count goes to zero.

case WM_GETOBJECT:
   if (lParam == OBJID_CLIENT && m_pAcc != NULL)
   {
      return LresultFromObject(m_pAcc);
   }
   else if (lParam == OBJID_CLIENT && m_pAcc == NULL)
   {
      // Create the object and adjust its reference count
      m_pAcc = CreateNewAccObj(&UI_Data); // Ref count is 1
      LRESULT lAcc = LresultFromObject(m_pAcc); //Increments ref count
      m_pAcc->Release(); // Decrement ref count back to 1
     return lAcc;
   }
break;  // Fall through to DefWindowProc


Create New Interfaces to the Same Object

Servers respond to WM_GETOBJECT by obtaining a new interface pointer to the same object. In the pseudo-code below, pUIObj is a pointer to an existing user interface object that supports more than one COM interface. Even though an existing object is reused, a new interface pointer is created each time WM_GETOBJECT arrives for the object, so the reference count decrements.

case WM_GETOBJECT:
   if (lParam == OBJID_CLIENT)
   {
      // Get new interface from same object
      IAccessible *pAcc = NULL;
      pUIObj->QueryInterface(IID_IAccessible, &pAcc); //Ref count is 1
      LRESULT lAcc = LresultFromObject(pAcc); // Increments ref count
      pAcc->Release(); // Decrement ref count back to 1
      return lAcc;
   }
   break;  // Fall through to DefWindowProc


Shortcuts for Exposing Custom User Interface Elements

This section describes shortcuts that application developers can use to expose certain kinds of custom user interface elements. The techniques described in this section either simplify the implementation of the IAccessible interface, or provide an alternative to exposing information without implementing IAccessible.

The following topics have more information:

  • Exposing Controls Based on System Controls
  • Exposing Owner-Drawn Menu Items
  • Labeling Owner-Drawn Controls
  • Exposing Owner-Drawn List Box Items
  • Exposing Owner-Drawn Combo Box Items

Additionally, application developers should follow the guidelines in The Microsoft Windows Guidelines for Accessible Software Design to ensure that their applications are accessible. This document is available on the Microsoft Accessibility Web site at www.microsoft.com/enable.


Exposing Controls Based on System Controls

In most cases, Active Accessibility exposes information about superclassed or subclassed controls. Superclassing and subclassing allow an application developer to create a custom control with the basic functionality of a system control, plus enhancements provided by the application. A superclassed control has a different window class name than the system control on which it is based. A subclassed control has the same window class name. For more information about superclassing and subclassing, see the Platform SDK documentation.

Because Active Accessibility exposes information about system-provided controls, unless a superclassed or subclassed control is significantly different from the base control, Active Accessibility exposes the modified control. To determine if the modified control is accessible, application developers should use utilities such as Inspect Objects and Accessible Event Watcher to compare the behavior of the modified control with the base control.

If after using these utilities you determine that the modified control is not accessible, you must treat the control as any other custom control. The control must trigger events, and the application's window procedure responds to the WM_GETOBJECT message by supplying an IAccessible interface that client applications use to obtain information about the control.

CreateStdAccessibleProxy and CreateStdAccessibleObject

If all or most of the IAccessible properties for the modified control are the same as the base control, use CreateStdAccessibleProxy or CreateStdAccessibleObject to simplify the implementation of the control's IAccessible interface.

Both of these functions retrieve an IAccessible interface pointer for the specified system control. The difference in these functions is that CreateStdAccessibleObject uses the window class name obtained from its hwnd parameter whereas CreateStdAccessibleProxy uses the window class name specified in its szClassName parameter. Therefore, if you decide to use these functions, use CreateStdAccessibleProxy to expose information about superclassed controls, and either function with subclassed controls.

After obtaining an IAccessible interface pointer to the system control, use the pointer in your implementation of the IAccessible interface for the modified control. If a property or method for the modified control is the same as the base control, use the IAccessible pointer to return the information provided by the base control. If a property for the modified control is different from the base control, override the base control's property.

In the following example, CAccCustomButton is the application-defined class derived from IAccessible. The member variable m_pAccDefaultButton is a pointer to an IAccessible interface that was retrieved from CreateStdAccessibleObject during the initialization procedure for the control. In this example, the Role property for the custom control is the same as the Role property of the system control, so the Role property of the base control is returned. However, the Description property is different from that of the base control, so this property is overridden.

HRESULT CAccCustomButton::Initialize( HWND hWnd, HINSTANCE hInst )
{
.
.
.
    hr = CreateStdAccessibleObject( m_hWnd,
                                    OBJID_CLIENT,
                                    IID_IAccessible,
                                    (void **) &m__pAccDefaultButton );
.
.
.
}

STDMETHODIMP CAccCustomButton::get_accRole( VARIANT varID )
{
    return m_pAccDefaultButton->get_accRole(varID);
}

STDMETHODIMP CAccCustomButton::get_accDescription( VARIANT varChild,
                                                   BSTR* pszDesc )
{
    TCHAR   szString[256];
    OLECHAR wszString[256];

    LoadString( m_hInst, ID_DESCRIPTION, szString, 256 );
    MultiByteToWideChar( CP_ACP, 0, szString, -1, wszString, 256 );
   *pszDesc = SysAllocString( wszString );
   if ( !pszDesc )
       return S_OK;
   else
       return E_OUTOFMEMORY;
}

For more information about the IAccessible properties and methods of system controls, Appendix A: Supported User Interface Elements Reference.


Exposing Owner-Drawn Menu Items

Application developers can use the MSAAMENUINFO structure to expose the names of owner-drawn menu items. By associating this structure with the owner-drawn menu item data, you do not need to expose the menu items with IAccessible.

When creating an owner-drawn menu, define a class or structure for the owner-drawn menu item data and create instances of this class for each menu item. Pass in a pointer to the item data when adding items to the menu.

To expose the names of the menu items, the MSAAMENUINFO structure must be the first member of the structure that defines the application-specific item data, as the following example shows:

// Application-specific owner-drawn menu info struct. Owner-drawn data
// is a pointer to one of these.
struct MenuEntry
{
    MSAAMENUINFO m_MSAA;       // MSAA info - must be first member
    LPTSTR       m_pName;      // Displayed menu text or NULL for
                               //   separator item
    int          m_CmdID;      // Menu command ID
    int          m_IconIndex;  // Index of icon in bitmap or -1 for
                               //   for separator
};

The MSAAMENUINFO structure cannot be a member in a class that contains virtual functions. When the code is compiled, the first member of the class is always a compiler-generated pointer to a table of the virtual functions. To work around this problem, create an item data structure that contains MSAAMENUINFO as the first member. The second member is a pointer to an instance of the class that defines the owner-drawn data. The following example demonstrates this technique.

// Application-defined class that contains the owner-drawn data and
//  virtual functions that operate on that data.
class MenuEntry
{
    LPTSTR       m_pName;      // Displayed menu text or NULL for
                               //  separator item.
    int          m_CmdID;      // Menu command ID
    int          m_IconIndex;  // Index of icon in bitmap or -1 for
                               //  separator item
    virtual void m_AnimateIcon();
    virtual void m_ChangeIconColor();
}

// Application-defined struct that contains MSAAMENUINFO as first
//  member. Second member points to owner-drawn data.
struct MenuInfo
{
    MSAAMENUINFO m_MSAA;       // MSAA info - must be first member
    MenuEntry *pMenuData;      // Points to the owner-drawn data
}

When adding items to the menu, pass a pointer to an instance of the structure that contains MSAAMENUINFO to expose the names of the menu items.


Labeling Owner-Drawn Controls

Application developers should define a label, also known as caption text, for all owner-drawn controls, even if the label is not visible on the screen.

For example, if you define a label when creating an owner-drawn button in which a graphic is displayed instead of the normal caption text, client applications get the label and use it to identify the control.

For more information about exposing owner-drawn controls and menus, see:

  • Exposing Owner-Drawn Menu Items
  • Exposing Owner-Drawn List Box Items
  • Exposing Owner-Drawn Combo Box Items


Exposing Owner-Drawn List Box Items

Application developers do not need to implement IAccessible to expose the items in an owner-drawn list box that has the style LBS_HASSTRINGS because Active Accessibility exposes the items in list boxes with this style. The items in an owner-drawn list box with the LBS_HASSTRINGS style are displayed as text. However, this style is also used with owner-drawn list boxes that do not display text so that the list box items are exposed by Active Accessibility.

To allow Active Accessibility to expose the items in an owner-drawn list box that does not display text:

  • Use the LBS_HASSTRINGS style when creating the list box.
  • Create a textual counterpart that names or describes each item in the list box.
  • When adding items to the owner-drawn list box, use the LB_ADDSTRING message to add the text that you want Active Accessibility to expose. This text is not displayed, so it is not part of the owner-drawn data. Add the owner-drawn item data using the LB_SETITEMDATA message.

When using the above method, note the following:

  • If you use the LBS_SORT style, the list box is sorted using the supplied strings and not the WM_COMPAREITEM callback procedure.
  • With owner-drawn variable list boxes, created with the style LBS_OWNERDRAWVARIABLE, use a global variable or some other mechanism to keep track of when the itemData member of the MEASUREITEMSTRUCT is valid. The global variable is needed because the system sends the WM_MEASUREITEM message as soon as the string is added but before the item data is attached, and at this point the itemData member is not valid.
  • To change the string for an item in a list box with the LBS_HASSTRINGS style, delete the item with the LB_DELETESTRING message and add the new string with the LB_ADDSTRING message.


Exposing Owner-Drawn Combo Box Items

Application developers do not need to implement IAccessible to expose the items in an owner-drawn combo box that has the style CBS_HASSTRINGS because Active Accessibility exposes the items in combo boxes with this style. The items in an owner-drawn combo box with the CBS_HASSTRINGS style are displayed as text. However, this style is also used with owner-drawn combo boxes that do not display text so that the combo box items are exposed by Active Accessibility.

To allow Active Accessibility to expose the items in an owner-drawn combo box that does not display text:

  • Use the CBS_HASSTRINGS style when creating the combo box.
  • Create a textual counterpart that names or describes each item in the combo box.
  • When adding items to the owner-drawn combo box, use the CB_ADDSTRING message to add the text that you want Active Accessibility to expose. This text is not displayed, so it must not be part of the owner-drawn data. Add the owner-drawn item data using the CB_SETITEMDATA message.

When using the above method, note the following:

  • If you use the CBS_SORT style, the combo box is sorted using the supplied strings and not the WM_COMPAREITEM callback procedure.
  • With owner-drawn variable combo boxes created with the style CBS_OWNERDRAWVARIABLE, use a global variable or some other mechanism to keep track of when the itemData member of the MEASUREITEMSTRUCT is valid. The global variable is required because system sends the WM_MEASUREITEM message as soon as the string is added but before the item data is attached, and at this point the itemData member is not valid.
  • To change the string for an item in a combo box with the CBS_HASSTRINGS style, delete the item with the CB_DELETESTRING message and add the new string with the CB_ADDSTRING message.


Sample Programs and Testing Tools

The Microsoft Active Accessibility SDK provides several utilities that can be used by both clients and servers use as testing tools. The source code for most of these testing tools is also provided in the SDK. The code for the testing tools and the other sample programs in the SDK demonstrate the use of IAccessible interface and Active Accessibility APIs.

All of the samples are written in C++ except for the VBInsp sample, and they are built using Microsoft Visual C++ version 4.0 or greater. Each sample comes with the project and workspace files that you can use with Visual C++. To build the samples with another C++ compiler, each sample comes with a makefile (with the .mak extension).

Before compiling the samples, configure Visual C++ to search the \inc32 and \lib directories that the Active Accessibility SDK setup program created. If you accepted the default folder during setup, these directories are located in C:\Program Files\Microsoft Active Accessibility SDK\Dev. In addition to the Dev directory, the setup program creates a Samples directory with subdirectories that contain the source code for the samples and testing tools.

If there are additional steps that need to be performed to build the sample, a ReadMe.txt file is included in that sample's folder.

The following sample programs and testing tools are included in the Active Accessibility SDK:

  • Accessible Event Watcher
  • Accessible Explorer
  • Babble
  • Inspect Objects
  • Magnifier
  • MSAA Verification Tool
  • VBInsp


Accessible Event Watcher

The Accessible Event Watcher program logs WinEvents as they occur within the system. From the program's Option menu, choose the Settings item to display a dialog box in which you can specify the kind of object and which WinEvents to watch.

The source code for Accessible Event Watcher is provided in the AccEvent directory.


Accessible Explorer

The Accessible Explorer program allows you to examine the IAccessible properties of objects and how objects are related to each other.

When you first start Accessible Explorer, the display area is empty. To examine the objects in a window, from the Tree menu, choose the Refresh item to specify the window to explore. Accessible Explorer displays the window's objects in a hierarchical fashion. When you click on an object in the tree view, the object's properties are displayed.

You can examine how objects are related to each other by expanding and collapsing the objects in the tree view. The Tree menu also provides menu items to manage the hierarchy. Additionally, the Navigation menu provides many ways to navigate to other objects.

The numerous options and features of Accessible Explorer are documented in the ReadMe file that are viewed from the Help menu.

The source code for Accessible Explorer is not provided with the Active Accessibility SDK.


Babble

Babble is a sample Active Accessibility client utility that uses the Microsoft Speech API (SAPI) to vocalize the properties of an object. Babble requires a SAPI-compliant speech engine, which is not provided as part of the Microsoft Active Accessibility SDK.

To build the Babble project, you must have the SAPI SDK installed on your machine. Additionally, define the environment variable SPEECHDK to point to the SAPI SDK installation. If you do not have the SAPI SDK installed on your machine, you can download it from www.microsoft.com/iit.

For more information about the Babble sample, see Active Accessibility Client Tutorial.

The source code for the Babble utility is provided in the Babble directory.


Inspect Objects

The Inspect Objects program allows you to examine the IAccessible properties of the object at the current mouse location and to navigate to other objects.

The Inspect Objects System menu is expanded to provide many options and features. Many of the menu items on the System menu are invoked with a keyboard shortcut even when Inspect Objects is not the active application. Note however, that the shortcut keys conflict with some applications.

The following are keyboard shortcut keys used to activate the various options on the System menu:

Key Combination | Menu Item | Action
CTRL+SHIFT+F2 | Do Default Action | Invokes the default action of the object under the cursor.
CTRL+SHIFT+F3 | Select | Selects the object under the cursor.
CTRL+SHIFT+F4 | Focus | Sets the keyboard focus to the object under the cursor.
CTRL+SHIFT+F5 | Simple Previous | Moves the cursor to the previous sibling object from the one under the cursor. This command navigates to objects only within a container.
CTRL+SHIFT+F6 | Move to Parent | Moves the cursor to the object's parent.
CTRL+SHIFT+F7 | Move to 1st Child | Moves the cursor to the first child of the current object.
CTRL+SHIFT+F8 | Simple Next | Moves the cursor to the next sibling object from the one under the cursor. This command navigates to objects only within a container.
CTRL+SHIFT+F9 | Move to Last Child | Moves to the last child of the current object.
CTRL+SHIFT+F11 | Move to Previous | Moves the cursor to the previous object from the one under the cursor. This command navigates the object hierarchy.
CTRL+SHIFT+F12 | Move to Next | Moves the cursor to the next object from the one under the cursor. This command navigates the object hierarchy.
CTRL+SHIFT+1 | Voice Verbosity | Changes the TTS voice verbosity setting.
CTRL+SHIFT+7 | Move Left | Moves the cursor to the sibling object to the left of the one the cursor is over.
CTRL+SHIFT+8 | Move Up | Moves the cursor to the sibling object above the object the cursor is over.
CTRL+SHIFT+0 | Move Right | Moves the cursor to the sibling object to the right of the one the cursor is over.
CTRL+SHIFT+9 | Move Down | Moves the cursor to the sibling object below the one the cursor is over.

Other options for this sample application are also 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 Objects to refresh its properties in about one second.

Note that Inspect Objects always starts navigation using the current cursor location.

You can start Inspect Objects with one of the following command-line options to have it use the Speech API (SAPI) or a speech synthesizer to vocalize the displayed properties.

Option | Description
s | Use SAPI
a1 | Use Accent SA on COM1
a2 | Use Accent SA on COM2
d1 | Use DECtalk on COM1
d2 | Use DECtalk on COM2

If Inspect Objects is using SAPI to vocalize the properties, you can control the verbosity (loudness) setting by pressing CTRL-SHIFT-1 to cycle through the following three states:

  • On/Low
  • On/High
  • Mute

The source code for Inspect Objects is provided in the Inspect directory.


Magnifier

Magnifier is a screen enlarger utility that enables a user to magnify the contents of the computer screen.

Magnifier provides a floating window that enlarges a portion of the computer screen. Magnifier tracks the mouse location and keyboard focus so the active area is automatically enlarged.

Magnifier causes the mouse pointer to flash if any mouse pointer scheme other than Windows Standard is used. This problem also happens on Windows Standard (large) and Windows Standard (extra-large).

The source code for Magnifier is not provided with the Active Accessibility SDK.


MSAA Verification Tool

The MSAA Verification Tool allows you to examine the IAccessible properties of objects and how objects are related to each other.

When you first start the MSAA Verification Tool, it displays a dialog box from which to choose a window to examine. After selecting a window, the program displays the window's objects and properties in a hierarchical fashion.

The source code for the MSAA Verification Tool is provided in the MSAAVeri directory.


VBInsp

The VBInsp sample program is written using Microsoft Visual Basic® version 4.0. VBInsp allows you to examine the IAccessible properties of the object at the current mouse location.

The VBInsp sample code incorporates a timer control that it uses to determine the time increments between each query for accessible information. On every timer tick, the code queries the object under the pointer and displays the results in a Visual Basic form.

The source code for VBInsp is provided in the VBInsp directory.


Active Accessibility C/C++ Reference

The following topics are covered in this reference:

  • IAccessible
  • Active Accessibility Client Functions
  • Active Accessibility Server Functions
  • Structures and Data Types
  • WM_GETOBJECT Window Message
  • Constants and Enumerated Types
  • Return Values


IAccessible

The IAccessible interface is the heart of Microsoft® Active Accessibility®. Server. Applications implement this Component Object Model (COM) interface to represent their custom user interface elements, which includes their client area if necessary, as accessible objects. Client applications call the IAccessible methods and properties to obtain information about an application's user interface and data.

The documentation for the IAccessible interface uses the standard COM parameter attributes [in], [out], [in/out], and [out, retval], which identify the direction of the flow of information to and from a function and specify whether the caller or callee is responsible for allocating memory. If you are unfamiliar with these attributes, see Definitions of Parameter Attributes before reading about the IAccessible interface.

As with any COM interface, the system file initguid.h is included in any source code that requires Active Accessibility.

For more information on the IAccessible interface, see the following:

  • Definitions of Parameter Attributes
  • IAccessible Interface Quick Reference
  • IAccessible::accDoDefaultAction
  • IAccessible::accHitTest
  • IAccessible::accLocation
  • IAccessible::accNavigate
  • IAccessible::accSelect
  • IAccessible::get_accChild
  • IAccessible::get_accChildCount
  • IAccessible::get_accDefaultAction
  • IAccessible::get_accDescription
  • IAccessible::get_accFocus
  • IAccessible::get_accHelp
  • IAccessible::get_accHelpTopic
  • IAccessible::get_accKeyboardShortcut
  • IAccessible::get_accName
  • IAccessible::get_accParent
  • IAccessible::get_accRole
  • IAccessible::get_accSelection
  • IAccessible::get_accState
  • IAccessible::get_accValue

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.


Definitions of Parameter Attributes

The standard COM parameter attributes [in], [out], [in/out], and [out, retval] not only identify the direction of the flow of information to and from a function, they also specify whether the caller or callee is responsible for allocating and freeing memory.

You allocate and free memory using standard COM memory functions, such as SysAllocString and SysFreeString.

The parameter attributes are defined as follows:

[in]
Input data for a function, allocated and freed by the caller using whatever memory management the caller wants. An [in] parameter is not modified by the called function.
[out]
Output data from a function, allocated by the function and freed by the caller.
[in/out]
Input data for the function, modified and returned to the caller as output data. Initially allocated by the caller, an [in/out] parameter may be freed and reallocated by the function if necessary. Ultimately, it is the caller's responsibility to free the memory.
[out, retval]
The [retval] attribute designates the parameter that receives the return value of the member function. This attribute is used on parameters of interface members that describe methods or get properties. The [retval] attribute applies only to the last parameter of a member function, and the parameter is a pointer type.


IAccessible Interface Quick Reference

The IAccessible interface methods and properties are organized into the following groups:

Navigation and Hierarchy

accHitTest ( long, long, VARIANT* );

accLocation ( long*, long*, long* long*, VARIANT);

accNavigate ( long, VARIANT, VARIANT* );

get_accChild ( VARIANT, IDispatch** );

get_accChildCount ( long* );

get_accParent ( IDispatch** );

Descriptive Properties and Methods

accDoDefaultAction ( VARIANT );

get_accDefaultAction ( VARIANT, BSTR* );

get_accDescription ( VARIANT, BSTR* );

get_accHelp ( VARIANT, BSTR* );

get_accHelpTopic ( BSTR*, VARIANT, long* );

get_accKeyboardShortcut ( VARIANT, BSTR* );

get_accName ( VARIANT, BSTR* );

get_accRole ( VARIANT, VARIANT* );

get_accState ( VARIANT, VARIANT* );

get_accValue ( VARIANT, BSTR* );

Selection and Focus

accSelect ( long, VARIANT );

get_accFocus ( VARIANT* );

get_accSelection ( VARIANT * );


IAccessible::accDoDefaultAction

The IAccessible::accDoDefaultAction method performs the specified object's default action. Not all objects have a default action.

HRESULT accDoDefaultAction(
  VARIANT varID
);

Parameters

varID
[in] Specifies whether the default action is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to perform the object's default action) or a child ID (to perform the default action of one of the object's child elements). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code.

Error | Description
DISP_E_MEMBERNOTFOUND | The object does not support the method. This value is returned for controls that do not perform actions, such as edit fields.
E_INVALIDARG | An argument is invalid.

Remarks

Clients retrieve the object's default action by calling IAccessible::get_accDefaultAction.

A client uses Automation, if supported, instead of accDoDefaultAction to perform an object's default action. However, accDoDefaultAction provides an easy way to perform an object's most commonly used action.

Note to client developers The default action performed by system-provided user interface elements depends on the keyboard state. That is, if a modifier key such as SHIFT, ALT, or CTRL is down, either by a user action or programmatically, when accDoDefaultAction is called, the default action is not the same as when those keys are not down. For example, in a list view that contains multiple folders that have been selected, if a user double-clicks a folder, only that folder opens. However, if the user holds down the SHIFT key and double-clicks a folder, all the selected folders open. The same behavior happens if the SHIFT key is down when you call accDoDefaultAction on a folder in a list view control.

When used on a menu item, accDoDefaultAction returns S_OK but fails to perform the action if the character used in the access key (the underlined character in the text of a menu item name, also called a mnemonic) is ?, !, @, or any other character that requires the SHIFT key or another modifier key. This also happens on international keyboards with an access key character that requires the ALT GR key pressed. For more information about access keys, see IAccessible::get_accKeyboardShortcut.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accDefaultAction, IAccessible::get_accKeyboardShortcut, VARIANT Structure, Appendix A: Supported User Interface Elements Reference, DefaultAction Property


IAccessible::accHitTest

The IAccessible::accHitTest method retrieves the child element or child object at a given point on the screen. All visual objects support this method; sound objects do not support it.

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

Parameters

xLeft and yTop
[in] Specifies the screen coordinates of the point hit tested. When using screen coordinates, the origin is the upper-left corner of the screen. The x coordinates increase from left to right; y coordinates increase from top to bottom.
pvarID
[out, retval] Address of a VARIANT structure that receives information that identifies the object at the point specified by xLeft and yTop,. The information returned in pVarID depends on the location of the specified point in relation to the object whose accHitTest method is being called.
Point location | vt member | Value member
Outside the object's boundaries and either inside or outside of the object's bounding rectangle. | VT_EMPTY | None.
Within the object but not within a child element or a child object. | VT_I4 | lVal is CHILDID_SELF.
Within a child element. | VT_I4 | lVal contains the child ID.
Within a child object. | VT_DISPATCH | pdispVal is set to the child object's IDispatch interface pointer.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The point is outside the object's boundaries. The vt member of pvarID is VT_EMPTY.
DISP_E_MEMBERNOTFOUND | The object does not support this method.
E_INVALIDARG | An argument is invalid.

Note to client developers Although servers return S_FALSE if the vt member of pvarID is VT_EMPTY, clients must also handle the case where pVarID->vt is VT_EMPTY and the return value is S_OK.

Remarks

If the tested point is on one of the object's children, and this child supports the IAccessible interface itself, this method must return the IDispatch interface for the child object and not a child ID.

For non-rectangular objects, such as list view items, the coordinates of the object's bounding rectangle retrieved by IAccessible::accLocation fails if tested with accHitTest because accHitTest determines the object's boundaries on a pixel-by-pixel basis.

When this method is used in certain situations, additional usage notes apply. For more information, see Navigation Through Hit Testing and Screen Location.

Clients must call IUnknown::Release to release the IDispatch interface when finished using it. Failure to do so keeps the object in memory, even though it is not used.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT Structure, IDispatch Interface, IAccessible::accLocation , Navigation Through Hit Testing and Screen Location


IAccessible::accLocation

The IAccessible::accLocation method retrieves the specified object's current screen location. All visual objects must support this method; sound objects do not support it.

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

Parameters

pxLeft and pyTop
[out] Address of the variables that receive the x and y coordinates of the upper-left boundary of the object's location, in screen coordinates. When using screen coordinates, the origin is the upper-left corner of the screen. The x coordinates increase from left to right; y coordinates increase from top to bottom.
pcxWidth and pcyHeight
[out] Address of the variables that receive the object's width and height, in pixels.
varID
[in] Specifies whether the location retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.

Return Values

If successful, returns S_OK. If not successful, returns the following value or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
DISP_E_MEMBERNOTFOUND | The object does not support this method.
E_INVALIDARG | An argument is invalid.

Remarks

This method retrieves the object's bounding rectangle. If the object has a non-rectangular shape, then this method returns the smallest rectangle that completely encompasses the entire object region. For non-rectangular objects such as list view items, the coordinates of the object's bounding rectangle fails if tested with IAccessible::accHitTest because IAccessible::accHitTest determines the object's boundaries on a pixel-by-pixel basis. For more information, see Navigation Through Hit Testing and Screen Location.

The Inspect Objects testing tool that comes with the Active Accessibility SDK displays an object's location as a rectangle: xLeft, yTop, xRight, yBottom. After Inspect Objects calls accLocation, it adds pcxWidth to pxLeft and pcxHeight to pyTop and then displays the location.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT structure, IAccessible::accHitTest, Navigation Through Hit Testing and Screen Location


IAccessible::accNavigate

The IAccessible::accNavigate method traverses to another user interface element within a container and retrieves the object. All visual objects must support this method.

HRESULT accNavigate(
  long navDir,
  VARIANT varStart,
  VARIANT *pvarEnd
);

Parameters

navDir
[in] Specifies the direction to navigate. This direction is in spatial order, such as left or right, or logical order, such as next or previous. This value is one of the navigation constants.
varStart
[in] Specifies whether the starting object of the navigation is the object itself or one of the object's children. This parameter is either CHILDID_SELF (to start from the object) or a child ID (to start from one of the object's children). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pvarEnd
[out, retval] Address of a VARIANT structure that receives information about the destination user interface (UI) element. The following describes the information returned in pvarEnd.
vt member | Value member
VT_EMPTY | None. There wasn't a UI element in the specified direction.
VT_I4 | lVal contains the child ID of the UI element.
VT_DISPATCH | pdispVal contains the address of the UI element's IDispatch interface.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | No screen element was found in the specified direction.
DISP_E_MEMBERNOTFOUND | The object does not support this method.
E_INVALIDARG | An argument is invalid.

Remarks

Clients must call IUnknown::Release to release the IDispatch interface when finished. Failure to do so keeps the object in memory, even though it is not used.

Navigation, both spatial and logical, is always restricted to the user interface elements within a container. With spatial navigation, clients navigate only to a sibling of the starting object (varStart). Depending on the navigational flag used with logical navigation, clients navigate to either a child or to a sibling of the starting object.

The accNavigate method retrieves only user interface elements that have a defined screen location.

This method does not change the selection or focus. To change the focus or to select an object, use IAccessible::accSelect.

To prevent looping when traversing screen elements using NAVDIR_NEXT and NAVDIR_PREVIOUS, accNavigate returns S_FALSE after the last or first object is found, respectively.

If an object has the state STATE_SYSTEM_INVISIBLE, navigation to this hidden object fails. Some system-defined UI elements such as menus, menu items, and pop-up menus allow navigation to invisible objects. However, other system-defined UI elements do not support this. Servers support navigating to invisible objects, but this support is not required and clients do not expect it.

If navigating from an accessible object to a sibling user interface element, the result in pvarEnd is either a child ID or an IDispatch interface. For example, the lVal member of varStart is CHILDID_SELF and the specified flag in navDir is any navigation flag except NAVDIR_FIRSTCHILD or NAVDIR_LASTCHILD. If pvarEnd contains a child ID, to navigate from this user interface element or to obtain more information about it, clients must first obtain a pointer to the parent's IAccessible interface. To obtain the parent object, clients call the IAccessible::get_accParent property of the sibling object, that is, the starting object of the navigation.

If a user interface element has both a child ID and supports the IAccessible interface, servers should return an IDispatch interface. However, if a child ID is returned, clients should determine whether the child is an accessible object or a simple element that is exposed through the parent object. To make this determination, clients must obtain a pointer to the parent's IAccessible interface and call the parent object's IAccessible::get_accChild.

For more information, see Object Navigation Properties and Methods.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT Structure, IDispatch Interface, IAccessible::accSelect, Object Navigation Properties and Methods


IAccessible::accSelect

The IAccessible::accSelect method modifies the selection or moves the keyboard focus of the specified object. All objects that select or receive the keyboard focus must support this method.

HRESULT accSelect(
  long flagsSelect,
  VARIANT varID
);

Parameters

flagsSelect
[in] Specifies how to change the current selection or focus. This parameter must have a combination of the values from the SELFLAG enumerated type.
varID
[in] Specifies the selected object. This parameter is either CHILDID_SELF (to select the object itself) or a child ID (to select one of the object's children). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code.

Error |  | Description
S_FALSE | The specified object is not selected.
E_INVALIDARG | An argument is invalid. This return value means that the specified SELFLAG combination is invalid, or that the SELFLAG value does not make sense for the specified object. For example, the flags SELFLAG_EXTENDSELECTION, SELFLAG_ADDSELECTION, and SELFLAG_REMOVESELECTION are not allowed on a single-selection list box.
DISP_E_MEMBERNOTFOUND | The object does not support this method.

Remarks

Applications use this method to perform complex selection operations. For more information, see Selecting Child Objects.

Note to client developers Active Accessibility does not support the selection of text contained in edit and rich edit controls because the text is exposed as a string in the object's Value property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

SELFLAG, VARIANT Structure, Selection and Focus Properties and Methods, IAccessible::get_accFocus, IAccessible::get_accSelection


IAccessible::get_accChild

The IAccessible::get_accChild method retrieves the address of an IDispatch interface for the specified child. All objects must support this property.

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

Parameters

varChildID
[in] Identifies the child whose IDispatch interface is retrieved. For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
ppdispChild
[out, retval] Receives the address of the child object's IDispatch interface.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | Indicates that the child is not an accessible object.
E_INVALIDARG | An argument is invalid.

Remarks

Clients must call IUnknown::Release to release the IDispatch interface when finished using it. Failure to do so keeps the object in memory even though it is not being used.

If get_accChild fails because the application cannot create an accessible object for the specified child, the parent must take responsibility for exposing the child's properties.

Note to server developers If varChildID contains VT_EMPTY, then E_INVALIDARG is returned.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accParent, AccessibleChildren, VARIANT Structure, IDispatch Interface, Object Navigation Properties and Methods


IAccessible::get_accChildCount

The IAccessible::get_accChildCount method retrieves the number of children that belong to this object. All objects must support this property.

HRESULT get_accChildCount(
  long* pcountChildren
);

Parameters

pcountChildren
[out, retval] Address of a variable that receives the number of children that belong to this object. The children are accessible objects or child elements. If the object has no children, this value is zero.

Return Values

If successful, returns S_OK. If not successful, returns a standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Remarks

The number of children in an object changes. To keep track of changes to the child count, an application watches for EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY events generated by this object.

Note to server developers If the object does not have any children, return S_OK and set pcountChildren to zero.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accParent, IAccessible::get_accChild, AccessibleChildren


IAccessible::get_accDefaultAction

The IAccessible::get_accDefaultAction method retrieves a string that describes the object's default action. Not all objects have a default action.

HRESULT get_accDefaultAction(
  VARIANT varID,
  BSTR* pszDefaultAction
);

Parameters

varID
[in] Specifies whether the default action retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszDefaultAction
[out, retval] Address of a BSTR that receives a localized string that describes the default action for the specified object, or NULL if this object has no default action.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The specified object does not have a default action.
E_INVALIDARG | An argument is invalid.
DISP_E_MEMBERNOTFOUND | The specified object does not support this property.

Remarks

The retrieved string describes the action that is performed on an object, not what the object does as a result. For example, a toolbar button that prints a document has a default action of "Press" rather than "Prints the current document."

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 server developers Localize the string returned from this property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::accDoDefaultAction, VARIANT Structure, DefaultAction Property.


IAccessible::get_accDescription

The IAccessible::get_accDescription method retrieves a string that describes the visual appearance of the specified object. Not all objects have a description.

HRESULT get_accDescription(
  VARIANT varID,
  BSTR* pszDescription
);

Parameters

varID
[in] Specifies whether the description retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszDescription
[out, retval] Address of a BSTR that receives a localized string that describes the specified object, or NULL if no description is available for this object.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The specified object does not have a description.
E_INVALIDARG | An argument is invalid.
DISP_E_MEMBERNOTFOUND | The specified object does not support this property.

Remarks

This property describes the object's visual appearance to the user. The description should be similar to the text supplied with the ALT attribute in HTML, which is the text that is displayed to describe images for people using text-only browsers. For more information about this property, see Description Property.

Note to server developers Localize the string returned from this property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accName, IAccessible::get_accHelp, IAccessible::get_accValue, Description Property


IAccessible::get_accFocus

The IAccessible::get_accFocus method retrieves the object that has the keyboard focus. All objects that receive the keyboard focus must support this property.

HRESULT get_accFocus(
  VARIANT *pvarID
);

Parameters

pvarID
[out, retval] Address of a VARIANT structure that receives information about the object that has the focus. The following describes the information returned in pvarID.
vt member | Value member
VT_EMPTY | None. This object does not have the keyboard focus itself and does not contain a child that has the keyboard focus.
VT_I4 | lVal is CHILDID_SELF. The object itself has the keyboard focus.
VT_I4 | lVal contains the child ID of the child element with the keyboard focus.
VT_DISPATCH | pdispVal member is the address of the IDispatch interface for the child object with the keyboard focus.

Return Values

If successful, returns S_OK. If not successful, returns one of the following value or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The window that contain this object is not the active window.
DISP_E_MEMBERNOTFOUND | The object does not support this property.

Remarks

The concept of keyboard focus is related to that of an active window. An active window is the foreground window on which the user works. The object with the keyboard focus is either the active window or a child object of the active window.

Only one object or item within a container has the focus at any one time. The object with the keyboard focus is not always the selected object. For more information about the difference between selection and focus, see Selection and Focus Properties and Methods.

If a user interface element has both a child ID and supports the IAccessible interface, servers return an IDispatch interface. However, if a child ID is returned, clients determine whether the child is an accessible object or a simple element that is exposed through the parent object. To make this determination, clients must call the parent object's IAccessible::get_accChild and pass it the child ID.

Clients must call IUnknown::Release to release the IDispatch interface when finished using it. Failure to do so keeps the object in memory, even though it is not used.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accSelection, IAccessible::accSelect, IDispatch Interface, Selection and Focus Properties and Methods


IAccessible::get_accHelp

The IAccessible::get_accHelp method retrieves an object's Help property string. Not all objects support this property.

HRESULT get_accHelp(
  VARIANT varID,
  BSTR *pszHelp
);

Parameters

varID
[in] Specifies whether the help information retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about one of the object's child elements). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszHelp
[out, retval] Address of a BSTR that receives the localized string that contain the help information for the specified object, or NULL if no help information is available.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | No help information is available.
E_INVALIDARG | An argument is invalid.
DISP_E_MEMBERNOTFOUND | The object does not support this property.

Remarks

None of the predefined and common controls support this property.

Note to server developers The information in this property should be similar to the help provided in ToolTips (balloon-style help). Use this property to provide a description of what the object does, or how to use it, as opposed to IAccessible::get_accDescription, which describes an object's appearance.

This property returns a string, whereas IAccessible::get_accHelpTopic provides access to a Help topic in WinHelp. Objects are not required to support both IAccessible::get_accHelp and IAccessible::get_accHelpTopic, but they must support at least one. If they easily return a string they must support IAccessible::get_accHelp, otherwise they must support IAccessible::get_accHelpTopic. If both are supported, IAccessible::get_accHelpTopic provides more detailed information.

Localize the string returned from this property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT Structure, IAccessible::get_accDescription, IAccessible::get_accHelpTopic, Help Property


IAccessible::get_accHelpTopic

The IAccessible::get_accHelpTopic method retrieves the full path of the WinHelp file associated with the specified object and the identifier of the appropriate topic within that file. Not all objects support this property.

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

Parameters

pszHelpFile
[out] Address of a BSTR that receives the full path of the WinHelp file associated with the specified object.
varChild
[in] Specifies whether the Help topic retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain a Help topic for the object) or a child ID (to obtain a Help topic for one of the object's child elements). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pidTopic
[out, retval] Address of a variable that identifies the Help file topic associated with the specified object. This value is used as the context identifier of the desired topic that passes to the Microsoft Win32 function WinHelp. When calling WinHelp to display the topic, set the uCommand parameter to HELP_CONTEXT, and cast the value pointed to by pidTopic to a DWORD and pass it as the dwData parameter.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | No Help information is available.
E_INVALIDARG | An argument is invalid.
DISP_E_MEMBERNOTFOUND | The object does not support this property.

Remarks

Getting information from a Help file might be expensive in terms of time and memory.

Note to server developers This property provides access to a Help topic in WinHelp, whereas IAccessible::get_accHelp returns a string. Objects are not required to support both IAccessible::get_accHelp and IAccessible::get_accHelpTopic, but they must support at least one. If they can easily return a string they must support IAccessible::get_accHelp, otherwise they must support IAccessible::get_accHelpTopic. If both are supported, IAccessible::get_accHelpTopic provides more detailed information.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accHelp, HelpTopic Property


IAccessible::get_accKeyboardShortcut

The IAccessible::get_accKeyboardShortcut method retrieves the specified object's shortcut key or access key, also known as the mnemonic. All objects that have a shortcut key or access key support this property.

HRESULT get_accKeyboardShortcut(
  VARIANT varID,
  BSTR *pszKeyboardShortcut
);

Parameters

varID
[in] Specifies whether the keyboard shortcut retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszKeyboardShortcut
[out, retval] Address of a BSTR that receives a localized string that identifies the keyboard shortcut, or NULL if no keyboard shortcut is associated with the specified object.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The object does not have an associated keyboard shortcut.
E_INVALIDARG | An argument is invalid.
DISP_E_MEMBERNOTFOUND | The object does not support this property.

Remarks

An access key is an underlined character in the text of a menu, menu item, or the label of a button, or some other control. For example, a user can display a menu by pressing the ALT key while also pressing the indicated underlined key, such as ALT+F to open the File menu. To use the access key of a menu item, the menu that contains the item must be active.

Controls such as toolbar buttons and menu items often have an associated shortcut key, also known as a keyboard accelerator. A menu item has both an access key and a shortcut key associated with it. For example, a menu item called New has an access key N and a shortcut key CTRL+N. The menu does not have to be active for the shortcut key to work.

Note to client developers If this property returns a single character, assume it is an access key. With standard menu items, the access key is returned by IAccessible::get_accKeyboardShortcut, and the shortcut key is returned as part of the menu item name returned from IAccessible::get_accName.

Note to server developers The access key should be exposed as ALT+<letter>.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT Structure, IAccessible::get_accName , KeyboardShortcut Property


IAccessible::get_accName

The IAccessible::get_accName retrieves the name of the specified object. All objects support this property.

HRESULT get_accName(
  VARIANT varID,
  BSTR* pszName
);

Parameters

varID
[in] Specifies whether the name retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszName
[out, retval] Address of a BSTR that receives a string that contains the specified object's name.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | The specified object does not have a name.
E_INVALIDARG | An argument is invalid.

Remarks

The name of an object must be unique within the container. Many objects such as icons, menus, check boxes, combo boxes, and other controls have labels that are displayed to users. Any label that is displayed to users are used for the object's name property. For more information, see the Name Property.

Note to server developers If you are using menu or button text for the name property, strip out any ampersands (&) marking the keyboard access keys. Provide the access key to the client in response to IAccessible::get_accKeyboardShortcut.

Localize the string returned from this property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accKeyboardShortcut, VARIANT Structure, Name Property


IAccessible::get_accParent

The IAccessible::get_accParent method retrieves the IDispatch interface of the object's parent. All objects support this property.

HRESULT get_accParent(
  IDispatch** ppdispParent
);

Parameters

ppdispParent
[out, retval] Receives the address of the parent object's IDispatch interface. The variable is set to NULL if no parent exists, or if the child cannot access its parent.

Return Values

If successful, returns S_OK. If not successful, returns the following value or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | No parent exists for this object.

Remarks

Clients must call IUnknown::Release to release the IDispatch interface when finished. Failure to do so keeps the object in memory even though it is not used.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::get_accChild, Object Navigation Properties and Methods, IDispatch Interface


IAccessible::get_accRole

The IAccessible::get_accRole method retrieves information that describes the role of the specified object. All objects support this property.

HRESULT get_accRole(
  VARIANT varID,
  VARIANT *pvarRole
);

Parameters

varID
[in] Specifies whether the role information retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pvarRole
[out, retval] Address of a VARIANT structure that receives an object role constant. The following table describes the information returned in pvarRole.
vt member | Value member
VT_I4 | The lVal member contains an object role constant.
VT_EMPTY | The object does not have an assigned role.

Return Values

If successful, returns S_OK. If not successful, returns the following value or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
E_INVALIDARG | An argument is invalid.

Remarks

Clients call GetRoleText to retrieve a localized string that describes the object's role.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

VARIANT Structure, GetRoleText, Role Property


IAccessible::get_accSelection

The IAccessible::get_accSelection method retrieves the selected children of this object. All objects selected mustsupport this property.

HRESULT get_accSelection(
  VARIANT *pvarChildren
);

Parameters

pvarChildren
[out, retval] Address of a VARIANT structure that receives information about which children are selected. The following table describes the information returned in pvarChildren.
vt member | Value member
VT_EMPTY | No children are selected.
VT_DISPATCH | One child object is selected, and the address of its IDispatch interface is set in the pdispVal member.
VT_I4 | lVal contains the child ID of the child element that is selected. If lVal is CHILDID_SELF, then the object itself is selected.
VT_UNKNOWN | Multiple child objects are selected and the punkVal member contains the address of the IUnknown interface. The client queries this interface for the IEnumVARIANT interface, which it uses to enumerate the selected objects.

Return Values

If successful, returns S_OK. If not successful, returns the following value or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
S_FALSE | Neither the object nor any of its children are selected.
DISP_E_MEMBERNOTFOUND | The object does not support this property.

Remarks

This property must support the IEnumVARIANT interface.

If a user interface element has both a child ID and supports the IAccessible interface, servers return an IDispatch interface. However, if a child ID is returned, clients determine whether the child is an accessible object or a simple element that is exposed through the parent object. If the child ID is CHILD_SELF, it is a full IAccessible object. If the child ID is less than zero, the element is exposed through its parent. Clients must call the parent object's IAccessible::get_accChild and pass it the child ID.

Clients must call IUnknown::Release to release the IDispatch interface when finished. Failure to do so keeps the object in memory even though it is not used.

Note to clients Active Accessibility does not expose the text selection in edit and rich edit controls.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible::accSelect, IAccessible::get_accFocus, VARIANT Structure, IDispatch Interface, Selection and Focus Properties and Methods


IAccessible::get_accState

The IAccessible::get_accState method retrieves the current state of the specified object. All objects support this property.

HRESULT get_accState(
  VARIANT varID,
  VARIANT *pvarState
);

Parameters

varID
[in] Specifies whether the state information retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pvarState
[out, retval] Address of a VARIANT structure that receives information that describes the object's state. The vt member is VT_I4 and the lVal member is one or more of the object state constants.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
E_INVALIDARG | An argument is invalid.

Remarks

If predefined state values are returned, clients call GetStateText to retrieve a localized string that describes the object's state.

Note to server developers When possible, use the predefined state values; otherwise, localize the string returned from this property.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

GetStateText, State Property, VARIANT Structure, Object State Constants


IAccessible::get_accValue

The IAccessible::get_accValue method retrieves the value of the specified object. Not all objects have a value.

HRESULT get_accValue(
  VARIANT varID,
  BSTR* pszValue
);

Parameters

varID
[in] Specifies whether the value information retrieved is that of the object or one of the object's child elements. This parameter is either CHILDID_SELF (to obtain information about the object) or a child ID (to obtain information about the object's child element). For more information about initializing the VARIANT structure, see How Child IDs Are Used in Parameters.
pszValue
[out, retval] Address of the BSTR that receives a localized string that contains the object's current value.

Return Values

If successful, returns S_OK. If not successful, returns one of the following values or another standard COM error code. Although servers return these values, clients must always check output parameters to ensure that they contain valid values. For more information, see Checking IAccessible Return Values.

Error | Description
DISP_E_MEMBERNOTFOUND | The object does not support this property.
E_INVALIDARG | An argument is invalid.

Remarks

The values returned from scroll bar and trackbar accessible objects indicate percentages, so they are integers between zero (0) and one hundred (100), inclusive.

Note to server developers Localize the string returned from this property.

When implementing trackbar controls, use the trackbar style TBS_REVERSED to provide more meaningful information. This style reverses the scale used by IAccessible::get_accValue.

For vertical trackbars without this style, IAccessible::get_accValue returns zero (0) when the trackbar thumb is at the top of the control, and the values increase as you slide the thumb towards the bottom. With the TBS_REVERSED style, IAccessible::get_accValue returns one hundred (100) when the trackbar thumb is at the top, and the numbers decrease as you move the trackbar thumb towards the bottom.

For horizontal trackbars without this style, zero (0) is returned when the trackbar thumb is at the left end of the control, and the values increase as you move the trackbar thumb to the right. With the TBS_REVERSED style, IAccessible::get_accValue returns one hundred (100) when the trackbar thumb is at the left, and the values decrease as you move the trackbar thumb to the right.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

Value Property


IAccessible::put_accName

The IAccessible::put_accName method is no longer supported. The SetWindow Text or control-specific APIs are used in place of this method.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.


IAccessible::put_accValue

The IAccessible::put_accValue method is no longer supported. Control-specific APIs are used in place of this method.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.


Active Accessibility Client Functions

Clients call the following functions to obtain pointers to accessible objects.

  • AccessibleObjectFromEvent
  • AccessibleObjectFromWindow
  • AccessibleObjectFromPoint
  • AccessibleChildren

The following functions are also provided for clients:

  • GetOleaccVersionInfo
  • GetRoleText
  • GetStateText
  • SetWinEventHook
  • UnhookWinEvent
  • WindowFromAccessibleObject
  • WinEventProc Callback Function


AccessibleChildren

The AccessibleChildren function retrieves the child ID or IDispatch interface of each child within an accessible container object.

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

Parameters

paccContainer
[in] Pointer to the container object's IAccessible interface.
iChildStart
[in] Specifies the zero-based index of the first child retrieved. This parameter is an index, not a child ID. Typically, this parameter is set to zero.
cChildren
[in] Specifies the amount of children to retrieve. An application calls IAccessible::get_accChildCount to retrieve the current number of children.
rgvarChildren
[in/out] Pointer to an array of VARIANT structures that receives information about the container's children. If the vt member of an array element is VT_I4, then the lVal member for that element is the child ID. If vt member of an array element is VT_DISPATCH, then the pdispVal member for that element is the address of the child object's IDispatch interface.
pcObtained
[out] Address of a variable that receives the number of elements in the rgvarChildren array filled in by the function. This value is the same as the cChildren parameter.

Return Values

If successful, returns S_OK. If not successful, returns one of the following or another standard COM error code.

Error | Description
E_INVALIDARG | An argument is invalid.
S_FALSE | The function succeeded, but the number of array elements in rgvarChildren is fewer than the number of children requested in cChildren.

Remarks

To retrieve information about all of the children in a container, the parameter iChildStart must be zero (0), and cChildren must be the value returned by IAccessible::get_accChildCount.

When calling this function to obtain information about the children of a system-provided user-interface element, it is recommended that clients obtain information about all the children. For example, iChildStart must be zero (0), and cChildren must be the value returned by IAccessible::get_accChildCount.

If a child ID is returned for an element, then the container must provide information about the child element. To obtain information about the element, clients use the container's IAccessible interface pointer and specify the obtained child ID in calls to the IAccessible properties.

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

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible, VARIANT Structure, IDispatch Interface


AccessibleObjectFromEvent

The AccessibleObjectFromEvent function retrieves the address of the IAccessible interface for the object that generated the event. The event is the one that the client's event hook function is currently processing.

STDAPI AccessibleObjectFromEvent(
  HWND hwnd,
  DWORD dwObjectID,
  DWORD dwChildID,
  IAccessible** ppacc,
  VARIANT* pvarChild
);

Parameters

hwnd
[in] Specifies the window handle to the window that generated the event. This value must be the window handle sent to the event hook function.
dwObjectID
[in] Specifies the object ID of the object that generated the event. This value must be the object ID sent to the event hook function.
dwChildID
[in] Specifies whether an object or one of the object's children generated the event. If dwChildID is CHILDID_SELF, the object triggered the event. If not, dwChildID is the child ID of the element that triggered the event. This value must be the child ID sent to the event hook function.
ppacc
[out] Address of a pointer variable that receives the address of an IAccessible interface for either the object that generated the event or for the parent of the element that generated the event.
pvarChild
[in/out] Address of a VARIANT structure that specifies whether the IAccessible interface pointer returned in ppacc belongs to the object that generated the event or to the parent of the element that generated the event. The vt member of the VARIANT is always VT_I4. If the lVal member is CHILDID_SELF, then the IAccessible interface pointer at ppacc belongs to the object that generated the event. Otherwise, ppacc is the address of the IAccessible interface of the child element's parent object. Clients must call VariantClear on the retrieved VARIANT parameter when finished using it.

Return Values

If successful, returns S_OK. If not successful, returns the following or another standard COM error code.

Error | Description
E_INVALIDARG | An argument is invalid.

Remarks

Clients call this function within an event hook function to obtain an IAccessible interface pointer to either the object that generated the event or to the parent of the element that generated the event. The parameters sent to the WinEventProc callback function must be used for this function's hwnd, dwObjectID, and dwChildID.

This function retrieves the lowest-level accessible object in the object hierarchy that is associated with an event. If the element that generated the event is not an accessible object, that is, does not support IAccessible, then the function retrieves the IAccessible interface of the parent object. The parent object must provide information about the child element through the IAccessible interface.

This function increases an object's reference count. When finished using the IAccessible interface retrieved by this function, clients must call the Release method to decrement the reference count on the object.

As with standard Automation objects, even though an object has a reference count greater than zero, an application still destroys the object. It is possible that calls to the IAccessible properties and methods fail because the object is destroyed. For example, when a user closes a dialog box, the accessible object for a dialog box control is destroyed even though the reference count on the object is greater than zero.

This function fails if called in response to EVENT_OBJECT_CREATE because the object is not fully initialized. Similarly, an object is in the process of shutting down and cannot respond if this function is called in response to EVENT_OBJECT_DESTROY. Clients watch for EVENT_OBJECT_SHOW and EVENT_OBJECT_HIDE events rather than EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible, AccessibleObjectFromPoint, AccessibleObjectFromWindow, WinEventProc Callback Function, VARIANT Structure


AccessibleObjectFromPoint

The AccessibleObjectFromPoint function retrieves the address of the IAccessible interface for the object at a specified point on the screen.

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

Parameters

ptScreen
[in] Specifies the point that is examined in screen coordinates.
ppacc
[out] Address of a pointer variable that receives the address of the object's IAccessible interface.
pvarChild
[in/out] Address of a VARIANT structure that specifies whether the IAccessible interface pointer returned in ppacc belongs to the object at the specified point or for the parent of the element at the specified point. The vt member of the VARIANT is always VT_I4. If the lVal member is CHILDID_SELF, then the IAccessible interface pointer at ppacc belongs to the object at the point. Otherwise, ppacc is the address of the IAccessible interface of the child element's parent object. Clients must call VariantClear on the retrieved VARIANT parameter when finished using it.

Return Values

If successful, returns S_OK. If not successful, returns the following or another standard COM error code.

Error | Description
E_INVALIDARG | An argument is invalid.

Remarks

This function retrieves the lowest-level accessible object in the object hierarchy at a given point. If the element at the point is not an accessible object, that is, does not support IAccessible, then the function retrieves the IAccessible interface of the parent object. The parent object must provide information about the child element through the IAccessible interface.

This function increases an object's reference count. When finished using the IAccessible interface retrieved by this function, clients must call the Release method to decrement the reference count on the object.

As with standard Automation objects, even though an object has a reference count greater than zero, an application still destroys the object. It is possible that calls to the IAccessible properties and methods fail because the object is destroyed. For example, when a user closes a dialog box, the accessible object for a dialog box control is destroyed even though the reference count on the object is greater than zero.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible, AccessibleObjectFromEvent, AccessibleObjectFromWindow, VARIANT Structure


AccessibleObjectFromWindow

The AccessibleObjectFromWindow function retrieves the address of the specified interface to the object associated with the given window.

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

Parameters

hwnd
[in] Specifies the handle to the window retrieved by the object interface pointer. To retrieve an interface to the cursor or caret object, specify NULL and use the appropriate object ID in dwObjectID.
dwObjectID
[in] Specifies the object ID. This value is one of the standard object identifier constants or a custom object ID, such as OBJID_NATIVEOM, which is the object ID for the Microsoft® Office® native object model. For more information about OBJID_NATIVEOM, see the remarks later in this topic.
riid
[in] Specifies the reference identifier of the requested interface. This value is either IID_IAccessible or IID_IDispatch.
ppvObject
[out] Address of a pointer variable that receives the address of the specified interface.

Return Values

If successful, returns S_OK. If not successful, returns one of the following or another standard COM error code.

Error | Description
E_INVALIDARG | An argument is invalid.
E_NOINTERFACE | The requested interface is not supported.

Remarks

Clients call this function to retrieve the address of an object's IAccessible, IDispatch, IEnumVARIANT, IUnknown, or other supported interface.

This function increases an object's reference count. When finished using the IAccessible interface retrieved by this function, clients must call the Release method to decrement the reference count on the object.

As with standard Automation objects, even though an object has a reference count greater than zero, an application still destroys the object. It is possible that calls to the IAccessible properties and methods fail because the object is destroyed. For example, when a user closes a dialog box, the accessible object for a dialog box control is destroyed even though the reference count on the object is greater than zero.

Clients use this function to obtain access to the Microsoft® Office 2000® native object model. The native object model provides clients with accessibility information about an Office application's document or client area, which is not exposed by Active Accessibility.

To obtain an IDispatch pointer to a class supported by the native object model, specify OBJID_NATIVEOM (0xFFFFFFF0) in dwObjectID. When using this object identifier, the hwnd parameter must match the following window class types.

Office Application | Window Class | IDispatch Pointer To
Word | _WwG | Window
Excel | EXCEL7 | Window
PowerPoint | paneClassDC | DocumentWindow
Command Bars | MsoCommandBar | CommandBar

Note that the above window classes correspond to the inner-most document window or pane window. For more information about the Office object model, see the Microsoft Office/Visual Basic Programmer's Guide.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible, AccessibleObjectFromEvent, AccessibleObjectFromPoint, IDispatch Interface


GetOleaccVersionInfo

The GetOleaccVersionInfo function retrieves the version and build numbers of the Active Accessibility file Oleacc.dll.

void STDAPI GetOleaccVersionInfo(
  DWORD *pdwVer,
  DWORD *pdwBuild
);

Parameters

pdwVer
[in/out] Address of a DWORD that receives the version number. The major version number is placed in the high word, and the minor version number is placed in the low word.
pdwBuild
[in/out] Address of a DWORD that receives the build number. The major build number is placed in the high word, and the minor build number is placed in the low word.

Remarks

This function is provided as an easy way to get the version and build numbers for Oleacc.dll. The Microsoft Win32 APIs GetFileVersionInfoSize, GetFileVersionInfo, and VerQueryValue are used to retrieve the same information.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.


GetRoleText

The GetRoleText function retrieves the localized string that describes an object's role for the specified role value.

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

Parameters

dwRole
[in] Specifies the object role value that identifies the retrieved string. This value is one of the object role constants.
lpszRole
[in/out] Address of a buffer that receives the role text string. If this parameter is NULL, the function returns the role string's length, not including the null character.
cchRoleMax
[in] Specifies the size of the buffer pointed to by the lpszRole parameter. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

Return Values

If successful, and lpszRole is non-NULL, the return value is the number of bytes (ANSI version) or characters (Unicode version) copied into the buffer, not including the null-terminated character. If lpszRole is NULL, then the return value represents the string's length, not including the null character.

If the string resource does not exist, or if the lpszRole parameter is not a valid pointer, the return value is zero. To get extended error information, call GetLastError.

Remarks

The following code fragment demonstrates how to call GetRoleText to determine how much memory to allocate for the role text string.

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

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.


GetStateText

The GetStateText function retrieves a localized string that describes an object's state for a single predefined state bit flag. Because state values are a combination of one or more bit flags, clients call this function more than once to retrieve all the state strings.

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

Parameters

dwStateBit
[in] Specifies the object state value that identifies the retrieved string. This value is only one of the object state constants.
lpszStateBit
[in/out] Address of a buffer that receives the state text string. If this parameter is NULL, the function returns the state string's length, not including the null character.
cchStateBitMax
[in] Specifies the size of the buffer pointed to by the lpszStateBit parameter. For ANSI strings, this value is measured in bytes. For Unicode strings, this value is measured in characters.

Return Values

If successful, and lpszStateBit is non-NULL, the return value is the number of bytes (ANSI version) or characters (Unicode version) copied into the buffer, not including the null-terminated character. If lpszStateBit is NULL, then the return value represents the string's length, not including the null character.

If the string resource does not exist, or if the lpszStateBit parameter is not a valid pointer, the return value is zero. To get extended error information, call GetLastError.

Remarks

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

The following code fragment demonstrates how to call GetStateText to determine how much memory to allocate for the state text string.

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

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.
Unicode: Implemented as Unicode and ANSI versions on Windows NT/2000.


SetWinEventHook

The SetWinEventHook function sets an event hook function for a range of events.

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

Parameters

eventMin
[in] Specifies the event constant for the lowest event value in the range of events handled by the hook function. This parameter is EVENT_MIN to indicate the lowest possible event value.
eventMax
[in] Specifies the event constant for the highest event value in the range of events handled by the hook function. This parameter is EVENT_MAX to indicate the highest possible event value.
hmodWinEventProc
[in] Handle to the dynamic-link library (DLL) that contains the hook function at lpfnWinEventProc if the WINEVENT_INCONTEXT flag is specified in the dwFlags parameter. If the hook function is not located in a DLL, or the WINEVENT_OUTOFCONTEXT flag is specified, this parameter is NULL.
lpfnWinEventProc
[in] Pointer to the event hook function. For more information about this function, see WinEventProc callback function.
idProcess
[in] Specifies the ID of the process from which the hook function receives events. Specify zero to receive events from all processes.
idThread
[in] Specifies the ID of the thread from which the hook function receives events. If this parameter is zero, the hook function is associated with all existing threads.
dwflags
[in] Flag values that specify the location of the hook function and events to skip. The following are valid flags:
WINEVENT_INCONTEXT
The DLL that contains the callback function is mapped into the address space of the process that generates the event. With this flag, the system sends event notifications to the callback function as they occur. The hook function must be in a DLL when this flag is specified. For more information, see In-Context Hook Functions.
WINEVENT_OUTOFCONTEXT
The callback function is not mapped into the address space of the process that generates the event. Because the hook function is called across process boundaries, the system must queue events. Although this method is asynchronous, events are guaranteed to be in sequential order. For more information, see Out-of-Context Hook Functions.
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 processes notifications from receiving any events it might have generated itself. This flag does not prevent the thread from generating events.

Following are the allowed combinations of these flags:

  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_INCONTEXT | WINEVENT_SKIPOWNTHREAD
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNPROCESS
  • WINEVENT_OUTOFCONTEXT | WINEVENT_SKIPOWNTHREAD

Return Values

If successful, returns an HWINEVENTHOOK value that identifies this event hook instance. Applications save this return value to use with the UnhookWinEvent function. If unsuccessful, returns zero.

Remarks

This function allows you to specify which events the hook function receives, and also the process and thread in which events are generated. This is useful when you want to work only with certain applications or just the system.

If the idProcess parameter is non-zero and idThread is zero, the hook function receives the specified events from all threads in that process. If the idProcess parameter is zero and idThread is non-zero, the hook function receives the specified events only from the thread specified by idThread. If both are zero, the hook function receives the specified events from all threads and processes.

Clients call SetWinEventHook more than once to register different hook functions or to set additional events of which a previously registered hook function is notified.

The client thread that calls SetWinEventHook is a thread that has a message loop, sometimes known as a "GUI thread."

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.

See Also

Registering a Hook Function, WinEventProc callback function, UnhookWinEvent


UnhookWinEvent

The UnhookWinEvent function removes an event hook function created by a previous call to SetWinEventHook.

BOOL WINAPI UnhookWinEvent(
  HWINEVENTHOOK hWinEventHook
);

Parameters

hWinEventHook
[in] Handle to the event hook returned in the previous call to SetWinEventHook.

Return Values

If successful, returns TRUE. If unsuccessful, returns FALSE.

Three common errors cause this function to fail:

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

Remarks

This function removes the event hook specified by hWinEventHook, that prevents the corresponding callback function from receiving further event notifications. Clients call this function when event notification is no longer required, or if the client's thread ends.

Call this function from the same thread that installed the event hook. UnhookWinEvent fails if called from a different thread than the call that corresponds to SetWinEventHook.

If WINEVENT_INCONTEXT was specified when this event hook was installed, the system attempts to unload the corresponding DLL from all processes that loaded it. Although unloading does not occur immediately, the hook function is not called after UnhookWinEvent returns.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.


WindowFromAccessibleObject

The WindowFromAccessibleObject function retrieves the window handle that corresponds to a given instance of an IAccessible interface.

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

Parameters

pacc
[in] Pointer to the IAccessible interface whose corresponding window handle will be retrieved. This parameter must not be NULL.
phwnd
[in/out] Address of a variable that receives a handle to the window containing the object specified in pacc. If this value is NULL after the call, the object was not contained within a window. (For example, the mouse pointer is not contained within a window.)

Return Values

If successful, returns S_OK. If not successful, returns the following or another standard COM error code.

Error | Description
E_INVALIDARG | An argument is invalid.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IAccessible, AccessibleObjectFromWindow


WinEventProc Callback Function

The WinEventProc function is an application-defined callback (or hook) function that the system calls in response to events generated by an accessible object. The hook function processes the event notifications as required. Clients install the hook function and request specific types of event notifications by calling SetWinEventHook.

The WINEVENTPROC type defines a pointer to this callback function. WinEventProc is a placeholder for the application-defined function name.

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

Parameters

hWinEventHook
Handle to an event hook function. This value is returned by SetWinEventHook when the hook function is installed and is specific to each instance of the hook function.
event
Specifies the event that occurred. This value is one of the event constants.
hwnd
Handle to the window that generates the event, or NULL if no window is associated with the event. For example, the mouse pointer is not associated with a window.
idObject
Identifies the object associated with the event. This is one of the object identifiers or a custom object ID.
idChild
Identifies whether the event was triggered by an object or a child element of the object. If this value is CHILDID_SELF, the event was triggered by the object; otherwise, this value is the child ID of the element that triggered the event.
dwEventThread
Identifies the thread that generated the event.
dwmsEventTime
Specifies the time, in milliseconds, that the event was generated.

Remarks

Within the hook function, the parameters hwnd, idObject, and idChild are used when calling AccessibleObjectFromEvent.

Servers generate events by calling NotifyWinEvent.

Create multiple callback functions to handle different events. For more information, see Registering a Hook Function.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

WINEVENTPROC, SetWinEventHook


Active Accessibility Server Functions

The following functions are provided for Active Accessibility servers:

  • CreateStdAccessibleObject
  • CreateStdAccessibleProxy
  • LresultFromObject
  • NotifyWinEvent


CreateStdAccessibleObject

The CreateStdAccessibleObject function creates an accessible object with the methods and properties for the specified type of system-provided user interface element.

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

Parameters

hwnd
[in] Window handle of the system-provided user interface element, a control, for which an accessible object is created.
idObject
[in] Object ID. This value is OBJID_CLIENT, but it may be another object identifier.
riidInterface
[in] Reference identifier of the requested interface . This value is one of the following :IID_IAccessible, IID_IDispatch, IID_IEnumVARIANT, or IID_IUnknown.
ppvObject
[out] Address of a pointer variable that receives the address of the specified interface.

Return Values

If successful, returns S_OK. If not successful, returns a standard COM error code.

Remarks

Server applications call this function when they contain a custom UI object that is similar to a system-provided object. Server applications call CreateStdAccessibleObject and override the IAccessible methods and properties, as required, to match their custom object. This approach saves server developers the work of fully implementing all the IAccessible properties and methods.

This function is similar to CreateStdAccessibleProxy, except that CreateStdAccessibleProxy allows you to specify the class name as a parameter whereas CreateStdAccessibleObject uses the class name associated with the hwnd.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

IDispatch Interface, CreateStdAccessibleProxy, Shortcuts for Exposing Custom User Interface Elements


CreateStdAccessibleProxy

The CreateStdAccessibleProxy function creates an accessible object that has the properties and methods of the specified class of system-provided user interface element.

STDAPI CreateStdAccessibleProxy(
  HWND hwnd,
  LPCTSTR pszClassName,
  LONG idObject,
  REFIID riidInterface,
  void ** ppvObject
);

Parameters

hwnd
[in] Window handle of the system-provided user interface element, a control, for which an accessible object is created.
pszClassName
[in] Pointer to a null-terminated string of the class name of a system-provided user interface element for which an accessible object is created. The window class name is any of the following common controls (defined in comctl32.dll), predefined controls (defined in user32.dll), or window elements. Note that the class names in quotation marks are strings and the class names not in quotation marks are constants that define strings.
UI Element | Window Class Name
Common Controls
Animation Control | ANIMATE_CLASS
Hot Key Control | HOTKEY_CLASS
Calendar Control | MONTHCAL_CLASS
Progress Bar Control | PROGRESS_CLASS
Status Bar Control | STATUSCLASSNAME
Toolbar Control | TOOLBARCLASSNAME
ToolTip Control | TOOLTIPS_CLASS
Slider Control | TRACKBAR_CLASS
Up-Down Control | UPDOWN_CLASS
Header Control | WC_HEADER
List View Control | WC_LISTVIEW
Tab Control | WC_TABCONTROL
Tree View Control | WC_TREEVIEW
Predefined Controls
Push Button, Radio Button, Check Box, or Group Box | "BUTTON"
Combo Box | "COMBOBOX"
Edit Control | "EDIT"
List Box | "LISTBOX"
Edit Control | "RichEdit"
Edit Control | RICHEDIT_CLASS
Scroll Bar | "SCROLLBAR"
Static Text | "STATIC"
Window Elements
MDI Client Window | "MDIClient"
Menu Item or Pop-up Menu | "#32768"
Desktop Window | "#32769"
Dialog Box | "#32770"
Switch Window | "#32771"

idObject
[in] Object ID. This value is OBJID_CLIENT, which is one of the object identifier constants.
riidInterface
[in] Reference identifier of the interface requested. This value is one of the following: IID_IAccessible, IID_IDispatch, IID_IEnumVARIANT, or IID_IUnknown.
ppvObject
[out] Address of a pointer variable that receives the address of the specified interface.

Return Values

If successful, returns S_OK. If not successful, returns a standard COM error code.

Remarks

Server applications call this function when they contain a custom control that is similar to a system-provided control. Applications call CreateStdAccessibleProxy and override the IAccessible methods and properties as required to match their custom control. This approach saves server developers the work of fully implementing all the IAccessible properties and methods.

This function is similar to CreateStdAccessibleObject, except that CreateStdAccessibleObject always uses the class name associated with the hwnd whereas CreateStdAccessibleProxy allows you to specify the class name as a parameter.

Use CreateStdAccessibleProxy to create an accessible object for a user interface element that is superclassed. When a user interface element is superclassed, an application creates a custom control with a different window class name than the predefined control on which it is based. Because the class name associated with the hwnd is the superclass window class name, specify the base class name, the system class name on which the superclassed control is based, in pszClassName.

Requirements

Version: Requires MSAA 1.2 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

Appendix A: Supported User Interface Elements Reference, Shortcuts for Exposing Custom User Interface Elements, IDispatch Interface, CreateStdAccessibleObject


LresultFromObject

The LresultFromObject function returns a reference, that is similar to a handle, to the specified object. Servers return this reference when handling WM_GETOBJECT.

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

Parameters

riid
[in] Reference identifier of the interface provided to the client. This parameter is IID_IAccessible.
wParam
[in] Value sent by the associated WM_GETOBJECT message in its wParam parameter.
pAcc
[out] Address of the IAccessible interface to the object that corresponds to the WM_GETOBJECT message.

Return Values

If successful, returns a positive value that is a reference to the object. If not successful, returns one of the following values or another standard COM error code.

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

Remarks

Servers call this function only when handling the WM_GETOBJECT message. For an overview of how LresultFromObject is related to WM_GETOBJECT, see How WM_GETOBJECT Works.

LresultFromObject increments the object's reference count. If you are not storing the interface pointer passed to the function, (that is, you create a new interface pointer for the object each time WM_GETOBJECT is received), call the object's Release method to decrement the reference count back to one. Then the client calls Release and the object is destroyed. For more information, see How to Handle WM_GETOBJECT.

Each time a server processes WM_GETOBJECT for a specific object, it calls LresultFromObject to obtain a new reference to the object. Servers do not save the reference returned from LresultFromObject from one instance of processing WM_GETOBJECT to use as the message's return value when processing subsequent WM_GETOBJECT messages for the same object. This causes the client to receive an error.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Oleacc.h.
Library: Use Oleacc.lib.

See Also

How WM_GETOBJECT Works, How to Handle WM_GETOBJECT, WM_GETOBJECT, Creating Proxy Objects

ObjectFromLresult

The ObjectFromLresult function retrieves a requested interface pointer for an accessible object based on a previously generated object reference.

This function is designed for internal use by Active Accessibility and is documented for informational purposes only. Neither clients nor servers should call this function.

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

Parameters

lResult
[in] A 32-bit value returned by a previous successful call to the LresultFromObject function.
riid
[in] Reference identifier of the interface to be retrieved. This is IID_IAccessible.
wParam
[in] Additional information is provided in the associated wParam parameter of the WM_GETOBJECT message.
ppvObject
[out] Receives the address of the interface pointer to return to the client.

Return Values

If successful, returns S_OK. If not successful, returns one of the following standard COM error code.

Error | Description
E_INVALIDARG | One or more arguments are invalid. 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.

See Also

WM_GETOBJECT Window Message


NotifyWinEvent

The NotifyWinEvent function signals the system that a predefined event occurred. If any client applications have registered a hook function for the event, the system calls the client's hook function.

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

Parameters

event
[in] Specifies the event that occurred. This value must be one of the event constants.
hwnd
[in] Handle to the window that contains the object that generated the event.
idObjectType
[in] Identifies the kind of object that generated the event. This value is one of the predefined object identifiers or a custom object ID value.
idObject
[in] Identifies whether the event was generated by an object or a child element of the object. If this value is CHILDID_SELF, the event was generated by the object itself. If not, this value is the child ID of the element that generated the event.

Remarks

Servers call this function whenever they notify the system that an event has occurred. Active Accessibility checks to see if any client applications have set hook procedures for the event and calls the appropriate hook procedures.

If no hook procedures are registered for the event, the performance penalty for calling this function is minor.

Servers call NotifyWinEvent to announce the event to the system after the event has occurred; they must never notify the system of an event before the event has occurred.

When the client's hook procedure is called, it receives a number of parameters that describe the event and the object that generated the event. The hook procedure uses the AccessibleObjectFromEvent to retrieve a pointer to the IAccessible interface of the object that generated the event.

Requirements

Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.
Library: Use User32.lib.

See Also

WinEvents Notify Changes, AccessibleObjectFromEvent, SetWinEventHook, UnHookWinEvent


Structures and Data Types

This section contains information on the following structures and data types used with Active Accessibility:

  • MSAAMENUINFO
  • HWINEVENTHOOK
  • WINEVENTPROC


MSAAMENUINFO

Server developers use the MSAAMENUINFO structure to expose the names of owner-drawn menu items.

typedef struct tagMSAAMENUINFO {
    DWORD    dwMSAASignature;
    DWORD    cchWText;
    LPWSTR   pszWText;
} MSAAMENUINFO, *LPMSAAMENUINFO;

Members

dwMSAASignature
Must be the value MSAA_MENU_SIG, which is defined in oleacc.h.
cchWText
Length, in characters, of the text for the menu item, excluding the Unicode null-terminated character.
pszWText
The text of the menu item, in Unicode, including the Unicode null-terminated character.

Remarks

By associating the MSAAMENUINFO structure with owner-drawn menu item data, application developers can expose the menu items without having to implement IAccessible.

The MSAAMENUINFO structure is the first member of the application-specific structure (or class) that contains the data for an owner-drawn menu item, which is pointed to by the dwItemData member of the MENUITEMINFO structure.

The MSAAMENUINFO structure cannot be a member in a class that contains virtual functions because the first member of the class is always a compiler-generated pointer to a table of the virtual functions. To work around this problem, you can implement a structure that contains the MSAAMENUINFO as the first member, and the second member is a pointer to the class with the virtual functions, which contains the owner-drawn item data.

Example

The following code fragment shows the declaration of an application-specific owner-drawn menu information structure that includes MSAAMENUINFO:

// Application-specific owner-drawn menu info struct. Owner-drawn data
// is a pointer to one of these. MSAAMENUINFO must be the first
// member.
struct MenuEntry
{
    MSAAMENUINFO m_MSAA;       // MSAA info - must be first element.
    LPTSTR       m_pName;      // Menu text, for display. NULL for
                               //  separator item.
    int          m_CmdID;      // Menu command ID.
    int          m_IconIndex;  // Index of icon in bitmap.
};

See Also

Exposing Owner-Drawn Menu Items, IAccessible


HWINEVENTHOOK

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

typedef DWORD HWINEVENTHOOK

Remarks

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


WINEVENTPROC

The WINEVENTPROC defines a pointer type for an application-defined callback function that the system calls in response to events generated by an accessible object.

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

Remarks

For more information, see WinEventProc Callback Function


WM_GETOBJECT Window Message

This section contains information about the window message WM_GETOBJECT. The system sends to Active Accessibility servers to obtain information about an object. For additional information about WM_GETOBJECT, see the following topics:

  • How WM_GETOBJECT Works
  • How to Handle WM_GETOBJECT


WM_GETOBJECT

Active Accessibility sends the WM_GETOBJECT message to obtain information about an accessible object contained in a server application.

Applications never send this message directly. It is sent only by Active Accessibility in response to calls to AccessibleObjectFromPoint, AccessibleObjectFromEvent, or AccessibleObjectFromWindow. However, server applications handle this message.

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

Parameters

dwFlags
Provides additional information about the message, and is used only by the system. Servers pass dwFlags as the wParam parameter in the call to LresultFromObject when handling the message.
dwObjId
Object identifier. This value is one of the object identifier constants or a custom object identifier. Servers process WM_GETOBJECT only if the dwObjId is OBJID_CLIENT.

Return Values

The return value depends on whether the window or control that receives the message implements IAccessible.

  • If implementing IAccessible for the object, the application returns the result obtained from LresultFromObject.
  • If not implementing IAccessible, or if dwObjID is not OBJID_CLIENT, the application returns zero or allows the message fall through to DefWindowProc, which returns zero.

Remarks

When a client calls AccessibleObjectFromWindow or any of the other AccessibleObjectFromX APIs that retrieve an interface to an object, Active Accessibility sends the WM_GETOBJECT message to the appropriate window procedure within the appropriate server application. While processing WM_GETOBJECT, server applications call LresultFromObject and use the return value of this function as the return value for the message. Active Accessibility, in conjunction with the COM library, performs the appropriate marshaling and passes the interface pointer from the server back to the client.

Servers do not respond to WM_GETOBJECT before the object is fully initialized or after it begins to close down. When an application creates a new window, the system sends EVENT_OBJECT_CREATE to notify clients before it sends the WM_CREATE message to the application's window procedure. Because many applications use WM_CREATE to start their initialization process, servers do not respond to the WM_GETOBJECT message until finished processing the WM_CREATE message.

A server handles WM_GETOBJECT in the following ways:

  • Create New Accessible Objects
  • Reuse Existing Pointers to Objects
  • Create New Interfaces to the Same Object

For clients, this means that they receive distinct interface pointers for the same user interface element. To determine if two interface pointers point to the same user interface element, clients compare IAccessible properties of the object. Comparing pointers does not work.

Requirements

Windows NT/2000 or later: Requires Windows NT 4.0 SP4 or later.
Windows 95/98/Me: Requires Windows 95 or later.
Version: Requires MSAA 1.0 or later.
Header: Declared in Winuser.h; include Windows.h.

See Also

LresultFromObject, How WM_GETOBJECT Works, How to Handle WM_GETOBJECT


Dynamic Annotation

This section contains information about the Dynamic Annotation interfaces: IAccIdentity, IAccPropServer, and IAccPropServices.

For more information on the Dynamic Annotation interfaces, see the following:

  • IAccIdentity::GetIdentityString
  • IAccPropServer::GetPropValue
  • IAccPropServices::SetPropValue
  • IAccPropServices::SetPropServer
  • IAccPropServices::ClearProps
  • Utility Methods SetHwndProp, SetHwndPropStr, SetHwndPropServer, ClearHwndProps
  • Utility Methods SetHmenuProp, SetHmenuPropStr, SetHmenuPropServer, ClearHmenuProps
  • IAccPropServices::ComposeHwndIdentityString
  • IAccPropServices::DecomposeHwndIdentityString
  • IAccPropServices::ComposeHmenuIdentityString
  • IAccPropServices::DecomposeHmenuIdentityString


Type MSAAPROPID

typedef GUID MSAAPROPID;

Remarks

This type represents a property. Examples of predefined values include PROPID_ACC_NAME, PROPID_ACC_VALUE, and PROPID_ACC_ROLEMAP. For more information, see properties supported when specifying a value, or properties supported when specifying a callback for a complete list of supported properties.


IAccIdentity::GetIdentityString

The IAccIdentity interface is implemented by IAccessibles objects and currently implemented by most OLEACC proxies. This interface allows clients to obtain a string of bytes (an identity string) that uniquely identifies a particular accessible element. Other Dynamic Annotation methods use the identity string to refer to accessible elements. GetIdentityString is the only method in this interface.

HRESULT GetIdentityString (
  DWORD dwIDChild,
  BYTE**     ppIDString,
  DWORD*     pdwIDStringLen
);

Parameters

dwIDChild
[in]Specifies which child of the IAccessible object the caller wants to identify.
ppidString, pdwIDStringLen
[out]Callee-allocated identity string and its length. Callee allocates this using CoTaskMemAlloc; caller must release using CoTaskMemFree when finished.

Return Values

Should always return S_OK, except under exceptional error conditions (low memory, etc). If not supported, calling QueryInterface on IAccIdentity should fail.

Remarks

The returned string should be considered opaque; clients should only use it as a whole, and should not attempt to dissect it or otherwise interpret it manually.

If a client knows or expects that a string is HWND- or HMENU- based, it can use IAccPropServices::DecomposeHwndIdentityString() or IAccPropServices::DecomposeHmenuIdentityString() to attempt to decompose the identity string.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServer::GetPropValue

An annotator implements this callback interface. This interface is passed to the annotation methods and is called back when a client requests the values of one of the properties being annotated. GetPropValue is the only method in this interface.

HRESULT GetPropValue (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  MSAAPROPID  idProp,
  VARIANT *  pvarValue,
  BOOL *  pfHasProp
);

Parameters

pIDString, dwIDStringLen
[in]Identity string that identifies the object for the request, and the length of the identity string.
idProp
[in]GUID indicating the desired property.
pvarValue
[out]Callee should set this to return the value of the overridden property. This is only valid if pfHasProp is TRUE. Callee must set this to VT_EMPTY if pfHasProp is set to FALSE.
pfHasProp
[out]Indicates whether the callee is supplying a value for the requested property. Callee should set this to TRUE if it is returning an overriding property; or should set this to FALSE if it is not returning a property (in which case it should also set pvarValue to VT_EMPTY).

Return Values

Should always return S_OK, except under exceptional error conditions (low memory, etc). If the specified property is not overridden, then pfHasProp should be set to FALSE and pvarValue should bet set to VT_EMPTY by the callee.

Remarks

If a single callback object is registered for annotating multiple accessible elements, the identity string can be used to determine which element this request refers to.

If the accessible element is HWND-based, IAccPropServices::DecomposeHwndIdentityString() can be used to extract the HWND/idObject/idChild from the identity string.

If the callback has a value to return for the specified property, it should return it in pvarValue and set pfHasProp to TRUE. Otherwise it should set pvarValue to VT_EMPTY and set pfHasProp to FALSE. In this latter case, the original IAccessible will be used to obtain a value for this property.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::SetPropValue

Implemented by the MSAA run time, the IAccPropServices interface contains methods for annotating accessible elements, and also for manipulating identity strings.

HRESULT SetPropValue (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  MSAAPROPID  idProp,
  VARIANT  var
);

Parameters

pIDString, dwIDStringLen
[in]Identifies the accessible element that is to be annotated.
idProp
[in]Specifies which property of that element is to be annotated.
var
[in]Specifies a new value for that property.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if idProp is not a supported property, if var is not a supported type for that property, or if the identity string is not valid.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

See the support section for a list of supported properties and their expected types. Note that currently some properties are supported only when a callback is used, and can not be specified directly using this method.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::SetPropServer

Implemented by the MSAA run time, the IAccPropServices interface contains methods for annotating accessible elements, and also for manipulating identity strings.

HRESULT SetPropServer (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  const MSAAPROPID *  paProps,
  int  cProps,

  IAccPropServer *  pServer,
  AnnoScope  annoScope
);

Parameters

pIDString, dwIDStringLen
[in]Identifies the accessible element that is to be annotated.
paProps, cProps
[in]Specifies an array of properties that is to be handled by the specified callback object.
pServer
[in]Specifies the callback object, which will be invoked when a client requests one of the overridden properties.
annoScope
[in]May be ANNO_THIS, indicating that the annotation affects the indicated accessible element only; or ANNO_CONTAINER, indicating that it applies to the element and its immediate element children.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if any of the properties in the paProps array are not supported properties, if the identity string is not valid, or annoScope is not one of ANNO_THIS or ANNO_CONTAINER.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

See the support section for a list of supported properties and their expected types.

The annotation run time will AddRef the pServer callback object appropriately. The caller is free to Release it after calling this method. The annotation run time will automatically release the callback object after the accessible element being annotated goes away.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::ClearProps

Implemented by the MSAA run time, the IAccPropServices interface contains methods for annotating accessible elements, and also for manipulating identity strings.

HRESULT ClearProps (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  const MSAAPROPID *  paProps,
  int  cProps
);

Parameters

pIDString, dwIDStringLen
[in]Identifies the accessible element that is to be un-annotated.
paProps, cProps
[in]Specifies an array of properties that is to be reset. These properties will revert to the default behavior they displayed before they were annotated.

Return Values

Returns S_OK on success. S_OK is returned even if the specified properties were never annotated on the accessible object; clearing already cleared properties is considered a success.

Returns E_INVALIDARG if any of the properties in the paProps array are not supported.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

See the support section for a list of supported properties and their expected types.

Clearing annotation for a property will cause any associated resources to be released. If a callback property server was used (see SetPropServer), it will be Release()'d.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


Utility Methods SetHwndProp, SetHwndPropStr, SetHwndPropServer, ClearHwndProps

HRESULT SetHwndProp (
  HWND  hwnd,
  DWORD  idObject,
  DWORD  idChild,
  MSAAPROPID  idProp,
  VARIANT  var
);

HRESULT SetHwndPropStr (
  HWND  hwnd,
  DWORD  idObject,
  DWORD  idChild,
  MSAAPROPID  idProp,
  LPCWSTR  str
);

HRESULT SetHwndPropServer (
  HWND  hwnd,
  DWORD  idObject,
  DWORD  idChild,

  const MSAAPROPID *  paProps,
  int  cProps,
  IAccPropServer *  pServer,

  AnnoScope  annoScope
);

HRESULT ClearHwndProps (
  HWND  hwnd,
  DWORD  idObject,
  DWORD  idChild,

  const MSAAPROPID *  paProps
  int  cProps,
);

Parameters

hwnd, idObject, idChild
[in]Identifies the accessible element that is to be annotated. This replaces the identity string.

For descriptions of other parameters, see the corresponding SetPropValue, SetPropServer, or ClearProps method.

Return Values

For descriptions of return values, see the corresponding SetPropValue, SetPropServer, or ClearProps method.

Remarks

These methods wrap SetPropValue, SetPropServer, and ClearProps, and provide more convenient entry points for callers who are annotating Hwnd-based objects.

By using these methods, the caller does not have to obtain an identity string; it can specify the HWND, idObject, and idChild directly.

Additionally, SetHwndPropStr takes a regular Unicode string as a parameter; the caller does not need to specially allocate a BSTR.


Utility Methods SetHmenuProp, SetHmenuPropStr, SetHmenuPropServer, ClearHmenuProps

HRESULT SetHmenuProp (
  HMENU  hmenu,
  DWORD  idChild,
  MSAAPROPID  idProp,
  VARIANT  var
);

HRESULT SetHmenuPropStr (
  HMENU  hmenu,
  DWORD  idChild,
  MSAAPROPID  idProp,
  LPCWSTR  str
);

HRESULT SetHmenuPropServer (
  HMENU  hmenu,
  DWORD  idChild,

  const MSAAPROPID *  paProps,
  int  cProps,

  IAccPropServer *  pServer,
  AnnoScope  annoScope
);

HRESULT ClearHmenuProps (
  HMENU  hmenu,
  DWORD  idChild,

  const MSAAPROPID *  paProps
  int  cProps,
);

Parameters

hmenu, idChild
[in]Identifies the accessible element that is to be annotated. This replaces the identity string.

For descriptions of other parameters, see the corresponding SetPropValue, SetPropServer, or ClearProps method.

Return Values

For descriptions of return values, see the corresponding SetPropValue, SetPropServer, or ClearProps method.

Remarks

These methods wrap SetPropValue, SetPropServer, and ClearProps, and provide more convenient entry points for callers who are annotating HMENU-based objects.

By using these methods, the caller does not have to obtain an identity string; it can specify the HMENU and idChild directly.

Additionally, SetHmenuPropStr takes a regular Unicode string as a parameter; the caller does not need to specially allocate a BSTR.


IAccPropServices::ComposeHwndIdentityString

HRESULT ComposeHwndIdentityString (
  HWND  hwnd,
  DWORD  idObject,
  DWORD  idChild,

  BYTE **  ppIDString,
  DWORD *  pdwIDStringLen
);

Parameters

hwnd, idObject, dwIDChild
[in]Specifies the accessible element that the caller wants to identify.
ppidString, pdwIDStringLen
[out]Callee-allocated identity string and its length. Callee allocates this using CoTaskMemAlloc; caller must release using CoTaskMemFree when finished.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if dwHWND, idObject, or idChild are not valid.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

(None)

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::DecomposeHwndIdentityString

HRESULT DecomposeHwndIdentityString (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  HWND *  phwnd,
  DWORD *  pidObject,
  DWORD *  pidChild
);

Parameters

pIDString, dwIDStringLen
[in]Specifies the identity string of a HWND-based accessible element.
phwnd, pidObject, pidChild
[out]Returns the HWND, idObject, and idChild corresponding to the accessible element referenced by the given identity string.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if phwnd, idObject, or idChild are not valid, or if the given identity string is not a HWND-based identity string.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

This method succeeds only if the provided identity string is a HWND-based identity string.

This method is useful when used in a IAccPropServer callback server that was registered with ANNO_CONTAINER scope, as it allows the server to determine, from the given identity string, which child element (idChild) it is being called for.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::ComposeHmenuIdentityString

HRESULT ComposeHmenuIdentityString (
  HMENU  hmenu,
  DWORD  idChild,

  BYTE **  ppIDString,
  DWORD *  pdwIDStringLen
);

Parameters

hmenu, dwIDChild
[in]Specifies the accessible element that the caller wants the identity string for.
ppidString, pdwIDStringLen
[out]Callee-allocated identity string and its length. Callee allocates this using CoTaskMemAlloc; caller must release using CoTaskMemFree when finished.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if hmenu or pidChild are not valid.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

(None)

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


IAccPropServices::DecomposeHmenuIdentityString

HRESULT DecomposeHmenuIdentityString (
  const BYTE *  pIDString,
  DWORD  dwIDStringLen,

  HMENU *  phmenu,
  DWORD *  pidChild
);

Parameters

pIDString, dwIDStringLen
[in]Specifies the identity string of a HWND-based accessible element.
phmenu, pidChild
[out]Returns the HWND and idChild corresponding to the accessible element referenced by the given identity string.

Return Values

Returns S_OK on success.

Returns E_INVALIDARG if phmenu or pidChild are not valid, or if the given identity string is not a valid HMENU-based identity string.

May return other error codes under exceptional error conditions (low memory, etc).

Remarks

This method only succeeds if the provided identity string is a HMENU-based identity string.

This method is useful when used in a IAccPropServer callback server that was registered with ANNO_CONTAINER scope, as it allows the server to determine, from the given identity string, which child element (idChild) it is being called for.

Requirements

Version: Requires MSAA 2.0.
Header: Declared in initguid.h and oleacc.h (include initguid.h in one file prior to including oleacc.h).


Constants and Enumerated Types

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

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


Event Constants

The following describes the meaning of events generated by the operating system and server applications. The constants are listed in ascending numeric order. Additionally, the EVENT_MIN constant represents the lowest possible event values and EVENT_MAX constant represents the highest possible event values.

For more information about events in general, see What are WinEvents? and System Level and Object Level Events. For more information about the events sent by the system, see Appendix A: Supported User Interface Elements Reference.

EVENT_SYSTEM_SOUND
A sound was played. The system sends this event when a system sound, such as for menus, is played even if no sound is audible, for example, lack of a sound file or sound card. Servers send this event if a custom user interface element generates a sound.

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

EVENT_SYSTEM_ALERT
An alert was generated. Server applications send the this event whenever an important user interface change occurs that a user needs to know about. For more information, see Alerts.

This event is not sent consistently by the system for dialog box objects. This is a known problem and is being addressed.

EVENT_SYSTEM_FOREGROUND
The foreground window changed. The system sends this event even if the foreground window is changed to another window in the same thread. Server applications never send this event.

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

EVENT_SYSTEM_MENUSTART
A menu item on the menu bar was selected. The system sends this event for standard menus, identified by HMENU, created using menu-template resources or Microsoft Win32 menu APIs. Servers send this event for custom menus, (user interface elements that function as menus but are not created in the standard way).

For this event, the WinEventProc callback function's hwnd, idObject, and idChild parameters refer to the control that contains the menu bar or the control that activates the context menu. The hwnd parameter is the handle to the window related to the event. The idObject parameter is OBJID_MENU or OBJID_SYSMENU for a menu, or OBJID_WINDOW for a pop-up menu. The idChild parameter is CHILDID_SELF.

The system triggers more than one EVENT_SYSTEM_MENUSTART event that does not always correspond with the EVENT_SYSTEM_MENUEND event.

EVENT_SYSTEM_MENUEND
A menu from the menu bar was closed. The system sends this event for standard menus. Servers send this event for custom menus.

For this event, the WinEventProc callback function's hwnd, idObject, and idChild parameters refer to the control that contains the menu bar or the control that activates the context menu. The hwnd parameter is the handle to the window related to the event. The idObject parameter is OBJID_MENU or OBJID_SYSMENU for a menu, or OBJID_WINDOW for a pop-up menu. The idChild parameter is CHILDID_SELF.

EVENT_SYSTEM_MENUPOPUPSTART
A pop-up menu was displayed. The system sends this event for standard menus, identified by HMENU, created using menu-template resources or Win32 menu APIs. Servers send this event for custom menus (user interface elements that function as menus but are not created in the standard way).

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_MENUPOPUPEND
A pop-up menu was closed. The system sends this event for standard menus. Servers send this event for custom menus.

When a pop-up menu is closed, the client receives this message followed almost immediately by the EVENT_SYSTEM_MENUEND event.

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_CAPTURESTART
A window has received mouse capture. This event is sent by the system; servers never send this event.
EVENT_SYSTEM_CAPTUREEND
A window has lost mouse capture. This event is sent by the system; servers never send this event.
EVENT_SYSTEM_MOVESIZESTART
A window is being moved or resized. This event is sent by the system; servers never send this event.
EVENT_SYSTEM_MOVESIZEEND
The movement or resizing of a window is finished. This event is sent by the system; servers never send this event.
EVENT_SYSTEM_CONTEXTHELPSTART
A window entered context-sensitive Help mode.

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_CONTEXTHELPEND
A window exited context-sensitive Help mode.

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_DRAGDROPSTART
An application is about to enter drag-and-drop mode. Applications that support drag-and-drop operations must send this event; the system does not send this event.
EVENT_SYSTEM_DRAGDROPEND
An application is about to exit drag-and-drop mode. Applications that support drag-and-drop operations must send this event; the system does not send this event.
EVENT_SYSTEM_DIALOGSTART
A dialog box was displayed. This event is sent by the system for standard dialog boxes, created using resource templates or Win32 dialog box APIs. Servers send this event for custom dialog boxes (windows that function as dialog boxes but are not created in the standard way).

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_DIALOGEND
A dialog box was closed. This event is sent by the system for standard dialog boxes. Servers send this event for custom dialog boxes.

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_SYSTEM_SCROLLINGSTART
Scrolling has started on a scroll bar. This event is sent by the system for scroll bars attached to a window and for standard scroll bar controls. Servers send this event for custom scroll bars (user interface elements that function as scroll bars but are not created in the standard way).

The idObject parameter sent to the WinEventProc callback function is OBJID_HSCROLL for horizontal or OBJID_VSCROLL for vertical scroll bars.

EVENT_SYSTEM_SCROLLINGEND
Scrolling has ended on a scroll bar. This event is sent by the system for scroll bars attached to a window and for standard scroll bar controls. Servers send this event for custom scroll bars.

The idObject parameter sent to the WinEventProc callback function is OBJID_HSCROLL for horizontal or OBJID_VSCROLL for vertical scroll bars.

EVENT_SYSTEM_SWITCHSTART
The user pressed ALT+TAB, which activates the switch window. This event is sent by the system; servers never send this event. The hwnd parameter of the WinEventProc callback function identifies to which window the user is switching.

If only one application is running when the user presses ALT+TAB, the system sends EVENT_SYSTEM_SWITCHEND event without a corresponding EVENT_SYSTEM_SWITCHSTART event.

EVENT_SYSTEM_SWITCHEND
The user released ALT+TAB. This event is sent by the system; servers never send this event. The hwnd parameter of the WinEventProc callback function identifies to which window the user has switched.

If only one application is running when the user presses ALT+TAB, the system sends this event without a corresponding EVENT_SYSTEM_SWITCHSTART event.

EVENT_SYSTEM_MINIMIZESTART
A window object is about to be minimized or maximized. This event is sent by the system; servers never send this event.
EVENT_SYSTEM_MINIMIZEEND
A window object was minimized or maximized. This event is sent by the system; servers never send this event.
EVENT_OBJECT_CREATE
An object was created. The system sends this event for the following user interface elements: caret, header control, list view control, tab control, toolbar control, tree view control, and window object. Server applications send this event for their accessible objects.

Servers must send this event for all of an object's child objects before sending the event for the parent object. Servers must ensure that all child objects are fully created and ready to accept IAccessible calls from clients when the parent object sends this event.

Because a parent object is created after its child objects, clients must make sure that an object's parent has been created before calling IAccessible::get_accParent, particularly if in-context hook functions are used.

EVENT_OBJECT_DESTROY
An object is destroyed. The system sends this event for the following user interface elements: caret, header control, list view control, tab control, toolbar control, tree view control, and window object. Server applications send this event for their accessible objects.

Clients assume that all the children of an object are destroyed when the parent object sends this event.

Clients do not call an object's IAccessible properties or methods after receiving this event because the interface pointer is no longer valid. Servers prevent this situation by creating proxy objects that wrap accessible objects and monitor the life span of those objects.

EVENT_OBJECT_SHOW
A hidden object is shown. The system sends this event for the following user interface elements: caret, cursor, and window object. Server applications send this event for their accessible objects.

Clients assume that when this event is sent by a parent object, all child objects are already displayed. Therefore, server applications do not send this event for the child objects.

Hidden objects include the STATE_SYSTEM_INVISIBLE flag and shown objects do not include this flag. The EVENT_OBJECT_SHOW event also indicates that the STATE_SYSTEM_INVISIBLE flag is cleared. Therefore, servers do not send the EVENT_STATE_CHANGE event in this case.

EVENT_OBJECT_HIDE
An object is hidden. The system sends this event for the following user interface elements: caret and cursor. Server applications send this event for their accessible objects.

When this event is generated for a parent object, all child objects are already hidden. Server applications do not send this event for the child objects.

Hidden objects include the STATE_SYSTEM_INVISIBLE flag and shown objects do not include this flag. The EVENT_OBJECT_HIDE event also indicates that the STATE_SYSTEM_INVISIBLE flag is set. Therefore, servers do not send the EVENT_STATE_CHANGE event in this case.

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_OBJECT_REORDER
A container object has added, removed, or reordered its children. The system sends this event for the following user interface elements: header control, list view control, toolbar control, and window object. Server applications send this event as appropriate for their accessible objects.

For example, this event is generated by a list view object when the number of child elements or the order of the elements changes. This event is also sent by a parent window when the z order for the child windows changes.

EVENT_OBJECT_FOCUS
An object receives the keyboard focus. The system sends this event for the following user interface elements: list view control, menu bar, pop-up menu, switch window, tab control, tree view control, and window object. Server applications send this event for their accessible objects.

The hwnd parameter of the WinEventProc callback function identifies the window that receives the keyboard focus.

EVENT_OBJECT_SELECTION
The selection within a container object changed. The system sends this event for the following user interface elements: list view control, tab control, tree view control, and window object. Server applications send this event for their accessible objects.

This event signals a single selection—either a child is selected in a container that previously did not contain any selected children or the selection has changed from one child to another.

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

EVENT_OBJECT_SELECTIONADD
An item within a container object was added to the selection. The system sends this event for the following user interface elements: list box, list view control, and tree view control. Server applications send this event for their accessible objects.

This event signals that a child is added to an existing selection.

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

EVENT_OBJECT_SELECTIONREMOVE
An item within a container object was removed from the selection. The system sends this event for the following user interface elements: list box, list view control, and tree view control. Server applications send this event for their accessible objects.

This event signals that a child is removed from an existing selection.

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

EVENT_OBJECT_SELECTIONWITHIN
Numerous selection changes occurred within a container object. The system sends this event for list boxes. Server applications send this event for their accessible objects.

This event is sent when the selected items within a control have changed substantially. This event informs the client that many selection changes have occurred, instead of sending several EVENT_OBJECT_SELECTIONADD or EVENT_OBJECT_SELECTIONREMOVE events. The client queries 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.

EVENT_OBJECT_STATECHANGE
An object's state has changed. The system sends this event for the following user interface elements: check box, combo box, header control, push button, radio button, scroll bar, toolbar control, tree view control, up-down control, and window object. Server applications send this event for their accessible objects.

For example, a state change occurs when a button object is pressed or released, or when an object is enabled or disabled.

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

This event is not sent consistently by the system. This is a known problem and is being addressed.

EVENT_OBJECT_LOCATIONCHANGE
An object has changed location, shape, or size. The system sends this event for the following user interface elements: caret and window object. Server applications send this event for their accessible objects.

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

The system does not send this event for every non-floating child window when the parent moves. However, if an application explicitly resizes child windows as a result of resizing, the system sends multiple events for the resized children.

If an object's State property is set to STATE_SYSTEM_FLOATING, servers sends EVENT_OBJECT_LOCATIONCHANGE whenever the object changes location. If an object does not have this state, servers only triggers this event when the object moves relative to its parent.

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

EVENT_OBJECT_NAMECHANGE
An object's Name property changed. The system sends this event for the following user interface elements: check box, cursor, list view control, push button, radio button, status bar control, tree view control, and window object. Server applications send this event for their accessible objects.
EVENT_OBJECT_DESCRIPTIONCHANGE
An object's Description property changed. Server applications send this event for their accessible objects.
EVENT_OBJECT_VALUECHANGE
An object's Value property changed. The system sends this event for the following user interface elements: edit control, header control, hot key control, progress bar control, scroll bar, slider control, and up-down control. Server applications send this event for their accessible objects.
EVENT_OBJECT_PARENTCHANGE
An object has a new parent object. Server applications send this event for their accessible objects.
EVENT_OBJECT_HELPCHANGE
An object's Help property changed. Server applications send this event for their accessible objects.
EVENT_OBJECT_DEFACTIONCHANGE
An object's DefaultAction property changed. The system sends this event for dialog boxes. Server applications send this event for their accessible objects.
EVENT_OBJECT_ACCELERATORCHANGE
An object's KeyboardShortcut property changed. Server applications send this event for their accessible objects.


Navigation Constants

The following values, defined in oleacc.h, indicate spatial (up, down, left, and right) or logical (first child, last child, next, and previous) directions when clients navigate from one user interface element to another within the same container using IAccessible::accNavigate. For more information, see Object Navigation Properties and Methods.

The following are navigation constants:

NAVDIR_DOWN
Navigate to the sibling object located below the starting object.
NAVDIR_FIRSTCHILD
Navigate to the first child of this object. When using this flag, the lVal member of the varStart parameter must be CHILDID_SELF.
NAVDIR_LASTCHILD
Navigate to the last child of this object. When using this flag, the lVal member of the varStart parameter must be CHILDID_SELF.
NAVDIR_LEFT
Navigate to the sibling object located to the left of the starting object.
NAVDIR_NEXT
Navigate to the next logical object, generally a sibling to the starting object.
NAVDIR_PREVIOUS
Navigate to the previous logical object, generally a sibling to the starting object.
NAVDIR_RIGHT
Navigate to the sibling object located to the right of the starting object.
NAVDIR_UP
Navigate to the sibling object located above the starting object.


Object Identifiers

Object identifiers are 32-bit values that identify categories of accessible objects within an application.

Clients receive these values in their WinEventProc callback function and use them to identify parts of a window. Servers also use these values to identify the corresponding parts of a window when calling NotifyWinEvent or when responding to the WM_GETOBJECT message.

Servers can define custom object IDs to identify other categories of objects within their application. Custom object IDs must be assigned positive values because Microsoft Active Accessibility reserves zero and all negative values to use for the following standard object identifiers.

The following constants are defined in winable.h:

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. When processing the WM_GETOBJECT message, servers only process the messages in which the lParam is OBJID_CLIENT.
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.

Clients retrieve an object's role by calling IAccessible::get_accRole, which returns either a string or one of the following values. Clients call GetRoleText with the role value to retrieve a localized string that describes the object's role. The localized strings for the role values are in the file oleaccrc.dll.

ROLE_SYSTEM_ALERT
The object represents an alert or a condition that a user should be notified about. This role is used only for objects that embody an alert but are not associated with another user interface element such as a message box, graphic, text, or sound.
ROLE_SYSTEM_ANIMATION
The object represents an animation control, which contains content that changes over time, such as a control that displays a series of bitmap frames, like a film strip. Animation controls are displayed when files are copied, or when some other time-consuming task is performed.
ROLE_SYSTEM_APPLICATION
The object represents a main window for an application.
ROLE_SYSTEM_BORDER
The object represents a window border. The entire border is represented by a single object, rather than by separate objects for each side.
ROLE_SYSTEM_BUTTONDROPDOWN
The object represents a button that drops down a list of items.
ROLE_SYSTEM_BUTTONDROPDOWNGRID
The object represents a button that drops down a grid.
ROLE_SYSTEM_BUTTONMENU
The object represents a button that drops down a menu.
ROLE_SYSTEM_CARET
The object represents the system caret.
ROLE_SYSTEM_CELL
The object represents a cell within a table.
ROLE_SYSTEM_CHARACTER
The object represents a cartoon-like graphic object, such as Microsoft® Office Assistant®, which is displayed to provide help to users of an application.
ROLE_SYSTEM_CHART
The object represents a graphical image used to represent data.
ROLE_SYSTEM_CHECKBUTTON
The object represents a check box control, an option turned on or off independently of other options.
ROLE_SYSTEM_CLIENT
The object represents a window's client area.
ROLE_SYSTEM_CLOCK
The object represents a control that displays time.
ROLE_SYSTEM_COLUMN
The object represents a column of cells within a table.
ROLE_SYSTEM_COLUMNHEADER
The object represents a column header, providing a visual label for a column in a table.
ROLE_SYSTEM_COMBOBOX
The object represents a combo box; an edit control with an associated list box that provides a set of predefined choices.
ROLE_SYSTEM_CURSOR
The object represents the system mouse pointer.
ROLE_SYSTEM_DIAGRAM
The object represents a graphical image used to diagram data.
ROLE_SYSTEM_DIAL
The object represents a dial or knob. This is also a read-only object with like a speedometer.
ROLE_SYSTEM_DIALOG
The object represents a dialog box or message box.
ROLE_SYSTEM_DOCUMENT
The object represents a document window. A document window is always contained within an application window. This role applies only to multiple-document interface (MDI) windows and refers to the object that contains the MDI title bar.
ROLE_SYSTEM_DROPLIST
The object represents a drop-down list box. It shows one item and allows the user to display and select another from a list of alternative values.
ROLE_SYSTEM_EQUATION
The object represents a mathematical equation.
ROLE_SYSTEM_GRAPHIC
The object represents a picture.
ROLE_SYSTEM_GRIP
The object represents a special mouse pointer, which allows a user to manipulate user interface elements such as a window. For example, a user clicks and drags a sizing grip in the lower-right corner of a window to resize it.
ROLE_SYSTEM_GROUPING
The object logically groups other objects. There is not always a parent-child relationship between the grouping object and the objects it contains.
ROLE_SYSTEM_HELPBALLOON
The object displays help in the form of a ToolTip or help balloon.
ROLE_SYSTEM_HOTKEYFIELD
The object represents a hot-key field that allows the user to enter a combination or sequence of keystrokes.
ROLE_SYSTEM_INDICATOR
The object represents an indicator such as a pointer graphic that points to the current item.
ROLE_SYSTEM_LINK
The object represents a link to something else. This object might look like text or a graphic, but it acts like a button.
ROLE_SYSTEM_LIST
The object represents a list box, allowing the user to select one or more items.
ROLE_SYSTEM_LISTITEM
The object represents 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
The object represents the menu bar, following (beneath) the title bar of a window, from which menus are selected by the user.
ROLE_SYSTEM_MENUITEM
The object represents a menu item, which is an entry in a menu that a user can choose to carry out a command, select an option, or display another menu. Functionally, a menu item is equivalent to a push button, radio button, check box, or menu.
ROLE_SYSTEM_MENUPOPUP
The object represents a menu, which presents a list of options from which the user can make a selection to perform an action. All menu types must have this role, including drop-down menus that are displayed by selection from a menu bar, and shortcut menus that are displayed when the right mouse button is clicked.
ROLE_SYSTEM_OUTLINE
The object represents an outline or tree structure, such as a tree view control, which displays a hierarchical list and allows the user to expand and collapse branches.
ROLE_SYSTEM_OUTLINEITEM
The object represents an item in an outline or tree structure.
ROLE_SYSTEM_PAGETAB
The object represents a page tab. The only child of a page tab control is a ROLE_SYSTEM_GROUPING object that contains the contents of the associated page.
ROLE_SYSTEM_PAGETABLIST
The object represents a container of page tab controls.
ROLE_SYSTEM_PANE
The object represents a pane within a frame or document window. Users can navigate between panes and within the contents of the current pane, but cannot navigate between items in different panes. Thus, panes represent a level of grouping lower than frame windows or documents, but above individual controls. The user navigates between panes by pressing TAB, F6, or CTRL+TAB, depending on the context.
ROLE_SYSTEM_PROGRESSBAR
The object represents a progress bar, dynamically showing the user the percent complete of an operation in progress. This control takes no user input.
ROLE_SYSTEM_PROPERTYPAGE
The object represents a property sheet.
ROLE_SYSTEM_PUSHBUTTON
The object represents a push button control.
ROLE_SYSTEM_RADIOBUTTON
The object represents an option button, also called a radio button. It 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. Use ROLE_SYSTEM_GROUPING objects to divide them into separate groups.
ROLE_SYSTEM_ROW
The object represents a row of cells within a table.
ROLE_SYSTEM_ROWHEADER
The object represents a row header, that provides a visual label for a table row.
ROLE_SYSTEM_SCROLLBAR
The object represents a vertical or horizontal scroll bar, which is part of the client area or used in a control.
ROLE_SYSTEM_SEPARATOR
The object is used to visually divide a space into two regions, such as a separator menu item or a bar that divides split panes within a window.
ROLE_SYSTEM_SLIDER
The object represents a slider, which allows the user to adjust a setting in given increments between minimum and maximum values.
ROLE_SYSTEM_SOUND
The object represents a system sound, which is associated with various system events.
ROLE_SYSTEM_SPINBUTTON
The object represents a spin box, which is a control that allows the user to increment or decrement the value displayed in a separate "buddy" control associated with the spin box.
ROLE_SYSTEM_STATICTEXT
The object represents read-only text such as labels for other controls or instructions in a dialog box. Static text cannot be modified or selected.
ROLE_SYSTEM_STATUSBAR
The object represents a status bar, which is an area at the bottom of a window that displays information about the current operation, state of the application, or selected object. The status bar has multiple fields, which display different kinds of information.
ROLE_SYSTEM_TABLE
The object represents a table that contains rows and columns of cells, and optionally, row headers and column headers.
ROLE_SYSTEM_TEXT
The object represents selectable text that allows edits or is read-only.
ROLE_SYSTEM_TITLEBAR
The object represents a title or caption bar for a window.
ROLE_SYSTEM_TOOLBAR
The object represents a toolbar, which is a grouping of controls that provide easy access to frequently used features.
ROLE_SYSTEM_TOOLTIP
The object represents a ToolTip that provides helpful hints.
ROLE_SYSTEM_WHITESPACE
The object represents blank space between other objects.
ROLE_SYSTEM_WINDOW
The object represents the window frame, which contains child objects such as a title bar, client, and other objects contained in a window.


Object State Constants

The following values, defined in oleacc.h, describe the states of objects. An object is associated with one or more of these state values at any time.

Clients retrieve an object's state by calling IAccessible::get_accState, which returns a string or an integer that is a combination of the following bit flags. Clients call GetStateText with the state value to retrieve a localized string that describes the object's state. The localized strings for the state values are in the file oleaccrc.dll.

When the state of an object changes, servers should call NotifyWinEvent with the EVENT_OBJECT_STATECHANGE WinEvent.

The following are object state constants:

STATE_SYSTEM_ALERT_HIGH
Indicates important information to convey to the user immediately. For example, a battery level indicator that reaches a critical low level transitions to this state, in which case a blind access utility announces this information immediately to the user, and a screen magnification program scrolls the screen so the battery indicator is in view. This state is also appropriate for any prompt or operation that must be completed before the user can continue.
STATE_SYSTEM_ALERT_MEDIUM
Indicates important information that is not conveyed to the user immediately. For example, when a battery level indicator is starting to reach a low level, it generates a medium-level alert. Blind access utilities 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_ALERT_LOW
Indicates low-priority information that is not important to the user. This state is used, for example, when Word changes the appearance of the TipWizard button on its toolbar to indicate that it has a hint for the user.
STATE_SYSTEM_ANIMATED
The object's appearance changes rapidly or constantly. Graphics that are occasionally animated are described as ROLE_SYSTEM_GRAPHIC with the State property set to STATE_SYSTEM_ANIMATED. This state is be used to indicate that the object's location is changing.
STATE_SYSTEM_BUSY
The control cannot accept input at this time.
STATE_SYSTEM_CHECKED
The object's check box is selected.
STATE_SYSTEM_COLLAPSED
Children of this object that have the ROLE_SYSTEM_OUTLINEITEM role are hidden.
STATE_SYSTEM_DEFAULT
The default button or menu item.
STATE_SYSTEM_EXPANDED
Children of this object that have the ROLE_SYSTEM_OUTLINEITEM role are displayed.
STATE_SYSTEM_EXTSELECTABLE
Indicates that an object extends its selection using SELFLAG_EXTENDSELECTION in the IAccessible::accSelect method.
STATE_SYSTEM_FLOATING
The object is not clipped to the boundary of its parent object and does not move automatically when the parent moves.
STATE_SYSTEM_FOCUSABLE
The object is on the active window and ready to receive keyboard focus.
STATE_SYSTEM_FOCUSED
The object has the keyboard focus. Do not confuse object focus with object selection. For more information, see Selection and Focus Properties and Methods.
STATE_SYSTEM_HOTTRACKED
The object is hot-tracked by the mouse, meaning that its appearance has changed to indicate that the mouse pointer is located over it.
STATE_SYSTEM_INVISIBLE
Object is hidden or not visible. A list of files names in a list box contain several hundred names, but only a few are visible to the user. The rest are clipped by the parent and have STATE_SYSTEM_INVISIBLE set. Objects that are never visible are set as STATE_SYSTEM_OFFSCREEN. Note that an object is considered visible when the STATE_SYSTEM_INVISIBLE flag is not set, and yet obscured by another application, so is not visible to the user. For example, an object is considered visible if it appears in the main window of an application even though it is obscured by a dialog.
STATE_SYSTEM_MARQUEED
Indicates scrolling or moving text or graphics.
STATE_SYSTEM_MIXED
Indicates that the state of a three-state check box or toolbar button is not determined. The check box is neither checked nor unchecked and is therefore in the third or mixed state.
STATE_SYSTEM_MULTISELECTABLE
Object accepts multiple selected items, SELFLAG_ADDSELECTION for the IAccessible::accSelect method is valid.
STATE_SYSTEM_OFFSCREEN
Indicates that the object has no on-screen representation. A sound or alert object has this state, or a hidden window that is never made visible.
STATE_SYSTEM_PRESSED
The object is pressed.
STATE_SYSTEM_PROTECTED
The object is a password-protected edit control.
STATE_SYSTEM_READONLY
The object is read-only.
STATE_SYSTEM_SELECTABLE
The object accepts selection.
STATE_SYSTEM_SELECTED
The object is selected.
STATE_SYSTEM_SELFVOICING
The object or child uses text-to-speech (TTS) for description purposes. A speech-based accessibility aid does not announce information when an object with this state has the focus because the object automatically announces information.
STATE_SYSTEM_UNAVAILABLE
The object is unavailable.


SELFLAG

The SELFLAG constant describes how an accessible object becomes selected or takes 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
A NO-OP that does not change the selection or focus.
SELFLAG_TAKEFOCUS
Sets the focus to the object and makes it the selection anchor. Used by itself, this flag does not alter the selection, and similarly moves the focus manually by pressing the arrow keys while holding down the CTRL key in Windows Explorer or in any multiple-selection list box.

With objects that have the state STATE_SYSTEM_MULTISELECTABLE, SELFLAG_TAKEFOCUS is combined with the following values:

  • SELFLAG_TAKESELECTION
  • SELFLAG_EXTENDSELECTION
  • SELFLAG_ADDSELECTION
  • SELFLAG_REMOVESELECTION
  • SELFLAG_ADDSELECTION | SELFLAG_EXTENDSELECTION
  • SELFLAG_REMOVESELECTION | SELFLAG_EXTENDSELECTION

If you call IAccessible::accSelect with the SELFLAG_TAKEFOCUS flag on an object that has an HWND, the flag takes effect only if the object's parent already has the focus.

SELFLAG_TAKESELECTION
Selects the object and removes the selection from all other objects in the container.

This flag does not change the focus or the selection anchor unless it is combined with SELFLAG_TAKEFOCUS. The SELFLAG_TAKESELECTION | SELFLAG_TAKEFOCUS is equivalent to single-clicking an item in Windows Explorer.

This flag must not be combined with the following flags:

  • SELFLAG_ADDSELECTION
  • SELFLAG_REMOVESELECTION
  • SELFLAG_EXTENDSELECTION.
SELFLAG_EXTENDSELECTION
Alters the selection so that all objects between the selection anchor and this object take on the anchor object's selection state. If the anchor object is not selected, the objects are removed from the selection; if the anchor object is selected, the selection is extended to include this object and all the objects in between. Set the selection state by combining this flag with SELFLAG_ADDSELECTION or SELFLAG_REMOVESELECTION.

This flag does not change the focus or the selection anchor unless it is combined with SELFLAG_TAKEFOCUS. The SELFLAG_EXTENDSELECTION | SELFLAG_TAKEFOCUS is equivalent to adding an item to a selection manually by holding down the SHIFT key and clicking an unselected object in Windows Explorer.

  • This flag is not combined with SELFLAG_TAKESELECTION.
SELFLAG_ADDSELECTION
Adds the object to the current selection, possible result is a noncontiguous selection.

This flag does not change the focus or the selection anchor unless it is combined with SELFLAG_TAKEFOCUS. The SELFLAG_ADDSELECTION | SELFLAG_TAKEFOCUS is equivalent to adding an item to a selection manually by holding down the CTRL key and clicking an unselected object in Windows Explorer.

  • This flag is not combined with SELFLAG_REMOVESELECTION or with SELFLAG_TAKESELECTION.
SELFLAG_REMOVESELECTION
Removes the object from the current selection, possible result is a noncontiguous selection.

This flag does not change the focus or the selection anchor unless it is combined with SELFLAG_TAKEFOCUS. The SELFLAG_REMOVESELECTION | SELFLAG_TAKEFOCUS is equivalent to removing an item from a selection manually by holding down the CTRL key while clicking a selected object in Windows Explorer.

  • This flag is not combined with SELFLAG_ADDSELECTION or with SELFLAG_TAKESELECTION.

Remarks

For information on how to perform complex selection operations, see Selecting Child Objects.

In summary, the following flag combinations are not allowed:

  • SELFLAG_ADDSELECTION | SELFLAG_REMOVESELECTION
  • SELFLAG_ADDSELECTION | SELFLAG_TAKESELECTION
  • SELFLAG_REMOVESELECTION | SELFLAG_TAKESELECTION
  • SELFLAG_EXTENDSELECTION | SELFLAG_TAKESELECTION

Note to clients Active Accessibility does not support the selection of the text contained in edit and rich edit controls because the text is exposed as a string in the object's Value property.

See Also

IAccessible::accSelect, Selecting Child Objects


Return Values

Clients do use the COM macros SUCCEEDED and FAILED to test IAccessible return values because values other than S_OK are considered a success. For example, a method returns S_FALSE, which is considered a success by the SUCCEEDED macro, but still receives a NULL pointer in an output parameter. Only a return value equal to S_OK is considered successful.

Clients ensure that all the output parameters contain valid information. Clients check output parameters to ensure that:

  • All pointers are non-NULL.
  • The vt member of the VARIANT structures is not equal to VT_EMPTY.

The IAccessible methods return one of the following values, defined in winerror.h, or another standard COM error code.

DISP_E_MEMBERNOTFOUND
The 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 does not have a value property.
E_INVALIDARG
One or more arguments were invalid. This error occurs when the caller attempts to identify a child object using an identifier that the server does not recognize. This error also results 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 occurs when a client calls a method that is not 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 happens when the method succeeds, but the requested information is not available. For example, this return value results if you call IAccessible::accHitTest to retrieve a child object at a given point, and the specified point is not within the object or the object's child.
S_OK
The method succeeded.


Notes for Visual Basic Developers

This section provides information about Microsoft® Active Accessibility® for Microsoft Visual Basic® developers.

For more information, see the following:

  • Visual Basic Method Notes: accName
  • Visual Basic Method Notes: accValue
  • Visual Basic Sample Programs


Visual Basic Method Notes: accName

The Object Description Language (ODL) file, oleacc.odl, contains information that differs from the C/C++ implementation. The file oleacc.odl contains the following definition for the version that sets the property 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 from the C/C++ implementation. The file oleacc.odl contains the following definition for the version that sets the property 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 Programs

The Active Accessibility SDK includes the VBInsp sample program that demonstrates how to call the IAccessible properties to obtain information about the object at the current mouse location.

The book Advanced Microsoft Visual Basic 6.0, 2nd Edition (Mandelbrot Set International, Ltd.) includes a chapter that discusses Active Accessibility. The chapter provides sample code that demonstrates how to use key Active Accessibility APIs. (Microsoft Press, ISBN 1-57231-893-7)


Active Accessibility Appendixes

  • The following topics are covered:
  • Appendix A: Supported User Interface Elements Reference
  • Appendix B: Standard Dialog Manager Support
  • Appendix C: IAccessible DISPIDs


Appendix A: Supported User Interface Elements Reference

This reference contains information about the system-provided user interface (UI) elements exposed by Microsoft® Active Accessibility® in Microsoft® Windows® 95, Windows® 98, Windows NT version 4.0, and Windows® 2000. This support allows client utilities to get information about system-provided UI elements in applications that do not implement Active Accessibility. The supported UI elements include:

  • Predefined controls, defined in User32.dll, such as list boxes.
  • Common controls, defined in Comctl32.dll, such as tool bars.
  • Window elements, UI elements such as title bars and menus.

Although some support for system-provided UI elements is provided by Active Accessibility on Microsoft Windows NT 4.0 service pack 4 (SP4), this support is limited. For more information, see Support Provided on Windows NT 4.0.

This appendix lists the IAccessible properties and methods that Active Accessibility supports for each UI element. Where applicable, the documentation also lists the WinEvents that the UI element triggers and includes additional information about the supported properties and methods.

These details can help client developers avoid making unnecessary calls to unsupported properties and methods. The information also provides server developers with a guide for the properties and methods their custom controls should support and the WinEvents that the controls should trigger.

For more information, see the following:

  • How Active Accessibility Exposes User Interface Elements
  • Providing the Name Property
  • Support Provided on Windows NT 4.0
  • Unsupported User Interface Elements

Supported User Interface Elements

  • Animation Control
  • Pop-up Menu
  • Calendar Control
  • Progress Bar Control
  • Caret
  • Push Button
  • Check Box
  • Radio Button
  • Client Object
  • Scroll Bar
  • Combo Box
  • Size Grip
  • Cursor
  • Slider Control
  • Desktop Window
  • Static Text
  • Dialog Box
  • Status Bar Control
  • Edit Control
  • Switch Window
  • Header Control
  • Tab Control
  • Hot Key Control
  • Toolbar Control
  • List Box
  • ToolTip Control
  • List View Control
  • Title Bar
  • MDI Client Window
  • Tree View Control
  • Menu Bar
  • Up-Down Control
  • Menu Item
  • Window


How Active Accessibility Exposes User Interface Elements

Active Accessibility creates a proxy object for each user interface element that it exposes. A proxy object acts as an intermediary between the client utility and the user interface element. The purpose of the proxy object is to monitor the life span of the UI element and to implement the IAccessible properties and methods on behalf of the UI element. Server developers who create custom controls or other custom UI elements should also create proxy objects. For more information, see Creating Proxy Objects.

When Active Accessibility creates an object to expose a predefined or common control, it actually creates at least two objects: one for the control and one for the window that surrounds the control. In most cases, these parent windows have the Role property of ROLE_SYSTEM_WINDOW and have the same Name property and window class name as the control. The information about the control that clients convey to end users is contained in the object that Active Accessibility creates to expose the control, not the parent object that exposes the window that surrounds the control.

Screening Out Unnecessary Objects

If you use either of the Active Accessibility SDK tools Inspect Objects or Accessible Explorer to examine a simple control such as an OK push button in the WordPad accessory, you can see that these parent window objects also contain several invisible child objects. These invisible objects have the same window class name as the control and have the State property of STATE_SYSTEM_INVISIBLE. Following are the invisible child objects that Active Accessibility creates for the control:

Name | Role | ChildCount
"System" | ROLE_SYSTEM_MENUBAR | 0
None | ROLE_SYSTEM_TITLEBAR | 5
"Application" | ROLE_SYSTEM_MENUBAR | 0
"Vertical" | ROLE_SYSTEM_SCROLLBAR | 5
"Horizontal" | ROLE_SYSTEM_SCROLLBAR | 5
"Size Box" | ROLE_SYSTEM_GRIP | 0

Client developers must identify and filter out these parent window objects and invisible child objects because they do not provide meaningful information to end users.


Providing the Name Property

Server developers must take care when creating predefined and common controls to ensure that Active Accessibility can expose the Name property for the control. Depending on the kind of control, the text for the Name property comes from one of the following:

  • The control's window text (or caption).
  • Static text that labels the control.

To find the control's window text, Active Accessibility sends the WM_GETTEXT message to the control. This text corresponds to the text parameter in the control's resource definition statement. For some controls, such as buttons, this is the same text that is displayed with the control. For other controls, such as toolbars, this text is not displayed. Therefore, server developers must provide meaningful text in the control's resource definition statement to help users of client utilities identify the control.

To find the control's label, Active Accessibility searches for a static text control by calling GetWindow with the GW_HWNDPREV flag. The search is halted if a static text control is found, or if a control is encountered that has the window styles WS_GROUP | WS_TABSTOP. This search order corresponds to the reverse tab order on a dialog box. Server developers must observe the tab order when creating controls so that a static text control immediately precedes the control that it labels.

The documentation in this appendix describes which of the above techniques Active Accessibility uses to expose the Name.


Support Provided on Windows NT 4

Platform SDK: Accessibility

Support Provided on Windows NT 4.0

[This is preliminary documentation and subject to change.]

Active Accessibility provides the same support for common controls, defined in Comctl32.dll on Windows NT 4.0 SP 4 as it does on Windows 95 and Windows 98.

Support for other system-provided UI elements on Windows NT 4.0 SP4 is limited. In general, any control defined in User32.dll is not fully supported. Very few WinEvents are triggered for these controls, which makes obtaining an IAccessible interface pointer difficult. While some of the controls support some IAccessible properties and methods, the following system-provided UI elements are not supported at all:

  • Combo boxes
  • Menus
  • Scroll bars
  • Task switch window
  • Title bars

Although clients obtain an IAccessible interface pointer to these objects, the IAccessible properties and methods for these objects return an error or return generic information about the object based on the window class name.


Unsupported User Interface Elements

Active Accessibility does not support the following common controls:

Control Name | Window Class Name
Date and time picker controls | DATETIMEPICK_CLASS
IP address controls | WC_IPADDRESS
Pager controls | WC_PAGESCROLLER
Rebar controls | REBARCLASSNAME

Active Accessibility does not support the following predefined controls and window elements:

Window Class Name | Description
DDEMLEvent | Windows NT: The class for DDEML events.
Message | Windows 2000 and later: The class for a message-only window.
#32772 | Windows NT: The class for icon titles.


Animation Control

Animation controls silently display an audio video interleaved (AVI) clip. Animation controls are usually displayed when files are being copied, or when some other time-consuming task is being performed.

The window class name for an animation control is ANIMATE_CLASS, which is defined as "SysAnimate32" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accKeyboardShortcut
Animation controls do not have keyboard shortcuts. However, if the label for the control contains an access key, an underlined character in the text of the control's label, the KeyboardShortcut returns a non-NULL string. This string contains the access key character appended to the string "Alt+". For example, if the label is "Downloading Files", the KeyboardShortcut is "Alt+d".
get_accName
The Name is obtained from the static text control that labels the animation control. When creating controls, server developers must ensure that a static text control immediately precedes the control that it labels within the tab order.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_ANIMATION.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_ANIMATED

Events Generated

None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Calendar Control

Calendar controls provide a simple and intuitive way for a user to select a date from a familiar interface.

The window class name for a calendar control is MONTHCAL_CLASS, which is defined as "SysMonthCal32" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
The ChildCount is zero.
get_accFocus
get_accName
The Name is obtained from the static text control that labels the calendar control. When creating controls, server developers must ensure that a static text control immediately precedes the control that it labels within the tab order.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_CLIENT.
get_accState
The State property is a combination of one or more of the following values

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Caret

The caret is a flashing line, block, or bitmap in the client area of a window or in a control that accepts keyboard input. It indicates the place at which text or graphics are inserted. Because only one window at a time has the keyboard focus, there is only one caret in the system.

Properties and Methods Supported

accHitTest
accLocation
get_accChildCount
The ChildCount is zero.
get_accName
The Name is "Edit".
get_accRole
The Role is ROLE_SYSTEM_CARET.
get_accState
Possible values for the State property are:

zero, which means the caret is visible, or STATE_SYSTEM_INVISIBLE.

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_SHOW
  • EVENT_OBJECT_HIDE
  • EVENT_OBJECT_LOCATIONCHANGE

Remarks

Unlike other UI elements, the caret object does not have an associated window handle. To obtain access to the caret object, clients must set a WinEventProc callback function and wait for the caret object to generate events.

The caret object in the rich edit control provided by Riched20.dll, which is used in text editors such as WordPad in Windows 98, does not send any WinEvents when its position is changed during text selection. When users press SHIFT and arrow keys to select text, the caret object does not trigger the EVENT_OBJECT_LOCATIONCHANGE WinEvent. Similarly, when the selection is set programmatically through rich edit messages, the caret object does not send any events to indicate its new position.

All applications that use Riched20.dll exhibit this problem. Applications using earlier versions of the rich edit control correctly send events based on the selection.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Check Box

Check boxes are used to enable or disable one or more features or options from a set, usually within a dialog box. Typically, a check box contains a small box with text next to it. When an option is selected, a check mark appears in the box.

The window class name for a check box is "BUTTON".

Properties and Methods Supported

accDoDefaultAction
The DoDefaultAction method calls PostMessage with the BM_CLICK button message to click the check box.
accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accDefaultAction
The DefaultAction of a check box depends on whether it is selected. A check box that is not selected has "Check" as its DefaultAction, and a check box that is selected has "UnCheck" as its DefaultAction. The DefaultAction for a three-state check box is "Toggle".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the check box's access key, which is an underlined character in the control's window text. This string contains the access key character appended to the string "Alt+".
get_accName
The Name is obtained from the control's window text (or caption), which is displayed with the check box.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_CHECKBUTTON.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_MIXED | STATE_SYSTEM_CHECKED

Events Generated

  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_NAMECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Client Object

The client area is the part of a window where the application displays output, such as text or graphics. For example, a desktop publishing application displays the current page of a document in the client area.

Server application developers are responsible for creating accessible object(s) that provide information about the contents of the application's client area.

If a client requests information about a custom user interface element within an application that does not support the IAccessible interface, Active Accessibility creates a default accessible object, the client object, with minimal information.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
get_accFocus
get_accKeyboardShortcut
get_accName
Sends the WM_GETTEXT message to retrieve the window text.
get_accParent
get_accRole
The Role is ROLE_SYSTEM_CLIENT.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Combo Box

A combo box is a list box combined with a static control or an edit control that displays the currently selected item in the list box portion of the combo box. The list box portion of the control is displayed at all times or only drop down when the user selects the drop-down arrow, which is a push button, next to the control. If the selection field is an edit control, the user can enter information not in the list; otherwise, the user can only select items in the list.

The window class name for a combo box is "COMBOBOX".

The contents of the IAccessible properties depend on which of the following parts of the combo box is queried by the client:

  • The combo box window.
  • The edit control or static text control.
  • The drop-down arrow, which is a push button.
  • The list box.
  • The list items in the list box.

Properties and Methods Supported

accDoDefaultAction
Combo Box Part | DoDefaultAction
Combo box window | None.
Edit control | None.
Drop-down arrow | Either drops down or closes the list.
List box | None.
List item | Selects the list item.

accHitTest
accLocation
accNavigate
get_accChild
get_accChildCount
Combo Box Part | ChildCount
Combo box window | 3
Edit control | 0
Drop-down arrow | 0
List box | The number of list items.
List item | 0

get_accDefaultAction
Combo Box Part | DefaultAction
Combo box window | None.
Edit control | None.
Drop-down arrow | "Open" or "Close" depending on the state of the drop-down list.
List box | None.
List item | "Double Click".

get_accKeyboardShortcut
Combo Box Part | KeyboardShortcut
Combo box window | Access key of associated label.
Edit control | None.
Drop-down arrow | "Alt+Down Arrow".
List box | None.
List item | None.

The access key for a combo box is the underlined character in the text from an associated static text control that labels the combo box. For example, on a standard Open dialog box that opens files, such as in WordPad, the combo box labeled "Files of type:" has the KeyboardShortcut "Alt+t".

get_accName
Combo Box Part | Name
Combo box window | Static text control used as a label.
Edit control | Static text control used as a label.
Drop-down arrow | "Open" or "Close" depending on the state of the drop-down list.
List box | Associated label.
List item | Text of the list item.

The Name of a combo box, its child edit control, and its child list box is the text from an associated static text control that labels the combo box. For example, on a standard Open dialog box that opens files, such as in WordPad, the Name properties for the two combo boxes are "Look in:" and "Files of type:".

get_accParent
Combo Box Part | Parent
Combo box window | A window with the Role of ROLE_SYSTEM_WINDOW that surrounds the combo box and has the same Name property and window class name as the combo box.
Edit control (or static text control) | The combo box window.
Drop-down arrow | The combo box window.
List box parent window | The combo box window. This window surrounds the list box.
List box | The list box parent window.
List item | The list box.

get_accRole
Combo Box Part | Role
Combo box window | ROLE_SYSTEM_COMBOBOX
Edit control (or static text control) | ROLE_SYSTEM_TEXT or ROLE_SYSTEM_STATICTEXT
Drop-down arrow | ROLE_SYSTEM_PUSHBUTTON
List box | ROLE_SYSTEM_LIST
List item | ROLE_SYSTEM_LISTITEM

get_accState
Combo Box Part | Possible States
Combo box window | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE
Edit control | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE
Drop-down arrow 0, which means the button is visible and not pressed; or STATE_SYSTEM_PRESSED; or

STATE_SYSTEM_INVISIBLE

List box | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FLOATING
List item | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_SELECTABLE | STATE_SYSTEM_SELECTED

get_accValue
Combo Box Part | Value
Combo box window | Text of currently selected list item.
Edit control | Text of currently selected list item.
Drop-down arrow | None.
List box | None.
List item | None.

Events Generated

EVENT_OBJECT_STATECHANGE

Remarks

When accNavigate is called with the NAVDIR_NEXT flag on the list box part of a combo box, it incorrectly navigates to the tray window when it should return VT_EMPTY.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Cursor

A cursor is a small picture whose location on the screen is controlled by a pointing device, such as a mouse, pen, or trackball. When the user moves the pointing device, the Windows operating system moves the cursor.

Properties and Methods Supported

accHitTest
accLocation
get_accChildCount
The ChildCount is zero.
get_accName
Developers can create custom cursors or use the predefined cursors that are identified by their cursor ID. The Name of the cursor depends on its shape and is one of the following:
Cursor Shape | Name
Custom cursor | "Unknown"
IDC_ARROW | "Normal"
IDC_IBEAM | "Edit"
IDC_WAIT | "Wait"
IDC_CROSS | "Graphic"
IDC_UPARROW | "Up"
IDC_SIZENWSE | "NWSE size"
IDC_SIZENESW | "NESW size"
IDC_SIZEWE | "Horizontal size"
IDC_SIZENS | "Vertical size"
IDC_SIZEALL | "Move"
IDC_NO | "Forbidden"
IDC_APPSTARTING | "App start"
IDC_HELP | "Help"

get_accRole
The Role is ROLE_SYSTEM_CURSOR.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FLOATING

Events Generated

  • EVENT_OBJECT_SHOW
  • EVENT_OBJECT_HIDE
  • EVENT_OBJECT_NAMECHANGE

Remarks

Unlike other UI elements, the cursor object does not have an associated window handle. To obtain access to the cursor object, clients must set a WinEventProc callback function and wait for the cursor object to generate events.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Desktop Window

The desktop window displays the desktop list view, which contains icons such as "My Computer", and the task bar that contains the Start button.

This object is rarely queried by clients because the list view and the taskbar cover the entire desktop. The desktop object is retrieved at login time, before the operating system shell displays the list view and taskbar. In some cases, the desktop is obtained when navigating from other objects.

The window class name for the desktop window is "#32769".

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
get_accFocus
get_accName
The Name is "Desktop".
get_accRole
The Role is ROLE_SYSTEM_CLIENT.
get_accSelection
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Dialog Box

A dialog box is a temporary window an application creates to retrieve user input. An application uses dialog boxes to prompt the user for additional information about commands the user has chosen from a menu. A dialog box contains one or more controls (child windows) with which the user enters text, chooses options, or directs the action of the command.

The window class name for dialog boxes is "#32770".

Properties and Methods Supported

accDoDefaultAction
If the dialog box contains a default push button, the DoDefaultAction method calls PostMessage with the BM_CLICK button message to click the default push button.
accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is equal to the number of child window controls on the dialog box.
get_accDefaultAction
If the dialog box contains a default push button, the DefaultAction is "Press".
get_accFocus
get_accKeyboardShortcut
Typically, dialog boxes do not have keyboard shortcuts. If the window text for the dialog box contains an ampersand (&) character, Active Accessibility returns a non-Null string as the KeyboardShortcut.
get_accName
The Name is the window text, or caption, that is displayed in the title bar of the dialog box.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the dialog box and has the same Name property and window class name as the dialog box.
get_accRole
The Role is ROLE_SYSTEM_DIALOG or ROLE_SYSTEM_PROPERTYPAGE.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • EVENT_SYSTEM_ALERT
  • EVENT_SYSTEM_DIALOGSTART
  • EVENT_SYSTEM_DIALOGEND
  • EVENT_OBJECT_DEFACTIONCHANGE

Remarks

The dialog object does not support the get_accChild property. To obtain an IAccessible interface pointer to a control on a dialog box, clients must obtain the window handle of the control and then call AccessibleObjectFromWindow.

These events are not sent consistently by the system. This is a known problem and is being addressed.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Edit Control

Edit controls let a user view and edit text. Edit controls are created with many different styles such as ES_MULTILINE. This style creates a multi-line edit control, such as the client area of the Windows accessory NotePad, and ES_READONLY, which creates a read-only edit control.

Active Accessibility does not make a distinction between edit controls created with the window class name "EDIT" and rich edit controls created with the window class name "RichEdit" or "RichEdit20A".

Properties and Methods Supported

get_accKeyboardShortcut
The KeyboardShortcut is the edit control's access key, which is an underlined character in the text of the edit control's label. For example, on a standard File Open dialog box such as in WordPad, the KeyboardShortcut for the edit control labeled "File name:" is "Alt+n".
get_accName
The Name is the text from a static text control that labels the edit control. For example, on a standard File Open dialog box such as in WordPad, the Name property for the edit control is "File name:".
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_TEXT.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_READONLY | STATE_SYSTEM_PROTECTED

get_accValue
The Value property is a single string that contains the text in the edit control. However, if the control is password protected, the Value property returns E_ACCESSDENIED. For multi-line edit controls, the string contains a carriage return and newline character at the end of each line.

Events Generated

  • EVENT_OBJECT_VALUECHANGE

Remarks

Active Accessibility does not support the selection of the text contained in edit and rich edit controls because the text is exposed as a string in the object's Value property.

The rich edit control provided by Riched20.dll, (which is used in text editors such as WordPad in Windows 98, does not send any WinEvents when the caret position is changed during text selection. When users press SHIFT and arrow keys to select text, the caret object does not trigger the EVENT_OBJECT_LOCATIONCHANGE WinEvent. When the selection is set programmatically through rich edit messages, the caret object does not send any events to indicate its new position.

All applications that use Riched20.dll exhibit this problem. Applications using earlier versions of the rich edit control correctly send events based on the selection.

The State value for password edit controls always includes the bit flag STATE_SYSTEM_PROTECTED.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Group Box

A group box is a rectangle that surrounds a set of controls, such as check boxes or radio buttons, and contains an application-defined text (label).

The sole purpose of a group box is to organize controls related by a common purpose, indicated by the label.

The window class name for a group box is "BUTTON".

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is always zero.
get_accFocus
get_accKeyboardShortcut
Group boxes do not have keyboard shortcuts. However, if the window text for the group box contains an ampersand (&) character, Active Accessibility returns a non-Null string as the KeyboardShortcut.
get_accName
The Name is obtained from the control's window text (or caption), which is displayed with the group box.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_GROUPING.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Header Control

A header control displays headings at the top of columns of information and lets the user sort the information by clicking the headings. Windows Explorer uses a header control when the Details view is selected.

The window class name for a header control is WC_HEADER, which is defined as "SysHeader32" in commctrl.h.

Properties and Methods Supported

accDoDefaultAction
The DoDefaultAction method clicks the header.
accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accDefaultAction
The DefaultAction is "Click".
get_accFocus
get_accName
The Name property is the same as the name of the column header.
get_accParent
The Parent is a window (ROLE_SYSTEM_LIST) that surrounds the control and has the same window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_COLUMNHEADER.
get_accState
The value for the State property is always STATE_SYSTEM_READONLY and can also include STATE_SYSTEM_INVISIBLE.

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_REORDER
  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_VALUECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Hot Key Control

Hot key controls allow a user to enter a combination of keystrokes used as a hot key, which enables users to perform an action quickly. A hot-key control displays the keystrokes entered by the user and ensures that the user selects a valid key combination.

The window class name for a hot key control is HOTKEY_CLASS, which is defined as "msctls_hotkey32" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is always zero.
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the hot key control's access key, which is an underlined character in the text of the hot key control's label. The returned string contains the access key character appended to the string "Alt+".
get_accName
The Name is the text from a static text control that labels the hot key control.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_HOTKEYFIELD.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

get_accValue
The Value property is a string that contains the text in the hot key field.

Events Generated

  • EVENT_OBJECT_VALUECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


List Box

List boxes display a list from which a user can select one or more items. A list box is created with a vertical scroll bar, a horizontal control bar, or both.

The window class name for a list box is "LISTBOX".

Properties and Methods Supported

accDoDefaultAction
The list box object itself does not have a DefaultAction; however, DoDefaultAction double clicks list box items.
accHitTest
The HitTest method returns zero if the tested point is within the list box but not on an item in the list box. If the tested point is on an item in the list box, HitTest returns the index of the list box item.
accLocation
accNavigate
accSelect
get_accChildCount
The ChildCount is the number of items in the list box.
get_accDefaultAction
The list box object itself does not have a DefaultAction; however, the DefaultAction for each list item is "Double Click".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the list box's access key, which is an underlined character in the text of the label associated with the list box. The returned string contains the access key character appended to the string "Alt+".
get_accName
The Name for the list box object is the text from a static text control that labels the list box. For the list box items, the Name is the text of the list item.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the list box and has the same Name property and window class name as the list box. The Parent of the list box items is the list box object.
get_accRole
The Role property is ROLE_SYSTEM_LIST. The items in the list box have the Role ROLE_SYSTEM_LISTITEM.
get_accSelection
The Selection property retrieves the selected items in the list box.
get_accState
The State property of the list box object is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

The State property of the list box item is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_SELECTABLE | STATE_SYSTEM_SELECTED

Events Generated

  • EVENT_OBJECT_SELECTIONADD
  • EVENT_OBJECT_SELECTIONREMOVE
  • EVENT_OBJECT_SELECTIONWITHIN

Remarks

Because the list box object does not support get_accChild, the items in the list box are simple elements, that is, they do not support the IAccessible interface themselves. The list box object provides information about the items.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface, Combo Box, Scroll Bar


List View Control

A list view control displays a collection of items, each consisting of an icon and a label, and provides several ways to display and arrange the items. For example, additional information about each item is displayed in columns to the right of the icon and label. Microsoft Windows Explorer uses a list view control to display files.

The window class name for a list view control is WC_LISTVIEW, which is defined as "SysListView" in commctrl.h.

Properties and Methods Supported

accDoDefaultAction
The list view object itself does not have a DefaultAction; however, DoDefaultAction double clicks list view items.
accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
Returns the number of items in the list.
get_accDefaultAction
The list view object itself does not have a DefaultAction; however, the DefaultAction for each list view item is "Double Click".
get_accDescription
The list view object itself does not support the Description property; however, the Description for each list view item is the text contained in the item's second and subsequent columns. A comma is inserted between the text for each column.
get_accFocus
get_accKeyboardShortcut
List views objects do not have keyboard shortcuts. However, if the window text for the list view contains an ampersand (&) character, Active Accessibility returns a non-Null string as the KeyboardShortcut.
get_accName
The Name for the list view object is obtained from the control's window text (or caption). This text is not displayed with the list view control, so server developers must provide meaningful text in the control's resource definition statement to help users of client utilities to identify the control. For the list view items, the Name is the text of the list item.
get_accParent
The Parent of the list view object is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control. The Parent of the list view items is the list view object.
get_accRole
The list view window has the Role ROLE_SYSTEM_LIST, and each item in the list view has the Role ROLE_SYSTEM_LISTITEM.
get_accSelection
get_accState
The State property of the list view object is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

The State property of the list view items is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_SELECTABLE | STATE_SYSTEM_SELECTED | STATE_SYSTEM_MULTISELECTABLE | STATE_SYSTEM_HOTTRACKED

Additionally, check box list view items also have the state STATE_SYSTEM_CHECKED.

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_REORDER
  • EVENT_OBJECT_FOCUS
  • EVENT_OBJECT_SELECTION
  • EVENT_OBJECT_SELECTIONADD
  • EVENT_OBJECT_SELECTIONREMOVE
  • EVENT_OBJECT_NAMECHANGE

Remarks

Because the list view object does not support get_accChild, the items in the list view are simple elements. They do not support the IAccessible interface themselves. The list view object provides information about the items.

Active Accessibility does not expose list view item text in applications that use a callback function to add the text to the item.

List view items that are clipped do not have STATE_SYSTEM_INVISIBLE set. To determine if a list item is clipped, clients can compare the item's coordinates returned by accLocation with the clipping region of the window.

Active Accessibility does not support using the accNavigate method to navigate to the header control within a list view control that is in Details view. However, clients use the AccessibleObjectFromPoint function to get to the header control.

For non-rectangular objects such as list view items in the Details view, the coordinates of the item's bounding rectangle retrieved by accLocation fail if tested with accHitTest because accHitTest determines the object's boundaries on a pixel-by-pixel basis.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


MDI Client Window

The multiple document interface (MDI) is a specification that defines the standard user interface for applications written for Windows. An MDI application enables a user to work with more than one document at a time.

An MDI application has three kinds of windows: a frame window, a client window, and a number of child windows. The frame window is like the main window of an application, and it surrounds the client window. The client window is a child of the frame window and serves as the background for the child windows. The client window also provides support for creating and manipulating the child windows in which documents are displayed.

The window class name for an MDI client window is "MDIClient".

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is the number of child windows in which documents are displayed.
get_accFocus
get_accName
The Name is "Workspace".
get_accParent
The Parent is the MDI frame window.
get_accRole
The Role is ROLE_SYSTEM_CLIENT.
get_accSelection
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Menu Bar

A menu bar is the area of a window immediately beneath the title bar and contains menu items such as File, Edit, Window, and Help. Active Accessibility also creates a menu bar object for a system menu, which is the menu in the top, left corner of the title bar and contains menu items such as Restore, Move, Size, Minimize, and Maximize.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
accSelect
get_accChild
Retrieves the IDispatch interface for the specified menu item. The child IDs for the menu items are numbered sequentially from left to right starting with one.
get_accChildCount
The ChildCount is the number of menu items on the menu bar. The ChildCount for a system menu is one.
get_accDescription
The Description property for a menu bar is "Contains commands to manipulate the current view or document". The Description property for a system menu is "Contains commands to manipulate the window".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut for a menu bar beneath the title bar is "Alt". The KeyboardShortcut for a system menu is "Alt+Space".
get_accName
The Name property for a menu bar beneath the title bar is "Application". The Name property for a system menu is "System".
get_accRole
The Role is ROLE_SYSTEM_MENUBAR.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • EVENT_SYSTEM_MENUSTART
  • EVENT_SYSTEM_MENUEND
  • EVENT_SYSTEM_MENUPOPUPSTART
  • EVENT_SYSTEM_MENUPOPUPEND
  • EVENT_OBJECT_FOCUS

Remarks

The system triggers more than one EVENT_SYSTEM_MENUSTART event that does not always have a corresponding EVENT_SYSTEM_MENUEND event. Additionally, the system does not trigger the EVENT_SYSTEM_MENUPOPUPSTART and EVENT_SYSTEM_MENUPOPUPEND events consistently. This is a known problem and is being addressed.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Menu Item, Pop-up Menu


Menu Item

A menu item represents a particular item in a menu bar or pop-up menu. For example, Active Accessibility creates a menu item object for the File menu in the menu bar. Similarly, Active Accessibility creates a menu item object for the Open menu item from the File pop-up menu.

The window class name for a menu item is "#32768".

Properties and Methods Supported

accDoDefaultAction
For menu items from the menu bar, DoDefaultAction either displays or closes the menu depending on the state of the menu. For menu items from a pop-up menu, DoDefaultAction clicks the menu item to execute the menu command.
accHitTest
accLocation
accNavigate
accSelect
get_accChild
Retrieves the IDispatch interface to the pop-up menu object for this item.
get_accChildCount
The ChildCount is one for menu items that display a menu or submenu; otherwise the ChildCount is zero.
get_accDefaultAction
The DefaultAction for menu items that display a menu or submenu is either "Open" or "Close" depending on the state of the menu. The DefaultAction for all other menu items is "Execute".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the menu item's access key, which is the underlined character in the text of the menu item's name. For example, the KeyboardShortcut for the File menu item is "f".
get_accName
The Name property is the same as the name of the menu item.
get_accParent
The Parent is the menu bar or pop-up menu that contains the menu item.
get_accRole
The Role is ROLE_SYSTEM_MENUITEM.
get_accState
The State property is either STATE_SYSTEM_INVISIBLE or a combination of one or more of the following values:

STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_CHECKED | STATE_SYSTEM_DEFAULT | STATE_SYSTEM_HOTTRACKED | STATE_SYSTEM_FOCUSED

Events Generated

  • None

Remarks

When used on a menu item, accDoDefaultAction returns S_OK but fails to perform the action if the character used in the access key is ?, !, @, or any other character that requires the SHIFT key or another modifier key. This also happens on international keyboards with an access key character that requires the ALT GR key to be pressed.

The accSelect method with SELFLAG_TAKEFOCUS does not cause a menu item to open or close a pop-up menu. Clients use the accDoDefaultAction method to open or close a pop-up menu.

A menu bar item that does not display a pop-up menu returns "Application" for the Name property instead of the name of the menu item.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Menu Bar, Pop-up Menu


Pop-up Menu

A popup menu displays a list of menu commands. Active Accessibility creates a menu pop-up object when a menu item in a menu bar is opened. Active Accessibility also creates menu pop-up objects for context menus, which are displayed when the user right-clicks on a user interface element.

The window class name for a pop-up menu is "#32768".

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChild
Retrieves the IDispatch interface for the specified menu item. The child IDs for the menu items are numbered sequentially from top to bottom starting with one.
get_accChildCount
The ChildCount is the number of menu items in the menu including menu separators.
get_accFocus
get_accName
The Name property for a pop-up menu is the same name as the menu. The Name property for a context menu is "Context".
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the pop-up menu and has the same Name property and window class name as the pop-up menu .
get_accRole
The Role is ROLE_SYSTEM_MENUPOPUP.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • EVENT_SYSTEM_MENUSTART
  • EVENT_SYSTEM_MENUEND
  • EVENT_SYSTEM_MENUPOPUPSTART
  • EVENT_OBJECT_FOCUS

Remarks

Pop-up menu objects do not trigger EVENT_OBJECT_CREATE and EVENT_OBJECT_DESTROY events.

Multi-column menus do not support the NAVDIR_LEFT or NAVDIR_RIGHT flags of the accNavigate method.

The events EVENT_SYSTEM_MENUPOPUPSTART and EVENT_SYSTEM_MENUPOPUPEND are not sent consistently. This is a known problem and is being addressed.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Menu Bar, Menu Item


Progress Bar Control

Progress bar controls indicate the progress of a lengthy operation such as downloading a file from the Internet. Usually the progress is expressed as a percentage from zero (0) to one hundred (100).

The window class name for a progress bar control is PROGRESS_CLASS, which is defined as "msctls_progress" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the progress bar's access key, which is an underlined character in the text of the label for the progress bar. The returned string contains the access key character appended to the string "Alt+".
get_accName
The Name is the text from a static text control that labels the progress bar.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_PROGRESSBAR.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

get_accValue
The Value is a string from "0%" to "100%" that describes the progress.

Events Generated

  • EVENT_OBJECT_VALUECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Push Button

A push button is a small, rectangular object used to perform an action. For example, the OK and Cancel buttons on a dialog box are push buttons.

The window class name for a push button is "BUTTON".

Properties and Methods Supported

accHitTest
accDoDefaultAction
The DoDefaultAction method clicks the push button.
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accDefaultAction
The DefaultAction is "Press".
get_accKeyboardShortcut
The KeyboardShortcut is the button's access key, which is an underlined character in the text of the button's window text. For example, "Alt+o" is the KeyboardShortcut for an OK button.
get_accFocus
get_accName
The Name is obtained from the control's window text (or caption), which is displayed in the push button. For example, "OK" is the Name for an OK button.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_PUSHBUTTON.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_PRESSED | STATE_SYSTEM_DEFAULT

Events Generated

  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_NAMECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Check Box, Group Box, Radio Button


Radio Button

Radio buttons are used to select one of several options, usually within a dialog box. A radio button contains a small circle with text next to it. When selected, the circle has a smaller, filled circle inside it. Selecting one button in a set deselects the previously selected button, so only one of the options in the set is selected at a time.

The window class name for a radio button is "BUTTON".

Properties and Methods Supported

accDoDefaultAction
The DoDefaultAction method clicks the radio button.
accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accDefaultAction
The DefaultAction for a radio button is "Check".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the radio button's access key, which is an underlined character in the control's window text. This string contains the access key character appended to the string "Alt+".
get_accName
The Name is obtained from the control's window text (or caption), which is displayed with the radio button.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_RADIOBUTTON.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_CHECKED

Events Generated

  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_NAMECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Check Box, Group Box, Push Button


Scroll Bar

Scroll bars let a user choose the direction and distance to scroll through information in a related window or list box. The window class name for a scroll bar is "SCROLLBAR".

The contents of the IAccessible properties depends on whether the scroll bar is vertical or horizontal and on which of the following parts of the scroll bar is being queried by the client:

  • The scroll bar itself.
  • The top or right arrow button.
  • The bottom or left arrow button.
  • The scroll box (thumb).
  • The page up or page right region.
  • The page down or page left region.

Properties and Methods Supported

accDoDefaultAction
The scroll bar object itself and the scroll thumb do not support the DoDefaultAction method.

For the other scroll bar parts on a vertical scroll bar, DoDefaultAction calls PostMessage with the WM_VSCROLL message with wParam set to the following:
Scroll Bar Part | DoDefaultAction
Top arrow button | SB_LINEUP
Bottom arrow button | SB_LINEDOWN
Page up region | SB_PAGEUP
Page down region | SB_PAGEDOWN

For the other scroll bar parts on a horizontal scroll bar, DoDefaultAction calls PostMessage with the WM_HSCROLL message with wParam set to the following:
Scroll Bar Part | DoDefaultAction
Left arrow button | SB_LINELEFT
Right arrow button | SB_LINERIGHT
Page left region | SB_PAGELEFT
Page right region | SB_PAGERIGHT

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount for the scroll bar object is five. For the other scroll bar parts, the ChildCount is zero.
get_accDefaultAction
The scroll bar object itself and the scroll thumb do not support the DefaultAction property. The DefaultAction for the arrow buttons and the shaded areas on either side of the scroll thumb is "Press".
get_accDescription
The Description depends on the part of the scroll bar that is queried.

The parts of a vertical scroll bar have the following descriptions:
Scroll Bar Part | Description
Scroll bar itself | "Used to change the vertical viewing area"
Top arrow button | "Moves the vertical position up one line"
Bottom arrow button | "Moves the vertical position down one line"
Scroll thumb | "Indicates the current vertical position, and can be dragged to change it directly"
Page up region | "Moves the vertical position up a couple of lines"
Page down region | "Moves the vertical position down a couple of lines"

The parts of a horizontal scroll bar have the following descriptions:
Scroll Bar Part | Description
Scroll bar itself | "Used to change the horizontal viewing area"
Left arrow button | "Moves the horizontal position left one column"
Right arrow button | "Moves the horizontal position right one column"
Scroll thumb | "Indicates the current horizontal position, and can be dragged to change it directly"
Page left region | "Moves the horizontal position left a couple of columns"
Page right region | "Moves the horizontal position right a couple of columns"

get_accName
The Name property depends on the part of the scroll bar that is queried.

The parts of a vertical scroll bar have the following names:
Scroll Bar Part | Name
Scroll bar window | "Vertical"
Top arrow button | "Line up"
Bottom arrow button | "Line down"
Scroll thumb | "Position"
Page up region | "Page up"
Page down region | "Page down"

The parts of a horizontal scroll bar have the following names:
Scroll Bar Part | Name
Scroll bar window | "Horizontal"
Left arrow button | "Column left"
Right arrow button | "Column right"
Scroll thumb | "Position"
Page right region | "Page right"
Page left region | "Page left"

get_accParent
The Parent of the arrow buttons, scroll thumb, and the shaded area on either side of the thumb is the scroll bar window. The Parent of the scroll bar window is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name.
get_accRole
The Role property depends on the part of the scroll bar that is queried.
Scroll Bar Part | Role
Scroll bar itself | ROLE_SYSTEM_SCROLLBAR
Top, down, left, and right arrow buttons | ROLE_SYSTEM_PUSHBUTTON
Scroll thumb | ROLE_SYSTEM_INDICATOR
Page up, page down, page left, and page right regions | ROLE_SYSTEM_PUSHBUTTON

get_accState
The State of each scroll bar component includes a combination of the following values:
Value | Meaning
STATE_SYSTEM_INVISIBLE | For the scroll bar itself, this indicates the specified vertical or horizontal scroll bar does not exist. For the page up or page down regions, this indicates the thumb is positioned such that the region does not exist.
STATE_SYSTEM_OFFSCREEN | For the scroll bar itself, this indicates the window is sized such that the specified vertical or horizontal scroll bar is not currently displayed.
STATE_SYSTEM_PRESSED | The arrow button or page region is pressed.
STATE_SYSTEM_UNAVAILABLE | The component is disabled.

get_accValue
The Value property for the scroll bar window indicates the scroll bar position and is a string that contains an integer from "0" through "100".

Events Generated

  • EVENT_SYSTEM_SCROLLINGSTART
  • EVENT_SYSTEM_SCROLLINGEND
  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_VALUECHANGE

Remarks

Because the scroll bar object does not support get_accChild, the controls on the scroll bar are simple elements, they do not support the IAccessible interface themselves. The scroll bar object provides information about the child controls.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Size Grip

The size grip is a special mouse pointer in the lower-right corner of a window and allows a user to click and drag the size grip to resize the window.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accDescription
The Description is "Can be used to resize a window's width and height".
get_accName
The Name is "Size box".
get_accParent
The window that contains the size grip.
get_accRole
The Role is ROLE_SYSTEM_GRIP.
get_accState
The value for the State property is zero, which means the object is visible, or STATE_SYSTEM_INVISIBLE.

Events Generated

  • None.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Slider Control

A slider control, also called a trackbar control, lets a user select from a range of values by moving a slider. The volume controls in the Windows operating system are slider controls.

The window class name for a slider control is TRACKBAR_CLASS, which is defined as "msctls_trackbar" in commctrl.h.

The contents of the IAccessible properties depends on whether the slider is vertical or horizontal and on which of the following parts of the slider control is queried by the client:

  • Slider window
  • Slider thumb
  • Shaded area above (or to the left of) the slider thumb
  • Shaded area below (or to the right of) the slider thumb

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accKeyboardShortcut
The KeyboardShortcut is the slider window's access key, which is an underlined character in the text of the label for the slider. The returned string contains the access key character appended to the string "Alt+".
get_accName
The Name property depends on the part of the slider that is queried.

The parts of a vertical slider have the following names:
Slider Part | Name
Slider window | Static text control used as a label
Slider thumb | "Position"
Shaded area above slider thumb | "Page up"
Shaded area below slider thumb | "Page down"

The parts of a horizontal slider have the following names:
Slider Part | Name
Slider window | Static text control used as a label
Slider thumb | "Position"
Shaded area to the left of slider thumb | "Page left"
Shaded area to the right of slider thumb | "Page right"

get_accParent
The Parent of the arrow buttons, scroll thumb, and the shaded area on either side of the thumb is the slider window. The Parent of the slider window is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name.
get_accRole
The Role property depends on the part of the slider that is queried.
Slider Part | Role
Slider window | ROLE_SYSTEM_SLIDER
Slider thumb | ROLE_SYSTEM_INDICATOR
Shaded areas on either side of the slider thumb | ROLE_SYSTEM_PUSHBUTTON

get_accState
Values for the State property depend on the part of the slider that is queried.
Slider Part | Possible State Values
Slider window | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE
Slider thumb | Zero (0), which means the object is visible, or STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE
Shaded areas on either side of the slider thumb | Zero (0), which means the object is visible, or STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE

get_accValue
The Value property for the slider window indicates the position of the thumb and is a string that contains an integer from "0" through "100".

Events Generated

  • EVENT_OBJECT_VALUECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface Scroll Bar


Static Text

Static text controls provide a convenient way to display text on dialog boxes and other windows. Static text controls often serve as labels for other controls.

The window class name for a static text control is "STATIC".

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the access key, which is the underlined character in the text that activates the control associated with the static text. The returned string contains the access key character appended to the string "Alt+".
get_accName
The Name is the same as the text in the static text control.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role property is ROLE_SYSTEM_STATICTEXT.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_READONLY | STATE_SYSTEM_INVISIBLE

Events Generated

  • None

Remarks

The accSelect method returns DISP_E_MEMBERNOTFOUND when it is called with SELFLAG_TAKEFOCUS on a static text object.

Static controls with the SS_ICON style returns invalid data in the Name property.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Status Bar Control

Status bars display status information in a horizontal window at the bottom of an application window. Status bars are often divided into parts, called panes, and each pane displays different status information. Additionally, status bars can contain objects of different types, including buttons and progress bars. The window class name for a status bar control is STATUSCLASSNAME, which is defined as "msctls_statusbar32" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is the number of panes in the status bar.
get_accFocus
get_accKeyboardShortcut
get_accName
The status bar object itself does not have a Name. The Name of each pane in the status bar is the same as the displayed text.
get_accParent
The Parent of the status bar object is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same window class name as the control. The Parent of the panes in the status bar is the status bar object.
get_accRole
The Role for the status bar object itself is ROLE_SYSTEM_STATUSBAR. The text displayed in a status bar has ROLE_SYSTEM_STATICTEXT as its Role.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • EVENT_OBJECT_NAMECHANGE

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Switch Window

The switch window displays whenever a user presses ALT+TAB to switch to a different application. The switch window contains an icon for each application currently running.

The window class name for the switch window is "#32771".

Properties and Methods Supported

accDoDefaultAction
The switch window object itself does not have a DefaultAction. The DoDefaultAction method for each item in the switch window activates the specified item.
accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
The ChildCount is zero.
get_accDefaultAction
The switch window object itself does not have a DefaultAction. The DefaultAction for each item in the switch window is "Switch".
get_accFocus
get_accName
The switch window object itself does not have a Name. The Name property for each application icon in the switch window is the same as the displayed application name.
get_accRole
The switch window object itself does not have a Role. Each application icon in the switch window has the Role ROLE_SYSTEM_LISTITEM.
get_accState
The switch window object itself does not support the State property. The State value for the list view items is STATE_SYSTEM_FOCUSABLE.

Events Generated

  • EVENT_SYSTEM_SWITCHSTART
  • EVENT_SYSTEM_SWITCHEND
  • EVENT_OBJECT_FOCUS

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Tab Control

A tab control defines multiple pages for the same area of a window or dialog box. Each page consists of a set of information or a group of controls that an application displays when the user selects the corresponding tab. The Windows operating system uses tab controls to display the taskbar buttons, with the exception of the Start button.

The window class name for a tab control is WC_TABCONTROL, which is defined as "SysTabControl" in commctrl.h.

Properties and Methods Supported

accDoDefaultAction
The DoDefaultAction method clicks the page tab.
accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
get_accDefaultAction
The DefaultAction is "Switch".
get_accFocus
get_accKeyboardShortcut
The KeyboardShortcut is the tab control's access key, which is an underlined character in the control's window text. This string contains the access key character appended to the string "Alt+".
get_accName
The Name is obtained from the control's window text (or caption), which is displayed within the tab control.
get_accParent
The Parent is a window (ROLE_SYSTEM_PAGETABLIST) that surrounds the control and has the same window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_PAGETAB.
get_accSelection
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_SELECTABLE | STATE_SYSTEM_SELECTED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_PRESSED

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_FOCUS
  • EVENT_OBJECT_SELECTION

Remarks

Tab controls incorrectly return S_OK from the accSelect method when called with the SELFLAG_TAKEFOCUS flag. Tab controls cannot take the keyboard focus.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Title Bar

The title bar at the top of a window displays an application-defined icon and line of text. The text specifies the name of the application and or indicates the purpose of the window. The title bar also makes it possible for the user to move the window using a mouse or other pointing device.

Title bars contain at least three small buttons that minimize, maximize or restore, and close the window associated with the title bar. Title bars also contain a context-sensitive Help button. Applications running in the Far-East version of the Windows operating system may also contain Input Method Editor (IME) buttons. Active Accessibility exposes these buttons as child elements of the title bar.

Properties and Methods Supported

accDoDefaultAction
accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
The ChildCount is five. The ChildCount includes the IME and context-sensitive Help buttons even when they are not displayed. Buttons that are not displayed have the State STATE_SYSTEM_INVISIBLE.
get_accDefaultAction
get_accDescription
The Description of the title bar itself is: "Displays the name of the window and contains controls to manipulate it".

The child buttons in the title bar have the following descriptions:

  • "Moves the window out of the way"
  • "Makes the window full screen"
  • "Puts a minimized or maximized window back to normal"
  • "Closes the window"
  • "Enters or leaves context sensitive help mode"
  • "Brings up the keyboard when pressed"
get_accName
The title bar itself does not support the Name property. The child buttons in the title bar have the following names:
  • "Minimize"
  • "Maximize" or "Restore", depending on the size of the window.
  • "Close"
  • "Context help"
  • "IME"
get_accParent
The Parent of the title bar is the main application window (ROLE_SYSTEM_WINDOW) that has the same application-defined window class name as the title bar.
get_accRole
The Role is ROLE_SYSTEM_TITLEBAR. The child buttons in the title bar have the Role ROLE_SYSTEM_PUSHBUTTON.
get_accState
The State property for the title bar and the child buttons can be a combination of one or more of the following values:

STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_OFFSCREEN | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_PRESSED

get_accValue
The Value property is a string that is the same as the text displayed in the title bar.

Events Generated

  • None

Remarks

Although an application's title bar has the State property flag STATE_SYSTEM_FOCUSABLE, it never has the State flag STATE_SYSTEM_FOCUSED. Setting focus to a title bar object focuses the application window.

Because the title bar object does not support get_accChild, the buttons on the title bar are simple elements. They do not support the IAccessible interface themselves. The title bar object provides information about these child buttons.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Toolbar Control

A toolbar control contains buttons that carry out menu commands and is usually contained within a window below the menu bar.

The window class name for a toolbar control is TOOLBARCLASSNAME, which is defined as "ToolbarWindow32" in commctrl.h.

Properties and Methods Supported

accDoDefaultAction
The toolbar itself does support the DefaultAction method. For the buttons on the toolbar, DoDefaultAction calls PostMessage with the BN_CLICK message to click the specified button.
accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is the number of controls contained in the toolbar.
get_accDefaultAction
The toolbar object itself does not have a DefaultAction. The DefaultAction for toolbar buttons depends on the toolbar button style. Buttons with the style TBSTYLE_DROPDOWN have "Open" as their DefaultAction. The DefaultAction for all other toolbar buttons is "Press".
get_accFocus
get_accKeyboardShortcut
Toolbars do not have keyboard shortcuts. However, if the window text for the toolbar contains an ampersand (&) character, Active Accessibility returns a non-Null string as the KeyboardShortcut.
get_accName
The Name for the toolbar is obtained from the control's window text (or caption). This text is not displayed with the toolbar, so server developers must provide meaningful text in the control's resource definition statement to help users of client utilities identify the control.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_TOOLBAR.
get_accState
The value for the State property for the toolbar itself is zero, which means the object is visible. Possible values for the State of the toolbar buttons are:

STATE_SYSTEM_INVISIBLE or

STATE_SYSTEM_CHECKED | STATE_SYSTEM_PRESSED | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_MIXED | STATE_SYSTEM_MOVEABLE

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_REORDER
  • EVENT_OBJECT_STATECHANGE

Remarks

Because the toolbar object does not support get_accChild, the controls on the toolbar are simple elements. They do not support the IAccessible interface themselves. The toolbar object provides information about the controls on the toolbar.

The buttons on a toolbar do not send EVENT_OBJECT_STATECHANGE events.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


ToolTip Control

A ToolTip control displays a small pop-up window that contains a line of text that describes the purpose of a tool, represented as a graphical object, in an application.

The window class name for a ToolTip is TOOLTIPS_CLASS, which is defined as "tooltips_class" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is zero.
get_accFocus
get_accName
The Name is the text contained in the tool tip.
get_accParent
The Parent is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control.
get_accRole
The Role is ROLE_SYSTEM_TOOLTIP.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

Events Generated

  • None

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Tree View Control

A tree view control displays a hierarchical list of items using lines to connect related items in a hierarchy. Each item consists of a label and an optional bitmap. Windows Explorer uses a tree view control to display directories.

The window class name for a tree view control is WC_TREEVIEW, which is defined as "SysTreeView" in commctrl.h.

Properties and Methods Supported

accDoDefaultAction
The tree view object itself does not have a DefaultAction. Depending on the State of an item in the tree view, DoDefaultAction either expands or collapses the specified item.
accHitTest
accLocation
accNavigate
accSelect
get_accChildCount
The ChildCount for the tree view object is the number of items contained in the tree view. The ChildCount for each tree view item is zero.
get_accDefaultAction
The tree view object itself does not have a DefaultAction. An item in the tree view that is expanded has "Collapse" as its DefaultAction, and an item that is not expanded has "Expand" as its DefaultAction.
get_accFocus
get_accName
The Name for the tree view object is obtained from the control's window text (or caption). This text is not displayed with the tree view control, so server developers must provide meaningful text in the control's resource definition statement to help users of client utilities to identify the control. The Name for an item in the tree view is the text displayed in the tree view item.
get_accParent
The Parent of the tree view object is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control. The Parent of each item in the tree view is the tree view object.
get_accRole
The tree view object has the Role ROLE_SYSTEM_OUTLINE. Each item in the tree view has the Role ROLE_SYSTEM_OUTLINEITEM.
get_accSelection
get_accState
The State property for the tree view is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE

For the tree view items, the State property includes either STATE_SYSTEM_EXPANDED or STATE_SYSTEM_COLLAPSED.

Additional possible values for the State property include:

STATE_SYSTEM_FOCUSED | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_SELECTABLE | STATE_SYSTEM_SELECTED | STATE_SYSTEM_HOTTRACKED

get_accValue
The tree view object does not have a value. The Value property for each tree view item is the indentation level of the item in the hierarchy. For example, in Windows Explorer, the item "Desktop" has a Value of zero; the item "My Computer", which is at the next level in the hierarchy, has a Value of one; and each of the disk drives, which are at the next level in the hierarchy, have a Value of two.

Events Generated

  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_FOCUS
  • EVENT_OBJECT_SELECTION
  • EVENT_OBJECT_SELECTIONADD
  • EVENT_OBJECT_SELECTIONREMOVE
  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_NAMECHANGE

Remarks

Because the tree view object does not support get_accChild, the items in the tree view are simple elements. They do not support the IAccessible interface themselves. The tree view object provides information about the tree view items.

The accLocation property of tree view items returns the location only of the text in the item. The coordinates returned by accLocation for tree view items does not include the icon located to the left of the text.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Up-Down Control

An up-down control, also known as a spin control, combines a pair of buttons displayed as arrows with a buddy edit control. Clicking the arrows increments or decrements the value in the edit control.

The window class name for a up-down control is UPDOWN_CLASS, which is defined as "msctls_updown32" in commctrl.h.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
get_accChildCount
The ChildCount is two (the up and down arrow buttons).
get_accFocus
get_accName
The Name for the up-down control object is obtained from the control's window text (or caption). This text is not displayed with the up-down control, so server developers must provide meaningful text in the control's resource definition statement to help users of client utilities identify the control. The Name for the top arrow button in the up-down control is "More", and the Name for the bottom arrow button is "Less".
get_accParent
The Parent of the up-down control is a window (ROLE_SYSTEM_WINDOW) that surrounds the control and has the same Name property and window class name as the control. The Parent of the up and down arrow buttons is the up-down control object.
get_accRole
The Role for up-down control object is ROLE_SYSTEM_SPINBUTTON. The Role for the arrow buttons is ROLE_SYSTEM_PUSHBUTTON.
get_accValue

Events Generated

  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_VALUECHANGE

Remarks

Because the up-down control object does not support get_accChild, the up and down arrow buttons are simple elements. They do not support the IAccessible interface themselves. The up-down control object provides information about the arrow buttons. Active Accessibility exposes the buddy edit control as a separate object.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Window

Active Accessibility creates a generic window object as a container for another object. Client developers do not convey the information from window objects to end users because these objects do not contain useful information.

If a server application creates a custom control, Active Accessibility creates a window object that contains the custom control, but the server creates an accessible object to provide information about the contents of the control. The system generates object-level events for the window object, but the server must send events for the accessible object that provides information about the control.

Properties and Methods Supported

accHitTest
accLocation
accNavigate
accSelect
get_accChild
Retrieves the IDispatch interface of the specified child. Because window objects always contain invisible objects, clients specify a child ID of four to obtain the IDispatch interface to the object that contains meaningful information to end users.
get_accChildCount
The ChildCount is seven.
get_accDescription
The window object itself does not have a Description. The Description for the child object can be retrieved through the window object.
get_accFocus
get_accKeyboardShortcut
The window object itself does not have a KeyboardShortcut. The KeyboardShortcut for the child object is retrieved through the window object.
get_accName
The Name of the window object is the same as the child object.
get_accParent
get_accRole
The Role is ROLE_SYSTEM_WINDOW. The Role of the child object is retrieved through the window object.
get_accState
The State property is a combination of one or more of the following values:

STATE_SYSTEM_INVISIBLE | STATE_SYSTEM_UNAVAILABLE | STATE_SYSTEM_SIZEABLE | STATE_SYSTEM_MOVEABLE | STATE_SYSTEM_FOCUSABLE | STATE_SYSTEM_FOCUSED

Events Generated

  • EVENT_SYSTEM_FOREGROUND
  • EVENT_SYSTEM_CAPTURESTART
  • EVENT_SYSTEM_CAPTUREEND
  • EVENT_SYSTEM_MOVESIZESTART
  • EVENT_SYSTEM_MOVESIZEEND
  • EVENT_SYSTEM_DRAGDROPSTART
  • EVENT_SYSTEM_DRAGDROPEND
  • EVENT_SYSTEM_MINIMIZESTART
  • EVENT_SYSTEM_MINIMIZEEND
  • EVENT_OBJECT_CREATE
  • EVENT_OBJECT_DESTROY
  • EVENT_OBJECT_SHOW
  • EVENT_OBJECT_HIDE
  • EVENT_OBJECT_REORDER
  • EVENT_OBJECT_FOCUS
  • EVENT_OBJECT_SELECTION
  • EVENT_OBJECT_STATECHANGE
  • EVENT_OBJECT_LOCATIONCHANGE
  • EVENT_OBJECT_NAMECHANGE
  • EVENT_OBJECT_PARENTCHANGE

Remarks

The events EVENT_SYSTEM_DRAGDROPSTART, EVENT_SYSTEM_DRAGDROPEND, EVENT_OBJECT_HIDE, and EVENT_OBJECT_PARENTCHANGE are not sent by the window object. This is a known problem and is being addressed.

See Also

Appendix A: Supported User Interface Elements Reference, IAccessible Interface


Appendix B: Standard Dialog Manager Support

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

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

The following illustration shows a sample dialog box from Word. Although it looks like a regular Windows-based dialog box that uses the tab control, it is really an SDM dialog box.

Screenshot of the Options dialog box in Microsoft Word with the View tab selected


Appendix C: IAccessible DISPIDs

A DISPID allows the implementation of the IDispatch interface to look up 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:  Descriptive
#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)


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.