<type>documentation</type>
<domain>custom</domain>
<id>key-maps</id>
<title>Key Maps</title>
<date>$Date: 2012-11-15 16:19:20 -0500 (Thu, 15 Nov 2012) $</date>
<version>$Revision: 27653 $</version>
<product>per+</product>

Wing ships with several keyboard maps, found at the top level of the installation
directory as ``keymap.*``.  These implement the keyboard
personalities in the `User Interface > Keyboard > Personality
<script:show_preferences_gui#prefname="edit.personality">`__ preference.

In order to develop an entirely new key binding, it is possible to create and 
select a custom key map with the `User Interface > Advanced > Key Map File
<script:show_preferences_gui#prefname="gui.keymap">`__ preference.

In a key map file, each key binding is built from the names listed in `Key
Names <ref:custom/key-names>`__. These names are the same as the bindings
produced when adding a binding with the `User Interface > Keyboard > Custom Key Bindings 
<script:show_preferences_gui#prefname="gui.keymap-override">`__ preference,
with some additional options.  They may include:

1) A single unmodified key, which is specified by its name alone.  For example,
   ``'Down'`` for the down arrow key.

2) Modified keys, which are specified by hyphenating the key names, for example 
   ``'Shift-Down'`` if pressing the down arrow while ``Shift`` is held 
   down. Multiple modifiers may be specified, as in ``'Ctrl-Shift-Down'``.
   However, ``Shift`` should only be used for keys that have a lower case
   and upper case variant.  For example, ``'Shift-5'`` is invalid and should
   be replaced with the key actually produced (``Percent`` on US keyboards). 

3) Multi-part key bindings can be specified by several bindings
   separated by a space. For example, to define a key binding that consists
   of first pressing and releasing ``Ctrl-X`` and then pushing the ``A`` key by 
   itself, use ``'Ctrl-X A'`` as the key binding.

4) The special modifier ``Timeout`` may be used in multi-part key bindings with 
   otherwise unmodified keys, to indicate a provisional key that is emitted as a regular
   key if no matching key binding is found within the timeout period. For example,
   ``Timeout-J K`` requires typing ``jk`` in rapid succession. If only ``j`` is typed, it
   will be entered after the timeout elapses. If ``jp`` is typed and there is no binding
   for ``Timeout-J P`` then both ``j`` and ``p`` will be entered as soon as ``p`` is
   pressed. Bindings using ``Timeout`` only work while the focus is in the editor.
   Otherwise, they are ignored. The timeout used is configured with the `User Interface >
   Keyboard > Typing Group Timeout
   <script:show_preferences_gui#prefname="gui.typing-group-timeout">`__ preference.

5) The ``Release`` modifier can be used with any single-part key binding to specify 
   that a command should be bound to the release of a key combination.  For example, 
   ``'Release-Ctrl-X'`` invokes a command only when releasing ``Ctrl-X``.
   
6) Special modifiers are defined for VI/Vim mode:  ``Visual``, ``Browse``,
   ``Insert``, and ``Replace``. These correspond with the different editor modes, so that
   the binding will only work in that mode. These modifiers only work if the `User
   Interface > Keyboard > Keyboard Personality
   <script:show_preferences_gui#prefname="edit.personality">`__ preference has been set to
   ``VI/Vim``.
   
The command portion of the key binding may be any of the
commands listed in the `Command Reference <ref:commands/index>`__. See 
`Key Bindings <ref:custom/key-equivalents>`__ and the examples below for details.

Includes
--------

Key maps can include other keymaps.  For example, all the default keymaps include
a basic map that defines the action of the arrow keys, function keys, and
other common functionality::

  %include keymap.basic

The referenced file must be in the same directory as the keymap that contains
the include, or a full path.

Examples
--------

Here is an example that adds a key binding.  If the command already has a default 
key binding, both bindings will work::

  'Ctrl-X P': 'debug-attach'
  
This example undefines a key binding from an earlier definition (usually, from an 
included key map file)::

  'Ctrl-C Ctrl-C': None

These can be combined to change the key binding for a command without
retaining its default key binding::

  'Ctrl-C Ctrl-C': None
  'Ctrl-G': 'debug-continue'

Wing always retains only the last key binding for a given key combination.
This example binds ``Ctrl-X`` to ``quit`` and no other command::

  'Ctrl-X': 'debug-stop'
  'Ctrl-X': 'quit'

If multiple commands are separated by commas, Wing executes the
first command that is available.  For example, the following will 
restart the debug process whether or not one is already running::

  'Ctrl-X': 'debug-restart, debug-continue'

Command arguments can be specified as part of the binding.  Any unspecified
arguments that do not have a default will be collected from the user
in a dialog or in the data entry area at the bottom of the IDE window::

  'Ctrl-X P': 'show-panel(panel_type="debug-console")'

If Keyboard Personality is set to VI/Vim, modifiers corresponding to the
editor modes restrict availability of the binding to only that mode::

  'Visual-Ctrl-X': 'cut'
  
Here is an example that combines several of the above with the ``Release``
modifier::

  'Shift-Space': 'debug-show-value-tips', 'send-keys(keys=" ")'
  'Release-Shift-Space': 'debug-hide-value-tips'

