From time to time, I get questions of “Which properties do I need to support for my control?” or “What values do I put 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 the MsaaVerify Specification or a MSAA Properties test specification.
Frequently Ask Questions regarding MSAA Properties
Which Properties Must Every Control Support?
Name – absolutely all controls must have an AA 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 objects 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?
It is a bug. Only DISP_E_MEMBERNOTFOUND or S_OK are supported. 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: http://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: http://msdn.microsoft.com/library/en-us/dnacc/html/ATG_UpdatedListViewWithCheckboxes.asp
What if I’ve created my own custom control that isn’t necessarily a <insert control here> or a <insert control here>, but behaves like <insert control here>? Or I have a control 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:
Required fields are indicated in red and with an asterisk (*).
How To Implement
Return 0. A button doesn’t have any children
Return “Press”. Just use oleaccrc.dll to get the correct localization
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).
Returns the mnemonic. All buttons must have a mnemonic.
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.
Returns the invisible window container wrapper that has the same name of the control. This window’s parent is the dialog itself.
ROLE_SYSTEM_PUSHBUTTON (defined in oleacc.h)
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
Return 0. A checkbox doesn’t have any children
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
Returns the mnemonic. All checkboxes must have a mnemonic.
Returns the caption.
ROLE_SYSTEM_CHECKBUTTON (defined in oleacc.h)
STATE_SYSTEM_MIXED – indeterminate state
STATE_SYSTEM_CHECKED – checked
Return “Check” Use oleaccrc.dll to get the correct localization
Returns the mnemonic. All radiobuttons must have a mnemonic.
ROLE_SYSTEM_RADIOBUTTON (defined in oleacc.h)
For the Combo Box window:
Return 3. (the push button, the edit box, and the drop-down list)
Returns the mnemonic from its label.
Returns its label. The label must precede (come before) the combo box in tab order
ROLE_SYSTEM_COMBOBOX (defined in oleacc.h)
The text within the edit box / combo box itself
For the Button:
If the list isn’t opened, return “Open”; otherwise, “Close”. Use oleaccrc.dll to get the correct localization
Returns the combo box
STATE_SYSTEM_PRESSED – if depressed with list showing
For the Edit Box:
Same as the combo box’s name
ROLE_SYSTEM_TEXT (defined in oleacc.h)
For the List:
Return the number of items in the list
ROLE_SYSTEM_LIST (defined in oleacc.h)
STATE_SYSTEM_FLOATING – if it is opened
For the ListItem:
Return “Double Click” Use oleaccrc for the correct localization
The list item text
Returns the list
ROLE_SYSTEM_LISTITEM (defined in oleacc.h)
STATE_SYSTEM_SELECTABLE – if the user can select it
STATE_SYSTEM_SELECTED – if selected
Return 0. An edit box doesn’t have any children
Returns the mnemonic from the label. All edit boxes must have a mnemonic.
Returns the caption. The label must precede (come before) the combo box in tab order
ROLE_SYSTEM_TEXT (defined in oleacc.h)
STATE_SYSTEM_READONLY – Read-only edit box
STATE_SYSTEM_PROTECTED – password protected
The text within the edit box itself
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.
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.
STATE_SYSTEM_OFFSCREEN – the control is there, but just scrolled off the screen
For the list view item
Return “Double Click” use oleaccrc for correct localization
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.
The same as the text of the list view item
Return the list view
STATE_SYSTEM_MULTISELECTABLE – if multi-selected
STATE_SYSTEM_CHECKED – if it has checkboxes.
The label must precede the list view in tab order. And, it must have a mnemonic.
The label must precede the list view in tab order.
For the list box item, see List View Item above.
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.
ROLE_SYSTEM_PROGRESSBAR (defined in oleacc.h)
Return a string from "0%" to "100%" that describes the progress.
Return DISP_E_MEMBERNOTFOUND (unless it is acting like a label)
The caption or the actual text of the static text. Pretty simple.
ROLE_SYSTEM_STATICTEXT (defined in oleacc.h)
STATE_SYSTEM_READONLY – if disabled
Return DISP_E_MEMBERNOTFOUND .