Custom JAWS Scripts For Unigram
Doug Lee
Last Revised March, 2020

This document describes the custom scripts for Unigram and provides tips for using this application with JAWS. This document can be opened from within the application via a double press of JAWSKey+F1 (or Insert+F1) when the scripts are running.

Table of Contents

System Requirements For JAWS Users

In addition to any system requirements for the application, the following apply for JAWS users:

Script Installation Instructions

To install these scripts on a new system:

  1. Load JAWS if this has not already been done. This will require administrative privileges on the computer.
  2. 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.
  3. 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.
  4. To verify successful installation, type Insert+q from within the application. 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 may incorporate commands that consist of sequences of keystrokes, all beginning with a common prefix, or "command key." 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 key if necessary.

By default, the Command key for these scripts is the left bracket ([) key. This document may refer to this key as [ or Command; so, for example, [ Tab and Command Tab both refer to typing the prefix key, then separately the Tab key. Some sequences may consist of more than two keys, or "levels"; for example, [ d r would refer to typing [, then d, then finally r.

Script Commands and Features

These scripts provide the following commands beyond those provided by the application itself:

These scripts also provide the following features:

Tips and Tricks

The JAWS touch cursor sometimes provides more information than the PC cursor, especially in Settings pages where it can find hints for fields, group headings, etc.

After opening a Settings page or subpage, it is often faster to reach the resulting screen area via Shift+Tab rather than with Tab.

When setting input and output devices in Settings > Advanced > Call Settings, use F4 rather than Alt+Down to open the combo boxes and then arrows to find a device and Enter to select it.

When setting a color theme in Settings > Chats, use Left and Right arrows to move among choices (Light, Dark, etc.), then Tab to the radio button corresponding to the last-selected list item and press Space to select the desired theme. Arrows will not move focus directly among these radio buttons.

A fast way to scroll through members of a group is to type an at sign (@) into the chat's edit box, then use Up and Down arrows to scroll through members via the autocomplete box. Press Backspace when done, to clear the at sign out of the edit box. Be aware that this trick will cause members to see that you are typing. Also, this will only show the first 20 members. You can also use this trick to look for specific members by typing partial names after the at sign; just remember to clear all characters out of the edit box when finished exploring.

To play a voice or video message, find it in the chat message list, Tab once to its link (optional for voice messages when using current scripts), and press Space to play. The Context menu, reached with the Menu or Applications key, also provides alternatives such as saving, opening in another application, and opening the message's containing folder to facilitate manipulation of these messages via Windows Explorer. Voice message files have a .oga extension and are Ogg-encapsulated Opus data readable by players that can handle this format, including the Windows 10 Groove Music app. Video messages have a .mp4 extension.

While a voice message is playing within the Unigram application, a media player will be available from which you can pause/resume the message, close the player to stop playback, or choose between normal and double-speed playback. This last option is remembered for future playbacks. Shift+Tab will most efficiently reach the controls in this player.

Known Issues

The following issues are known and may be encountered during use of the application with these JAWS scripts. These issues may be fixed in a future update to the scripts or to the application itself.

Unigram builds 2689 and 2691 include support for playing a short, unobtrusive sound to indicate the arrival of a new chat message or the successful transmission of an outgoing one. Unfortunately, for reasons yet to be determined, the playing of this very short sound coincides with JAWS becoming stalled trying to read UIA information from Unigram, for roughly five to ten seconds per inbound or outbound message. This problem does not affect Microsoft Narrator or NVDA 2019.3.x but does affect JAWS both with and without these scripts loaded. To work around this problem, uncheck "In-App Sounds" in Settings > Notifications and Sounds. This problem is under active scrutiny and may have been fixed prior to the next update of this documentation.

If JAWSKey+t says there are, for example, 4 new entries in 2 chats, but only one chat shows as having new messages, this tends to mean that that chat also includes a Mention icon.

The scripted commands for focusing specific tabs may not always land focus on the expected control within those tabs, due to variations in application behavior. A specific trick for reaching the correct control in the Contacts tab is to type Alt+1 to bring up the Chats tab, then Alt+2 to switch from there to Contacts.

From time to time, navigation in the Chats list may produce irregular reading, such as the announcement of "Chats tab" after an arrow key. The cause of this problem is not known, but incorrect UIA information or hierarchy is a suspect. Alt+Tab may rectify this situation, or it may simply go away on its own, usually within a minute or two in this author's experience. This problem was last reported under Unigram version 3.14.0.2665 in late February, 2020. The problem can affect all screen readers.

It is not currently possible to hear the name of a sticker before sending it. This would need to be fixed in the application.

Braille support is not well tested and is likely incomplete.

Revision History

This is the revision history of these scripts, most recent revision first:

Revision 105, released May 01, 2020, tested against application version 3.15.0.3073
Revision 97, released April 19, 2020, tested against application version 3.14.0.2691
Revision 86, released March 29, 2020, tested against application version 3.14.0.2691
Revision 80, released March 13, 2020, tested against application version 3.14.0.2691
Revision 79, released March 12, 2020, tested against application version 3.14.0.2691
Revision 64, released March 09, 2020, tested against application version 3.14.0.2691
Revision 63, released March 08, 2020, tested against application version 3.14.0.2691
Revision 53, released March 07, 2020, tested against application version 3.14.0.2691
Revision 32, released February 25, 2020, tested against application version 3.14.0.2683
Revision 19, released February 16, 2020, tested against application version 3.14.0.2665