Which Controls Support Which MSAA Properties, and How These Controls Implement MSAA Properties

  • Article

From time to time, I get questions of “Which properties do I need to support for my control?” or “What values do I specify for these properties.” I wrote the MsaaVerify Testing Tool to do this level of testing for you, but from a dev’s perspective, they need to know this information at design time, not at testing time. Consider this post to be a specification on how to implement (and test!) Windows controls for accessiblity.

Frequently Ask Questions regarding MSAA Properties

Which Properties Must Every Control Support?

There are 4 properties every control must support:

  • Name – absolutely all controls must have an MSAA name. Imagine a button not having a caption, or a checkbox without any text describing what you’re checking.
  • Role – describes what sort of control you’re interacting with. Imagine if a dev where to owner-draw all buttons to look like edit boxes. It would be very disconcerting to use such UI.
  • State- describes whether a checkbox is checked or not, whether the control is available, and so forth.
  • Parent – the object’s relationship to all other objects.

Can I Use E_NOTIMPL instead of DISP_E_MEMBERNOTFOUND?

No. Because of the time when MSAA was written, DISP_E_MEMBERNOTFOUND was used instead of E_NOTIMPL. Always return DISP_E_MEMBERNOTFOUND if a method or property is not supported.

What if another HRESULT is returned for a Property?

Then it is a bug. Only DISP_E_MEMBERNOTFOUND or S_OK are supported. For example, no properties that I am aware of should ever return S_FALSE.

Are Help and Help Topic really required?

No. Help and HelpTopic are not required. I have rarely seen them used by an Assistive Technology. HelpTopic is a URL that provides help for the given control and Help is just more info on how to use the control. To the best of my knowledge, HelpTopic is the same thing as if the user were to press F1 for a dialog in Visual Studio. The result is that a help topic link is opened for the user. Technically, you need to return DISP_E_MEMBERNOTFOUND for both of these; however, it isn’t necessarily a bug if the dev returns S_OK with a null string.

What Is a Normal State? Why isn’t there an Uncheck State?

MSAA States are represented as bits. If no bits are set, the control is said to be in a “normal” state. Actually ::get_accState will return 0. If a checkbox is checked, the “checked” state is set. If the checkbox isn’t checked, the “checked” state isn’t checked, hence the normal state.

What about Tables?

Check out this whitepaper about tables: https://msdn.microsoft.com/library/en-us/dnacc/html/ATG_MSAASupportforTables.asp

What if I have a control that merges a list view or tree view with check boxes?

Check out this whitepaper about list views / tree views with check boxes: https://msdn.microsoft.com/library/en-us/dnacc/html/ATG_UpdatedListViewWithCheckboxes.asp

What if I have a custom control (something I implemented myself) that doesn’t look anything like any standard Windows Controls?

What you’ll want to do is to look at all of the MSAA properties for all of the standard Windows controls your custom control kinda looks like or kinda behaves like. Then you’ll need to merge these properties together.

Or say you’re designing something that doesn’t even look like a Windows control. You’ll want to match your control’s behavior as closely as possible to a Windows control. For example, say you implemented some color picker that contains a bunch of “boxes” that represent colors. The UI looks something like a color palette that you can navigate and select different colors, but what should the MSAA properties look like? One idea, and this is just an idea or suggestion (use at own risk), is to represent each of the boxes of the color palettes as a radio button in MSAA, because only one color can ever have selection. If the designer were to replace the color palette with a standard Windows control, he/she could use a radio button group. A color palette is just a better visual representation of the UI than the radio button group, but for MSAA, using a radio button group should work.

How To Implement MSAA for A Given Control

Button

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_6ypa.asp

ChildCount – Return 0.  A button doesn’t have any children.

DefaultAction* – Required. Return “Press”.  Just use oleaccrc.dll to get the correct localization.

Description – 99% of the time, just return DISP_E_MEMBERNOTFOUND.  According to docs, this is used to describe an image on a button, but I’ve seen this used to describe what the button does (although help topic would be a better choice).

KeyboardShortcut – Required. Returns the mnemonic.  All buttons must have a mnemonic.

Name -   Required. Returns the caption.  If you have a button that has a graphic, you must use either Dynamic Annotation to set the AA name directly or use a win32 call to set an invisible caption on the button.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_PUSHBUTTON (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_PRESSED – if depressed
  • STATE_SYSTEM_DEFAULT – is default button on dialog

Value – Return DISP_E_MEMBERNOTFOUND

CheckBox

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_4erc.asp

ChildCount – Return 0.  A checkbox doesn’t have any children.

DefaultAction -   Required. Depends on the current state of the checkbox.  If currently checked, return “Uncheck”.  If currently unchecked, return “Check”.  If currently a three-state checkbox, return “Toggle.”  Use oleaccrc.dll to get the correct localization.

Description – Return DISP_E_MEMBERNOTFOUND.

KeyboardShortcut – Required. Returns the mnemonic.  All checkboxes must have a mnemonic.

Name – Required. Returns the caption.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_CHECKBUTTON (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_MIXED – indeterminate state
  • STATE_SYSTEM_CHECKED – checked

Value – Return DISP_E_MEMBERNOTFOUND

RadioButton

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_7ulq.asp

ChildCount – Return 0.  A button doesn’t have any children.

DefaultAction – Required. Return “Check”  Use oleaccrc.dll to get the correct localization.

Description – Return DISP_E_MEMBERNOTFOUND.

KeyboardShortcut – Required. Returns the mnemonic.  All radiobuttons must have a mnemonic.

Name – Required. Returns the caption.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_RADIOBUTTON (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_CHECKED – checked

Value – Return DISP_E_MEMBERNOTFOUND

ComboBox

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_53nc.asp.

For the Combo Box window:

ChildCount – Required. – Return ’3′.  (the push button, the edit box, and the drop-down list)

DefaultAction - Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Required. Returns the mnemonic from its label.

Name – Required. Returns its label.  Note: The label must precede (come before) the combo box in tab order.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_COMBOBOX (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it

Value – Required. Return the text within the edit box / combo box itself.

For the Combo Box button:

ChildCount – Return 0.

DefaultAction – Required. If the list isn’t opened, return “Open”; otherwise, “Close”.  Use oleaccrc.dll to get the correct localization.

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Required. Correct keyboard shortcut is “Alt+Down Arrow”.

Name – Required. If the list isn’t opened, return “Open”; otherwise, “Close”.  Use oleaccrc.dll to get the correct localization.

Parent – Required. Returns the combo box.

Role – Required. ROLE_SYSTEM_PUSHBUTTON (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_PRESSED – if depressed with list showing

Value – Return DISP_E_MEMBERNOTFOUND

For the Combo Box Edit Box:

ChildCount – Return 0

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Required. Return DISP_E_MEMBERNOTFOUND

Name – Required. Same as the combo box’s name

Parent – Required. Returns the combo box

Role – Required.  ROLE_SYSTEM_TEXT  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it

Value – Required. The text within the edit box / combo box itself

For the Combo Box List:

ChildCount – Required. Return the number of items in the list

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Return DISP_E_MEMBERNOTFOUND

Name – Required. Same as the combo box’s name

Parent – Required. Returns the combo box

Role – Required. ROLE_SYSTEM_LIST  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_FLOATING – if it is opened

Value – Return DISP_E_MEMBERNOTFOUND

For the Combo Box ListItem:

ChildCount – Return 0

DefaultAction – Required. Return “Double Click” Use oleaccrc for the correct localization

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Return DISP_E_MEMBERNOTFOUND

Name – Required. The list item text

Parent – Required. Returns the list

Role – Required. ROLE_SYSTEM_LISTITEM  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_SELECTABLE – if the user can select it
  • STATE_SYSTEM_SELECTED – if selected

Value – Return DISP_E_MEMBERNOTFOUND

Edit Box

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_7bu4.asp

ChildCount – Return 0.  An edit box doesn’t have any children

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND.

KeyboardShortcut – Required. Returns the mnemonic from the label.  All edit boxes must have a mnemonic.

Name – Required. Returns the caption. Note: The label must precede (come before) the combo box in tab order.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_TEXT (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_READONLY – Read-only edit box
  • STATE_SYSTEM_PROTECTED – password protected

Value – Required. The text within the edit box itself

List View

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_3y5o.asp

ChildCount – Return the number of items in the list

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Required. About 90% of the time, there’s a label for the list view.  If there is a label, it must precede the list view in tab order.  And, it must have a mnemonic.

Name – Required. About 90% of the time, there’s a label for the list view.  If there is a label, it must precede the list view in tab order.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_LIST  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_OFFSCREEN – the control is there, but just scrolled off the screen

Value – Return DISP_E_MEMBERNOTFOUND

For the List View item

ChildCount – Return DISP_E_MEMBERNOTFOUND

DefaultAction – Required. Return “Double Click” use oleaccrc for correct localization.

Description – Required. If the list view contains columns, then 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.

KeyboardShortcut – Return DISP_E_MEMBERNOTFOUND

Name – Required. The same as the text of the list view item.

Parent – Required. Return the list view.

Role – Required. ROLE_SYSTEM_LISTITEM  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_OFFSCREEN – the control is there, but just scrolled off the screen
  • STATE_SYSTEM_SELECTABLE – if the user can select it
  • STATE_SYSTEM_SELECTED – if selected
  • STATE_SYSTEM_MULTISELECTABLE – if multi-selected
  • STATE_SYSTEM_CHECKED – if it has checkboxes

Value – Return DISP_E_MEMBERNOTFOUND

List Box

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_1jy0.asp

ChildCount – Return the number of items in the list

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Required. Note: The label must precede the list view in tab order.  And, it must have a mnemonic.

Name – Required.  Note: The label must precede the list view in tab order.

Parent – Required: Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_LIST  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_FOCUSED – has focus
  • STATE_SYSTEM_FOCUSABLE – the user can tab to it
  • STATE_SYSTEM_OFFSCREEN – the control is there, but just scrolled off the screen
  • STATE_SYSTEM_UNAVAILABLE – if disabled

Value – Return DISP_E_MEMBERNOTFOUND

List Box Item

For the list box item, see the “List View Item” above.

Progress Bar

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_5u7g.asp

ChildCount – Return 0

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Return DISP_E_MEMBERNOTFOUND

Name – Required. Note: If there is a label, it must precede the progress bar in tab order.  If it isn’t clear what this progress bar does, place an invisible label that precedes the progress bar in tab order, so that it will have an AA Name.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. Return ROLE_SYSTEM_PROGRESSBAR  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled

Value – Required. Return a string from “0%” to “100%” that describes the progress.

Static Text

Reference: https://msdn.microsoft.com/library/en-us/msaa/msaapndx_4ws4.asp

ChildCount – Return 0

DefaultAction – Return DISP_E_MEMBERNOTFOUND

Description – Return DISP_E_MEMBERNOTFOUND

KeyboardShortcut – Return DISP_E_MEMBERNOTFOUND (unless it is acting like a label)

Name – Required. The caption or the actual text of the static text.  Pretty simple.

Parent – Required. Returns the invisible window container wrapper that has the same name of the control.  This window’s parent is the dialog itself.

Role – Required. ROLE_SYSTEM_STATICTEXT  (defined in oleacc.h)

State – Required:

  • STATE_SYSTEM_INVISIBLE – if invisible (not shown yet)
  • STATE_SYSTEM_UNAVAILABLE – if disabled
  • STATE_SYSTEM_READONLY – if disabled

Value – Return DISP_E_MEMBERNOTFOUND