So, typically what happens depends on the type of dialog:
- If the dialog is, say, an install wizard dialog, or a message box or similar, the flow is simple: the screen reader will read the title bar, the main text (if any), and then the currently focused widget will be read after that. Tab/shift-tab is used to navigate among controls in their appropriate tab order.
- If the dialog is a web view, the navigation is a lot more complicated. Screen readers (at least on Windows) use an internal virtual “buffer” of sorts to understand the construction of a web page (landmarks, headings, sections, lists, links, etc.). As such, far more navigational options are made available to you: the b key navigates among buttons; the h key goes by heading; the t key goes to the next table; etc etc etc. I however get the feeling that you won’t be writing a full webview implementation so this isn’t much of a concern.
The “main text” of a dialog is a bit subjective and hard to nail down, and screen readers have different ideas as to what this actually is. Something similar happens with labels for controls: if a control (say, an edit box) has a label above it, the distance between the labelled control and it’s label have to be close together (I think the max is 10-15 coordinates), otherwise the screen reader won’t be able to automatically associate the two. I’m not honestly sure why this problem exists, or what it’s parameter space is. However, if you don’t want to deal with this problem, set the accessible name of the control to whatever the label is. This is one of the accessibility properties which you should generally expose to consumers of the library.
The accessible name is the name of the control which will be exposed to accessibility clients. When set, this overrides any label detection logic the screen reader might ordinarily employ. Thus, the most ideal is to set this to either the label of the control as it would visually appear to end-users, or to set it to something which is equally as descriptive.
The next property is the accessible description. This usually isn’t set by many applications, but the general idea is to supplement the label. As an example, this is used in Reaper, in it’s preferences dialog: if I go to the audio settings and tab to the audio system combo box, NVDA will say “Audio system: combo box WASAPI collapsed Choose your desired audio system here. By default, REAPER uses WaveOut for compatibility, but ASIO is recommended for best performance.” instead of just “Audio system: combo box WASAPI collapsed” as it would were an accessibility description not set.
The last property in this trio is the accessible role. Client applications (applications consuming dvui or similar) should rarely, if ever, set this property, and I strongly discourage anyone from doing it without an extremely good reason. UI frameworks such as .NET’s Windows Forms allow you to do this for any control, as an example. .But you shouldn’t ever do this beyond what the UI framework does, because this changes how the screen reader reports the control to the user. But it also changes how the screen reader interacts with the control. For example, if you have a button but you tell the screen reader that it’s a spin button, the screen reader will treat it like a spin button: it has a value associated with it, you can use the arrow keys to change the value, or the left/right arrows to navigate by character, or you can enter a custom value. Naturally, a button won’t exactly react well to this kind of interaction. You should expose it but put all kinds of red flags around it, since this property should only be used if there is no other possible way of getting accessibility clients to properly interact with the control the way you’d like. Otherwise, it should remain unchanged.
I know this is significantly more than you asked for, but I figured the more information the better.
Edit:
I also want to note that there are controls that the UI framework should NOT expose in tab order. Labels, for example. This usually ends up confusing people instead of being helpful. So in those instances, clear the focusable attribute on those widgets.
The NVDA screen reader has a way of allowing you to hear the accessibility tree, at least sort of. In any application, a feature called object navigation can be used to navigate any window, all the way up to the DWM/compositor. Orca on Linux also has a similar feature. If you ever want to test NVDA with dvui, you can use object nav in both laptop or desktop mode:
- In desktop mode, you use the numpad. Numpad 8, 4, 6, and 2 navigate via object nav.
- On laptop, caps-lock + shift + arrow keys. is used to navigate among objects. In an edit field, caps-lock and up/down/left/right is used to navigate the field even when focus is not set to it using what is known as the review cursor.
I hope all this helped! 