JAWS Alert Manager (JAM)
Doug Lee
Last Revised July, 2023
The JAWS Alert Manager (JAM) is a set of JAWS scripts aimed at giving JAWS users control over the handling of Windows and application alert messages.
It also includes a few other, admittedly unrelated but useful features.
Notable among these is a system for examining websites without launching a browser or permitting any
downloaded web code to run locally.
This document describes JAM and how to use it.
This document can be opened by typing JAWSKey+/ followed by F1 if JAM is running in the
current JAWS version.
Note that the June, 2022 update to JAWS 2022 introduced a JAWS-native system for handling notification history
and review. This review system uses a popup dialog whereas JAM allows review without a dialog. The JAWS native
system also, by default, records UIA notifications that are by default ignored by JAM; see the JAM
Command U keystroke for toggling JAM's handling of UIA events.
See the JAM and the JAWS Native Notification Review System section for further
information on how the two systems differ and can cooperate.
Table of Contents
System Requirements For JAWS Users
The following requirements apply for JAWS users:
- The computer should be running Windows 10 or later. Older Windows versions may work but are likely not to send most alerts through the system that these scripts use, which means that many alerts will likely not be manageable with
these scripts except under Windows 10 and later.
- JAWS 18.0 or later should be used. The scripts will not work with or install into older JAWS versions.
Script Installation Instructions
To install these scripts 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.
- To verify successful installation, type JAWSKey+/ followed by Q.
Part of the JAWS spoken response should be a revision number. If you do not hear a revision number, the scripts are not correctly loaded.
In some cases, restarting JAWS may fix this issue.
Key Sequences
These scripts incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "command keystroke."
This approach allows many script commands without the risk of conflicting with application keystrokes.
See the "Multi-Key Command Sequences" section of the "Common Script Elements" document for further details, including
how to explore the available script commands (similar to exploring a menu system),
and how to change the Command keystroke if necessary.
By default, the Command keystroke for these scripts is JAWSKey+/.
This document may refer to this keystroke as JAWSKey+/ or Command;
so, for example, JAWSKey+/ Tab and Command Tab both refer to typing the prefix keystroke, then separately the Tab key.
Some sequences may consist of more than two keystrokes, or "levels"; for example, JAWSKey+/ d r would refer to typing JAWSKey+/, then d, then finally r.
Script Commands and Features
These scripts provide the following commands and features for users. The features are broken down into groups
based on their functionality.
Notification Handling
- All detected notifications are stored in an alert history for later review. By default, the history keeps up to the most recent 1,000 alerts. Old alerts are automatically removed as necessary.
- The alert history survives across JAWS and system restarts, though alerts will not be detected or added while JAWS and JAM are not running.
The history is also independent of JAWS version, so that switching or upgrading between JAWS versions does not create copies or gaps.
- Restarting JAWS will add a "JAM alert" indicating the event, so that users may have an idea of when the history was not being maintained immediately prior.
- By default, UIA notifications are not handled by JAM; but this may be toggled on and off with the sequence Command U.
JAWS starting in version 2021 calls these "accessibility notification events" and also announces them by default, but older JAWS versions ignore them.
Note that UIA alerts are only stored in the JAM alert store if they are handled by JAM in the first place. If JAM is set to let JAWS handle them, they will not appear in the alert store.
- Many alerts are shortened and/or otherwise reformatted for efficiency:
- The phrase "New notification from" is removed.
- Phone numbers that appear without divisions are divided into segments for easier reading.
- The extra announcement of the originating application name, such as "Skype," at the end of the alert is removed in many cases.
- Some application-specific further shortening may occur.
- Duplicate alerts, when detected, are silenced. A small scissor-clip sound will be heard when this occurs.
To qualify for silencing, an alert must duplicate the previously stored alert (i.e., there must be no other intervening alerts) and occur within two seconds of the original.
(From April, 2020 through January, 2022, this was eleven seconds to work around a Unigram bug:
(Unigram has been known to send duplicate chat message alerts eight or nine seconds after the original.)
- Command S toggles whether all alerts will be sent to JAWS for processing or silenced.
Note that when alerts are sent to JAWS for processing, whether they speak will be determined by JAWS.
When all alerts are silenced, they will all generate the scissor-clip sound and will be stored in the alert history for review,
but they will not be sent to JAWS for processing.
This setting will persist until changed again, even across JAWS or system restarts.
This can be especially handy during Zoom meetings and at other times when numerous alerts may be present and not wanted.
- When JAM is handling UIA alerts, UIA notification alerts that ask to replace recent instances of themselves, such as rapid volume change alerts, will store only the last instance.
The scripts define "recent" as "five seconds or less ago."
- Alerts may be reviewed by typing the Command keystroke followed by any number of these:
- Home and End: Jump to and read the first and last stored alert.
H and ; (semicolon) also work.
- Left and Right arrows move to and read the previous and next alert.
J and L are alternatives.
If no alert has yet been read, these commands will move to and read the first and last alert, respectively. The position of the
last-read alert is saved across JAWS and system restarts.
These commands provide an easy way to discover alerts missed during an extended time away from a running computer.
- NumPad 5 or K repeats the current alert (the last one moved to) and announces its position among stored alerts.
Using one of these commands twice in quick succession will spell the alert.
- 1 through 9 and 0: Read the most recent ten alerts, with 1 reading the most recent, 2 the next most recent, etc.
These commands do not update the current position used by arrows and do not honor any alert filtering;
they are meant as a quick way to check recently arrived alerts while reading through older ones.
Press Esc to stop navigation and return to the active application.
- During relative navigation, notification shortening may occur based on the previously read alert. See the next section for details.
This feature is off by default.
- For even faster skimming through notifications, use Command T to toggle on/off the announcement of alert times.
Times are announced by default.
The Minibrowser
- Command G allows you to bring up a webpage in a JAWS virtual view by typing (or
pasting) its URL into an edit box. This can be useful for rapid and/or safe examination of
a website. See the Browserless Web Page Review section for details and
caveats.
- While this dialog and edit box are open, the Up arrow will move, most recent first, through
recognized URLs found in speech history. The Down arrow will move forward through these choices.
JAWS will announce the position among choices, choice count, and URL for each arrow key, and will place the
URL chosen in the edit box.
In most cases, pressing Enter on such a URL will open the virtual view for that page; however, it
may occasionally be necessary to edit the URL before pressing Enter if the scripts collected too
much text, such as by including trailing sentence punctuation as part of the address.
- If you want to use a regular browser to visit a page listed by arrow keys in this dialog, type
Ctrl+A to select it after choosing it, then Ctrl+C to copy the URL to the clipboard.
Close the dialog with Esc, launch your browser or use the Windows Run dialog, and paste in the URL
to visit its page.
Miscellaneous Features
- On Windows versions that support this functionality, pressing the Del key while holding down Alt during an Alt+Tab cycle will close the currently selected application.
This is perhaps a random feature to include in these scripts, but the author's defense is that it provides a way to "unjam" a crashed or frozen application, whereas attempting to bring focus to it might freeze JAWS.
This is a standard Windows 10 feature that happens not to work in JAWS, at least up through JAWS 2023, because Alt+Del is a scripted keystroke.
Future JAWS versions may address this issue natively.
- Command F attempts to fix a script loading issue in Chrome web pages and applications:
If Insert+Q reports that "Chrome settings are loaded" but there should be active scripts for the current application or page, try this sequence to see if it causes the correct scripts to load. The usual workaround
for this issue is to type Alt+Tab twice to move out of and back into the current screen; this key sequence should be a faster solution.
Note that the sequence may say nothing if it has no effect in the current situation.
This is another feature that may seem misplaced in JAM but that is here to "unjam" a situation.
- Command Q announces the revision number of these scripts.
- Command Shift+U attempts to update these scripts from the author's website. This feature requires that BX is also installed.
Depending on the nature of the update applied, restarting JAWS after the update may be necessary before some or all new features or fixes function as expected.
At this writing, this quick-update feature will not activate any new command keystrokes or sequences; this will require running the full JAM installer.
- Command F1 loads this document for review in the default browser.
For the more technically inclined, and for those who wish to help with JAM development by providing information, JAM offers another convenience:
- Command Ctrl+C copies an XML representation of the events collected so far to the Windows clipboard for further examination.
For users of BX, this makes available the XML representation of the events thus far collected for inspection with that tool:
Type Command Ctrl+C to put the XML on the clipboard, then in the BX XML Navigation map, type Ctrl+V to jump to the XML structure from the clipboard.)
Note that BX revisions starting at 2434 also include a Ctrl+J command in XML Navigation that jumps directly to the last alert in JAM's live XML store when available.
Alert Shortening During Relative Navigation
The following script feature is turned off by default and may be toggled on and off via Command R.
During relative navigation through notifications, JAM can abbreviate each notification by removing from its start and end whatever start and end were spoken as part of the previous notification.
This tends to reduce repetitions of application names, text channel and sender names, trailing button text, etc. as you move through a series of notifications from the same origin.
Beware, though, that this can also remove actual content from what is spoken.
A famous example of this extra removal occurs when two notifications from a Windows Store update follow each other and are then read via relative navigation. Imagine that the following two notifications are encountered
during navigation, in this order:
12:14 New notification from Microsoft Store, Xbox Game Bar, Just got updated, check it out.
12:14 Microsoft Store, App Installer, Just got updated, check it out.
With the extra shortening in effect, JAM will announce them thus:
12:14 New notification from Microsoft Store, Xbox Game Bar, Just got updated, check it out.
12:14 App Installer,
Use Command K or Command NumPad5 to read the entire current notification without any extra shortening.
Notification shortening applies only during relative navigation and among notifications reached via that command set. Use of sequences like Command 1 (most recent notification) does not affect this shortening
feature; and speech on notification arrival is not abbreviated in this way.
JAM and the JAWS Native Notification Review System
The June, 2022 update to JAWS 2022 introduced a notification handling system similar to (and possibly based
on) JAM. JAM still works in that and subsequent JAWS versions and will continue to be supported for those who
prefer it.
A few things to keep in mind:
- If JAM is set to silence events, the silenced events will of course still appear in JAM's notification
history but will not appear in the JAWS notification history.
- If JAM is set to send alerts through to JAWS, the alerts will appear in both histories.
- Any alert processing rules set up in the JAWS system will not apply to or affect JAM's notification
handling.
This includes both rules for filtering notifications and rules for shortening text output from them in JAWS.
Some differences between the two notification management systems, in no particular order:
- The JAWS system uses an application and dialog to allow history review,
which moves focus out of the current application and may take a moment to load.
JAM provides commands to navigate history without a dialog and does not load a separate application.
Both systems include means to spell notification text.
- The notification store for JAM is shared among all JAWS versions; the store for the JAWS system is
specific to each JAWS version although it may well be migrated on a JAWS upgrade.
- The JAWS system currently has better support for customizing which alerts to announce and how to do it.
- The JAWS system handles UIA notifications, which can be numerous, by default whereas this must be enabled
in JAM with the Command U key sequence.
Browserless Web Page Review
These scripts provide a way to bring up a webpage directly from its URL without opening a browser:
Type Command G. A dialog will appear requesting a URL. Type or paste the URL of
interest and press Enter.
Up and Down arrows will alternatively allow choosing among URLs found in speech history;
see the
Minibrowser section in Script Commands and Features for details.
The requested page will appear in a JAWS virtual view.
Any links in the page will appear as links in this view, and pressing Enter will load the
corresponding page into a new JAWS virtual view when possible.
This system provides an often very fast way to examine a linked web page by avoiding the need
to open a browser. It may also improve security, since
absolutely no Javascript or other active client-side code from a website will be run on your computer in this case.
Corporate and government IT departments might also appreciate the fact that this system does not support
submission of web forms either.
There are a few caveats to keep in mind:
- Not all websites or pages will work well with this system. Pages that require code to run on your computer in order to function properly may not display fully, for example. In addition, sites that block automated scanning
and/or (bots) may be confused by this browserless approach and may return an error or different content accordingly.
- The JAWS scripts make an effort to eliminate prefatory material (navigation links, leading advertisements, etc.), but the approaches used for this will not likely work equally across all pages on the Internet.
- Some pages may fail to show the full main content in this view, for any number of reasons.
- At the time of writing, this system does not properly support frames.
At this writing though, this author finds frames mostly used as means of showing advertisements, as opposed to primary content.
- Links in a virtualized page may, but currently often do not, work. They do show up as links, however; and support of this sort of actual page-to-page browsing may be included in a future script release if of sufficient
interest.
- Finally, pages that send content in chunks and wait for responses may load slowly and/or incompletely.
At this writing, this appears to be a rare scenario in this author's experience.
In general, this author finds the following approach extremely helpful and efficient for reading
many reports, blogs, news articles, etc. that are advertised via Twitter, Discord, company Teams meetings, etc.:
- Obtain a URL to investigate by putting it on the clipboard from the application where it is found.
- Type Command G, paste the URL into the resulting edit box, and press Enter to bring
up the JAWS virtual view for the page.
- Use Ctrl+Down repeatedly to jump past any prefatory material not removed by the JAWS scripts from the view.
- Use arrows and/or the JAWS "Say all" command, Insert+Down, to read the page content.
- Press Esc when finished, to return to the active application.
This virtualization feature will likely undergo updates from time to time to improve its ability to work with more pages, based on user needs and requests.
Known Issues
The following issues are known and may be encountered during use of these JAWS scripts.
These issues may be fixed in a future script update .
Some alerts that should be shortened may be left unchanged.
The author considers this safer than accidentally cutting important text out of an alert as a result of trying too hard to make all alerts shorter.
When the scripts are removed, the alert data is not. This is harmless and will not impair uninstallation, future reinstallation, or computer operation.
If you later re-install the scripts, the alerts you previously stored will again be available.
Removing the alert store during uninstallation would cause all alerts to be lost on every script upgrade.
The alert store may be deleted manually by removing folder "%APPDATA%\JAWS Alert Manager" and its contents.
If you have saved filters or other configuration settings for JAM, these will be removed by deleting this folder as well.
Braille support is not well tested and is likely incomplete.
Fun Notes
The name JAM is an acronym for "JAWS Alert Manager." It is also convenient, however, that it is good at jamming the transmission of duplicate alerts.
For this reason, the author considers both "JAM" and "Jam" spellings appropriate for the utility.
Revision History
This is the revision history of these scripts, most recent revision first:
Revision 99, released August 1, 2023
- If JAM is handling UIA event announcements, updates from Windows volume controls and
from Windows Terminal screen changes are ignored automatically.
- Added the Minibrowser feature activated by Command G.
This command sequence permits quick review of many web pages without launching a browser or permitting any
form submission or any downloaded code to run on the local computer.
This feature is borrowed directly from this author's OpenTween scripts and is
included here to facilitate use of this feature from within other applications, such as Skype, Teams, Slack,
and Discord.
Here though, it also includes support, via Up and Down arrows in the "Enter URL" edit
box, for selecting a URL from speech history.
Revision 92, released June 22, 2022
Revision 88, released August 5, 2021
- The sound produced on hitting an end of the alert store is changed from a system beep to a short click.
- The prefix keystroke listed in the directives text file is corrected; it was Shift+Esc but
should have been JAWSKey+/.
Revision 86, released July 6, 2021
- Requesting the current alert twice in quick succession will spell it.
- Moving to next or previous stored alert no longer repeats the first/last message on encountering the end
of the message store.
This avoids a lot of extra speech in a very busy environment, such as during a very active Zoom meeting, when
JAM navigation is otherwise a very handy way to stay on top of rapidly arriving alerts.
- Improved the spoken messages for Command S.
- Added the Command F key sequence for fixing script loading issues in Chrome pages and web applications.
- Minor documentation updates.
Revision 74, released November 22, 2020
- The options for omitting time and shortening messages during message store navigation work as intended.
Unfortunately, the previous revision stored them correctly but acted as if they were both always turned on.
- The command sequences for toggling on and off the omit-time and shorten-message options do not leave the current key layer anymore.
This makes it easier to flip these switches on and off while navigating. Press Esc to exit the key layer as for navigation commands.
It will be necessary to use the script installer rather than the Command Shift+U update sequence to make this change take effect.
Revision 73, released November 19, 2020
Note: For correct operation of new commands, this script update must be installed via the installer rather than via the Command Shift+U sequence.
- The initial "New notification from" phrase is removed from many more notifications, both on arrival and during navigation through the alert store.
Thanks to Laurie Cherry-White for significant alert testing assistance.
- Alert shortening during relative navigation is implemented.
This can significantly speed reading through many notifications from the same application. (The feature was inspired by busy Discord chats.)
Use Command R to turn this feature on and off. The feature is turned off by default.
- Use Command T to turn on/off the announcement of times during navigation through alerts.
By default, times are announced.
- When JAM is set to handle UIA notifications, which JAWS 2021 calls "accessibility notification events," it will report them all rather than trying to be selective, so that none are lost.
JAM does still try to honor suggested rules for handling repeating alerts, however.
This change is prompted by apparent changes in how UIA notifications identify themselves in various versions of Windows 10.
Revision 66, released October 31, 2020