JAWS Scripts For TeamTalk Qt
Doug Lee
Last Revised August, 2024

This document describes the scripts for the TeamTalk 5 Qt client and provides tips for using this application with JAWS. This document can be opened from within TeamTalk via a double press of JAWSKey+F1 (or Insert+F1).

Note: This client is sometimes referred to here as the Qt (officially pronounced "cute") client to distinguish it from the retired Classic client.

Table of Contents

• System Requirements For JAWS Users
• Script Installation Instructions
• Migrating From the Classic Client and Configuring the Qt Client For Accessibility
• Key Sequences
• Script Commands and Features
  • Moving Focus Among Controls and Windows
  • TeamTalk Status Reporting and Inquiry
  • Miscellaneous Commands and Features
  • Making and Using Shortcuts For Sound Device Control
• Known Issues
• Revision History

System Requirements For JAWS Users

There are no known system requirements for these scripts beyond those for TeamTalk itself. These scripts only support the Qt client. JAWS 17.0 or later is required. JAWS versions older than 2021 have not recently been carefully tested with these scripts.

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

Migrating From the Classic Client and Configuring the Qt Client For Accessibility

For tips on migrating from the TeamTalk Classic client to the Qt client, and for differences between the clients, see the TeamTalk Classic To Qt Migration Guide. That page provides the following resources:

• Steps for migrating from the Classic client to the Qt client while preserving accessibility.
• A tool that can transfer your Classic client server entries to the Qt client all at once.
• A guide to help configure the Qt client for maximum accessibility and convenience with a screen reader.
• Tips on using the Qt client that do not depend on which screen reader is in use.
• A list of differences between the clients.

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

Moving Focus Among Controls and Windows

In the main TeamTalk window, [ C will focus the channel tree.

In the main window and in private chat windows, [ E focuses the chat input box, while [ H focuses the chat history output box.

In a private chat window, [ T announces whether the other user is typing. The scripts can also announce and/or make a sound when the other user is typing, depending on Quick Settings options. Note that not all TeamTalk clients send the necessary internal notifications to make this work. In particular, the Windows/Linux/MacOS Qt-based client does, but the Windows classic and iOS clients do not. At this writing, text clients such as TTCom also do not. If you are unsure of why you do not receive typing notifications in a particular chat, use Ctrl+I on the user in the channel tree to check the user's client type. Typing indicators are not available in a channel window.

From within any TeamTalk window, type the sequence [ N to move to the next visible TeamTalk window, and the sequence [ Shift+N to move to the previous one. These will include all chat windows and main TeamTalk windows from all open visible instances of TeamTalk Qt. The order of windows may sometimes seem arbitrary but is usually related to the order of window creation.

TeamTalk Status Reporting and Inquiry

While the scripts are running, JAWS will announce automatically any changes in the following on-screen indicators, which appear as checkboxes in a toolbar near the top of the TeamTalk window. For each of these, JAWS will say the indicator name along with "Enabled" or "Disabled" when the indicator changes.

• Push To Talk.
• Voice Activation.
• Video.
• Desktop (sharing).
• Stream to channel.
• Mute All.
• Store audio (recording).
• Question mode.

[ S will announce a summary of TeamTalk status information. This generally consists of a list of those items from the above set that are currently checked. Typing the sequence [ Shift+S will announce a somewhat more verbose version of the same information.

The sequence [ Q will toggle Question mode via one of the buttons on the toolbar. Question mode produces a blinking icon beside your name in other participants' channel trees. This is similar to raising your hand in some other chat applications.

The standard JAWS command for announcing the application status line, Insert+PgDn, will reliably announce this information even if it is clipped on screen. This information typically includes the rate at which packets are being received (RX) and transmitted (TX). Sometimes, it will also include a ping time, which is an indication of how long it takes data to travel between your machine and the TeamTalk server.

Miscellaneous Commands and Features

By default, JAWS will maximize main and chat TeamTalk windows automatically so that message reading will be more efficient, rather than allowing TeamTalk's native window sizing. Native window sizing can be turned on via the "Allow native window sizing" checkbox in Quick Settings (JAWSKey+V).

As you Up and Down arrow through a chat history window, JAWS will produce a small click sound when you encounter the top or bottom of history.

This client allows activation of links in a chat message with Enter: Navigate to the actual link, not just to the line containing it, and press Enter to activate it.

Message date and time stamps can be ignored during navigation through chat history even when displayed by TeamTalk. This feature is toggled on and off in the JAWS Quick Settings dialog (JAWSKey+V) with the "Suppress message date and time stamps when shown by TeamTalk" option. The JAWS SayLine command, Insert+Up, will speak the stamps regardless of this setting. Typing that command twice will, as usual in JAWS, spell the line but then will honor the suppress-stamps setting for convenience. Note that some types of entries in a message chat window may not have their stamps suppressed even when this option is in effect. Such entries include message of the day, this user joining a channel, and server name entries. At this writing, these are not formatted with the leading asterisk (*) that appears before most system message entries.

The scripts improve JAWS' reporting of correct information for Left and Right arrows, Backspace, Delete, etc. in an edit box. This does not work in a password box, however. For these, JAWS will report the number of asterisks shown.

The standard JAWS Ctrl+JAWSKey+V command for reporting the current application version reports the full correct version number. Without the scripts, the version number may be spoken oddly.

The sequences [ X and [ V are added as alternatives to the TeamTalk native commands Ctrl+Alt+X and Ctrl+Alt+V for marking and moving channel participants to another channel. These duplicate commands may be useful to those who struggle with compound keystrokes or prefer sequences over compound keystrokes.

Other random script features:

• The JAWS SayWindowTitle command, Insert+T, will indicate when there are multiple windows open for the current TeamTalk instance. This happens, for example, when Ctrl+Shift+U is used to open the Online Users window.
• In a user volume dialog, D returns volume sliders to their defaults just as the native Alt+D keystroke does. The scripts also cause this update to be announced if focus is on a slider at the time.
• Arrows announce the correctly updated value on sliders instead of sometimes announcing the old value instead.
• In the channel tree, Up and Down arrows announce tree items as normal; but the JAWS SayLine command, Insert+Up, also reads all columns of the grid. The other columns indicate whether the user is allowed to transmit text, voice, video, etc.
• Moving through tree controls announces tree level as appropriate.
• Insert+B, the command for reading the current dialog in a logical order, works much better.
• JAWS will announce the count of asterisks in a password field. This offsets the inability to count them manually with Left and Right arrows.

Features specific to field names and types:

• Edit combo boxes report themselves as such instead of saying "combo box."
• Left and Right arrows, Backspace, and Del work as expected in an edit combo box.
• Edit spin-box controls speak their values as they are changed.
• Combo box controls, when closed, do not double-speak values on change.
• Open combo box controls speak values properly as the user arrows through options. Note however that the item count for such an option list may sometimes be wrong for boxes with numerous options. This is because Qt may not report the full count of items in such a list.
• Combo box announcements will no longer be followed by the word "Down."
• The scripts prevent JAWS from reading a whole group of control names as the group box name for some controls.

Making and Using Shortcuts For Sound Device Control

The scripts provide a system for rapid changing of sound devices and/or sound device settings. This is considered an advanced feature of use mostly to those with complex needs, Virtual Audio Cable setups, etc. Users of the feature discussed in this section would also profit from understanding TeamTalk profiles, which are not covered in this document but which provide rapid means to launch TeamTalk instances with different configurations that will not collide with each other when settings are changed during use.

The system works by allowing storage of a menu option for future toggling or activation with a shortcut. After a shortcut is made, using it will activate its menu option very quickly without requiring the user to go through all the menu levels again to find it. Commands for this system begin with the sequence [ M and end with a plain digit to activate a shortcut, Ctrl with a digit to set a shortcut, and Shift with a digit to report the current setting of a shortcut.

There is one additional sequence, [ M L, which displays a list of assigned shortcuts. Pressing Enter on one of these will execute it. To close the list without running a shortcut, press Esc.

To create a shortcut:

1. Use the TeamTalk menu system to find the item you want to assign to a shortcut. For example:
   • Tap Alt for the menu system.
   • Use Down to find Sound Configuration, then press Enter or the Right arrow to open that submenu.
   • Arrow down to Input Devices and open its submenu.
   • Find the entry for your secondary microphone but do not activate the entry.
2. Upon finding the menu item you want to assign to a shortcut, type the sequence [ M followed by Ctrl with the number you want to assign as a shortcut. To use [ M 1 in the future for this menu item for example, type the sequence [ M Ctrl+1. This will make the sequence [ M 1 activate this option from now on.
3. You can assign more shortcuts while the menu system is open simply by navigating to them in turn and typing sequences to make the assignments. Close the menu system when done.

To use a shortcut, type [ M followed by the shortcut's digit. JAWS will say the name of the final menu item being activated. Note that it may take a couple seconds for the shortcut to complete its execution.

To check what is assigned to a shortcut, type [ M followed by Shift with the digit. In this case, JAWS will say the full menu path of the item that would be activated. Alternatively, type [ M L to display a list of all shortcut assignments at once.

This shortcut system can actually be used to assign a shortcut to any menu item in TeamTalk, but most items that are not for sound device control already have keyboard shortcuts in TeamTalk itself. Assigning shortcuts to items like Enable Echo Cancellation or Enable Denoising might be useful though.

There are a few caveats to keep in mind when using this system:

• If TeamTalk changes the wording or organization of menu items, shortcuts may cease to work and require reassignment.
• If multiple TeamTalk instances are running at once from the same configuration file, changing settings in one can sometimes alter the behavior of another. This is a side effect of the way TeamTalk uses its configuration files. Using TeamTalk profiles can prevent this problem.
• The scripts actually do navigate the menu system during the execution of a shortcut. This may be apparent visually, and interrupting this process with keystrokes or mouse movements could have unpredictable results.

Known Issues

Screen readers may repeat history entries during Up and Down arrowing, especially if the window is not maximized. This is a UIA issue.

Leaving the cursor at the end of a chat history, such as after typing Ctrl+End, will cause the cursor to remain at the end as new lines are added. This means that you must avoid leaving the cursor at the very end of the history if you want TeamTalk to remember where you left off reading. It is ok to leave the cursor anywhere else on the last line. This issue can also occur if you use the history control's Context menu to clear the message history, because doing so will often, if not always, cause the cursor to be at the end of the history as new messages arrive.

If a user is selected in the channel tree, such as by arrows, and that user changes status, such as when starting or stopping a stream or going away, screen readers may report a focus change even though none has occurred. This is a Qt issue. A good workaround is to move focus to a channel rather than a user before moving away from the channel tree.

Braille support is not well tested.

Revision History

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

Revision 437, August 15, 2024, tested against TeamTalk 5.17.0

• Several script features that stopped working in TeamTalk version 5.17.0work again. That TeamTalk version changed the way various controls are identified. The scripts should also still work under older versions of TeamTalk, though testing of this assertion is limited.
• Fixed a bug that prevented assignment or use of the sequence [ M 0 as a shortcut assignment.
• Added the sequence [ M L for listing all shortcut assignments at once. Pressing Enter on an assignment will execute its menu item.
• Failure to find a menu item during a sound device shortcut command sequence will speak a sensible error message instead of beeping and saying nothing. Some other menu processing errors that might occur will also speak a general message instead of only beeping.

Translators: There are changes in one message file.

Revision 431, July 20, 2024, tested against TeamTalk 5.17.0

• The key sequence [ S for reporting toolbar icon states reports Question Mode correctly.
• In support of the TeamTalk 5.17 ability to specify the message window date/time format, the scripts are much more flexible at figuring out what constitutes a stamp to be ignored during message navigation, when the "Suppress message date and time stamps when shown by TeamTalk" option is in effect.
• There is a new system for assigning shortcuts for sound device control. This is considered an advanced feature but may be of use to those with complex needs, Virtual Audio Cable setups, etc. The basic idea is to assign shortcuts for rapidly switching between sound devices or turning on and off features like denoising and echo cancellation.
• Much code for old JAWS versions is removed. This is a continuous process to keep projects from growing needlessly complex.

Translators: There are changes in one message file.

Revision 417, April 22, 2024, tested against TeamTalk 5.16.1

• JAWS says the "open" or "closed" state of treeView items, such as in the channel tree, after rather than before the text of the treeView item itself. This is consistent with normal JAWS behavior and has been requested occasionally by users of these scripts. (Because of the length of some treeView item names, this script author has mixed feelings about which order is most efficient but has decided to err on the side of expected behavior.)
• Arrows in combo boxes speak as they should. This bug was the result of a mismatch between TeamTalk-specific script code and evolving code for supporting Qt environments in general.

Revision 414, March 27, 2024, tested against TeamTalk 5.15.2

• This update includes a timing adjustment aimed at avoiding JAWS crashes when TeamTalk takes focus. The exact cause of the crashes is not known, nor are the number of users or frequency per user of these crashes; but they appear to have been caused by a UIARefresh request being made too soon after TeamTalk obtained focus.
• Removed some documentation material related to the retired TeamTalk Classic client.