JAWS Scripts For Unigram
Doug Lee
Last Revised November, 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 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:

• 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.
• 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 Application 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+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 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:
  • 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.
  • 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

Unigram includes a number of native keyboard shortcuts that will likely be of much use to screen reader users.

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 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 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.

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.

The SayWindowTitle command, Insert+T, may not announce the name of the "Chat Settings" page in Settings. Seen in Unigram version 7.1.0.5486.

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 135, May 4, 2021, tested against application version 7.7.0.6179

• The scripts now load for users of Unigram releases that do not come through the Microsoft app store.

Revision 134, April 26, 2021, tested against application version 7.7.0.6152

• The [ E sequence for focusing the chat input edit box works again in channels, where its name is "Broadcast" rather than "Message."
• There is a bit of protection against misreading during navigation through the conversation list when Unigram either structures the MSAA and UIA trees incorrectly or fires irregular or untimely events. The last version in which this author saw such behavior, and very rarely at that, was Unigram version 7.2.0.5889.

Revision 129, March 27, 2021, tested against application version 7.2.0.5889

• The [ H sequence for focusing chat history works even when stickers are enabled.
• Checkboxes in a live poll chat entry will announce percentages as they receive focus via Tab.
• This document explains how to record a voice message and also includes a link to the Unigram keyboard shortcut documentation.
• Some old code is removed, and there are minor updates to improve support for JAWS 2021.

Revision 122, November 11, 2020, tested against application version 7.2.0.5752

• During navigation through messages in a channel, JAWS will prefix commented messages with an indication of how many comments are attached. Tab to the comments link and press Enter to open the comment thread for reading.
• Typing a list focus command such as Alt+1 should indicate if the sought list is empty, and therefore not focusable, instead of saying nothing. This can happen, for example, after pressing the "Archived Chats" button when there are no archived chats.
• Fixed Alt+1 and Alt+2 to work in Unigram version 7.2.0.5752.
• Fixed honoring of the Quick Settings "Focus first chat list entry" option.
• Fixed the [ C sequence for closing the audio player so it works in Unigram version 7.2.0.5654 and later. Starting in that version, the Volume button has the same name.
• Fixed the name of the audio player's Volume button in the same Unigram versions.

Revision 118, October 12, 2020, tested against application version 7.1.0.5486

• Fixed SayWindowTitle (Insert+T) to work as described in Unigram version 7.1.0.5486, where the internal name of one of the screen elements changed and the internal organization of Settings pages also changed a bit.
• SayWindowTitle also includes the name of the active tab, even when there are no new items in it, and also includes "Search" when the Search screen is open.
• JAWS reads the dates of calls in the Calls tab along with what was already announced.
• Keystroke names in this document are more consistent, and there are other minor documentation improvements.
• Fixed a bug that could cause some localized strings not to be spoken where expected.
• Many internal improvements to code used to name fields.

Revision 108, 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, 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, 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, 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, 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, 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, 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, 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, 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, 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, February 16, 2020, tested against application version 3.14.0.2665

• Initial script release.