add-global-keyboard-accelerator

Function

Package: common-graphics

Arguments: event-synonym function-name

This function establishes a global keyboard shortcut that does not have a corresponding menu-item on a top-level menubar.

event-synonym should be a character or a list of modifier keys and a character, to denote a keyboard event that should run some function globally. This argument can be a key-chord that will invoke the command. An event-synonym always contains a single main non-SHIFT key, plus an optional set of one or more SHIFT keys.

If no SHIFT keys are used, then the event-synonym consists entirely of a character name like #\A or a key name like vk-comma or vk-f3.

If SHIFT keys are used, then the event-synonym is a list whose members are the names of the shift keys (in any order) and the main non-SHIFT key as the last member. The available shift key names are control-key, alt-key, and shift-key, and they may be used in any combination.

Normally, typable characters (such as letters and numbers) are used only in combination with either control-key or alt-key (or both), since otherwise you could not input the characters as text.

function-name denotes the function to run. The function should take one argument, which will be the window that had the keyboard focus when the specified keys were pressed. The function should return true to disable any further processing of this event, or nil to allow the keyboard event to still be looked up in the top-level window's menu bar or to be otherwise handled by the selected window's event handler.

In releases prior to 6.0, global keyboard accelerators did not work in windows that have comtabs, requiring a corresponding addition to the comtab to make it work there. (In the IDE, the editor and Debug Window have comtabs.) This is no longer true, and so a global keyboard accelerator will take precedence over any other handling of its keypress event in any window.

The function for a global keyboard accelerator will run in the thread that created the window that had the keyboard focus when the keypress event occurred (which is the window passed to the function). For standard IDE windows, this will be the IDE GUI thread. If it is desirable to run the code in a Listener thread instead, where user evaluations are normally done, the function eval-in-listener-thread could be used in the accelerator's function to do so.

Global keyboard accelerators can be removed with remove-global-keyboard-accelerator.

Examples

Here are two examples that define global accelerators that move the selected window by 8 pixels either up or down. The first example (to move the window up) illustrates calling a separately defined function and using one of the vk-foo names for keys that don't have printable characters on them, and the second example (to move the window down) illustrates using an in-place function object and using the character that's printed on the lower (unshifted) part of the key.

;; Define a function to move a window upward by eight pixels.
(defun move-up (window)
  (with-positions (pos1)
    (move-window-relative window (nmake-position pos1 0 -8)))
  t)

;; Make alt-backspace move the current window up.
(add-global-keyboard-accelerator
 '(alt-key vk-backspace) 'move-up)

;; Define a lambda function to move a window downward by eight pixels
;; and make control-shift-8 invoke it.
(add-global-keyboard-accelerator
 '(control-key shift-key #\8)
 #'(lambda (window)
     (with-positions (pos1)
       (move-window-relative window (nmake-position pos1 0 8)))
     t)) 
     ;; Return true to override any other control-shift-8 handling

Common Graphics and IDE documentation is described in About Common Graphics and IDE documentation in cgide.htm.

The documentation is described in introduction.htm and the index is in index.htm.

Created 2000.10.5.