<type>documentation</type>
<domain>custom</domain>
<id>key-equivalents</id>
<title>Key Bindings</title>
<date>$Date$</date>
<version>$Revision$</version>
<product>per+</product>

The command a key binding invokes may be modified with the `User Interface > Keyboard >
Custom Key Bindings <script:show_preferences_gui#prefname="gui.keymap-override">`__
preference. A custom key binding will override any binding found in the current keyboard
personality.

To add a binding, click the ``Insert`` button, press the key binding you wish to use
in the ``Key`` field, and then enter the name of the command to invoke in the 
``Command`` field.  To unbind a key that Wing defines by default, leave the ``Command``
field blank.

To determine what command a key is currently bound to, select ``Command by Name`` from the
``Edit`` menu, type ``describe-key-briefly`` and then press the key binding followed by
``Enter``.

**Key Bindings**

Key bindings consist of one or more key presses, including any regular key and one or
more modifier keys (``Shift``, ``Ctrl``, ``Alt``, and/or ``Command``).  Multiple 
modifiers may be pressed at once; ``Ctrl-Shift-X`` is distinct from ``Ctrl-X``.

The ``Shift`` key is treated as a modifier only for keys where there is a lower case and
upper case variant. For example, ``Shift-M`` is a valid binding for capital ``M`` while 
``Shift-9`` will result in a different key binding (``Parenleft`` on a US keyboard).
The dialog for adding key bindings from the Custom Key Bindings preference takes care
of this detail.

Key bindings may consist of multiple key strokes in a row, such as ``Ctrl-X
Ctrl-U``, ``Ctrl-X A``, or ``Esc X Y Z``.  

**Commands**

The command for a key binding may be any of Wing's internal commands, as documented
in the `Command Reference <ref:commands/index>`__, or (in Wing Pro and Wing Personal) 
any user-defined command provided by an `extension script <ref:scripting/index>`__.

To disable a key binding, leave the command field blank.

If multiple comma-separated commands are specified, the key binding will
execute the first available command in the list.  For example, specifying
``debug-restart, debug-continue`` as the command will first try to restart
an existing debug session, and if no debug session exists it will start
a new one.

Some commands take arguments, which can be specified in the binding, for example using
``enclose(start="(", end=")")`` in the ``Command`` field will enclose the current selection
with ``()``.  Any unspecified arguments that do not have a default defined by the command
will be collected from the user, either in a dialog or in the data entry area at the
bottom of the IDE window.

Key bindings defined by the keyboard personality or overridden by the Custom Key
Bindings preference will be shown
in menu items that implement the same command.  If a command is
given more than one key binding, only the last binding found will be
displayed, although all the bindings will work from the keyboard.

~~~if (WEBSITE or PLATFORM == "osx"):
**The Alt Key on macOS**

On macOS, the `User Interface > Keyboard > Alt Key
<script:show_preferences_gui(prefname="gui.qt-osx-key-for-alt")>`__ preference
allows selecting one or both of the ``Option`` keys or the ``Command`` keys to
act as the ``Alt`` key modifier for key bindings. 

This preference should be set according to keyboard type, so that
key bindings in Wing do not prevent entering characters composed with
the ``Option`` keys. 

For example, on German keyboards, ``[``, ``]``, and other common symbols are
entered with using ``Option`` key.  In those cases, setting the preference to
"Left Option key" frees up the right ``Option`` key for entering characters
and dedicates the left ``Option`` key to triggering key bindings.

When ``Command`` is used for ``Alt``, the binding for ``Alt-<key>`` takes
precedence over any binding for ``Command-<key>`` for the same key.
~~~
