| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html lang="en"> |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2019. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <LINK REL="STYLESHEET" HREF="../../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> |
| <title>Keys</title> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"> </script> |
| </head> |
| <body> |
| <h1>Keys</h1> |
| <p> |
| The function of the keyboard can be extensively customized in Eclipse using the |
| |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.svg" alt="command link"> |
| <strong>General > Keys</strong></a> |
| |
| preference page. Within Eclipse, key strokes and key sequences are assigned to |
| invoke particular commands. |
| </p> |
| <h2>Key Strokes, Key Sequences, and Key Bindings</h2> |
| <p> |
| A 'key stroke' is the pressing of a key on the keyboard, while optionally holding down one |
| or more of these modifier keys: <code>Ctrl</code>, <code>Alt</code> (<code>⌥</code> on macOS), <code>Shift</code>, or |
| <code>⌘</code> (only on macOS.) For example, holding down <code>Ctrl</code> then |
| pressing <code>A</code> produces the key stroke <code>Ctrl+A</code>. The pressing of the modifier keys themselves |
| do not constitute key strokes. |
| </p> |
| <p> |
| A 'key sequence' is one or more key strokes. Traditionally, Emacs assigned two or three key stroke key sequences to particular |
| commands. For example, the normal key sequence assigned to <code>Close All</code> in emacs is <code>Ctrl+X Ctrl+C</code>. |
| To enter this key sequence, one presses the key stroke <code>Ctrl+X</code> followed by the key stroke <code>Ctrl+C</code>. |
| While Eclipse supports key sequences of arbitrary lengths, it is recommended |
| that keyboard shortcuts be four key strokes in length (or less). |
| </p> |
| <p> |
| A 'key binding' is the assignment of a key sequence to a command. |
| </p> |
| <h2>Schemes</h2> |
| <p> |
| A 'scheme' is a set of bindings. Eclipse includes two schemes: |
| </p> |
| <ul> |
| <li>Default</li> |
| <li>Emacs (extends Default)</li> |
| </ul> |
| <p> |
| The <em>Default</em> scheme contains a general set of bindings, in many cases recognizable |
| as traditional key sequences for well known commands. For instance, <code>Ctrl+A</code> |
| is assigned to <code>Select All</code>, and <code>Ctrl+S</code> is assigned to <code>Save</code>. |
| </p> |
| <p> |
| The <em>Emacs</em> scheme contains a set of key bindings familiar to users of Emacs. |
| For instance, <code>Ctrl+X H</code> is assigned to <code>Select All</code>, and <code>Ctrl+X S</code> is assigned to <code>Save</code>. |
| </p> |
| <p> |
| It is important to understand why the <em>Emacs</em> scheme says that it 'extends Default'. The <em>Emacs</em> scheme |
| is not a complete set of bindings like the <em>Default</em> scheme. Rather, it borrows from the <em>Default</em> |
| scheme where possible, only defining explicit Emacs-style bindings where they vary from the |
| <em>Default</em> scheme. Generally, only well known commands like <code>Select All</code>, <code>Save</code>, etc. have specific Emacs key sequences associated with them. |
| </p> |
| <p>Choose the scheme you are most comfortable with by changing the 'Scheme' setting on the |
| keys preference page. If you choose the <em>Default</em> scheme, all <em>Emacs</em> bindings are ignored. If you choose |
| the <em>Emacs</em> scheme, explicit Emacs-style key sequence assignments take precedence over any conflicting assignments in the <em>Default</em> scheme. |
| </p> |
| <h2>Contexts</h2> |
| <p> |
| Key bindings can vary based on the current context of Eclipse. |
| </p> |
| <p> Sometimes the active part might be a Java file editor, for instance, where |
| a different set of key sequence assignments may be more appropriate than if |
| the active part was an html file editor. As a specific example, typically <code>Ctrl+B</code> |
| is assigned to <code>Build</code> in a context such as Java file editing, while |
| <code>Ctrl+B</code> is assigned to <code>Make Text Bold</code> in a context |
| such as HTML file editing. This context is usually determined by the active |
| part, but it can be influenced by the active window or dialog as well. If the |
| active part does not choose a particular context, the workbench will set the |
| active context to <em>In Windows</em>.</p> |
| <p>Eclipse includes a number of different contexts. Some examples are: </p> |
| <ul> |
| <li>In Dialogs and Windows</li> |
| <li>In Windows (extends In Dialogs and Windows)</li> |
| <li>In Dialogs (extends In Dialogs and Windows)</li> |
| <li>Editing Text (extends In Windows)</li> |
| <li>Editing Java Source (extends Editing Text)</li> |
| <li>Debugging (extends In Windows)</li> |
| <li>Debugging Java (extends Debugging)</li> |
| <li>In Console</li> |
| <li>Editing Ant buildfiles<br> |
| <br> |
| </li> |
| </ul> |
| <p> Much like configurations, contexts can extend other contexts. For example, |
| the <em>Editing Java Source</em> context borrows key bindings from the <em>Editing Text</em> |
| context, which in turn borrows key bindings from the <em>In Windows</em> context. |
| </p> |
| <p>Note: It is not recommended to promote a key binding to a context which it |
| extends. For example, it is not recommended to move an <em>Editing Text</em> key |
| binding to the <em>In Dialogs and Windows</em> context. This may have unexpected |
| results.</p> |
| <p>It is possible for some key bindings to work in dialogs. Those key bindings |
| are assigned to the <em>In Dialogs and Windows</em> context. One example of such a |
| key binding is the key binding for "cut". It is possible to change these key |
| bindings. For example, it is possible to have Ctrl+X as cut in dialogs, but |
| Ctrl+W as cut in windows.</p> |
| <h2>Platform and Locale</h2> |
| <p> |
| Key bindings also vary by platform and locale. On the macOS platform, <code>⌘+S</code> is assigned to <code>Save</code>, instead of the usual <code>Ctrl+S</code>. On Chinese locales (zh), <code>Alt+/</code> is assigned to <code>Content Assist</code>, instead of the usual <code>Ctrl+Space</code>. |
| </p> |
| <p> |
| The current platform and locale is determined when Eclipse starts, and does not vary over the course of an Eclipse instance. |
| </p> |
| <h2>Customizing Key bindings</h2> |
| <p> With multi-stroke key sequences, schemes, and contexts, there are a |
| lot of things to keep in mind when customizing key bindings. To make things |
| easier, all key customization is done on the |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.svg" alt="command link"> |
| <b>General > Keys</b></a> preference page. |
| </p> |
| <p> <img src="../../images/keys1.png" alt="Keys preference page the About command with no binding" > |
| </p> |
| <p> |
| In this example we want to bind <b>CTRL+5</b> to the About command. By default |
| the keys preference page will show you all possible keybindings. You can see |
| the About command listed in the Help category. You can bind the command |
| by putting focus in the Binding text box and pressing CTRL and 5 like you |
| would if you were executing the command. |
| </p> |
| <p> <img src="../../images/keys2.png" alt="Keys preference page the About command bound to CTRL+5" ></p> |
| <p> |
| When you type CTRL+5 you have created a binding for About. The right-most column |
| will indicate that this is a user binding by displaying a <b>U</b>. If there was |
| a conflict with another key, this column would also display a <b>C</b>. The binding |
| will be in the default context, "In Windows". You can now |
| use the When combo box to change the key binding context (for example, to move |
| this binding to "Editing Text"). |
| </p> |
| <p> |
| If you wanted to add a second key binding to About, you can use the |
| <b>Copy Command</b> button to create a second command entry for you to bind |
| another key to. If you want to delete a binding, you can either use the |
| <b>Remove Binding</b> button or simply give focus to the Binding text box |
| and hit <b>Backspace</b>. |
| </p> |
| |
| <h2>The Dynamic Nature of Key bindings</h2> |
| <p> |
| Key bindings are provided by plug-ins, and in Eclipse, plug-ins can be added or removed. |
| This can cause key bindings declared by these plug-ins to be added or removed. |
| Eclipse stores custom key bindings in a way to compensate for this. |
| Consider the example above where <code>CTRL+6</code> was assigned |
| to <code>About</code> in the <em>Default</em> scheme. Say you install a new |
| plug-in that assigns <code>CTRL+6</code> to a particular |
| command. Eclipse will preserve your assignment to <code>About</code>. |
| </p> |
| <h2>Conflict Resolution</h2> |
| <p> There are only a finite number of simple, common key strokes available to |
| assign to a multitude of commands. We have seen that scheme, context, |
| platform, and locale all partition key sequence assignments into domains where |
| they don't conflict with one another. Consider the case for <code>Ctrl+B</code> |
| above if contexts did not exist. One plug-in would assign <code>Ctrl+B</code> |
| to <code>Build</code>, the other plug-in would assign <code>Ctrl+B</code> to |
| <code>Make Bold Text</code>. How would Eclipse properly resolve this conflict? |
| </p> |
| <p> Though conflicts are drastically reduced by employing the above mechanisms, |
| they can still occur. Two plug-ins, independent of one another, could assign |
| the same key sequence to different commands with the same context, scheme, |
| platform, and locale. Consider if a plug-in assigned <code>Ctrl+F4</code> in |
| the <em>In Windows</em> context and <em>Default</em> scheme to one of its |
| commands. This directly conflicts with Eclipse assigning <code>Ctrl+F4</code> |
| to the close command in the same context and scheme. </p> |
| <p> |
| This is a conflict. It wouldn't be proper to invoke both commands, nor would it be proper to simply choose one of the two commands to receive the key stroke. |
| We pop up the Key Assist Dialog with the conflicting commands and allow the user |
| to select one. The Key Assist Dialog is the same dialog that displays |
| command choices for multiple key stroke key bindings. For example, if 2 commands |
| were bound to <b>F12</b> you might see: |
| </p> |
| <p> <img src="../../images/keys3.png" alt="Keys Assist dialog" ></p> |
| <p> |
| If the user sets a keybinding and creates a conflict, the conflicting bindings |
| will be displayed in the conflicts list. This can be used to navigate between |
| conflicting keybindings so that they can be changed. |
| </p> |
| <p> <img src="../../images/keys4.png" alt="Keys preference page conflict list" ></p> |
| <p> These types of conflicts can be resolved by explicitly assigning |
| the key sequence to one of the commands, or remove it from the other. </p> |
| <p> |
| Another type of conflict can be caused by multiple-key stroke key sequences. For example, in the <em>Emacs</em> scheme, there are many multiple-key stroke key sequences beginning with the key stroke <code>Ctrl+X</code>. <code>Ctrl+X K</code> is assigned to <code>Close</code>. <code>Ctrl+X H</code> is assigned to <code>Select All</code>. |
| </p> |
| <p> |
| As previously mentioned, the <em>Emacs</em> scheme borrows key bindings from the <em>Default</em> scheme. In the default scheme, <code>Ctrl+X</code> is assigned to <code>Cut</code>. Though the <em>Emacs</em> scheme doesn't explicitly redefine <code>Ctrl+X</code>, pressing <code>Ctrl+X</code> is required as part of many of its key bindings. In the <em>Emacs</em> scheme, when one presses <code>Ctrl+X</code>, one is half way to entering one of many possible assigned key sequences. One would not expect the <code>Cut</code> action to be invoked at this time. |
| </p> |
| <p> |
| For this type of conflict, the rule is that the <code>Ctrl+X</code> key sequence assigned to <code>Cut</code> would be ignored. Otherwise, it would not be possible to complete many of the key bindings in the <em>Emacs</em> configuration. |
| </p> |
| <h2>Export Key Bindings</h2> |
| <p> |
| The bindings can be exported to a CSV file. For this purpose, press the button <strong>Export CSV ...</strong>. This will launch a file dialog, where you can specify the location of the export file. |
| Note: The export file is for reporting purposes only and <strong>can not be used to import</strong> the binding files into Eclipse. |
| </p> |
| |
| <h2>Show Key Bindings When Command is Invoked</h2> |
| <p> |
| For learning purposes, presentations or screen casts it is very helpful to show the corresponding key binding when a command is invoked. Whenever the command is invoked (via the keyboard or via menu clicks), the key binding, the command's name and description are shown on the screen.</p> |
| <p> <img src="../../images/show_key_bindings.png" alt="Key binding of triggered command shown on screen" style="width: 40%" ></p> |
| <p> |
| This can be activated via the check boxes in the <em>Show key binding when command is invoked</em> group on the |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.svg" alt="command link"> |
| <strong>General > Keys</strong></a> preference page. |
| To toggle this setting quickly, the command 'Toggle Show Key Bindings' can be used (e.g. via the Find Actions dialog). |
| </p> |
| |
| <h3 class="related">Related concepts</h3> |
| <a href="accessmain.htm">Accessibility features in Eclipse</a><br> |
| <a href="../../tasks/tkeybindings.htm">Changing the key bindings</a><br> |
| <a href="../help.htm">Help</a> |
| |
| <h3 class="related">Related reference</h3> |
| <a href="fontsandcolors.htm">Font and color settings in Eclipse</a> |
| |
| </body> |
| </html> |