JAWS Scripts For Unigram
Doug Lee
Last Revised March, 2024

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
• Script Installation Instructions
• Key Sequences
• Script Commands and Features
• Tips and Tricks
• Known Issues
• Revision History

System Requirements For JAWS Users

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

• The computer should be running Windows 10 or later, as the scripted application comes from the Microsoft Store.
• JAWS 2018 or later should be used. The scripts will not work with or install into JAWS versions older than 2018.

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 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 [. This document may refer to this keystroke as [ or Command; so, for example, [ 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, [ 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:

• The sequence [ B brings up a list of buttons for selection. Press Enter on a button's name to click the button, or press Esc to close the list without activating any buttons. This command can be especially useful for finding buttons such as Call. It is also possible to Shift+Tab once from the button list and press Space or Enter on the Focus button, to focus the chosen button without activating it. This trick may be handy for moving to a month header in a conversation history list, though only the month buttons that are currently visible on screen will appear in the button list. Also, different versions of Unigram may or may not respond as expected to Up and Down arrows after such a focus move.
• Alt with number keys focus the specific available tabs, and there are corresponding sequences with the same effect:
  • Alt+1 or [ 1 activates the Chats tab and tries to focus the chat list. Note that this list also includes any groups and/or channels to which you are subscribed. Note also that by default, the focused Chats list item will be the one most recently focused. This can be changed in Quick Settings to be the first entry in the list instead.
  • Alt+2 or [ 2 activates the Contacts tab and tries to move focus to the contact list.
  • Alt+3 or [ 3 activates the Calls tab.
  • Alt+4 or [ 4 activates the Settings tab.
  Note that Alt+2 through Alt+4 may not work unless the respective tab has first been opened from the navigation menu.
• The sequence [ F tries to move focus to the first field in the currently active dialog area. This can be very useful, for example, after selecting a page in the Settings screen, to move to the first field on the page. It will also move to the Profile link of a contact or channel that is currently displayed in the Chats tab.
• The sequences [ E and [ H focus the chat input box and chat history list, respectively, in the active chat.
• The sequence [ U focuses, when possible, the "Unread Messages" indicator in the open chat. This requires the indicator to be on screen at the time. On first opening a chat with unread messages, Unigram typically does place this indicator on screen. This means that typing [ U immediately after opening such a chat should usually work.
• The sequence [ M focuses, but does not activate, the "Open navigation menu" button. This button is often useful as a starting point for tabbing into dialog areas.
• The sequence [ T reports if anyone in the currently displayed chat is typing.
• If the audio player for voice messages is open, the following sequences manipulate it:
  • [ Space presses Play or Pause. This can be used to pause a voice message without first finding it in the message list. This will also place focus on the Play/Pause button, from which tabbing forward will find other audio player controls.
  • [ P reports audio player progress, indicating number of seconds played and number of seconds total in the current voice message.
  • [ C closes the audio player, providing a way to stop playback of a message without remembering position.
  Note that older script revisions also included a [ R sequence for toggling between normal and double playback speed. This was then removed because the Unigram playback speed control now supports several different actions.
• The scripts include a system for reading chat messages without shifting focus away from the input edit box: Type the prefix key, the left bracket ([) by default, then type as many of the following keys as desired to navigate among chat messages. Press Esc to exit the chat review mode when done. The navigation keys comprise the right-hand portion of the home row on a standard English US QWERTY keyboard: The semicolon (;) reads the last message available, J the previous from current position, L the next from current position, and K repeats the last-read message. (There is no command for jumping to the first available message because the first message in a chat history is often not available without scrolling.)
• The standard JAWS commands for clicking with the right mouse button will, if executed while the PC cursor is active, right-click the currently focused item. This feature can sometimes be used to obtain a Context menu when the Application key does not do so.
• The standard JAWS ReadBoxInTabOrder command, JAWSKey+B, may be considerably faster than it would be natively, depending on running JAWS version.
• JAWSKey+Q, along with announcing the active configuration name, will announce the revision number of these scripts.
• Insert+F1, typed twice in quick succession, opens this document in the default browser.

These scripts also provide the following features:

• Full support in chat input edit boxes for autocomplete functionality for typing mentions, including (in JAWS 2019 and later) the playing of sounds when an autocomplete box opens and closes. (The sounds used are those used by JAWS natively for autocomplete boxes in Microsoft Outlook.) To use Unigram's autocomplete feature in a chat, type an at sign (@), optionally followed by one or more characters to restrict the member search; then use Up and Down arrows to search through names. Press Enter or Tab to make a selection and close the autocomplete box, or just Backspace as many times as necessary to erase the partially typed mention. Warning: Space will not make a selection but will instead leave the @ sign and whatever else you typed in the box with a subsequent space.
• Similar autocomplete support for typing slash commands in a bot chat, and for emoji options when they appear for a chat input box. For emoji autocomplete, the file id may be included as part of what JAWS says to describe an emoji. Many emojis have the same names and no other distinguishing characteristics that JAWS can report. Autocomplete popups can appear for an emoji when one is pasted in via the Windows emoji selector, accessed with Windows+Period.
• Sound and announcement indication of typing indicators in an active chat. Either or both of these features may be switched on and off via the JAWS Quick Settings dialog but are active by default. Typing indicators do not apply to notifications when someone is sending a voice or video message; however, JAWSKey+T will report when someone is in the process of recording a voice message.
• Announcement and sound indicating the arrival of a new message in the current chat, or the editing of an already-received message. These announcements and sounds may also be toggled on and off via items in Quick Settings. By default, announcements are enabled and incoming message sounds are disabled, because Unigram natively supports producing a sound for incoming chats. More specifics on the sound and announcement features provided by these scripts, when enabled:
  • When focus is in the chat message list, sounds will still occur; but announcements will not, so that new messages will not intermingle with old messages as you navigate among them.
  • During arrow navigation through a chat's message list, extremely long chat messages will be read in full rather than being cut short by JAWS.
  • When you send or edit a message, both sound and announcement will occur (if enabled of course).
  • When you switch to a new chat, JAWS may announce the last message in the new chat as it appears. This is because the scripts have difficulty distinguishing between a new message and a message that is only "new" on screen but not newly sent. This author regards this side effect as useful; but for technical reasons, the side effect is difficult to prevent without the risk of missing newly sent messages.
• Better naming of several fields and controls, especially in Settings screens.
• Evasion of double speech during navigation through the Chats list.
• Announcement of voice and video message lengths during navigation through a chat history list. When a message is playing, the amount played so far will also be announced.
• Announcement of file information for a file transfer when one is encountered in a chat message list. This includes the file name and can include the duration of the file. During an active transfer, it also includes the amount so far transferred and the total size of the file.
• Indication of the origin of a forwarded message during navigation through a chat message list.
• Indication before rather than after a message of when it has not yet been seen by the recipient.
• Indication of which messages in a message list have been edited, before the message content.
• Announcement of radio button state after the user presses Space.
• More information reported by the JAWS SayWindowTitle command, JAWSKey+T. Information included when applicable:
  • The name of the active tab, and an indication of new items not yet read in the tab, such as Chats.
  • When a chat is displayed, the chat's name and other status information shown, such as participant last-seen time, member count for a group, and subscriber count for a channel.
  • If the user in the active chat is typing or composing a voice or video message, the indicator text.
  • When a Settings page is open, the page name when it can be found.
  • When the embedded audio player or the emoji panel is showing, an indication of this fact.
• Better pronunciation of the application name while the application is in focus.

Tips and Tricks

Unigram includes a number of native keyboard shortcuts that will likely be of much use to screen reader users. Use the letter O to move directly to the area of the page that contains the shortcut list. (This is the JAWS command for moving to the next article on a page.)

Recent Unigram versions allow both coarse and fine playback speed adjustment for voice messages. A quick way to manage playback speed:

1. Start playing a voice message, then pause it with [ Space. This will place focus on the button that will now be called Play.
2. If you want to adjust speed while the message is actually playing, use Space or [ Space to resume playback.
3. Tab past Volume to the Speed button and press Space. This opens a menu containing a left/right slider and various specific speeds as options.
4. To select a specific listed speed, use Up and Down arrows to find it and press Enter to activate it and close the menu.
5. If you instead wish to adjust the speed more precisely, use Up and Down arrows to locate the left/right slider control, then use Left and Right arrows to select a speed. Beware that Unigram may take a moment to change the playback speed as you arrow among fine-grain speed options. Press Enter when done to close the menu.

To copy a single message to the Windows clipboard, place focus on it and use the Copy option in the Context menu for the message. Starting in Unigram 10.2.0.4, Ctrl+C will also copy the focused message, properly formatted, to the clipboard.

To select several messages at once, such as for copying as a block to the clipboard:

1. Find the first message you wish to select.
2. Open the Context menu via the Menu key, then choose Select. The message you chose will be selected, and Unigram will be in a message selection mode.
3. Arrow among the other messages and use Space to select or unselect messages. JAWS will say "checked" when you select and "not checked" when you unselect a message. In addition, JAWS will say "selected" before any selected message as you arrow through the list.
4. When done selecting messages, use the Context menu again to choose the action you wish to perform on the messages. Performing an action will exit the selection mode and unselect the selected messages.
5. If you wish instead to cancel the selection process, press Esc to exit the selection mode and unselect messages without performing an action.

The JAWS touch cursor sometimes might provide more information than the PC cursor, especially in Settings pages where it can find hints for fields, group headings, etc. By Unigram 10.2 however, these tend also to be reachable via the Tab key.

In some cases, the JAWS "read box in tab order" command, Insert+B, is a handy way to read a screen. Active call screens are good examples.

If Enter on a Settings page name does not open the page (depends on Unigram version), Tab to and press Space on the button by the same name to open the page.

After opening a Settings page or subpage, it is necessary to Tab several times to reach the first field of the newly opened screen area.

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 Play link, and press Space to play. The Context menu, reached with the Application 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 Groove Music app. Video messages have a .mp4 extension.

To start recording a voice message in the current chat, type Ctrl+R. Type the same keystroke a second time to send the recording when finished, or type Ctrl+D to discard the recording without sending. This functionality is provided natively by Unigram and does not require scripts.

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.

If a channel message is forwarded into a group and the user reads the message from the group's message history, JAWS will announce the number of views of the original channel message but will not indicate the number of times the forward, in the group itself, has been seen. This information is available to assistive technology and is probably also visually shown, though this visual display has not been verified.

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

In some situations, notably large group conversations, it is possible to hear computer code-like material instead of a message. At this time, it appears that all of the following must be true simultaneously for this anomaly to occur:

1. The current conversation is a large group chat.
2. The chat was opened but no navigation via focus among messages has yet taken place.
3. The user uses the scripted chat navigation system to read messages instead of moving focus.

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 224, March 28, 2024, tested against application version 10.9.0.0

• For users who do not choose to make Alt+1 always move to the first conversation in the conversation list, this revision fixes an issue that caused Alt+1 to land on the Archived Chats button when no conversation had yet been selected. (The choice of where this command lands is an option in Quick Settings, opened with JAWSKey+V.)
• For some users and in some situations, navigation may be notably faster due to a change in this revision's recognition of conversation message lists that need fixing. Such methods of situation recognition must periodically be updated as the application evolves.
• The sound made when use of the chat navigation system strikes the start or end of the available chat messages is now a short click rather than a system beep. Besides being faster and thus more efficient, it is less ambiguous and more likely to come through the JAWS sound output device rather than the system default device when they are different.

Revision 215, February 26, 2024, tested against application version 10.8.0.0

• Fixed a new surge of double speech in conversation message lists.
• Prevented repetition of a chat message with reactions on Tab from the message itself to the reaction list.
• Updated the script code that forces Unigram to repair its accessibility information structure for a conversation message list when necessary.
  Details on what this means

  Unigram, like many modern applications, produces a UI Automation (UIA) element tree that screen readers can examine to figure out what is on screen. Unfortunately, for conversation message lists, this tree is sometimes structured incorrectly, so that the focused message in the list appears to be parented by a strange element or directly by the element for the entire Unigram window. Because the various types of this misconstruction can cause JAWS to misread chat entry information, the scripts provoke a rebuild of this element tree when a problem is detected. This may cause a brief pause during navigation among chat messages but will also prevent misreading of the messages themselves.
• For translators: The "Messages for the err module" section is removed from unigram_lang.xml.

Revision 209, January 23, 2024, tested against application version 10.4.0.4

• The "not seen" announcement again works as expected as of Unigram version 10.4.0.4.
• JAWS no longer repeats the name of a channel before every message in the channel.
• The new ability to use Ctrl+C to copy a message to the clipboard is documented. This capability was added to Unigram in version 10.2.0.4.

Revision 205, November 16, 2023, tested against application version 10.2.0.1

This revision is for those who have upgraded to Unigram 10.2. Do not update to this script revision before updating Unigram to 10.2, or some script features may stop working until you upgrade Unigram.

• There is a new [ F sequence to move focus to the first field in a dialog area.
• Commands and sequences to jump to specific tabs work in Unigram 10.2. These are Alt with numbers and [ followed by numbers.
• The key sequence for moving focus to the navigation menu button, [ M, works in Unigram 10.2.
• Insert+T will include the page name when a Settings page is displayed.
• This revision includes minor updates to improve support for Windows 11.
• There is a semi-undocumented key sequence, [ Ctrl+E, for use in diagnosing script problems. This command will announce any messages associated with recent error conditions that caused the scripts to emit a system beep sound. These messages are sometimes technical in nature and are intended for script developers. Because of this, these messages are not localized and will always be spoken in English when the sequence [ Ctrl+E is typed.