Accelerators

The Accelerators extension allows simple keyboard shortcuts to be used for many operations in Chimera. Accelerator use must be enabled (Tools... General Controls... Accelerators On).

Many accelerators are included with Chimera, and new accelerators can be added. Accelerators (keyboard shortcuts) usually consist of two or three characters, but any number of characters is possible. Uppercase letters are sometimes used and are distinct from lowercase. Several accelerators provide capabilities not accessible through the graphical interface.

There are several ways to start each of the following, classified as tools in the General Controls category:

Accelerators On - enable the use of accelerators
Accelerators Off - disable the use of accelerators
Accelerator List - open the Accelerators dialog

Accelerators are disabled by default, but can be enabled by choosing Accelerators On from the menu or activating the Accelerators on checkbox on the Accelerators dialog. Accelerators can be disabled by choosing Accelerators Off from the menu, deactivating the Accelerators on checkbox on the Accelerators dialog, or using the accelerator af.

To enable accelerators automatically upon Chimera startup, check the Auto Start option for Accelerators On in the Tools preferences and then Save the preferences.

ACCELERATORS DIALOG

Accelerator List opens the Accelerators dialog, which lists the known accelerators along with brief descriptions. Clicking on an entry in the list shows a more detailed description (if available) at the bottom of the dialog.

Accelerators on controls whether accelerators are enabled.
Show main window status line controls whether a status line is shown under the Chimera window. Keystrokes interpreted as accelerators and messages reporting accelerator operations appear in the status line.

Load accelerator file reads accelerator definitions from the Python file whose pathname is shown in the field below. A file of default accelerator definitions is supplied with Chimera. New accelerators can be added by putting their definitions in a Python file and then using Load.

Key press time-out (seconds) (2 seconds by default) controls how long keystrokes that form part of an accelerator are remembered.

The status line setting, accelerator file pathname, and time-out setting are saved in the preferences file.

ACCELERATOR OR COMMAND?

Keystrokes may be interpreted as accelerators, as commands, or as information intended for other dialogs. Obviously, commands but not accelerators should be sent to the Command Line. In some situations, it is clear which type of input is intended:

If accelerators are on and the Command Line has not been shown, keystrokes are interpreted as accelerators when the mouse focus is in the graphics window.
If accelerators are off and the Command Line has been shown (even if subsequently hidden or quit), keystrokes are interpreted as commands when the mouse focus is in the graphics window.

An accelerator takes effect as soon as it is typed; there is no need to press return (Enter). A command takes effect after return is pressed. Note that a click in the graphics window is sometimes required for either accelerator or command keystrokes to register, since some other dialog has stolen the "focus."

Conflicts are possible when accelerators and the Command Line have both been turned on:

If accelerators are on and the Command Line is shown, one must click in the graphics window to indicate that keystrokes should be interpreted as accelerators and click in the command-line area to indicate that keystrokes should be interpreted as commands.
To allow both types of input, accelerators should be turned on after the Command Line has been shown. If the Command Line is started after accelerators, it will receive all of the keystrokes, even if subsequently hidden or quit. In this situation, there are a few ways to enable both types of input:
- turn or toggle accelerators on again
- use the command start Accelerators On
- use the command ac (only works if accelerators had been turned on or the Accelerators dialog opened earlier in the session)

The accelerator hm hides the Command Line (Midas Emulator), while the accelerator me opens it and turns off accelerators.

TIME-OUTS AND ENTRY ERRORS

Keystrokes being interpreted as accelerators are shown in the status line; the time-out setting controls how long a partial accelerator entry is retained. If the wrong key has been pressed, simply waiting for the time-out period to elapse allows a fresh start. Alternatively, pressing the escape key clears the partial accelerator from memory. Finally, if no accelerator starts with the key that has been pressed, an "unknown accelerator" status message results and the keystroke is not retained. Completed accelerator operations are reported in the status line and Reply Log.

ADDING ACCELERATORS

The standard accelerators are defined in

chimera/share/Accelerators/standard_accelerators.py

Accelerators can be added by writing their definitions in a Python file and reading the file with Load on the Accelerators dialog.

Example accelerators file:

def register_accelerators():

  from Accelerators import standard_accelerators
  standard_accelerators.register_accelerators()

  from Accelerators import add_accelerator
  add_accelerator('ry', 'Rotate models about y axis', rotate_y)
  add_accelerator('rs', 'Stop model rotation', stop_rotation)

def rotate_y():
  'Spins models about the y axis'
  import Midas
  Midas.roll(axis = 'y')

def stop_rotation():
  'Stops spinning models'
  import Midas
  Midas.freeze()

The register_accelerators() function is called by the Accelerators extension. The first two lines load the standard accelerators. The next three lines define accelerators ry and rs to spin the models about the Y axis and to stop the spinning. The routines that spin and stop the spinning use the Chimera Midas module. The comment strings in the add_accelerator lines are the short descriptions that appear in the top part of the Accelerators dialog and, when the accelerator operation is performed, in the status line; the comment string within each function is the explanation shown at the bottom of the Accelerators dialog when the accelerator list entry is clicked.

Since accelerators take effect immediately (without return), a new accelerator cannot start with an existing accelerator. For example, if ab is a known accelerator, accelerators of the form abx, where x is any character, cannot be used.

CURRENT LIMITATIONS

A click in the graphics window may be required.
As mentioned above, a click in the graphics window is sometimes required for either accelerator or command keystrokes to register, since some other dialog has stolen the "focus."

"Off by one" situations can occur.
Suppose sv (open the Side View) is intended, but "xv" is typed accidentally. If there is no accelerator starting with "x," an "unknown accelerator" status message results and only the "v" is retained in memory. If sv is then typed before the time-out period has elapsed, the keystrokes will be interpreted as the accelerator vs (show volume) and another "v" is retained in memory until the time-out period has again elapsed (or the escape key is pressed).

IDLE steals status messages.
When the IDLE tool (Python shell) is on, it displays all status messages and prevents them from being displayed on the status line. IDLE also diverts warnings, errors and all other messages that would otherwise go to the Reply Log and pop-up dialogs.

Only one line is visible for status messages.
Only a single line of text can be shown in the status line, even though status messages can be defined as multiple lines.

Accelerators could be shown on menu entries.
The keyboard shortcuts could be shown on the corresponding menu entries to make them easier to learn. More accelerators could be defined so that they are available for all suitable menu entries.

UCSF Computer Graphics Laboratory / October 2007