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
• 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, as the scripted application comes from the Windows 10 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 key 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 key, 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:

• 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 ctivates the Calls tab.
  • Alt+4 or [ 4 activates the Settings 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.
  • [ r toggles the playback rate between normal and double-speed (2x). Unigram remembers this setting until it is changed again.
  • [ 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.
• 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.)
• When focus is on a chat history list item that represents a voice message, Space or Enter will play or pause the message. Without scripts, it is necessary to Tab to a link for the message first.
• 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 Applications key does not do so.
• The standard JAWS ReadBoxInTabOrder command, JAWSKey+b, is considerably faster than it would be natively.
• 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 a plain at sign in the edit box followed by a space, and Esc will not close the autocomplete box and cancel selection but will instead close the entire chat but leave the autocomplete box active for the next time that chat is opened.
• 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 is 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 10 emoji selector, accessed with Windows+. (Windows key plus the period key).
• 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 also apply to notifications when someone is sending a voice or video 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 as of version 3.14.0.2689. 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 of which messages in a message list have been edited.
• Announcement of radio button state after the user presses Space.
• More information reported by the JAWS SayWindowTitle command, JAWSKey+t. Information included when applicable:
  • An indication of new items not yet read in the active tab, such as Chats.
  • When a chat is displayed, the chat's name and other status information shown, such as participant last-seen time.
  • If the user in the active chat is typing or composing a voice or video message, the typing indicator text.
  • When a Settings page is open, the page name.
  • 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

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 108, released June 07, 2020, tested against application version 4.0.0.5098

• Worked around cases where Unigram list items, usually if not always in the list of conversations, claim via UIA to be parented by other invisible list items. This caused JAWS to read random-sounding conversation entries before reading the actually focused entry during arrowing through the contact list. The cause of this issue is not known but is within Unigram itself.
• 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.

Revision 105, released May 01, 2020, tested against application version 3.15.0.3073

• 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.
• [ h, for focusing chat history, works in channels where there is no message input edit box.
• For those who need to change the Command key, the left bracket ([) by default, the system is significantly improved, so that you need not type the key or key combination out as a name or string of key names. You may edit the keystroke names before accepting them, but JAWS will type them out for you now. The system is documented in more detail in the Multi-Key Command Sequence section of my Common Script Elements page.

Revision 97, released April 19, 2020, tested against application version 3.14.0.2691

• The slider representing progress through a playing voice message speaks when reached via the keyboard.
• Screen readers respond better to activation of Table of Contents links in this document.
• The messages for these scripts are now distributed in XML rather than jsm files so that translators can create translations with no need for script source recompilation. See the Script Translation Procedure document for details on how to translate these scripts, including how to update the XML message file.

Revision 86, released March 29, 2020, tested against application version 3.14.0.2691

• Video chat messages that play in a Unigram popup window announce length before other material during chat message navigation, just as is done for voice messages.
• Quick Settings includes an option for making Alt+1 and the sequence [ 1 move to the first Chats list entry instead of to the one most recently focused.
• The autocomplete support works for the list that appears when the user types a slash (/) into the chat input box for a conversation with a bot that supports commands.
• Autocomplete support also works for emoji characters and includes the file id of each option, to help distinguish it from other options with the same name or no name that JAWS can identify.

Revision 80, released March 13, 2020, tested against application version 3.14.0.2691

• The autocomplete support works on systems where Unigram's chat input box reports via JAWS as being only one rather than multiple lines in height.

Revision 79, released March 12, 2020, tested against application version 3.14.0.2691

• Full support for Unigram's autocomplete functionality for typing mentions in a chat edit box.
• Commands to control the audio player directly when it is open: [ Space presses Play or Pause, [ r toggles the playback speed between normal and double, [ p reports progress in seconds (this feature was requested by a user), and [ c closes the audio player.
• Alt+1 tries to return focus to the last-focused entry in the Chats list rather than going to the first entry available.
• When focus is on a chat history list item that represents a voice message, Space or Enter will play or pause the message. Without scripts, it is necessary to Tab to a link for the message first.
• JAWSKey+t will not freeze Unigram when typed while the emoji panel is displayed but will indicate that the panel is open.
• The command sequences for jumping within a chat to its input and history boxes, [ e and [ h, work more reliably in busy chats.

Revision 64, released March 09, 2020, tested against application version 3.14.0.2691

• Minor revision to fix handling of a few lists. An effort to avoid treating chat messages containing code differently than other chat messages broke the handling of channel and group membership lists.

Revision 63, released March 08, 2020, tested against application version 3.14.0.2691

• More buttons are named.
• There is a new system for reading and navigating among chat messages in the current window without shifting focus away from the chat input edit box: See Script Commands and Features for details.
• New-message sounds and announcements, when enabled in Quick Settings, should not occur more than once for the same new message.
• File transfer entries in a chat message list speak the name of the file.
• Voice and video lengths speak before the rest of the information for a chat history list entry rather than after it.
• Replies (mentions) count as unread messages for the JAWSKey+t enhancement that counts unread messages and chats containing them. Replies did not count properly before because they show up with a different UI Automation name than the one used for unread message counts.
• Edited channel messages announce as "edited" more reliably.

Revision 53, released March 07, 2020, tested against application version 3.14.0.2691

• Announcement and script-generated sounds for an incoming chat, when enabled in Quick Settings, should work more reliably. They will still sometimes occur an extra time or two on a switch between conversation windows though.
• 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.
• 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.
• In a chat message list, location messages (sent via Attach Media) will read any included location name.
• In a chat message list for a group chat, voice message lengths will announce even when chat participants have admin-enhanced names.
• Typing indicators also apply to notifications when someone is sending a voice or video message.
• In Settings > Language and possibly in other places, JAWS should not say long and confusing code names for controls, like "System.Collections.Generic.List`1[Telegram.Td.Api.LanguagePackInfo]."
• In the screen for sending a broadcast message to a channel, JAWS more effectively describes how to handle the button that flips between "Send notifications" and "Send silently." This button's name represents how things work now, rather than how things will work after the button is pressed.
• JAWSKey+t, when typed very quickly after an Alt+Tab into the application, should speak the correct title rather than saying "popup host."
• In the Chats list, JAWS should no longer act as if the items are checkboxes and should speak the correct position information for each entry rather than saying "1 of 1" for all of them.
• In the history list for a channel, the channel name should not speak twice for each post.
• The scripts are ready for others to translate into non-English languages. See the "Script Translations" part of my "Script Distribution Policy" page for information on how this works.

Revision 32, released February 25, 2020, tested against application version 3.14.0.2683

• When a new message arrives in the focused chat, JAWS can read it and can also produce a short sound to indicate its arrival. This applies also to a newly edited message even if it is not the most recent, though this feature is not tested against messages old enough to have scrolled off screen. See the Script Commands and Features section for further details. The announcement and sound indicators for new messages can individually be toggled on and off via two new items in Quick Settings. By default, the announcement of incoming chats is enabled but the sound is disabled, because Unigram 3.14.0.2689 and later can natively produce a sound for an incoming chat.
• During navigation in a chat message list, forwarded messages will announce their origins. Edited messages will also say "edited."
• When the Chats tab is active and contains chats with unread entries, the JAWS SayWindowTitle command, Insert+t, includes an indication of how many unread items exist.
• When the embedded audio player is on screen, Insert+t indicates this.
• Insert+t correctly reports the active chat's name even when the audio player is also showing.
• The disappearance or invalidation of the typing indicator, such as on a switch to a different conversation, is more quickly recognized.

Revision 19, released February 16, 2020, tested against application version 3.14.0.2665

• Initial script release.