| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. 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"> </script> |
| </head> |
| <body> |
| <h1>Keys</h1> |
| <p> |
| The function of the keyboard can be extensively customized in Eclipse. 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>Option</code> on the Macintosh), <code>Shift</code>, or |
| <code>Command</code> (only on the Macintosh.) 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 to |
| users as traditional key sequences. 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> |
| The user decides which scheme they are most comfortable using by changing the 'Scheme' setting on the |
| keys preference page. If the user chooses the <em>Default</em> scheme, all <em>Emacs</em> bindings are ignored. If the user chooses |
| 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 nine different contexts. They 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 Macintosh platform, <code>Command+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.png"> |
| <b>General > Keys</b></a> preference page. |
| </p> |
| <p> <img src="../../images/keys1.png" alt="Keys preference page showing Emacs as the active configuration and the Close command selected" > |
| </p> |
| <p> |
| In this example, we have chosen to select <em>Emacs</em> as the scheme, |
| and have selected the command <code>Close</code> from the list of commands. Information |
| on this command, along with its current key bindings, is shown. </p> |
| <p> Notice that <code>Close</code> has three key sequences assigned to it: <code>Ctrl+F4</code> and <code>Ctrl+W</code> |
| in the <em>Default</em> scheme and <code>Ctrl+X K</code> in the <em>Emacs</em> |
| scheme. Both are assigned in the <em>In Windows</em> context. Thus, if the |
| user sets the scheme to <em>Default</em>, <code>Ctrl+F4</code> and <code>Ctrl+W</code> |
| will be assigned to <code>Close</code> while <code>Ctrl+X K</code> will not. |
| If the user sets the scheme to <em>Emacs</em>, however, <code>Ctrl+X |
| K</code> will be assigned to <code>Close</code>. As well, because the <em>Emacs</em> |
| scheme also borrows key bindings from the <em>Default</em> scheme, |
| <code>Ctrl+F4</code> and <code>Ctrl+W</code> will also be assigned to <code>Close</code> provided that |
| these key binding have not been assigned to another command in the <em>Emacs</em> |
| scheme. In this example, "Ctrl+W" is bound to <code>Cut</code> in the Emacs |
| scheme.</p> |
| <p> Below the list of key sequences assigned to <code>Close</code>, there is a |
| place to add or remove key bindings. By default, it selects the context as <em>In Windows</em>.</p> |
| <p> We type in the key sequence <code>Ctrl+W</code>, and the 'Add' button becomes |
| enabled. Also, a list of all the commands to which the key sequence <code>Ctrl+W</code> |
| is already assigned is show below the Add button. We can see that <code>Ctrl+W</code> |
| is currently assigned to the command <code>Cut</code> in the <em>In Windows and Dialogs</em> |
| context. We click the 'Add' button to assign <code>Ctrl+W</code> to <code>Close</code>. </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 This compensate for this. Consider the example above where <code>Ctrl+Alt+W</code> was assigned to <code>Cut</code> in the <em>Emacs</em> scheme. Consider the user installs a new plug-in which assigns <code>Ctrl+Alt+W</code> to a particular command. Eclipse will preserve the user's assignment to <code>Cut</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. The only proper thing to do is to ignore both key bindings, making <code>Ctrl+F4</code> effectively useless in this context and scheme. |
| </p> |
| <p> These types of conflicts can be resolved by the user explicitly assigning |
| the key sequence to one of the commands. </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> |
| <p><img src="../../images/ngrelc.png" alt="Related concepts" ><br> |
| <a href="accessmain.htm">Accessibility Features in Eclipse</a><br> |
| <a href="../../tasks/tkeybindings.htm">Changing the key bindings</a><br> |
| <a href="../chelpsys.htm">Online help system</a></p> |
| <p><img src="../../images/ngrelr.png" alt="Related references" ><br> |
| <a href="fontsandcolors.htm">Font and color settings in Eclipse</a></p> |
| |
| </body> |
| </html> |