Questions and answers about AA naming your control

  • Article

I’m often asked “What’s the correct name for this control?” There are many variations to this question, for example:

  1. Does this control need an AA name?
  2. Do we change the AA name if a control’s caption or label changes?
  3. Do we add the AA description to the AA name, in order to “force” the screen reader to read it?

Yes, yes, and no.

Explanation #1

All controls need to have a name, unless explicitly stated in the MSAA SDK. For example, a Win32 standard status bar does not have an AA name, but its children must support name. This is the only exception to the “always supply an AA Name” rule that I can think of off the top of my head. If you’re writing in managed code (.Net Framework), always supply an AA name. Consider it an ounce of prevention.

Explanation #2

Consider Visual Studio .Net’s New Project Dialog’s more/less button. Note that the caption changes based on the state of the button. I was asked if users would be confused if we changed the AA name for the control. It seems to me that it would be even more confusing if we didn’t. Imagine interaction with a more/less button that when toggled, still said “more”. This reminds me of that bad junior high school joke where you write on both sides of a sheet of paper, “How do you keep a <insert profession here> occupied? Answer on other side.”

Explanation #3

I’ve studied the MSAA SDK guidelines for quite some time now (long enough if AA properties were GUIDs, I’d have them memorized), and I’ve come to the conclusion that the AA Name must match whatever it is on the screen, with the following exceptions:

  1. The caption is a picture, hence requiring a textual name
  2. The caption or label is not unique to the dialog or form, hence requiring additional text.

Any other additional information required to explain what this control does must be provided via the AA description. That’s what the MSAA SDK guidelines say to do.

Having said all of this, remember we’re supporting “screen reading” technology. I say screen reading in quotes to draw attention to the literal notion of what we are supporting. If the AA Name didn’t match what was on the screen, are we really providing a way for a screen reader to read the screen?