Re: Control Usage Assistant: August 13th development snapshot



For anyone using Add-on Updater: Add-on Update method won’t work because Control Usage Assistant isn’t registered with this add-on. I’ll correct this issue as part of Add-on Updater 19.08.1/19.09. Sorry about that.




From: <> On Behalf Of Joseph Lee via Groups.Io
Sent: Monday, August 12, 2019 8:24 PM
Subject: [nvda-devel] Control Usage Assistant: August 13th development snapshot


Hi everyone,


Control Usage Assistant August 13th development snapshot is now available. As promised, this one introduces a completely new way of obtaining help, along with a new help message interface.


For anyone wishing to take a look at add-on source code: I’d like to inform you that the official source code repo for this add-on has changed. Going forward, all add-on development will take place on GitHub, not Bitbucket. The new (and now official) repo can be found at:


What’s new and different from version 2.5/nightlight: in addition to the new repo, we have:


Help messages database, completely redesigned: in version 2.5 and earlier, Control Usage Assistant used object role constants from control types module to retrieve help messages from a central database (really a dictionary), with some scenarios involving an offset (browse mode and messages for controls from some apps, for instance). While it did allow help messages to be defined for well-known controls, it did not leave room for extending the database by adding messages for controls only seen in some apps.


The new Control Usage Assistant add-on will now use multiple help message databases to store help messages. There is the default role-based help messages dictionary as before, along with dictionaries to store help messages based on class names for various objects (such as NVDAObjects.behaviors.EditableTextWithSuggestions), including those found in app modules (such as PowerPoint slide shows) included in NVDA. The just released snapshot collects messages found in version 2.5 with one notable omission: help message for read-only edit fields, which I’ll do something about soon.


A different procedure for fetching help messages from everywhere: coupled with help message database redesign, a new way to fetch help messages is introduced. Version 2.5 and earlier just looked at object roles and one or two constraints such as whether browse mode is active or dealing with one or two controls from specific apps. Starting with the just released snapshot, NVDA will first look at help messages for objects themselves, followed by one or more constraints such as browse mode, before resorting to role-based help messages.


The biggest change from the old releases is how NVDA can figure out help messages for objects. This is done by traversing an object’s method resolution order (MRO), a record of class hierarchy relationships used for attribute lookup and other tasks. For example, for an overlay class defined in an app module which is in turn based on an API class, the class hierarchy (or MRO) for an overlay class starts with the app module one, followed by one or more API level classes, and then proceeding to base NVDA object and its constituent objects such as scriptable object.


For each MRO entry, NVDA will look at a string representation of the class name, which is then used as a key to look up object-specific help message. For example, if one is dealing with a custom table object from an app module that is in turn a fake table row object, NVDA can potentially look up help messages for at least two objects: the overlay class found in the app module, and the help message for the fake table row behavior. Only after messages from objects are exhausted will NVDA retrieve help messages based on an object’s role provided that there is one, and if there is no help message whatsoever, NVDA will say, “no help for this control”.


During each help message retrieval pass, potential help messages are gathered into a list, including a message about no help for a control. This list is important because it powers the next feature.


Same command, different help message interface: the command for getting help on a focused control (NVDA+H) remains the same. But this is where the similarity ends. In version 2.5, NVDA would flash the help message in speech and/or braille. Starting with the just released snapshot, you can (finally) review help messages in a browse mode window. Not only this resolves a problem where you had to press the help command again if you missed the help message, you can now review help messages at your leisure and makes the experience closer to other screen readers.


Recall that potential help messages are gathered into a list. The above interface change is why: just before NVDA displays a help message (or several of them) in a browse mode window, entries in that list are transformed into a string. In addition, the help message screen ends with the phrase, “press Escape to close this help screen”. Sounds familiar? This is the exact message borrowed from PAC Mate’s help screen (if you know what I mean), and in some way, is very close to how help screen works for BrailleNote Touch/Touch Plus users (I now am a user of a BrailleNote Touch Plus).


How to obtain the development snapshot: there are two ways:


  1. Go to community add-ons website (, select Control Usage Assistant, and select development version link.
  2. If using Add-on Updater, go to NvDA Settings/Add-on Updater, and check “Control Usage Assistant” under “prefer development releases” list and click OK. Then check for add-on updates.


How to help: you can help out by sending feedback to me (either on various NVDA lists or privately), or if you are willing, filing issues and pull requests. In particular, I will need help with the following tasks:


  1. Code review (for add-ons community): I’ll be sending an official basic review request to add-ons community, because this add-on wasn’t reviewed in a long time.
  2. Adding help messages for specific controls: to do this, after locating the control in question, send me the developer info along with a short help message. If you wish to do so yourself, locate the class MRO for the object, add it to the objects help messages database along with a short help message, and package it as a pull request. If you are adding help messages for roles, be sure to record the role and the help message.
  3. If you are really adventurous and wish to help out with NVDA Core pull request: relevant details can be found at If you wish to track the work being done, check out josephsl/i2699contextSensitiveHelp branch.





Join to automatically receive all group messages.