Jump to: navigation, search

Difference between revisions of "FAQ How do I provide a keyboard shortcut for my action?"

m
(update menu item; now accessed from Eclipse menu)
 
(2 intermediate revisions by 2 users not shown)
Line 1: Line 1:
Keyboard shortcuts are created by defining a <i>key binding</i>, using the <tt>org.eclipse.ui.commands</tt> extension point. When you define a  key binding, you generally specify four things:
+
A keyboard shortcut (key binding) defines a key that when pressed will execute an Eclipse command.  Keyboard shortcuts are organized into independent sets called key configurations or schemes.  The user chooses the key configuration that emulates the shortcut keys of his or her favorite editor or IDE.
 +
 
 +
This FAQ describes two different ways to define shortcut keys.
 +
 
 +
== Display and Edit the Current Keyboard Shortcuts ==
 +
To see the current key configuration and its keyboard shortcuts, choose the '''Eclipse &gt; Preferences''' menu command to open the Eclipse workbench '''Preferences'''.  Select the '''General &gt; Editor &gt; Keys''' page.  This page displays the currently active '''Scheme''' (key configuration) and the keyboard shortcuts it defines.  '''Emacs''' is a set of keyboard shortcuts that emulates emacs.  Similarly, '''Microsoft Visual Studio''' defines a set of shortcuts that emulates that IDE.  The native configuration for Eclipse is '''Default'''.
 +
 
 +
== Define a Keyboard Shortcut Through an Extension Point ==
 +
Keyboard shortcuts can also be created by defining a <i>key sequence</i>, using the <tt>org.eclipse.ui.bindings</tt> extension point. When you define a  key sequence, you generally specify four things:
  
* The ID of the configuration to which it applies.
 
 
* The context, or scope, for the key binding.  For example, the text editor defines a context that can override bindings from the global context.
 
* The context, or scope, for the key binding.  For example, the text editor defines a context that can override bindings from the global context.
 +
* The scheme, for the key binding, for example, the default key binding scheme or the Emacs key binding scheme.
 
* The ID of the command that you are creating a binding for.  You can find command IDs by browsing the <tt>plugin.xml</tt> file of the plug-in that defines that action.
 
* The ID of the command that you are creating a binding for.  You can find command IDs by browsing the <tt>plugin.xml</tt> file of the plug-in that defines that action.
 
* The accelerator sequence.
 
* The accelerator sequence.
Line 8: Line 16:
 
You can also define a key binding that applies only to a particular locale or platform. For example, you can define an accelerator that applies only to a German Linux GTK installation of Eclipse.  See the <tt>command</tt> extension point documentation for more details on these advanced features.
 
You can also define a key binding that applies only to a particular locale or platform. For example, you can define an accelerator that applies only to a German Linux GTK installation of Eclipse.  See the <tt>command</tt> extension point documentation for more details on these advanced features.
  
The following is an example key-binding definition.  This binding sets the accelerator for the Java '''Sort Members''' action, which by default has no key binding:
+
The following is an example key-binding definition.  This binding sets up a toggle comment accelerator for a hypothetical [http://en.wikipedia.org/wiki/AMPLE AMPLE] language editor, which by default has no key binding:
 +
 
 
<pre>
 
<pre>
  &lt;keyBinding
+
&lt;extension point="org.eclipse.ui.bindings"&gt;
      string=&quot;Ctrl+Shift+D&quot;
+
&lt;key sequence="Ctrl+7"
      context=&quot;org.eclipse.ui.globalScope&quot;
+
commandId="uk.co.example.actions.togglecomment"
      command=&quot;org.eclipse.jdt.ui.edit.text.java.sort.members&quot;
+
schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"
      configuration=&quot;org.eclipse.faq.sampleConfiguration&quot;&gt;
+
contextId="uk.co.example.ampleEditorScope"/&gt;
  &lt;/keyBinding&gt;
+
&lt;/extension&gt;
 
</pre>
 
</pre>
  
The difference between a configuration and a context can be confusing  at first.  The configuration is explicitly set by the user; once it is set, it does not change.  The context can be changed programmatically by any plug-in.  For example, you can change the scope whenever your view or editor becomes active.  Scopes can be queried and set by using the <tt>IKeyBindingService</tt>. This service can be accessed within a workbench part by using the method <tt>getKeyBindingService</tt> on <tt>IWorkbenchPartSite</tt>.
+
The difference between a scheme and a [[org.eclipse.ui.context|context]] can be confusing  at first.  The scheme is explicitly set by the user; once it is set, it does not change.  The context can be changed programmatically by any plug-in.  For example, you can change the context whenever your view or editor becomes active, using <tt>AbstractTextEditor.setKeyBindingScopes()</tt>.
  
  

Latest revision as of 13:26, 9 July 2010

A keyboard shortcut (key binding) defines a key that when pressed will execute an Eclipse command. Keyboard shortcuts are organized into independent sets called key configurations or schemes. The user chooses the key configuration that emulates the shortcut keys of his or her favorite editor or IDE.

This FAQ describes two different ways to define shortcut keys.

Display and Edit the Current Keyboard Shortcuts

To see the current key configuration and its keyboard shortcuts, choose the Eclipse > Preferences menu command to open the Eclipse workbench Preferences. Select the General > Editor > Keys page. This page displays the currently active Scheme (key configuration) and the keyboard shortcuts it defines. Emacs is a set of keyboard shortcuts that emulates emacs. Similarly, Microsoft Visual Studio defines a set of shortcuts that emulates that IDE. The native configuration for Eclipse is Default.

Define a Keyboard Shortcut Through an Extension Point

Keyboard shortcuts can also be created by defining a key sequence, using the org.eclipse.ui.bindings extension point. When you define a key sequence, you generally specify four things:

  • The context, or scope, for the key binding. For example, the text editor defines a context that can override bindings from the global context.
  • The scheme, for the key binding, for example, the default key binding scheme or the Emacs key binding scheme.
  • The ID of the command that you are creating a binding for. You can find command IDs by browsing the plugin.xml file of the plug-in that defines that action.
  • The accelerator sequence.

You can also define a key binding that applies only to a particular locale or platform. For example, you can define an accelerator that applies only to a German Linux GTK installation of Eclipse. See the command extension point documentation for more details on these advanced features.

The following is an example key-binding definition. This binding sets up a toggle comment accelerator for a hypothetical AMPLE language editor, which by default has no key binding:

	<extension point="org.eclipse.ui.bindings">
		<key sequence="Ctrl+7"
			commandId="uk.co.example.actions.togglecomment"
			schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"
			contextId="uk.co.example.ampleEditorScope"/>
	</extension>

The difference between a scheme and a context can be confusing at first. The scheme is explicitly set by the user; once it is set, it does not change. The context can be changed programmatically by any plug-in. For example, you can change the context whenever your view or editor becomes active, using AbstractTextEditor.setKeyBindingScopes().


See Also:


This FAQ was originally published in Official Eclipse 3.0 FAQs. Copyright 2004, Pearson Education, Inc. All rights reserved. This text is made available here under the terms of the Eclipse Public License v1.0.