BX User's Guide
Last Revised January, 2021
Welcome to BX, the JAWS toolbox!
For installation instructions and a download link, go to the Script Installation Instructions section.
For news on updates, go to the Revision History section.
Copyright (c) 2003-2021 Doug Lee.
All rights reserved.
Redistribution and use in binary form is permitted provided that the
following conditions are met:
- Redistributions must reproduce the above copyright notice, this list of
conditions and the following disclaimer in the documentation and/or other
materials provided with the distribution.
- The names of the copyright holders and contributors may not be used to
endorse or promote products derived from this software without specific
prior written permission.
Except via specific prior written permission, distribution, acquisition,
or discovery of source code, such as by reverse engineering or decompiling,
is not permitted.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE
USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Table of Contents
What Is BX?
BX is a very comprehensive navigation and testing tool. It
will allow you to test many JAWS scripting functions without writing
scripts. Using BX, you will be able to use single
keystrokes to get the results of most any function in each of the
Summary of BX features by category
- Go to first, last, parent, child, next, previous, current, focus,
real, foreground, top-level, or other windows directly.
- Get a window's class, name, control ID, display style, dimensions and
location, contents, etc.
- Move directly from a window to various other exploration environments attainable from it, such as its SDM elements, MSAA or UIA object tree, AccessibleObject tree, or screen rectangle.
|SDM Window Functions
- Move to first, last, next, previous, current, or focused SDM
control and test all functions you might use to present the control to the user.
- Navigate among MSAA objects by all standard MSAA methods (spatial,
logical, hierarchical, or to focus or selection) and query all
properties of each object (name, role, state, value, etc.). (This is
done by direct manipulation of MSAA COM objects.)
|UIA support testing
- Exercise the features of the UIAScriptAPI introduced publicly in
JAWS 15 but also available (though with more limited and slightly
different functionality) in JAWS 14.
- Explore UIA trees, filter their content, collect UIA elements matching
specific criteria, examine all available properties, list available
UIA patterns for an element and test related properties and methods,
and move among related UIA elements, MSAA elements, window
handles, and screen rectangles.
- Capture any of up to about 200 events on a UIA element or tree and analyze them via an XML structure that can also be examined in BX.
|AccessibleObject tree testing
- Test navigation and properties in an AccessibleObject tree obtained from a window handle.
|Internet Explorer HTML testing
- In Internet Explorer, navigate an HTML document's tree of elements, query for
attributes, fire events by name on specific elements,
retrieve HTML source code blocks by element for display or copying,
and edit live DOM elements or trees by hand in place and test the results.
|XML testing and navigation
- In any browser supported by JAWS, obtain and navigate a web page's FSXML view as provided by JAWS 17 and later.
- Explore XML views of AccessibleObject trees built from MSAA or UIA, and an XML view of JAWS' Off-Screen Model (OSM).
- Explore an arbitrary XML file by loading it into BX for examination.
- Explore events captured from UIA.
- Use any standard JAWS navigation or cursor-changing/routing
command, plus a few for moving by other units such as text chunks; and
test cursor-sensitive functions such as
|JAWS Object Functions
- Navigate with cursors as above and test functions like
- Navigate and examine the JAWS internal object information hierarchy by level.
- Initiate MSAA or UIA refresh to test when these might be necessary.
- Move one screen pixel at a time, or search for color changes, detect color patterns on screen, etc., using the JAWS or invisible cursor.
|Java and Nav Module Functions
- Test JAWS functions for dealing directly with Java controls, including
the Nav Module system functions introduced in JAWS 5.0.
|Global (non-location-specific) Functions
- Test functions such as
DialogActive which don't relate to a location.
- Check JAWS or Windows version and obtain detailed version information about the application in focus.
- Update the scripts for the application in focus without running a script installer, or update BX itself.
|Braille support functions
- Test functions related to JAWS' support of Braille displays and the JAWS Braille Viewer application.
|COM Object Functions
- Find out if any of the JAWS functions returning COM object interfaces
work from the current cursor location.
- Explore the properties and methods of specific COM objects obtained from other BX functions or directly by instantiation from an edit box.
- Generate a list of keystrokes scripted for the active application along with their descriptions.
Additionally, you will be able to do all of the following:
- Use JAWS' normal Keyboard Help mode (JAWSKey+1) to find
out what any key's effect will be at your current location.
- Get a key's description instantly by pressing the space bar before
pressing the key (analogous to Kurzweil's "Nominator" concept).
- Call up into a virtual buffer a list of all BX commands available at
your current location.
- Navigate among commands available at your current location with
Tab and Shift+Tab and execute any one of them by
- Mark up to 26 locations, such as a window in the window tree,
an MSAA object, or a cursor location, and return to them later.
- Restrict the JAWS or invisible cursor to specific windows, object
regions, MSAA object rectangles, etc. for easier examination of
specific screen areas.
- Test the
GetItemRect function in detail to find out what is
returned for specific unit requests.
- Collect the output of any command or set of commands for display
in a virtual buffer for character-by-character examination, copying to
the clipboard for use elsewhere, etc.
- Execute an arbitrary script function at the current location by typing
the function call into an edit box.
- Execute arbitrary script functions from within the JAWS Script Manager, Notepad, or various other editors
and optionally collect their return values into the current file--analogous to the
"Immediate Window" in Visual Basic.
Finally, power users may customize the BX interface or add
commands by editing a .ini-style file and using a BX-specific syntax that
permits scripts and functions to be called directly from a text file
without the need to compile new code.
BX works with JAWS versions 15.0 and up.
BX may contain features that only work in newer versions of JAWS.
These features will fail under older versions of JAWS, but this
will not prevent BX from performing properly otherwise. In other words, BX
will do its best to adapt to what it can find and will do as much as it can.
Script Installation Instructions
To install BX on a new system:
- Load JAWS if this has not already been done. This will require administrative privileges on the computer.
- Run JAWS as the user for whom the scripts are to be installed.
This and the following steps must be performed for each user of the computer
who will be using JAWS with these scripts.
- Download and run, or run directly, the installer for these scripts; and follow the on-screen
directions. Be sure to install the scripts in the currently running JAWS version if a JAWS version list is presented.
BX Usage Overview
BX is activated, and also deactivated, by typing Insert+Space or JAWSKey+Space twice in a row.
BX will announce its state when turned on or off in this manner, e.g., by saying "BX on."
Note that before April, 2020, it was possible to use the JAWS "Script Utility Mode" commands to turn BX on or off. This is no longer the case, and the Script Utility Mode works entirely as determined by JAWS itself.
In JAWS' script utility mode, you have a location, defined by a
window handle, and a set of possible commands. The possible
keystrokes never change, but their output does: You can cycle
through output modes with F3 and through attribute search
types with F4 and thus change the effects of other commands.
BX extends these concepts significantly. In BX, a "location" is simply
a sufficient set of information to define where you are. Your current
location could be a window (as in script utility mode), an SDM control, an
MSAA object, a cursor position, etc. Naturally, each different type
of location has associated with it a unique set of possible commands,
corresponding to the things you can do there. When in a window, you
might want its class; when on an SDM control, you might want to hear
the result of calling
SDMSayControl; and when examining an
MSAA object, you might want to hear its name and role. You might even
want to combine various means of navigation to achieve one goal, such as
by finding a list box by navigating the window tree, then getting that
window's MSAA client object (which will be a Role_System_List object),
and finally using arrows to read all the list items whether or not they
are shown on screen.
Because there are a number of different location types in BX (window, MSAA
object, etc.), each with its own unique requirements and capabilities,
there will be different commands available depending on where you are.
The set of keystrokes available for a specific location type in BX is
called a map. Whenever possible, commands are uniform across
maps: To move to the first, last, previous, or next location from the
current one in any mode, use Home, End, Up,
and Down, respectively (except when
using screen coordinates as locations, at which time all normal JAWS
movement commands will work as expected). Commands for which uniformity
is impossible or unreasonable tend to have mnemonic key assignments:
C for window class, I for control ID, etc. Finally,
some conventions apply for grouping commands. For instance, commands
that jump to a new location by means other than relative movement are
activated with keys involving the Ctrl key. Thus, when
navigating among windows, Ctrl+F will jump to the window in
focus, and Ctrl+R will jump to the "real" window (the first
window above the current one with a title).
and commands that affect the environment, such as by changing focus,
tend to involve the Alt key; thus, during Window Navigation,
SayWindowTypeAndText and Alt+F
In summary then, BX is simply a system which gives you the
ability to navigate among locations and between types of locations and
to test numerous JAWS scripting functions pertinent to each type of
As such, it is of primary and considerable use to scripters; however, it is
also very helpful as an instructional tool for those wishing to learn how to
write scripts, and it can sometimes be used as a very effective means of
handling application accessibility problems on the fly--for example, setting
focus to an otherwise unreachable control, monitoring the progress of a long
operation by parking on an MSAA progress control and pressing V
periodically to check the position of the gauge, etc.
A Quick-Start Guide
There are several help facilities in BX which will be explained shortly. It
is not necessary to memorize a lot of commands right away; you can find
them all interactively. However, before presenting the help system, this
section will do a little to explain common BX usage.
The most frequent type of BX usage involves turning BX on,
choosing the map you want (for example, Apostrophe W
for Window Navigation or Apostrophe M for MSAA Navigation), setting a
starting point (for example, Ctrl+F to move to the current
location of focus), and starting to navigate and test functions and
properties. An example: To find the name of the current window and the
class of the top-level window above it in the window tree, you could do the
- Turn BX on.
- Choose the Window Navigation map (if not already active) by typing an
apostrophe (which will say "Map") and a w (which will say "Window
- Type a Ctrl+F to jump to the window with focus.
- Type an "n" to get the name of that window. This will answer the first
of our two questions.
- Type Ctrl+T to jump to the top-level window above the
- Type C to get the class of this window.
Here is a list of basic commands that should help you figure out the
rest of them. These commands work in all maps except where noted. A few
commands, shown at the end of this list, are not really related to the help
system but are helpful in just about any map sometimes.
Summary of basic BX commands available in all maps
|JAWSKey+1 (normal JAWS Keyboard Help command)
||Activates a mode in which you can type any key to get JAWS to
announce its function at the current location.
||The Describe-Next-Key function: Press just before pressing another key
or key combination to hear its function without having to enter help mode
||Display in the JAWS virtual buffer a list of commands available at
the current location. F1 and JAWSKey+F1 also do this.
|Tab, Shift+Tab, and Enter
||Move among and execute, respectively, the commands available at
the current location.
|Ctrl+Tab and Ctrl+Shift+Tab
||Jump to the first or last command available at the current
||Switch to another key map. This key actually puts you into a map whose
purpose is to choose a map though, so the above help facilities work here to
help you find a map to use.
||The Where-Am-I function: Announce the current map name and location.
||The Context key (not available in all maps): In maps supporting
it, goes to a context map for the current location. This is, for
example, a way to get the MSAA Window or Client object from a window
||Find or Search: In maps supporting this feature, moves to a map of commands for searching and reviewing search results related to the original map. For example, typing / from the UIA Navigation map reaches a "UIA
Find" map for performing UIAScriptAPI searches, whereas typing / from an XML map reaches a map for performing XPath queries on an XML tree.
||In maps supporting this feature, cycles among related maps for the
current type of location. For example, ; cycles among
Cursor Navigation, Pixel Navigation, and other related maps that
address physical screen locations.
|Alt+Shift+Up and Alt+Shift+Down
||BX history navigation: Move backward and forward among locations already visited, via any map, in visitation order.
||The BX Mark system: This goes to a small map used for setting,
clearing, and jumping to marks. A "mark" is a location (a
window, an MSAA object, an HTML object, etc.).
|Windows with a letter
||A shortcut for jumping to a specific mark. For example, if you
created mark A earlier, Windows+A will return to it.
Jumping to a mark will also return you to the map you were in when you
created that mark.
||Brings up an edit box in which you can type a JAWS function call
with parameters and press Enter to run it immediately.
Nested function calls will not work.
||Cycle through available cursors. Useful in maps where the normal
PC and JAWS cursor commands are not available.
||Object type name: Press once to hear the name of the current
object's type, assuming the current location involves an object,
and twice to hear its interface name.
This is an advanced feature and may require
TLBInf32.dll to be
||Object overview: Brings up a virtual buffer describing the
interface to the current object, assuming the current location
involves an object. This is another advanced feature requiring
||Exit a nested key map if one is active, returning to the one
active before it was loaded. This is a way out if, for example, you
hit an apostrophe (map switch) by mistake and don't really wish to
||Starts and stops text collection. Type once to start text collection,
then use one or more BX commands that produce collectable output (most
output is collectable, but the output of
Say commands, such as
SayWindowTypeAndText is not). Finally, type this command a
second time to place all collected output in the virtual buffer for viewing,
copying to clipboard, etc.
||Cycle through the three possible MSAA modes available in JAWS. The
first press of this command simply announces the current mode; subsequent
presses (without other intervening commands) will cycle through the
remaining modes. The MSAA mode can have an effect on the output of numerous
JAWS commands, notably commands like
The BX Quick Key
A more recent feature of BX is the so-called "BX Quick Key," sometimes
also written as "QuickKey" (without the space). This is a key that
provides access to a miscellaneous set of functions without requiring
BX itself to be activated first with JAWSKey+Space. By
default, the Quick Key is not set up; but it can be set up simply by
adding a QuickKey assignment to
the JAWS user folder. The BX author
prefers to assign the right bracket key (]) key as the BX
To assign a quick key:
- Enter BX and go to the BX Configuration map (Apostrophe Ctrl+B).
- Type J to load
bx_user.cnf into Notepad. If
it does not exist, let Notepad create it.
- Add a line saying, for example, "Quickkey=]" (without
the quotes) to the
[BX Options] section. If the section
does not exist, add that section header as well:
Replace "]" with the key you wish to use as a quick key.
- Save the file, then restart JAWS once or reload all scripts and
configurations with Ctrl+Insert+Esc.
Once the key is functioning, tapping it will cause JAWS to say "BX"
and wait for another key. The Tab and other help facilities
work here just as in BX itself to help you find commands and features
As of this writing, the built-in Quick Key functions fall into the
- Task switching
- Commands to speed jumping among running tasks when many are open
at once. This system is designed to be somewhat similar to that used
by the "Screen" utility found on some systems running Linux and
similar text-based operating systems.
- Text management
- Commands for cutting, copying, pasting, and combining text blocks
and holding blocks of text in up to 26 buffers named by single
letters. This system was inspired by the buffer system in the "Vi"
text editor found under Linux and other similar operating systems.
- A command for getting to a collection of reports that BX can generate.
- Test Functions
- A command for running any of 27 different functions you can write
for testing scripts etc. without requiring you to assign keys to them in a
This approach also has the advantage of keeping test code out of the way of script end users, as these test functions do not appear in lists of available scripts for users to run.
- App-specific functions
- Two commands for running functions related to specific
applications: one that brings you to a list of applications with such
functions available, and one that lets you run functions related to
the currently active application if any exist.
- Call logging functions
- Commands for tracing/logging function calls, events, etc., in JAWS
- Script updating functions
- Commands for updating BX itself and updating the running scripts
for the focused application, if such updates are available from the BX author.
- Miscellaneous functions
- Functionality that does not clearly fall into any other of the above categories.
Warning: The Quick Key functionality itself is
stable, but the specific available commands and their current layout
are subject to change. The text management commands
in particular could use rethinking.
Task Management Features
The BX Quick Key command set includes the following commands for managing tasks:
- List available tasks. The W keystroke comes from the Screen utility mentioned in the previous section.
- Numbers from the number row
- Switch to a task by its number. Digits 1 through 9 and 0 switch to tasks numbered 1 through 10. With Shift, these keys switch to tasks 11 through 20. With Ctrl, they
switch to tasks 21 through 30, and with Ctrl+Shift, tasks 31 through 40.
Note that while most Windows applications work well with the BX task switching methods, a few may not.
Also, though the intention is for the BX task list to duplicate the task list available via Alt+Tab, deviations may occasionally occur.
- Announce the number and name of the currently focused task.
- Allow the currently focused task to be renumbered to a number of your choosing. This numbering assignment will last as long as the task remains open, even if JAWS restarts.
This is a handy way to group tasks by purpose, get infrequently used tasks out of the way, etc.
Test Function Support
The BX Quick Key includes a "Test" sublayer, accessed via T, in which the following commands are available:
- Letters A through Z
- Invoke a function whose name is "
BXTest" followed by the letter typed; for example, typing QuickKey T S will run a function called
Any return value that is speakable will be spoken when the function completes.
- Letters A through Z with Shift, Ctrl, or Shift+Ctrl
- Run the same function but pass the integer
1 as a function argument for Shift,
2 for Ctrl, and
3 for Ctrl+Shift.
This quickly allows test function runs with special behaviors requested.
- Digits 1 through 9 and 0 from the number row, possibly with modifiers
- Run a test function called
BXTestNum passing, respectively,
10 as an integer function argument.
Add Shift to a digit key to pass
20, Ctrl to pass
30, and Ctrl+Shift to pass
- ? (Shift+Slash)
- Bring into a JAWS virtual view a list of the test functions available in current scope, with a description of each. See below for how descriptions are determined.
Calling any test function that does not exist will, naturally, produce an "Unknown function call" message.
Test function descriptions, for the above QuickKey T ? command, are retrieved in either of the following ways, the first to succeed for each function being the one that is used:
- If a function has a
Synopsis or, failing that, a
Description entry in any currently active
jsd file, the text of this entry is used as a function description. OR
- BX will call the test function with an integer argument of
-1 and use whatever string returns as a function description.
Note that typing QuickKey T ? will make this call for exactly and only the above function names that exist and that do not have
jsd entries as just described.
It is therefore important to provide either a
Description or in-code handling of a
-1 argument so that users who type QuickKey T ? get sensible
results for each available test function.
An example of a well-formed test function (this form works for both letter types and the
variant function BXTestS(int num)
if num == -1
return "Window class of top-level window, or window name if modifiers are typed"
var handle hwnd = getTopLevelWindow(getFocus())
var string val = getWindowClass(hwnd)
if num > 0
; The user typed Shift, Ctrl, or Ctrl+Shift with this call.
val = getWindowName(hwnd)
Event Logging and Tracing Features
BX is capable of generating, to clipboard and to JAWS virtual view, a
log of event calls. This can be very useful in determining which
events fire at certain times or in response to certain actions.
At this writing, about 230 event and
say functions can be
How To Log Events
To use this feature:
- Get to the point where you want to start logging events.
- Type the BXQuickKey,
then D for default (non-app-specific) application actions,
and finally Ctrl+E.
This will load a script file responsible for watching event calls. If
the active application has any associated script, key, or other
JAWS configuration files, they will be
temporarily unloaded at this time.
If this is a problem, use Ctrl+Shift+E instead of
If your interest is primarily Braille-related events, try
Ctrl+B or Ctrl+Shift+B instead.
- To start logging events, type JAWSKey+E twice in quick
- Perform any actions and/or wait for events to fire and log.
- When ready to stop logging and see results, type JAWSKey+E
once. The accumulated event log will appear in the JAWS virtual
viewer. A copy of the log will also be placed on the Windows
- Press Esc when done viewing the log.
- To save the log in a file, paste the clipboard into Notepad or a
similar text editor and save it.
- To unload the logging code and reload any application-specific scripts, Alt+Tab out
of and back into the application once.
Some applications may, such as during a login process, relinquish
and then retake focus, causing any loaded scripts to unload and then
load again. If this happens while events are being logged, the event
logging will stop and the event-logging scripts will be unloaded and
not reloaded automatically. You can retrieve the logs accumulated up
to the time of focus switch out of the application by repeating steps
2 and 5 from the above instructions (i.e., load the event-logging
scripts and type JAWSKey+E once to view the
It is currently not possible to log events safely through the
out-of-and-back-into-application focus switch.
The event logging system supports customization through callback
functions. These functions should reside in the custom default.jss
file that loads BX itself, so they will not go out of scope when the
event-logging code is loaded.
Code in these functions should execute quickly when possible, as these
functions may be called very frequently and rapidly.
To filter what is included in the output, write a
logcallInclude function like the following:
int function logcallInclude(string call)
; Call is the full function call being logged, e.g., "WindowCreatedEvent(12345)."
if call == "keymapchange" || call == "keyPressedEvent" then
; Do not log these events.
elif logcallLevel("FocusChangedEventEx") > 2 then
; Log FocusChangedEventEx and whatever it calls directly,
; but do not log any deeper calls stemming from this event.
; (level 1 is the event itself, 2 is a direct call from it, etc.)
elif stringContains(stringLower(logcallName(call)), "highlighted") then
; Do not log SayHighlightedText or SayNonHighlightedText.
; logcallName() returns the name from the call without the parameters.
; Log all other events being traced.
To add extra log lines for specific events, write a function like the
Any return value, which may contain multiple lines, will be included
and properly indented in the log output.
This example adds two lines below each original
WindowCreatedEvent call (two lines because of the
\n in the
string function logCallExtra(string call, int isReturning)
; Call is the full function call being logged, e.g., "WindowCreatedEvent(12345)."
; IsReturning is True if this is a function return and False if it is the original function call.
if isReturning then
; No extra log lines for returns, just for original calls.
if call == "WindowCreatedEvent" then
; Log useful information about the window being created.
let hwnd = stringToHandle(stringSegment(call, "(,", 2))
return formatString("Class %1, name %2, IDString %3\nOwningApp %4, type %5 (%6)",
getWindowClass(hwnd), getWindowName(hwnd), getControlIDString(hwnd),
getOwningAppName(hwnd), intToString(getWindowTypeCode(hwnd)), getWindowType(hwnd)
; No extra lines for any other events.
Updating Scripts With BX
BX includes features to facilitate updating BX and application
scripts from the BX author.
See the Global Functions map and the Default QuickKey map for related
bx.cnf for related configuration options.
The update system works without issue on many systems, but some
special preparation is needed for systems behind a web proxy:
The above procedure should not require administrative rights and
should provide update functionality until and unless the proxy address or port changes.
- Open Internet Explorer and go to Tools > Internet Options,
Connections tab. Press the "LAN Settings" button.
- Obtain the proxy address and port from the dialog that appears,
then close Internet Explorer and all of its open dialogs.
- If that method is unsuccessful, obtain the required proxy information from other sources, such as a system administrator.
- Enter BX and go to the BX Configuration map (Apostrophe Ctrl+B).
- Type J to load
bx_user.cnf into Notepad. If
it does not exist, let Notepad create it.
- Make sure there is a
[BX Options] section header in the file.
- Within that section, add lines for any required proxy settings. Usually this will be an
http_proxy line or an
https_proxy line, such as in the following example.
In rare cases, user and password information may be required by the proxy server. The final line in the below example demonstrates how to handle this.
- Save the file, then restart JAWS once or reload all scripts and configurations with Ctrl+Insert+Esc.
To avoid problems with Ctrl+Insert+Esc when controlling a JAWS Tandem session, instead make JAWS reload all configurations by compiling a script, such as the
default.jss stub in the JAWS user folder.
Advanced Usage and Tips
These are uses of BX that go outside the norm.
Examining Beep Call Stacks and Process Launch History
BX quietly records the script call stack every time the
beep() function is called. To see the recorded call stacks, type JAWSKey+Shift+B three times in quick succession. Press Esc when done
examining the stacks. BX will begin throwing away the oldest calls after the number of entries reaches 20.
This feature is intended to help debug scripts.
Note that beeps generated by something other than a JAWS script will not cause entries to appear here.
Entries appear newest first.
Below the call stack information, a list of process launches will also appear, one entry per line. Contrary to the call stack entry list, this list appears in chronological order
(oldest first). This means that typing Ctrl+End in the JAWS virtual view and then arrowing up will traverse the list from the newest entry backward.
This list is intended to help diagnose system and user activities that might slow JAWS processing, keyboard handling, etc.
Due to restrictions on the JAWS event used to make this list, however, processes whose executable files live under the
Windows folder will not be included.
Reading Invisible Lists, Combo Boxes, and HTML
Standard list and combo box controls support MSAA and thus make their
contents available even when not displayed on screen. This is also
true of standard HTML controls. This can sometimes be useful, as in
the following examples:
- Any pane of the Windows Task Manager that has been displayed at
least once since the Task Manager was last started will keep
up-to-date information in any list controls in that pane. This means,
for example, that you can check on the CPU usage and memory size of
any running process or the current utilization percentage of a network
adapter without actually displaying the Task Manager, provided that it
is running (minimized is fine) and has displayed the pane(s) you want
(Processes and Networking in this case).
- Some chat programs use lists and/or HTML controls to show chat
text. In such cases, background chat monitoring and reporting is
BX can be used to find and monitor this type of activity as follows:
- Pick a running program of interest, even if not displayed, and
search for its top-level window using Window Navigation.
Alternatively, if you're just curious what's out there on your
machine, just skim through the top-level windows looking for lists and
- Once you find a window of interest, mark it using the Mark system.
This will make it easy to return here later to check for changes.
- Get the MSAA object for your chosen list or combo box by typing a
dot and then c for the client object. For a list, this will be the
List object. For a combo box, this will be the root ComboBox object,
and you'll need to find the List object under that.
- Use RightArrow and then Up and DownArrows to explore the list's
contents. You may want to mark other positions in your navigation to
return to later as well.
The BX Configuration Files
BX ships with a
bx.cnf file and can also read a
bx_user.cnf file for user-specific configuration options.
Users are strongly urged to change only
bx.cnf so that future BX updates do not overwrite
bx.cnf for information on the options available.
BX Development History Overview (for the Curious)
BX has its beginnings as far back as 2001 in a lot of code snippets I
tinkered with as I found time. I kept trying to figure out a way to
reduce the amount of time I had to spend testing things for scripting
but I couldn't come up with a satisfactory interface just by creating
scripts., because the interface invariably became unwieldy. I wanted
a way to redefine any key on the keyboard dynamically, and also a way
to specify what each key should do in a more concise way than by
writing a new script for each case. I made several attempts at both
problems, one of which used the JAWS virtual buffer and allowed
keystrokes to add to it dynamically; but I was still not happy with
the results. The virtual buffer idea made me realize I also needed a
system that had absolutely no effect on what was in focus or on the
results returned by all the JAWS scripting functions. Using the
virtual buffer violated this requirement.
In late February of 2003, I finally met with success and began
collecting code snippets into a coherent system.
Predicting, accurately as it turned
out, that some of my coworkers might also want to use the result, I named the
budding tool Bart Explorer and sent a copy to a few coworkers for them
to play with. (This name is where the name BX initially came from.)
Although I created much of BX in my spare time and outside
any project under company direction, I actually thought it might one day
become either a part of JAWS itself or a
Bartimaeus Group company product for commercial distribution. Neither
happen, although one or two binary copies were actually sold.
Because of this thought though, because I had such a complete lack
of experience in the legal arena and did not know how to craft an
appropriate license agreement,, and perhaps mostly because I knew the tool
suffered from a profound lack of documentation, I said little of the tool's
existance to people outside the company. I did, however, keep
developing it regularly and kept my coworkers apprised of my progress,
adding features as I found need for them and occasionally in response
to coworkers' requests and suggestions. At some point I realized I was
also leaving a trail
of BX installations behind as I went from site to site scripting for
various companies and agencies, because I never scripted without it
and found it decidedly inconvenient to have to uninstall and reinstall
it on each visit to a site (BX at that time had no installer).
BX first went officially public on September 11, 2007. Shortly
thereafter, and to my surprise, a link to it appeared on a prominant
Freedom Scientific web page. The public release had no other noted
significant impact however, possibly due to the aforementioned
profound lack of documentation.
At some point after the above public release, I began implementing features for myself and coworkers in what had by this time become SSB BART Group, but features that I was reluctant to release to the public for various
reasons. For example, BX became capable of altering HTML code on an active web page, in place. This concern caused me to begin keeping a separate, "Pro" version of BX for myself and other SSB employees.
As a side effect though, my efforts to keep the public BX up to date suffered greatly.
In early 2017, prompted by several needs to give out BX copies to SSB clients and by the existence of other easily available tools that duplicated Pro features of BX (e.g., Firebug for editing HTML in place), I decided to again
unify BX into a single version. I also decided to stop including source code at this time, however. Reasons for this included
In February, 2019, many more of my free public projects also stopped including source code.
See my Script Distribution Policy document for details.
- Complications caused by the need to support compilation of BX under many JAWS versions.
- Recognition that most users of BX other than me use it for testing and not for scripting, which renders the source code useless to them.
- The sheer size of the source file (nearly 30,000 lines of code as of March, 2017).
I would like to thank Victor Tsaran for his constructive input in the
very early days of BX's creation, and for writing and allowing
Bartimaeus Group and me to use a Nullsoft installation script for it
(some of Victor's installer code is still in the BX installer as of this writing).
I also thank Jonathan Avila for suggestions that guided some of BX's early
development and, as he was my manager for BX's early years, for
encouragement to write it and permission to work on it from time to
time between projects at the office.
Chad Foster also contributed some ideas while he worked with us in the early 2000's, for
which I am grateful.
Beyond current and former coworkers,
Michael Damian Curran, also known just as Mick, deserves appreciation
as well, for contributing one major idea to BX, that being the irregular-looking
GetObjectFromEvent to retrieve MSAA objects directly from
window handles (I saw that his JFWTechnical scripts did that in the early 2000's).
I could try thanking all the companies and individuals who, in the
course of my doing scripting both on and off the job, caused me to
think of or need various specific BX features; but the list would be
long and the time to pull it together even longer. I will just say
that it was the widely varying character of my scripting projects over
the years that caused so much to happen to BX.
Last but certainly not least, and in the spirit and style of Larry
author of the Perl programming language among other major public
offerings, I wish to thank the Author of my story for prospering the work of
This is the revision history of BX, most recent revision first.
As BX has been under development for many years, this history is long; but it is included here partly in case portions of it may serve to document BX features not better explained elsewhere.
This author reserves the right to move details out of entries in this history section into their own sections of the user guide as time and need dictate.
If this happens, the altered history entries will include same-page links indicating where the material was moved.
Revision 2469, November 22, 2021
- Insert+B in UIA Navigation includes radio buttons in the results.
- The method of collecting tasks for the QuickKey W sequence and the sequences consisting of
QuickKey followed by a digit is changed (again) in an attempt to make task collection faster and
- The call stack and process launch lists shown by typing JAWSKey+Shift+B three times in quick succession separate the two lists by a blank line.
- The . command in the BX Debugger (Ctrl+X map) works instead of producing an unknown function call.
Thanks to Hamza Ahmad for catching this bug.
- Enter in submaps under the Quick Key will execute the last function spoken via the Tab help system, just as BX itself does when active.
This does not apply before a submap is entered under the QuickKey though, because the initial QuickKey map is not implemented in the same way as other maps.
- Removed the Shockwave Flash map added in 2010, for lack of use and because Flash
itself is no longer supported. The map was also only accessible from an HTML element obtained directly from
Internet Explorer's Document Object Model, which has been obsolete for years by now.
- Some code for supporting very old JAWS versions (11.0 through 13.0) is removed.
- There is new support for a
showRectangles option in
When set to something non-zero, BX will
Warning: This feature is not yet thoroughly tested.
- Draw a visible rectangle around the current BX object in various maps/contexts.
- Draw a visible rectangle to show what was just queried via l and similar commands in various maps.
- Turn off any such rectangle when BX is turned off.
Revision 2444, December 28, 2020
FSXML Testing map enhancements:
- Ctrl+P moves to the FSXML node at the currently active cursor position using the
GetElementXMLAtPoint function added in JAWS 2021.
Unfortunately though, this function appears, in JAWS 2021.2011.16.400 at least, to return the same element as
GetElementXML regardless of what x/y position is passed.
- Ctrl+G moves the active cursor, which should generally be the virtual PC cursor, to the current FSXML node if possible.
This will fail with an error message if the current node is a text node or otherwise has no
- Ctrl+Shift+L loads XML from the currently focused file in Windows Explorer, assuming focus is on a file there.
- Various problems on some discovered web pages that broke FSXML parsing are silently and automatically fixed for commands like Ctrl+F.
MSAA Navigation map enhancements:
- T and Shift+T report the results of calling
GetTypeAndTextStringsForObject without and with inclusion of invisible elements, respectively.
When possible, this result is placed in a virtual buffer for review.
Object Examination map enhancements:
- Shift+D reports the result of calling
This applies to focus and does not take the current object level into consideration.
- U reports the IAccessible2 (IA2) unique ID of the object at the current level. Press twice for hex.
This requires JAWS 2021 or later.
Window Navigation and related enhancements:
- Shift+S in Window Navigation reports the result of calling
GetWindowExStyleBits (extended style bits) in hex.
- The undocumented
DisplayMSAATree function call, previously Shift+T, is now Shift+D.
This function was added in JAWS 8.0 but has not proved necessary to this author for many years and may not work in current JAWS versions.
- Shift+T reports, via user buffer, the result of calling
GetTypeAndTextStringsForWindow on the current window.
The keystroke for this call is deliberately chosen to match the keystroke for
GetTypeAndTextStringsForObject in MSAA Navigation.
Note though that, as of this writing, this result speaks but fails to virtualize in some settings.
- There is a new context map for the ListView Functions map, and it permits jumping to the Rectangle Examination map on the current item, column, or cell rectangle.
(The ListView Functions map is reached from the context map for Window Navigation and is used for exploring ListView API calls directly via the JAWS functions that provide access to them.)
- The XML Navigation map includes a Ctrl+j command for jumping to an XML representation of
the last of the events thus far saved by the
JAWS Alert Manager (JAM) if it is installed and running.
This is mostly intended for the BX and JAM author to use while developing and maintaining JAM but may also prove useful to others in examining or identifying notification events.
- The call stack view invoked by typing JAWSKey+Shift+B three times in quick succession also includes a list of process launches to help debug causes of system performance issues.
- Updated the fix to the so-called idle fiddle freeze to apply more often by watching for not only what app the JAWS cursor is in but also which app is in focus, in case they are different.
This may prevent Microsoft Teams sluggishness for one or two of this author's coworkers under irregular conditions.
Revision 2425, October 30, 2020
- The QuickKey H sequence for toggling Script Utility Mode is now QuickKey U. The H was a holdover from many years ago when Script Utility Mode was instead called Home Row Mode.
- Removed the Script Utility Mode emulation map from BX as it can go out of date as JAWS evolves.
Use the native JAWS Script Utility Mode and its on/off toggle commands instead, or toggle it on/off with QuickKey U.
- Removed the F keystroke from the BX Configuration map, as it was for toggling the "BX First" flag that was removed in the June 24 (revision 2410) update.
- Addressed a rare situation that could cause the JAWS
GetItemRect function to be called while the active cursor is in a window hosted by an Electron (Chrome) application, such as Microsoft Teams.
In that environment, the call could cause significant sluggishness in JAWS and/or the hosting application under at least JAWS versions 2020 and earlier.
This issue is not expected to have affected anyone other than the BX author and one or two accessibility testers.
The issue does not occur under normal or default BX conditions.
For reference, this issue is referred to as the "idle fiddle freeze."
- Fixed an issue introduced in June 2020 that affected one of the author's remote work projects.
For reference, this issue is referred to as the "projName slash restriction."
Revision 2421, September 28, 2020
- The directives file includes directions on how to set up BX sound files and files for the BX Update feature.
(BX rarely but sometimes uses sound files included with it.)
- More and more parts of BX use the
CallFunctionByName function instead of the much older
FormatStringWithEmbeddedFunctions function as a means to call functions indirectly. This is more efficient
and ultimately will allow more flexible passing of values among function calls in BX maps.
- When Insert+E is used to execute a function call from the current PC cursor line, BX will indicate the type of the return value if it is not a string, int, or empty.
The type indication will consist of a hex variant type (
vt) value followed by a description of what that value means. Examples include "Variant type 0xd IUnknown" and "Variant type 0x24 record."
(The first of those is often an object pointer and the second a JAWS collection.)
At this writing (July, 2020), a decent reference on variant type values is https://en.wikipedia.org/wiki/Variant_type#Types.
- There are two new experimental commands in Rectangle Examination: S to save a rectangle's pixels and Shift+S to compare the current same rectangle to what was saved.
If differences are found, they are listed in a JAWS virtual buffer as old and new hex color values.
This pair of commands is intended to help in locating inaccessible checkboxes and other changeable screen elements that have no better representation for JAWS to use.
However, at this writing (September, 2020), it remains unclear whether changes will frequently enough be detected by this approach.
Under some conditions and especially with large rectangles, these commands may take too long to complete.
- The method of collecting tasks for the QuickKey W sequence and the sequences consisting of QuickKey followed by a digit is changed in an attempt to make task collection faster.
- Fixed a very rarely triggered but very inconvenient bug that would cause keyboard problems when an application script includes a script for the same keystroke that is assigned as the BX QuickKey.
- Keystroke names in this document are more consistent, and there are other minor documentation improvements.
Revision 2410, June 24, 2020
This is a big enough update to warrant a subsection in the release notes!
Changes are listed by category, followed by a subsection describing one particularly complicated feature update, that being the method to capture and examine up to about 200 different UIA events.
- The JAWS
HomeRowToggle commands no longer activate or deactivate BX; only typing Insert+Space or JAWSKey+Space twice in a row will do this.
As part of this, the
bx_user.cnf option is removed and is no longer supported.
The Script Utility mode continues to grow, and this move makes sure that BX does not interfere with its operation.
- JAWS no longer announces the second Insert+Space or JAWSKey+Space on BX exit.
- There is protection against key echo being set to None on BX being turned off. This was seen in JAWS 2020 and possibly 2019 and relates to a problem with the JAWS
The details of this problem are not known at this writing, but the effect is that a scheduled call to reset typing echo sometimes fails to happen.
- The BX Update feature will wait for only 10 seconds for an update download connection to succeed before giving up.
This is to prevent problems like proxy servers causing a freeze and a JAWS restart by allowing a connection attempt to stall as long as Windows will allow.
- The Alt+C command for collecting text output of BX commands now announces how to stop collection and view results.
- The installer contains version and product information visible from the Details tab in Windows Explorer, to better identify its contents. This update is being applied to all projects.
- A "directives" text file is included that provides information on how to install this set of scripts manually.
See "Handling Directives Files" in the "Common Script Elements" document for further information.
Changes in the BX documentation:
- The revision history for BX is included in the main BX user guide rather than being in separate documents.
This history is now quite comprehensive and in some cases may serve as additional documentation for features that are not thoroughly explained elsewhere.
- Same-page links within this document work more consistently across browsers.
- The What Is BX? section lists more features for several maps
and also documents the Alt+Shift+Up and Alt+Shift+Down commands for navigating the history of BX location visitations.
- Keystrokes are written in a more consistent manner, and some key names are spelled out rather than being written as native characters; e.g., Period.
This change is guided by multiple documentation standards (not all of which agree) and by JAWS behavior when encountering some characters.
- Other scattered and more minor updates not listed here individually.
Changes in Global Functions:
- Shift+D toggles the legacy accessibility driver on and off.
- Shift+K attempts to toggle between the legacy keyboard driver and the newer unified keyboard driver.
JAWS may not permit this change except via the Settings Center, however. This command will report the state of the keyboard driver after the attempt, in any case.
Changes in UIA Navigation:
- The information reported for the
TextChild pattern (see the P command) includes number of children and number of bounding rectangles contained in the text range as well as the
length and initial portion of the included text.
Also included are the names of the container element and of the text range's enclosing element, with an indication of when the two are equal.
- When typed after the announcement of
TextChild pattern information from the P command, Alt+P will
call the pattern's
ShowContextMenu method and report the integer (Boolean) result.
FindItemByProperty tests run by P include scanning for the first unselected item.
- There is a new, though still subject to significant change, method for capturing any or all of up to about 200 different UIA events on a UIA element or tree for examination.
This is described in detail in a separate subsection below.
- There is a new Find map, available from all XML maps, that allows searching for XML nodes in a tree that match an XPath expression. The operation of this map mirrors that of the UIA Navigation map's Find map and, again
similarly, is accessed with the Slash key (/) from within any XML map.
Use E to enter an XPath expression.
There is an extension though to what can be typed in place of an XPath expression:
Typing a value that contains no slashes results in a translation to an XPath expression that matches whatever is typed, currently case sensitively, against any of these:
This set of property and function result tests are aimed at making this a fast way to search XML trees generated from any of these:
- Node text (the result of the
text() function, which amounts to the content of whatever
#text node(s) may exist under the node being tested).
- Name (the result of the
name() function or the value of the
- The value of
- The value of
- The value of any
Note that, when a node's
- An FSXML tree.
AccessibleObject tree generated from UIA or MSAA.
- A tree generated by capturing UIA events.
- Application and event log trees where data is stored as
text() value matches, the node returned will not be the
#text node but, more usefully, the node containing it. For example, a match on
<log>This is a log
entry.</log> will return the
log node, not its descendant
Capturing and Examining UIA Events
BX allows capture and examination of any or all of up to about 200 different UIA events on a UIA element or tree.
As has admittedly been typical for BX in general, the documentation for this system currently lags behind the system itself; but this is a summary of how to use it:
- Activate BX and go to the UIA Navigation map with Apostrophe U.
- Find a UIA element of interest, and decide whether you want to capture events on just the element, on all its direct children, or on its entire subtree.
- Type Ctrl+E to open a box for entry of an event capture specification.
- To capture all possible events on the entire subtree (except for FocusChange events, which do not depend on current location), type a colon (:) by itself and press Enter.
Be aware that, in many cases, this will capture enough events to slow the system down.
The syntax of event capture specifications will be explained shortly.
- If necessary, perform tasks in the active application that trigger events. This may of course require you to exit and return to BX.
During event capture, a brief announcement of each captured event is made.
The announcement indicates the event type (e.g., Automation, PropertyChanged, etc.), specific information about the event when appropriate (e.g., event id or property id), and when possible, identifying information about
the UIA element that generated the event.
- To stop capturing events, type Ctrl+E again from UIA Navigation and press Enter without typing an event capture specification.
- To examine the events captured, which can also be done while they are being captured, type the sequence Period Ctrl+E to move to the UIA Navigation map's Context map and then to the "Events" node in the XML
view of the captured event information.
This will also move you to the XML Navigation map and allow you to peruse the events using all of the features provided in BX for examining an XML structure.
- To clear the events captured, type Ctrl+Shift+E from UIA Navigation.
An event capture specification consists of one or more event type specifications separated by a Space. In general, only one event type specification should be required for a capture session.
The elements of an event type specification are, in order
- A letter indicating the event type. Use the first letter of any of these: Automation, FocusChange, Notification, PropertyChange, StructureChange, or TextEditTextChange.
- If required, a letter indicating tree scope for this capture. Use the first letter of Ancestors, Children, Descendants, Element, Parent, or Subtree.
(The UIAScriptAPI, and probably UIA itself, does not support scopes of Parent or Ancestors at this time, however.)
Subtree is assumed if this letter is omitted.
- If the event type requires a further parameter, values of this parameter may be listed after a colon (:).
This applies to Automation events (which require an event id), PropertyChange events (which require a property id), and others.
In general, BX allows simple names for values of these parameters; see below examples.
To capture all except certain events, include an exclamation mark (!) immediately after the colon and before the names of items to exclude.
Example event capture specifications:
- Captures FocusChange events (these apply to UIA as a whole, not just to the current element or its subtree).
- Captures the Automation event
AsyncContentLoaded on the current element's subtree.
- Captures all except two possible PropertyChange events; those for the
IsOffscreen properties are ignored. These are captured on just the direct children of the current UIA element.
F A:asynccontentloaded Pc:!isoffscreen,name
- Captures all of the above, with their respective tree scopes, in a single capture session (this is an example of a capture specification containing three event type specifications).
- Capture everything imaginable (except FocusChange events) on the current element's entire subtree.
Caveats on the UIA event capture system at this time:
- The specific process for capturing and stopping capture of events is not set in stone and is likely to change.
- If you examine captured events while they are still being captured, new events are not added to the XML view in real time. This is likely to change in future.
If you return to UIA Navigation and then again use the sequence Period Ctrl+E to move to the XML event view, the new events will appear.
- There seem to be some stuck-key issues not yet resolved.
If your keyboard acts oddly during or after event capture, tap each modifier key (Ctrl, Shift, etc.) once to make sure Windows does not incorrectly assume that one of these keys remains held down.
Revision 2325, March 08, 2020
A block of BX code that has been active since 2003 is suspected of occasionally causing performance problems during focus switching between applications.
This update is therefore recommended for all BX users.
The performance issue appears to affect JAWS 2020 and possibly 2019 and consists of speech and keyboard stalls of several seconds' duration when the user switches between applications and then very quickly tries to issue
commands to the newly focused app.
Update, April 8, 2020:
Such stalls have, since publication of this release, been seen to occur without older BX versions active; but the advice to upgrade BX remains.
Along with removal of this code block, the following four BX commands are removed:
- In Window Navigation, Ctrl+Shift+A and Ctrl+Shift+V for jumping to the window that last called
- In MSAA Navigation, Ctrl+A and Ctrl+V for jumping to the object that last called
Revision 2303, February 15, 2020
- The message "can't make the wsc file" should no longer speak when the computer displays the lock screen due to inactivity.
- Numpad5 is globally duplicated in keymaps by comma (Comma), with the same modifiers wherever they occur, so that users without a numeric keypad can more easily use those commands.
- In UIA Navigation, numbers 1 through 9 and 0 go to 10%, 20%, etc., through 100% of the RangeValue if the current UIA element supports that pattern.
The Hyphen key (-) goes to 0%, the start of the range.
The value being set is announced and then applied, then the refreshed value is spoken.
The equal sign (=) announces the current value without changing it.
- In XML Testing, Ctrl+L maintains a config-file
XMLLoadPath folder so that simple file names can be used except when changing folders.
- Ctrl+S in Braille Testing toggles the Braille Viewer application on/off.
- Commands in Braille Testing that move the Braille display announce the resulting displayed line as originally intended, and also more immediately than in the past.
- The Browser map is now the map used as the application map for Slack. This map is reached with BXQuickKey A, if the QuickKey is configured.
beep() calls are saved, up to 20; and a triple JAWSKey+Shift+B shows them in a virtual view.
This is intended as a quick debugging aid for script developers.
- Removed the HTML report commands, documentation, and code. This report only worked in IE and would not port well to FSXML because it modified the IE DOM to do its work.
Revision 2246, October 14, 2019
- The BX Update feature assumes lower-case web file names. Long term, this will avoid letter casing problems between Windows and the website.
In the short term though, BX Update may fail for some applications with scripts until the actual web file name for those scripts is corrected.
Revision 2244, October 9, 2019
- Fixed removal of the BX QuickKey if configured (manually) by the BX user in
Caught and reported by Tyler Rodick (@TylerK93).
- Fix for mistimed announcement of the Ctrl+L keystroke in XML Testing.
- Shift+X in Cursor Navigation, for showing the
GetScreenXML result and placing it on the clipboard, is moved to Shift+S in XML Testing.
- Shift+D in XML Testing shows the
getDocumentXML result and places it on the Windows clipboard.
- Shift+E in XML Testing shows the
getElementXML result (with all ancestors included) and places it on the Windows clipboard.
- D in UIA Navigation says the UIA fullDescription before the LegacyIAccessibleDescription. Doubling the D spells both.
- Ctrl+F in XML Testing may work in more virtual cursor positions than before.
Revision 2214, July 3, 2019
This revision fixes a problem some users experienced with the BX Update system.
It also replaces some oddly-located features with more sensibly located and flexible commands and maps. The new commands and maps will be described first, followed by the removed commands and how they were replaced, and finally
some other changes and enhancements beyond the new commands and maps.
New commands and maps:
- Apostrophe X goes to a new XML Testing map designed to allow tree-like navigation in an arbitrary XML structure.
This map is the basis for several other new maps, but it also has commands for loading XML directly from several sources:
On loading XML from any source, BX will try to switch to a map best suited for the XML found but will stay in the XML Testing map if no better one is found.
- Ctrl+V loads XML from the Windows clipboard. Coupled with the ability to save XML to the clipboard in a Remote Desktop or JAWS Tandem session, and leveraging the other new maps, this permits local exploration of
remote accessibility structures.
- Ctrl+L prompts for a file path from which to load XML, which permits exploration of any XML structure that currently resides in a text file. This may be useful for examining software configuration files when
- Apostrophe Shift+S goes to a new Screen XML Testing map. This map allows navigation of the XML structure returned by
There are also new links to this map from others:
- The Cursor Navigation map now has a Context map with an X entry for going to Screen XML Testing while automatically retrieving the
getScreenXML tree for the current screen.
This replaces the previous technique of getting to this structure from the HTML Testing map; see below.
- The Rectangle Examination map's Context map now has an x entry for going to the getScreenXML structure for the current rectangle.
There was previously no way in BX to do this.
- Apostrophe Shift+A goes to a new AccessibleObject Tree XML Testing map. This is for navigating the XML structure returned by calling
getXML(-1) on an
AccessibleObject tree node.
Again, other maps now link to this one:
- The AccessibleObject Tree Navigation map's Context map includes an x entry for going to the XML structure for the current object.
This replaces oddly-placed and more limited commands in HTML Testing for reaching this XML structure.
Removed commands and how to accomplish what they once did:
- Alt+S in HTML Testing, which moved to the
getScreenXML structure for the screen, is removed.
To get to this structure, go to the Cursor Navigation map and type Period for its Context map, then X to get to the
- Alt+U and Alt+Shift+U in HTML Testing, for going to the UIA and MSAA
AccessibleObject XML structures for the last visited window, are removed.
To reach these structures now:
- Select the window of interest as usual in the Window Navigation map.
- Use the map's Context map to go to the UIA or MSAA
AccessibleObject object structure (Period A for UIA, Period Shift+A for MSAA).
- Use the AccessibleObject Tree Navigation's Context map to go to the XML structure for the current
AccessibleObject object and its descendants (Period X).
Other changes and enhancements:
- Some users who attempted to use the BX Update system to update BX itself encountered a freeze and an update failure.
There was one BX revision that required use of the full script installer, and updating BX past that revision via BX Update would cause this issue on the next BX Upate attempt.
This revision fixes this problem so that updating to this revision from a revision older than that one will not cause the issue.
Of course, if you have experienced this issue already, you will need to use the full installer to install this revision since BX Update is not working for you now.
- The HTML Testing Context map now uses R instead of L for all rectangle examination commands. R is now the BX-wide standard for Context maps to get to the rectangle map.
- The new AccessibleObject Tree XML Testing map is capable of announcing IAccessible2 role text during navigation.
These roles appear in AccessibleObject nodes but not in MSAA. The only other way to find them is from UIA via the
QT5 applications such as TeamSpeak 3 can use these roles, as can web pages and browser-based apps, notably Electron apps.
- When obtaining an XML DOM tree for XML obtained from an
AccessibleObject structure, BX will work to correct XML errors that would otherwise prevent the Microsoft XML parser from successfully rendering an object tree.
These corrections make examination of such trees possible in BX.
These errors will likely be prevented entirely in a future JAWS update.
In current JAWS versions (through the June JAWS 2019 update), they are caused by characters appearing in application text that are not permitted without alteration in an XML tree.
- Several related maps have acquired help and sometimes actual commands from their base maps:
- The following maps inherit help and non-conflicting commands from Cursor Navigation:
- Attribute Field Navigation
- Color Field Navigation
- ItemRect Testing
- Object Examination
- Pixel Navigation
- The Window Messages map inherits from the Window map.
- The iTextSelection map duplicates the iTextRange map.
- The UIA Find and UIA Virtual Elements maps include non-conflicting commands and help from UIA Navigation.
- L in the AccessibleObject Tree Navigation map has non-blank help text.
Other help text updates not listed here are also included in this update.
- In HTML Testing, a double press of Shift+I now spells the value of the
- In HTML Testing,
getElementID is now attached to a double press of I rather than a double press of Shift+I.
This function was never documented and is no longer part of JAWS.
- Support for calling
GetElementID is removed from FSXML Testing as it never applied there.
- E for editing, and D for deleting nodes are removed from the FSXML map as they were not useful there.
- The W, Shift+W, and Ctrl+Shift+W commands in Window Navigation for testing the JAWS
WindowVirtualView function are removed, along with their code, because the function itself
was removed in JAWS 11.0.
bx.kmp file is reorganized significantly.
- Some legacy code for supporting JAWS versions older than 10.0 is removed.
Revision 2171, June 7, 2019
- There is yet more code to handle web proxy situations during a BX Update retrieval.
The documentation here of this fact was missed until June 14, however.
Tlbinf32 files for object inspection are no longer included in BX. They were never used at work sites due to a DLL registration requirement, and they sometimes caused site protective software to block BX installation.
- A small
bx.jsd file is included in the distribution, documenting the BX quick key when assigned, for JAWS Keyboard Help mode.
- QuickKey B no longer loads the Braille Testing map but instead provides a battery checking feature described below this feature list.
- P in the UIA map, for the Selection pattern, reports names of selected elements if there are five or fewer of them.
- Removed from COM Object Testing the warning against using R, for
RichEditDocument, against a non RichEdit20/40w window. This applied in 2003 to JAWS 4.51
but probably is by now not necessary.
- Fix in COM Object Testing: R and a double I ignored the window handle by accident. This fix makes R work as intended on the current BX window.
There is no effect on I though because the
IEGetCurrentDocument function still does not accept a window handle.
- A double Apostrophe, for switching to the current location's COM object type's map, works for types with numeric suffixes like
iTextDocument2 when there is only a map for the base type.
This can help when a COM interface specification receives an upgrade.
- Added ItemContainer pattern support that works in at least the Windows Explorer item list:
- Psays first selection and first element.
- Alt+P from there says selection and element counts, which may take time on a large container.
AccessibleObject Tree (AOT) code tries to work around an anomaly found in the
.xml property in some cases under at least JAWS 17:
An ampersand (&) character followed by a space would throw a parsing error if fed to the Microsoft XML parser. BX will replace such ampersands with
& to avoid the parsing error.
- When removing text elements from an Ins+B read from UIA Navigation, BX omits underscores from the comparison of text element name to parent name,
so that the marking of hotkeys/underlined letters does not cause the code to fail to filter out a duplicate name.
Typeing QuickKey B toggles on/off a battery watching feature described below and also speaks, and shows in Braille where applicable,
"on" or "off" indicating whether the watch feature is on or off, then the following very briefly summarized computer power status information:
Typical battery status examples:
- The first character is P when the computer is running on AC power, or B when it is running on battery power.
Other rarely seen but possible values are U if the currently active power source is not known, and X (followed by
numbers indicating a raw integer result) if the system's response to a request for this information returned something unexpected.
- Following characters can be C for critical battery level, L for low, H for high, or N for no battery present.
Normally only one of those characters should appear at one time.
R means the battery is charging; if R does not appear, the battery is not reported by the system as charging.
Again, U for unknown status, or X followed by numbers may appear if unexpected results come back from the system.
- A space, then the current charge percentage follows, as a number between 0 and 100, inclusive; or 255 if the percentage is not known.
The percent character (%) follows this.
- When known, a space and then the number of hours/minutes/seconds of battery life remaining appears.
bl 25% 21 minutes remaining
If the watch feature is on, any change in the above status information, except for hours/minuts/seconds remaining, is reported as it occurs.
To turn the watch off again, type QuickKey B again.
Revision 2127, April 22, 2019
- Support for navigating FSXML trees, previously housed in the "HTML Testing" map which was thus renamed to "HTML and XML Testing" for a while, now has its own map. This update consists of these related changes:
Several commands initially in the HTML and XML Testing map for testing FSXML trees have different keystrokes now in the FSXML Testing map, for consistency with the structure of other maps.
- Apostrophe F goes to a new "FSXML Testing" map, which contains only commands relevant to testing FSXML trees.
- The HTML testing map is again named simply "HTML Testing" and applies only to testing of the Internet Explorer Document Object Model (DOM).
- The BX Quick Key support for task numbering and switching, and the support for test functions, are better documented.
- Means are included to get BX Update to work through more proxy situations, though the documentation for recent updates in this system was lost due to an accident.
- The code for obtaining a list of running tasks is updated to include a few edge cases, though currently at some expense to execution speed.
Newly included tasks include Microsoft Teams and Microsoft Office update completion notification windows.
- Exiting BX by typing JAWSKey+Space or Insert+Space twice no longer causes a beep.
- Fixed the long-standing bug of M G <markLetter>> failing to switch to the right map though Windows+<markLetter> did so.
- BX now tries during JAWS CachedMSAAInfo retrieval
(Shift+C in the Object Examination map)
to get only ancestors that exist rather than trying to retrieve 99 levels of data.
Revision 2085, March 5, 2019
- Ctrl+JAWSKey+R from any map restarts BX and leaves it active.
- Improved means of handling web proxy servers during script updates.
bx.htm documentation is updated accordingly.
- Fix to long-standing typos that broke the Describe (Space) description for the slash key at the default level.
- The sequence QuickKey A from within Internet Explorer, Firefox, and Google Chrome provides a few useful functions for browsers.
This sequence previously only worked from within Internet Explorer.
The most useful sequence is probably QuickKey A Shift+A, which does the same advanced-element-info retrieval as the default JAWSKey+Ctrl+Shift+F1 command. This alternative may be useful from keyboards which
are unable to issue the standard JAWS command due to its complexity.
- In the Browser map just mentioned, G and D apply to FSXML instead of the IE document object model.
These commands are minimally supported, however, as their use requires a command-line-based "diff" utility that is not included with BX.
- Some obsolete code is eliminated.
Revision 2041, November 19, 2018
This release contains several miscellaneous changes as well as a coordination of features for updating scripts.
- Shift+V in UIA Navigation reports the value of the UIA
- In the UIA map, pattern query changed from D to Shift+D, and D now announces
- In Global Functions, the N command's help string finally documents the fact that, in addition to reporting network user and domain names and computer name from the
WScript.Network object, it also
reports any of
userProfile that have a value.
The BX author to date has never observed values for these attributes, however.
- In Global Functions, the U command for retrieving values of
GetRegisteredTo is now changed to Shift+N.
It also spells the three values if typed twice in quick succession.
- The command sequences for retrieving CPU usage percent (QuickKey D W C) and highest CPU utilizer (QuickKey D W Shift+C)
See "The BX Quick Key" in the BX User's Guide for more information about the BX Quick Key.
- Should work in console settings like cmd on Windows 8/8.1/10, and
- Allow 7 seconds instead of 3 per COM call under JAWS 16 and later.
- A in HTML and XML Testing, intended for adding an attribute to an HTML node, is removed because its code was never written and it would only apply to Internet Explorer environments.
BX now includes means to pull updates to itself and to scripts for running applications from the BX author's website.
All updates use secure https rather than http to retrieve update files.
Warning: Use of the below update commands should be considered equivalent to following a beta track, as incomplete and experimental features may appear from time to time via such updates.
This warning applies to both updating BX and updating scripts for other applications.
Also, the update system's ability to function may be dependent on local and network policy restrictions on web access and/or local file and folder access.
The following commands from the Global Functions map are available for performing updates:
For those who have defined a BX Quick Key, the same three keys typed after QuickKey D will also work.
See "The BX Quick Key" in the BX User's Guide for more information.
- U attempts to update the scripts for the running application.
- Shift+U attempts to update the scripts for the running application without regard to any special scripting project namespace that may apply to this machine. This will not be of concern to anyone for
whom the BX author has not done direct scripting work.
This command may be useful though for those for whom such work has been done; e.g., to update scripts for Skype or Skype For Business (SFB) on a machine that is otherwise considered to be part of a specific scripting project.
- Ctrl+U attempts to update BX itself.
Revision 1982, August 9, 2018
- The CPU load query command sequences, ] D W C and ] D W C, should work more often. Previously they would fail in console windows. Now they will most often succeed in a console window if already once run
since JAWS restart in a non-console window.
- The BX Configuration map, Apostrophe Ctrl+B, contains a command (F) that toggles the effect of the JAWS Script Utility Mode command. By default, the Script Utility Mode command turns on BX when BX is loaded;
and typing the command twice quickly instead turns on Script Utility Mode. This toggle switches these so that a single press activates Script Utility Mode and a double press activates BX.
Typing F once in the BX Configuration map simply announces the toggle's current state. Typing F more than once, regardless of how fast, toggles the setting back and forth between the two alternatives.
This BX update fixes the announcement of the new state when it is toggled. The toggling worked before but was announced incorrectly.
Revision 1970, June 25, 2018
S in Object Examination includes the hex value from
GetObjectStateCode, a function that has been around for a long time.
In sufficiently new versions of JAWS 2018 and later, pressing S twice will report the hex values from
GetObjectIA2State, and pressing three times will report the hex
At least the first two of these three new functions are documented in versions of JAWS 2018 prior to their actual implementation in JAWS itself.
Revision 1961, May 8, 2018
- The minimum JAWS version for BX is now changed from 14 to 15.
bx_user.conf allows a new
fastSpeechHistory setting. When set to 1, this
causes the JAWS Insert+Space H sequence to bring up speech history in the old JAWS user buffer instead
of the newer Results Viewer. Especially if userBuffer display is switched Off in JAWS settings, this results in
much faster availability of speech history when this command is typed.
- Shift+C in the WTM QuickKey map includes highest processor user and usage percent under Windows 8/10, though out of 100 instead of within total CPU usage.
- In the UIA Navigation map, the UIA native window handle command is now W instead of Shift+H.
- In Global Functions, Shift+V reports major and minor Windows version numbers when unable to determine a friendlier name for the active Windows version.
- Some obsolete features of BX are removed, along with some superfluous output error messages held over from many years ago.
- The installer is a bit more likely to succeed in locations where read access to the Windows registry is not allowed.
Revision 1876, September 6, 2017
- The installer works under JAWS 2018 beta and should work under JAWS 2018 when it is released.
- If the installer fails to find a usable JAWS instance, it will display a log to help the developer understand why.
- L in HTML and XML Testing returns the bounding rectangle of an FSXML element when possible, though it may first move the element onto the screen.
- Shift+L in Window Navigation reports element count alongside length for
and the help string for the command is more accurate.
The text returned for double and triple presses may sometimes be cut short though.
- BX now includes nine new properties in UIA property lists that are not mentioned in the JAWS 18
A JAWS restart after updating BX may be required before these properties will appear in the Alt+Right property lists for UIA elements.
r8 variable types are reported properly in and out of arrays in the UIA element property list.
- A double D in UIA Navigation lists custom property values when property ids are available.
- Numerous tests for JAWS versions that BX no longer supports are removed.
- Shift+M in Global Functions reports Metro app name and version along with the already-reported
- Shift+A in Global Functions is just one function test, and Alt+A is removed.
These changes reflect changes to JAWS' handling of ARIA applications in or after JAWS 13.
- Multiple updates for virtual view handling (Shift+V in Cursor Navigation):
- The type "static text" is no longer announced.
- Regions no longer include type names on their start and end lines because the lines already include this.
- The state "Vertical" sometimes found on combo boxes is removed.
- Task switching by number
(BXQuickKey W when a quick key is defined)
will now attempt a special approach for Skype For Business 2016 conversation windows when appropriate.
- Windows 10 Settings and Store windows no longer appear to BX as tasks when their UI windows don't exist.
- There is a UIAScriptAPI object cache, to work around the problem of the BX event tracker, loaded on top of active scripts,
CreateObjectEx to fail to get one.
Revision 1813, April 1, 2017
bxman.htm is now just
bx.htm for consistency with other projects.
- Typing BX QuickKey sequences very rapidly should no longer cause keys to reach the focused application.
- Event tracing without unloading current app scripts works again.
- S in Window Navigation no longer includes code comments.
- Ctrl+Shift+JAWSKey+RightArrow in MSAA Navigation works on modern JAWS and Windows versions.
- Tab position in a map is not lost by visiting and returning from one of its context maps.
- Some functionality may be slightly faster due to use of scripting capabilities added in JAWS 14.
Revision 1797, March 28, 2017
There are numerous improvements and additions over the 15a release, unfortunately not at this time listed here.
Revision 1164 (Version 15a), January 20, 2014
This version was long considered experimental.
It is the last version supporting JAWS 13 and older and is not recommended for newer JAWS versions.
- Error messages on 64-bit Windows machines, such as "can't make the VBS environment," should no longer speak.
- Vvarious VBScript and JScript errors from HTML Navigation commands should now speak without bringing up error dialogs on 64-bit Windows versions just as on 32-bit ones.
Enhancements and changes:
- Major rewrite of BX's internal structure for handling locations.
- For string comparisons, the "
==" operator is now treated with JAWS 12+ semantics, i.e., full match rather than match only through shortest string. "
StringComparison Partial" is no longer used in BX.
- This and subsequent BX versions will not compile or run properly under anything older than the latest update of JAWS 11.
- New UIA Navigation map that can help in UIA testing under JAWS 14 and later. Includes the ability to type a filter specification to choose the UIA view to navigate (raw, control, content, current process,
specific control types, or any combination). More on filters below.
- New Context map from UIA Navigation for jumping from a UIA object to its window, MSAA element, or rectangle.
- New UIA Find map (/ from UIA Navigation) for collecting all elements matching a filter specification and moving through them with arrows. More on filters below.
- New Context map entries for Window and MSAA Navigation to jump to the corresponding UIA elements.
- Activating a map before you have a location (e.g., a window or MSAA object) will move to a default location for that map and announce this. This means you no longer have to type Ctrl+F when
switching to Window or MSAA Navigation for the first time.
- Most maps, not just the Window Navigation map, save their previous locations across BX activations. This means, for example, that MSAA Navigation will stay at the last object/element visited even when
you turn BX off and back on. A JAWS restart will of course reset all this.
- Marks are no longer saved across JAWS restarts.
- There is now a history system in BX: Alt+Shift+UpArrow returns to the previously visited location and the map from which it was visited. Subsequent presses retreat up to 20 locations back
through visitation history. Alt+Shift+DownArrow steps forward through these locations. Both wrap at the end of the history saved.
bx.jsd no longer contains function declaration overrides required for BX compilation.
UIA Filter Specifications:
BX now includes a system for letting users specify UIA tree filters via an edit box. This system encapsulates the various Condition-building features of the new JAWS 15 (and undocumented but present in JAWS 14) UIAScriptAPI COM system.
Filter strings, or specifications, consist of a series of one or more items separated by single spaces. The items
comprise an expression that forms a filter condition. The expression is in post-fix, or Reverse Polish Notation
(RPN) format. This may be unfamiliar to some users but significantly simplifies expressions by avoiding the need
for parentheses and for recursion in parsing (which JAWS does not support). Example expressions:
- Requests the entire UIA tree be visible for navigation.
- contentView focusedProcess and
- Include only content-view elements and only those in the focused Windows process.
- Shorthand for the above.
- FPRawView controlType checkBox controlType edit or and
- Include only checkboxes and edit controls in the focused process (this much complexity is rarely necessary).
Here are all the types of items permitted in a filter specification:
- contentView, controlView, rawView
- Require the given UIA tree view type.
- Require the process ID to match the focused application's process ID.
- One of the above with
- Reverse the previous condition: "
- and, or
- Combine previous two conditions: "
contentView focusedProcess and."
- property name
- The name of a property with a PropertyID. These are from
UIA.jsh without the
UIA_ prefix and PropertyId suffix. Examples:
- value name
- The name of a value with an ID. Categories:
- Control types like
- Other constants without *
_ prefix, like
- Other raw constants like
Next that contain no underscore.
- False, True
- Create a boolPropertyCondition with the previous item. Example: "
IsEnabled True." If not after a property, creates a
True condition (directly in JAWS 15.0.5056+, simulated before that).
- int like 1, -50, etc.
- An integer value. Makes an
IntPropertyCondition with the previous item. Example: "
- String like 'hello'
- A string value. Makes a
StringPropertyCondition with the previous item. Example: "
Name 'My UIA Application'" To get a literal apostrophe in a string, write two of them
together. Backslash escapes like \t also work.
Version 10a, January 14, 2014
This is the last BX version supporting JAWS 10 and older and is not recommended for newer JAWS versions.
This version calls itself "BX10" when Insert+Q is typed while BX is active.
There is no listed revision number for this release because it was for a while maintained in a separate code branch.
Window Navigation updates:
- A double Shift+C reports the total number of descendants (at any level) under the current BX window. If a filter is in effect, the number of descendants matching the filter and the total number of descendants are announced.
HTML Testing updates:
- Major event attribute announcement clutter in IE 9 fixed.
- Ctrl+L allows querying of
element.getBoundingClientRect(), which appears to be the best way to get the rectangle containing an HTML element.
- Major internal reorganizations including better modularization, more well-defined paths for data and execution to transfer among modules, and better namespace management. (This is an ongoing effort and is still not complete.)
bx.jsd entries required for compilation under very old JAWS versions reduced.
- The distributed
bx.jsb and other jsb files are compiled with JAWS 10.0 rather than JAWS 5.0.
- Various installer/uninstaller fixes, including better guessing of
jfw.exe file location when not findable in the Windows registry (helps when JAWS is not on drive C), not interfering with
SkypeWatch installations, better script chain management, and better handling of non-English BX uninstallation.
Revision 921, March 1, 2013
- ListView Navigation map significantly rewritten.
- Inspect Objects navigation works with an up-to-date inspect.exe as long as the view is set to MSAA rather than UI Automation.
- New maps for ITextDocument and ITextRange object inspection.
- New experimental Script Utility map inside BX to provide Script Utility features with BX-style help functionality. Not a complete Script Utility replacement though.
MSAA Navigation updates:
- BX can report properties that can be accessed from a native object but not via parent+childID; e.g., when one must call
oParent.accChild(childID).accName(0) rather than
oParent.accName(childID). This behavior is affected by Accent (`), which adjusts what BX does for objects that can be examined by parent+childID or as objects unto themselves.
Object Examination updates:
- Shift+C reports any or all JAWS object levels from the JAWS cache.
AccessibleObject Tree navigation updates:
- There is a Context map to allow examination of an AccessibleObject's screen rectangle.
- Marks work in this map.
- Ctrl+F twice forces use of the last window visited in Window Navigation.
Cursor Navigation updates:
- Shift+X displays an XML view of the DOM for the current screen (see the JAWS
Global Functions updates:
- O twice includes the
- Event logging documented in the manual (
bxman.htm), including how to customize log entries and what is logged.
- Installer significantly updated.
- BX and installer source files included in installer but not installed by it.
- Section and key lists at the end of
bx.kmp and code to use them removed (not needed since JAWS 5.0).
- PACMate support discontinued.
- ListTbl navigation and progress bar announcement support removed from BX.
Revision 818, December 19, 2011
AccessibleObject Tree Navigation (.a from Window Navigation):
- Ctrl+T goes to the top-level (root) object in the tree.
COM Object Testing:
- N for
COMGetAvailableNames (not yet documented by FS, lists COM object properties and methods).
- Alt+A turns on
UseApplicationMode on a single press and off on a double press.
- Shift+A reports the values of
- R reports various pieces of ribbon status info.
- L returns
getCurrentDocumentLength() (for virtual documents but returns results elsewhere also).
- Insert+V works in JAWS 13.
- Navigation by childID in MSAA Navigation (PgUp/PgDn etc.) will say "Try AccChild" on encountering a childID for which no
AccRole is returned but for which
would return an object. Inspired by something that happened to Jonathan Avila during a bug fixing project in an application supporting IA2.
- A for UIA automation ID at current object level.
- C for window class name of object at current object level.
- Alt+U for
- Alt+Shift+U for
UIARefresh(True, 5000) (synchronous with 5-second timeout).
- N for
- Shift+N for
SDMGetControlActiveItem (which I think may be misnamed).
- T for
- V for
- F for
- Double F for
- The Scroll submap under Window Messages, reachable from Window Navigation via ; S, should work now.
- The dotted focus rectangle for a window, reached via the Shift+R context map (Period Shift+R), should be better at finding dotted focus rectangles.
- The event watcher (BXQuickKey D then Ctrl+E or Ctrl+Shift+E) watches 40 more events and includes an indent level digit in its output.
- The Put-to-clipboard-from-buffer command, BXQuickKey P, works as advertised (thanks Roy for catching this one).
- The "Object created" message on 64-bit Windows is removed.
- Ctrl+Shift and Alt+Shift commands work on JAWS 13, and other JAWS 13 adjustments are also included.
Known remaining issues:
- Some multikey commands involving Insert or JAWSKey may still not work in JAWS 13.
Revision 718, August 6, 2011
New Maps and Features:
- There is a new Accessible Object Tree map reachable via A from Window Navigation's Context map. This allows exploration of UIA, Windows Forms, and Silverlight accessible object trees.
- There is a new iTextDocument map for inspecting RichEdit objects: Focus a RichEdit window, switch to the COM Object Testing map (Apostrophe Shift+O), get the nativeOM object (Shift+O),
and switch to the map for that object type (Apostrophe Apostrophe). This system is not as complete as it could be.
- BX should work on 64-bit Windows versions. At present, extra messages like "No object" and "Object created" may speak from time to time on 64-bit systems when BX is running and the user attempts to
activate BX or a BX function. News of any 64-bit system where BX will not work would be most appreciated. The 64-bit approach can be tested on 32-bit Windows by creating a file called
(no extension) in the active JAWS user folder.
- BX should work from within Excel 2007.
- J in the BX Configuration map now creates new
bx_user.cnf files in the JAWS user folder rather than in the shared folder. Problem discovered by Roy.
- The BXQuickKey is no longer enabled by default, largely because the BX uninstaller fails to disable
its key assignment, resulting in an unusable key. The recommended way to enable the key now is to add a
QuickKey=... line to
bx_user.cnf in the JAWS user folder.
WM_GetTextLength surprises (e.g., mismatches with
getWindowName() length) are announced as the user navigates among windows, rather than just when the user presses N.
- Shift+N in Window Navigation now attempts to announce or spell the actual
WM_GetText result for the current
BX window, instead of saying the
getRealWindow window's name. This is not always successful and usually returns
everything in lower case regardless of the
WM_GetText result's actual letter casing.
- Shift+R in the Context map for Window Navigation will, when possible, move to the dotted focus rectangle found
in the current window. This can find dotted rectangles that JAWS itself does not detect.
- Windows with Left/Right/Up in Window Navigation now send the active cursor position along with the
- Movements in MSAA Navigation now report all non-empty properties of the MSAA object or element moved to, instead of just name, role, and state. The newly spoken ones are prefixed with the basic property name, such as Description.
Revision 582, January 31, 2011
- New Window Navigation commands for sending right, left double click, and hover events to a window via
SendMessage. These are experimental and possibly temporary.
- Pressing R three times when the current object or element has a custom (string) role will spell the role string instead of trying to give it as a hex value. JAWS will currently say "empty
string" after this though, because of the way this feature is implemented.
- Workaround implemented for the JAWS 12 bug of
SwitchToScriptFile returning False even on success. This fixes the problem of BX unloading scripts for applications like Winamp under JAWS 12.
- Eliminated the "GetObjectFromEvent took 0 milliseconds" messages at lock and login screens by making
ObjTrackMaxTicks=0 mean the same as
-1. This still disables object call
tracking at these screens even if the user wants them enabled, but it's still an improvement.
- JAWSKey+7 (window class reassign) works under JAWS 12 when typed from within BX. (JAWS 12 changed how that script works.)
- A few bug fixes and improvements in the internal MSAA code library, and several other internal code fixes and reorganizations..
Known issues that have not yet been addressed:
- The BX script code installs
default.jkm mappings for the BXQuickKey, but the uninstaller does not remove them.
Revision 533, October 25, 2010
General (multiple map) changes:
- Most if not all L commands in various maps, when used to get location information, also include offScreen indications for rectangles after the width and height.
- V now reports anomalies in window visibility, such as the MSAA client being marked Visible when the window is not.
- V also announces percentages offScreen for windows and mentions if the width and/or height of the window is 0.
- Shift+F in Window Navigation reports the result of
IsWinFormsWindow on the current BX window. This function appears to be undocumented and may take other parameters or no parameters at all.
- Windows+LeftArrow sends a Click event to the current BX window without requiring it to be in focus or even visible.
- K twice spells the keyboard shortcut.
- Shift+E is now able to find the AccEvent32 event list even if AccEvent32 is minimized.
Inspect Objects navigation:
- Shift+A says Ancestors count and lists ancestors on a double press. On a triple press, it says the Parent value.
- A double C says the number of children actually listed, as opposed to the
ChildCount value; and a triple press lists the children shown.
- The help for G is working now, instead of making a silent tab stop for Tab. The functionality is not yet implemented though.
- a triple H says the "How Found" entry.
- a triple I spells the Annotation ID.
- Shift+I says the list of supported interfaces, and a double press says the Implementation for this object.
- Shift+S says the number of selected children, and Shift+S lists them.
- W says the Window entry.
- Ctrl+Shift+S shows all non-blank
runtimeStyle properties in a sorted list in the JAWS virtual buffer, and in a format that can
be copied in whole or in part into a style sheet. (Thanks to Bryan Garaventa for help with this functionality.)
- Ctrl+RightArrow from an Object tag announces the typeName of the
.object property of the node, and a quick double press moves to that object. Useful when there is a map for the
object type; see the information on the new Flash map below.
- Fix: Hitting an edge says "edge" and does not try to go one pixel too far.
COM Object Testing:
- VBScript errors encountered during a
TLIEval() call are announced.
- keymap safety escapes during
bxObjApply() and executions of "E" are disabled, because they caused key leaks.
- The TLI object is no longer used to get the interface name of an object created in COM Object Testing. Instead, the VBS environment and
TypeName() are used to get the object's name. This
further minimizes the need for
- There is a partial ShockwaveFlash map which can be reached with a double Apostrophe after moving to a Flash object with the Ctrl+RightArrow command from its HTML object tag.
keymap.jsh eliminated from sources (absorbed into
msaa.jsh included in sources (was left out as an oversight).
Revision 377, May 11, 2010
- JAWS will no longer say "JAWSKey+Windows+Dash" or similar when the user exits BX using that command in JAWS 11.
- Users should no longer alter
bx.cnf but should instead put their customizations in a
bx_user.cnf file, whose contents will override
bx.cnf. This will keep future
BX updates from clobbering user settings in that file.
- In the BX Configuration map, the key to open
bx.cnf is now Shift+J, and a plain J opens
bx_user.cnf. This parallels K and Shift+K
- S in Window Navigation attempts to report some of the extended window styles like
WS_EX_TOPMOST. This is experimental and is based on the assumption that the JAWS
GetWindowStyleBits() command is including some of those bits in its result. This seems to be true but is not absolutely proven.
- Shift+B in Window Navigation reports the result of calling the (apparently undocumented) JAWS
- Shift+M in Object Examination reports the
GetObjectModuleID result. This is a new function in JAWS 11 that reports the type of environment in focus, such as MSAA, IE, Firefox, PDF, ITunes, MSWord, etc.
- In Window Navigation, U is now a
FocusWindowSupportsUIA() call, and the
WM_GetObject UIARootObjectId SendMessage call is moved to Shift+U.
- The BXQuickKey sequence for dialing a phone number via Skype from near or under the active cursor should now work more reliably.
- BX compiles on JAWS 11.
- The event watcher now includes the following new events, found in at least JAWS 11.0.1430:
Revision 304, February 16, 2010
- Typing JAWSKey+Space or Insert+Space twice on JAWS 11 and later will enter or exit BX. This is for JAWS 10 and older users who are accustomed to the older command for starting BX
or Home Row mode (now Script Utility mode).
- The "GetObjectFromEvent took 0 milliseconds" and "can't make the VBS environment" messages that started plaguing JAWS 11 users as of the Freedom Scientific JAWS 11 security update should be gone. These
occurred when the effective user ID was "system," which includes login and security screens and UAC dialogs.
- Uninstalling BX no longer deletes
bx_user.kmp if it exists, since the installer doesn't install it and BX itself doesn't create it.
Revision 280, November 25, 2009
- Ctrl+P in MSAA Navigation is better at getting as close as it can to the current MSAA object on an IE page when
- Period C (Context Client) in Window Navigation and Ctrl+P (objectAtPoint) in MSAA Navigation will now use logic to find the usable MSAA client object for an IE window when the JAWS
GetObjectFromEvent functions return a client with no descendants.
JAWS will also announce which object ID was used and, for Ctrl+P in MSAA Navigation, how many
AccHitTest calls were then required.
- Fixed a number of issues with typeName determination.
- The installer should now run on 64-bit Windows.
Revision 244, September 27, 2009
The BXTest system is enhanced as follows:
- BXQuickKey T ? will bring into the JAWS virtual buffer a list of the
BXTest functions currently in scope, with descriptions of each. Important: Do not
use this feature until you have addressed the next item.
- All defined
BXTest functions (
BXTestNum()), be they loaded via application
scripts or via default scripts, must do one of two things to be safely usable with the above new command (doing
both is ok, but doing neither is not):
- Include jsd Description and/or Synopsis for itself, or
- Return a help string if passed a parameter of
The intent of this BXTest enhancement is to allow creation of comprehensive code testing systems that have no end-user impact, document themselves, and can remain in production code without causing any harm.
Revision 238, September 23, 2009
- The BXQuickKey is now set in the user's
default.jkm file from the QuickKey entry in
bx.cnf. Beware: This will cause everyone to have the right square bracket (])
assigned as a BXQuickKey by default. To type that character as a character, press it twice. To change the BXQuickKey, edit the
QuickKey= line in
bx.cnf and reload JAWS or re-initialize
scripts. To disable the BXQuickKey entirely, comment out or remove the
QuickKey= line and reload JAWS or re-initialize scripts.
bx.cnf contained a
BXQuickKey=<key> entry that was the real BXQuickKey, and an unused
QuickKey=1 line. Now, there's just a
QuickKey=<key> line. If you start having BXQuickKey problems, check your
bx.cnf file to make sure it matches this specification.
- BXQuickKey Space will activate BX, for convenience in JAWS 11.
- Fix: The BXQuickKey can again find its maps if activated after a JAWS load before the first use of BX itself. This was broken in the September 22 BX version.
- Fix: BX will again return to the last-used map when it should instead of always going to Window Navigation. This was also broken in the September 22 BX version.
Revision 233, September 22, 2009
- The reliability of the update code for
default_fs.jsb is improved,
default_fs.jsd is now managed as well, and the whole process is now automatic instead of requiring the user
to invoke it from the BX Configuration map.
- Shift+P in HTML Navigation includes the document type comment (if present) just as Shift+G from the #Document node already does.
- Much more documentation in
bx.jsd is accessible to the JAWS Script Manager.
Revision 212, September 17, 2009
Miscellaneous quick changes:
Beep() calls are now logged by the Event Watcher.
- JAWSKey+Q in any map says a more easily intelligible date/time.
- Fix: JAWS no longer says "Auto AccChild" when Ctrl+RightArrow in MSAA Navigation is used to request an
AccChild call directly. This bug was introduced on July 9, 2008.
- Fix: Typing Alt+C in a userBuffer from collecting text will beep instead of trying to start a new collection.
- Admin privileges are explicitly requested. This might help on Vista and/or Windows 7.
- Solid rather than plain LZMA compression is used, saving about 80 K.
- JAWS should no longer say "NullSoft Install System" three times in a row now and then during installation.
- The NSIS installer used is now 2.45 instead of 2.35.
And one big change:
This update eliminates a lot of JAWS-based tricks for identifying VARIANT variable types, in favor of a much more reliable VBScript-based approach. This enables the following new features:
- The elimination of an entire obsolete code module.
- No more ambiguity on MSAA and HTML DOM method and property return types.
- The elimination of Z and Shift+Z in MSAA Navigation, which were used to force JAWS to try to interpret navigation results as IDs or objects.
AccHitTest failures (Ctrl+Shift+P in MSAA Navigation) are fixed.
In addition, the following are included to aid in identifying exactly how MSAA calls respond:
- Navigations that return
ChildID_Self will say "self" in the JAWS message voice.
- Navigations to unexpected types will announce the unexpected type by name.
- If an
AccSelection call returns an array, JAWS will say "multiple items" in the JAWS message voice.
- If an
AccHitTest call returns a childID belonging to the current object's parent, this will be indicated by JAWS saying "ID for parent" in the JAWS message voice.
Revision 204, September 16, 2009
BX is now versioned in Bazaar rather than CVS.
default_bxsample.* may ease manual installation.
bx.jcf is now
bx.cnf, so if you customized
bx.cnf accordingly after installation. You can then delete your old
file. Freedom Scientific recommended this name change.
- You can delete old BX jsl files after this upgrade if you're not using them for other projects, as BX no longer uses jsl files.
- If your BX was old enough to have enabled BXGauge beeps by default, rest assured this is no longer the case in this version.
- Restart JAWS after upgrading to this version so the
bx.jcf/cnf name change will take proper effect.
- Shift+L in Window Navigation can now give the length, content, and spelling of the
GetListOfObjects result for the current window. The window spatial info formerly assigned to
Shift+L is now on Ctrl+L. This update revealed that many windows, such as in AIM 7, return nothing for this call under JAWS 10.
- Shift+R in Object Examination now tries every possible bit against
GetRelationText() (JAWS 10 and later) and speaks a summary of results. This is for IAccessible2 testing.
- Shift+G in HTML Testing now copies any top-level comment nodes, such as
DocType, to the clipboard and JAWS userBuffer along with the
outerHTML of the
documentElement. This should make it capable of regenerating a complete DOM in text form.
- JAWSKey+Q from any BX map says the BX compilation date, so it will start getting easier to find out who has what.
- Experimental real-time mouse position reporting is enabled when the JAWS cursor is active and BX is on. Features:
- BXGauge-style sounds indicating screen position as the mouse moves.
- Sounds for various types of window border crossings in real time.
- Reporting of control information where the mouse stops.
bx.jcf is renamed to
bx.cnf. A JAWS restart should be performed after upgrading across this boundary, and you may need to reapply any special changes you made to
in the new
- No more jsl files; all is in
- Code in BX is now in the BX namespace (function names have a "
bx__" prefix) so it won't collide with any other project.
- F1 and JAWSKey+F1 are being replaced by JAWSKey+H. Currently all three are active, but as of now, only JAWSKey+H is documented in the manual.
- Fix: Automatic update code for default JAWS files should be improved.
- Fix: The first launch of BX starts BX, not home-row mode, when
bxFirst is set in
bx.cnf, even if the machine has been running without a reboot for over 24 days.
- Fix: The "dial-from-cursor" sequence works again and with Skype 4.
bxGetJAWSVirtualView() (Shift+V in Cursor Navigation) turns off auto forms mode in JAWS 10 or later to avoid various mishaps.
AccHitTest (Ctrl+Shift+P in MSAA Navigation) uses 0-based coordinates for MSAA instead of 1-based ones.
IEFrame now has the same application map as
BrowseUI, so the HTML application map works on multiframe pages. TODO: It's done with an
Include, which makes
Tab etc. not find any help text.
bxGauge()'s last parameter is now explicitly optional.
June 2, 2009
BX development silence as preparations were made to convert versioning from CVS to Bazaar.
Revision 103 (end of CVS history), May 20, 2009
- Ctrl+Shift+E now loads the event watcher over the current scripts, rather than in place of them as with Ctrl+E.
- Ctrl+B and Ctrl+Shift+B load Braille event watchers much as Ctrl+E and Ctrl+Shift+E load non-Braille event watchers.
- BXQuickKey D d enters a debug log manager map:
- E to enable debug message logging.
- D to disable logging and show the log.
- U in Window Navigation will report the integer result of
sendMessage(hwnd, WM_GetObject, 0, UIARootObjectId) to the current window. May be useful for UI Automation testing, at
least to see what windows support it.
- Q in Window Navigation now returns the
QueryClassNameIdx window type as text on a single press, decimal on a double press, and hex on a triple press. According to Microsoft
documentation at MSDN, a non-zero result means the window is a standard User32 or ComCtl control. The index value can indicate what kind as well.
- BXQuickKey D F queries the
AutoFormsModeValue, and Shift+F toggles it.
- BXQuickKey A C in the JAWS Script Manager, if used while the cursor is on a function definition line, will paste below it a call to that function with all parameters included. Useful for writing event-chaining code:
- Copy event definition from
- Use BXQuickKey A C to create the event-chaining call.
- Fill in custom code.
- Add "
- There is a Scroll map accessible from the Window Messages map for testing
- Fix: Better
olutil::olGetJAWSInfo() return of JAWS build number.
- Fix: Exclusion of
TApplication windows from the BX task list when duplicated by something else.
- Fix: B and Shift+N were missing from BXQuickKey top-level map help (thanks Roy for pointing out that b was missing).
- Fix: Ctrl+P and Ctrl+Shift+P in HTML Navigation now work much more reliably and on more pages with frames. (Added use of
- Fix: Workarounds implemented in MSAA code for JAWS 10's apparent inability to return anything but 0 for
- Fix: More direct (
GetObject-based) method of getting the
TLI.TLIApplication object when necessary.
- Fix: Ctrl+Shift+L in Window Navigation should no longer say " to 100" instead of "0 to 100" when a window entirely covers its container.
olchar.jsl is now obsolete.
CVS tag bx_rel081211_sam, December 11, 2008
The CVS tag for this revision is so named because this version of BX was sent to a coworker named Sam for a project.
- In HTML Navigation, Expressions governing HTML attribute values should now be reported on Up/Down in an attribute list (from an Alt+RightArrow).
- S in Global Functions now says the
GetActiveConfiguration value before the name of the running script.
- Ctrl+Shift+T in Window Navigation goes if possible to the tooltip window that last fired for the app in focus. The tooltip must still be visible for this to work.
- E in COM Object Testing now works without
- A double quote (") from any map will announce the typeName of the current object without requiring
TLBInf32.dll. A double press is now required to get the interface name, which does require the DLL.
- Pressing Apostrophe (') from the Map map will now switch to the map for the current object if there is one, like a double press of double-quote did before.
- The edit command (E) in COM Object Testing now accepts arbitrary VBScript expressions in which "
o" refers to the current BX object, as long as the expression contains parentheses
somewhere so it can be distinguished from just an object ID like Scripting.Dictionary. Trick: If you want that kind of evaluation but have no parens in your expression, add a single quote and a left paren
to the end of the expression (that's a VBScript comment).
- There are some rearrangements and new commands in the Window Messages map, reachable via a semicolon (;) from the Window Navigation map.
- There is a Scroll map accessible via S from the Window Messages map for testing
- Fix: Warnings added for W, Shift+W, and Ctrl+Shift+W in Window Navigation.
- Fix: Attempts to help BX identify object types better in JAWS 10, where object references started sometimes returning an object's default value instead of the object's actual reference.
bxtliTypeName() should start working here.
bxmsaaShowVisiblePartOfTree now gets full-blown Accessible Objects from childIDs before looking for their properties, because at least one environment was seen to report empty properties
AccState when non-zero childIDs are used though correct values come back after a
bxGetInspectObjectsData doesn't miss the left bracket for
VarChild and is less easily fooled by text strings like "help" in the data.
bxIsActive() can be called from debugging code to see if BX is currently active.
logcallExtra() function for adding info to event logs can call a new
logcallParm() function to retrieve parameter values of logged function calls.
CVS tag bx_rel081017_scott, October 17, 2008
Like the above revision, this one was sent to a coworker after whom the CVS tag is named.
BXGauge beeps are now disabled by default.
- The Event Watcher watches more events, including events specific to FSReader and VB6.
CVS tag bx_rel081013_roy, October 13, 2008
Yet another CVS tag named after a coworker recipient of the revision.
- The Event Watcher logs calls to speech-generating functions (about 44 of them).
- Experiment: Tried using an MSAA method of setting focus to effect task switching via the BXQuickKey.
CVS tag bx_rel081010, October 10, 2008
(This text is drawn from an email.)
The most notable update is the addition of
bx_evwatch.jsb and a system that allows for event watching without
requiring application script files to be edited. The new system is documented in
BXMan.htm under its own section,
which should be easier to find because
BXMan.htm also has a table of contents now. In summary, it works like this:
- Before logging, type BXQuickKey D Ctrl+E to load the
- Type JAWSKey+E twice quickly to turn logging on.
- Do things for which you want event logs.
- Type another single JAWSKey+E to turn logging off and see the results in the JAWS virtual viewer.
- Repeat starting at step 2 to generate new logs.
- The event logging code unloads on the next Alt+Tab.
bx_evwatch code is running, application script and configuration files will not be loaded, so the events logged will be what JAWS does by itself.
The system currently tracks about 134 events and
Say functions, all I know of to date through JAWS 10 including some undocumented stuff. You can fine-tune what events are logged and even what
is logged for each by writing
logcallExtra() functions (names subject to change though). You can even pick functions to log by whether or not, and how deep,
they are found in the calling chain of another function; for example, log
FocusChangedEventEx but nothing called from it.
In the log output, which is also placed on the Windows clipboard automatically when shown, the first column is the decimal number of seconds from log start when the call occurred, the second column is "c"
for a call and "r" for its return, and the rest is the call itself with parameters, and return value where appropriate.
The semicolon key (;), which cycles among related maps from some maps, is now documented. In the Window Navigation map, it toggles with a new Window Messages map, which can be used to see what
happens when various messages are sent to a specific window using
PostMessage. Among other things, this map provides means to test methods of moving focus through a
dialog or among MDI children that Microsoft says are better than using
N in Window Navigation, which has always reported the result of the JAWS
GetWindowName function, now also reports when the length of that result differs from the result of the
WM_GetTextLength message, which can help detect when JAWS is "guessing" at a window name instead of providing what
WM_GetText would provide. We can't get
directly in JAWS, but this at least helps determine when this might matter. Caveat: The two lengths often differ by one character even when the strings otherwise would match, so at best this new report is
just a heads-up, not an indication of missing info.
E in COM Object Testing will now allow parameters to be passed to method calls.
P and Ctrl+P in HTML Navigation and Ctrl+P and Ctrl+Shift+P in MSAA Navigation should now work with the Virtual PC cursor active.
There are a few improvements in how the Braille map is implemented.
BXMSAA.jsh includes some extra MSAA constants listed as Gecko navigation commands. These have not been tested but will not apply to many applications.
When you navigate in the MSAA map, you may occasionally hear "AutoAccChild," indicating that BX automatically called
.AccChild to get somewhere even though you did not explicitly ask for this. The
behavior is not new, but the announcement of it is.
A few superfluous files are no longer included in the
src folder in the zip file.
CVS tag bx_rel080616, June 16, 2008
Revision history documentation stops here for now.