TextEditor Keystroke Remapping

What is it?

A DispatchTableEditor is a user interface which makes it easier for programmers to take existing ParagraphEditor keystroke assignments and reassign them to functions more in line with individual preferences. Those assignments can be saved, doucumented, and even shared with other users.

These editors can be started using the map keystrokes... menu item or by using an executable line in the supplied DevTools workspace.

Editing Methods pane:

This pane holds a list of all the methods to which keystrokes can be remapped.

If a method name is selected in the first pane, several other panes will be updated. The Code View pane will display the source code for the selected method and the Mapped keystrokes list pane will fill in with a list of all the keystrokes that are mapped to the selected method. In addition, if there is only one keystroke assigned to the method, then that keystroke is automatically selected in the Mapped Keystrokes pane, and other panes will be updated according to that selection.

See DispatchTableEditor>>methodListSelected and its callers for additional details.

The list of assignable methods is determined by collecting all the instance method names from the editing protocol of the class that the DispatchTableEditor was opened for.

For more information on the list of assignable methods, see DispatchTableEditor>>protocolList, ParagraphEditor class>>dispatchMethodListIn:, the implementors of the class method >>mapKeystrokes and their callers.

Pane pop-up menu:

If the middle mouse button is pressed in the Editing Methods, Mapped keystrokes list pane or Key/Method panes, the menu to the right pops up.

browse method

If this menu item is selected, or if the mouse is double clicked in the above listed subpanes, a class hierarchy browser will be brought up on ParagraphEditor or one of its subclasses. Then the current method in the Editing Methods subpane will be automatically selected in the browser.

The automatic selection of the method can be turned on or off using code in the supplied DevTools workspace.

The feature of double clicking with the mouse to bring up a class hierarchy browser can be turned on or off the using code in the supplied DevTools workspace.

See DispatchTableEditor>>browseClassHierarchy for additional details.

create documentation...

If this menu item is selected, a dialog will pop up that will allow a text file that will list the current keystroke assignments to be generated.

The Discard button means "continue, but don't create documentation", and only has meaning if the dialog is brought up during the processing of another button, like OK.

Examples based on some of the keystroke mappings that are shipped with the DevTools can be found in:

BaseInputBoxController Keymap Documentation.txt
BaseParagraphEditor Keymap Documentation.txt
BaseTextEditorController Keymap Documentation.txt

ControlWorksBaseInputBoxController Keymap Documentation.txt
ControlWorksBaseParagraphEditor Keymap Documentation.txt

CW 3.0 InputBoxController Keymap Documentation.txt
CW 3.0 ParagraphEditor Keymap Documentation.txt
CW 3.0 TextEditorController Keymap Documentation.txt

InputBoxController Keymap Documentation.txt
ParagraphEditor Keymap Documentation.txt
TextController Keymap Documentation.txt

See DispatchTableEditor>>saveDocumentation and its callers for additional details.

Mapped Keystrokes section:

Individual keystroke mappings can be added, changed or removed using this section of the window.

Mapped keystrokes list pane:

When a method name is selected in the Editing Methods pane, the mapped keystroke list subpane is filled with any keystrokes assigned to that method.

If one of the keystroke mappings is selected, the keystroke editing subpanes under the Remove button are activated and updated with the keystroke's information. The keystroke is also selected in the Key/Method pane.

See DispatchTableEditor>>mappedKeySelected, DispatchTableEditor>>updateMappedKeyList:, DispatchTableEditor>>methodListSelected and their callers for additional details.

Remove button:

Dialog Box: Are you sure that you want to remove this mapping to #backWordKey: ? --- yes | no

Use this button if you want to unmap a keystroke combination. It is enabled if a key combination is selected in the list above it. If pressed, a dialog box is brought up to confirm the action.

See DispatchTableEditor>>removeKeystroke and its callers for additional details.

Key entry field:

When active, this entry field can be filled with a keystroke character or symbolic keystroke name. The entry will be used as the primary key in a keystroke mapping.

The pop-up menu for the Key entry field contains a list of the most common symbolic keystrokes names that can be used as a primary keystroke.

See DispatchTableEditor>>keystrokeMenu and its callers for additional details on the pop-up menu.

Any of the twelve function keys can also be used by typing an uppercase F followed by the key number. (e.g. F5)

The check boxes in the Modifier Keys group box can be used to indicate which keys must be pressed along with the primary keystroke.

Followed By entry field:

When active, this entry field can be filled with a keystroke character or symbolic keystroke name. The entry will be used as a secondary required keystroke in a keystroke mapping.

Like the Key entry field, symbolic keystrokes from the pop-up menu or any of the twelve function keys can be used as one of these secondary keystrokes.

A keystroke method can be invoked if a specified key is pressed and it is immediately followed by another specified key. An example of this in the standard VisualWorks configuration is changeEmphasisKey:. This is normally configured to execute if the Escape key is pressed, plus any of the following keys: b,B,i,I,+,-,s,S,u,U.

Although changeEmphasisKey: tries to use the value of the second keystroke to guide its operation, it is not required when using a two-key assignment. As an example, Alt+b followed by h can be mapped to browseClassHierarchyKey: and Alt+b followed by c can be to browseClassKey:. In both of these methods the value of the passed character event is irrelevant.

Because of the internal workings of the keystroke DispatchTables, the second keystroke cannot be a modified character. No modifier keys can be applied, and when the Followed By entry field is filled, all the check boxes in the Modifier Keys group box are disabled.

Modifier Keys check boxes:

These check boxes can to be used change which keys are used in combination with the primary keystroke to call one of the editor functions.

For example, in the image of the window at the top of the page, the Ctrl and Shift boxes are checked and used as additional modifier keys to the Down arrow key. If the two modifier keys are held down and then the down arrow key is pressed, the method cursorDownKey: is called.

Some key combinations have predefined system constants. If you attempt to assign any of these combinations they will appear in the assignment list as their system equivalent. Letter characters that are entered with the Ctrl box checked will be converted to Ctrl(char). A + Ctrl will appear in the list as Ctrla.

There is one Ctrl based keystroke that requires remapping outside the DispatchTableEditor before it can be successfully remapped inside the editor. If the break key (Ctrl+c) is to be remapped to another method, the interrupt keystroke must be first remapped to another keystroke. VisualWorks has always provided a way to do this, but the feature has not been well publicized. Code is provided in the supplied DevTools workspace to make the external remapping easier.

See InputState class>>interruptKeyValue: for additional details.

Be aware that not all keystroke combinations will work on all platforms. Although a keystroke combination can be mapped to a method, some keyboards may not be able to generate the combination. In addition, some systems capture "system level" keystrokes before any application can parse it.

If testing indicates that a particular keystroke combination cannot be used, try another. There are many others that can be used.

If a satisfactory keystroke combination cannot be found, the method doMethod: can be assigned to a keystroke. This method will pop up a dialog box listing all of the assignable methods in the editing protocols.

Change button

When a keystroke mapping is selected in the Mapped keystrokes list pane, this button can be used to change the modifier keys used in conjunction with the mapped keystroke.

When the Change button is pressed, a check is made to make sure that the keystroke combination is not already mapped to another method. If the combination already exists, a dialog box pops up as a warning and to confirm that the keystroke should be remapped.

See DispatchTableEditor>>changeKeystroke and its callers for additional details.

Add button

Use this button to create a new mapped keystroke combination. If the keystroke combination is already mapped to another method, a dialog box like the one described above will be brought up to confirm the remapping.

See DispatchTableEditor>>addKeystroke and its callers for additional details.

Code view pane menu:

This pane displays the source of any method selected in the Editing Methods pane.

See DispatchTableEditor>>setMethodSource and its callers for additional details.

Key/Method pane:

This pane holds a sorted list of all keystroke combinations that have been mapped to a method. It is alphabetically sorted according to the symbols used by a DispatchTable to represent keystrokes.

If the middle mouse button is pressed, the pop-up menu is the same as the one in the Editing Methods pane.

See DispatchTable>>keyTable, DispatchTableEditor>>keyTableSelected, DispatchTableEditor>>updateKeyTable and their callers for additional details.

Bottom of the window buttons:

[Author's note: I am not really satisfied with this aspect of the DispatchTableEditor's interface. In a future version it may be changed to use drop down menus like the VisaulWorks window. I'm open to other suggestions.]

Open button

This button is used to load existing key map files into a DispatchTableEditor.

In a ContolWORKS image, an open file dialog like the one at the right will be presented. If not, a simple open file prompter will be presented.

In both cases, the initial filename will be filled in with the default keymap filename for the type of dispatch table being edited.

Unless a path name is prepended to the filename, the system will assume that the named file resides in the Smalltalk start-up directory. User created keymap files may also be opened. There are several examples of key map files shipped with the DevTools.

Loading a keymap file using the Open button overwrites any key mappings already in the editor.

See DispatchTableEditor>>openKeymap and its callers for additional details.

Apply button

This button is used to write the changed keystroke mappings to the DispatchTable of the class that the DispatchTableEditor was opened for.

The changed keystroke mappings do not go into effect until the Apply button is clicked. If the button is clicked, or if the main OK button is clicked, and the changes have not yet been applied, a dialog is popped up to confirm the writing of the new mappings.

The Discard button means "continue, but don't apply", and only has meaning if the dialog is brought up during the processing of another button, like OK.

See DispatchTableEditor>>applyChanges and its callers for additional details.

Save button

This button is used to write the keystroke mappings to an external file so that they can be reloaded at another time or shared with other users.

If the Save button is clicked, a dialog box will pop up to confirm the action. Like the Open button, an open file dialog or a save file prompter will pop up so that a name can be given to the keymap file.

The Discard button means "continue, but don't save", and only has meaning if the dialog is brought up during the processing of another button like OK.

See DispatchTableEditor>>save and its callers for additional details.

OK button

This button will start the process of closing of the window and may bring up some dialog boxes if there are any unsaved changes.

If there are any unsaved changes, dialog boxes will pop up to allow the the changes to be applied, saved and documented. The sequence of events will act as if the Apply and Save buttons have been pressed, and the create documentation... menu item has been chosen.

If the Cancel button is clicked in any of the popped up dialogs, the window close will abort and the editor will remain open.

See DispatchTableEditor>>ok, DispatchTableEditor>>requestForWindowClose, and their callers for additional details.

Cancel button

This button will close the window and discard changes that have not been applied or saved.

See DispatchTableEditor>>cancel, DispatchTableEditor>>requestForWindowClose, and their callers for additional details.

[ < TextEditor pop-up menu changes ] [ Application Manager changes > ]

[ Main ] [ Table of Contents ] [ Contact info ] [ Index ]

[ Home ]

This work is licensed under a Creative Commons License.