Eclipse Platform
Release 3.1

org.eclipse.ui.keys
Interface IBindingService


public interface IBindingService

Provides services related to the binding architecture (e.g., keyboard shortcuts) within the workbench. This service can be used to access the currently active bindings, as well as the current state of the binding architecture.

This interface should not be implemented or extended by clients.

Since:
3.1

Field Summary
static String DEFAULT_DEFAULT_ACTIVE_SCHEME_ID
          The default default value for the active scheme id.
 
Method Summary
 TriggerSequence[] getActiveBindingsFor(ParameterizedCommand parameterizedCommand)
          Gets the active bindings for a given parameterized command.
 TriggerSequence[] getActiveBindingsFor(String commandId)
          Gets the active bindings for a given command identifier.
 Scheme getActiveScheme()
          Returns the currently active scheme.
 Binding[] getBindings()
          Returns the current set of bindings.
 String getDefaultSchemeId()
          Returns the default scheme identifier for the currently running application.
 Scheme[] getDefinedSchemes()
          Returns the array of defined schemes in the workbench.
 String getLocale()
          Returns the currently active locale.
 Map getPartialMatches(TriggerSequence trigger)
          Returns all of the possible bindings that start with the given trigger (but are not equal to the given trigger).
 Binding getPerfectMatch(TriggerSequence trigger)
          Returns the command identifier for the active binding matching this trigger, if any.
 String getPlatform()
          Returns the currently active platform.
 Scheme getScheme(String schemeId)
          Retrieves the scheme with the given identifier.
 boolean isKeyFilterEnabled()
          Tests whether the global key binding architecture is currently active.
 boolean isPartialMatch(TriggerSequence trigger)
          Returns whether the given trigger sequence is a partial match for the given sequence.
 boolean isPerfectMatch(TriggerSequence trigger)
          Returns whether the given trigger sequence is a perfect match for the given sequence.
 void openKeyAssistDialog()
          Opens the key assistant dialog positioned near the key binding entry in the status bar.
 void readRegistryAndPreferences(ICommandService commandService)
           Reads the binding information from the registry and the preferences.
 void savePreferences(Scheme activeScheme, Binding[] bindings)
           Writes the given active scheme and bindings to the preference store.
 void setKeyFilterEnabled(boolean enabled)
           Enables or disables the global key binding architecture.
 

Field Detail

DEFAULT_DEFAULT_ACTIVE_SCHEME_ID

public static final String DEFAULT_DEFAULT_ACTIVE_SCHEME_ID
The default default value for the active scheme id. This value can be overridden using the "plugin_customization.ini" file. The BindingPersistence code needs to know this value so it can try to decide if someone overrode the default.

See Also:
Constant Field Values
Method Detail

getActiveBindingsFor

public TriggerSequence[] getActiveBindingsFor(ParameterizedCommand parameterizedCommand)
Gets the active bindings for a given parameterized command.

Parameters:
parameterizedCommand - The fully-parameterized command for which the active bindings should be found; must not be null.
Returns:
The array of all active bindings for the given command. This collection may be empty, but it is never null.

getActiveBindingsFor

public TriggerSequence[] getActiveBindingsFor(String commandId)
Gets the active bindings for a given command identifier. It is assumed that the command has no parameters.

Parameters:
commandId - The id of the command for which the active bindings should be found; must not be null.
Returns:
The array of all active bindings for the given command. This collection may be empty, but it is never null.

getActiveScheme

public Scheme getActiveScheme()
Returns the currently active scheme.

Returns:
The currently active scheme. This value may (in certain rare circumstances) be null.

getBindings

public Binding[] getBindings()
Returns the current set of bindings.

Returns:
The current array of bindings (Binding).

getDefaultSchemeId

public String getDefaultSchemeId()
Returns the default scheme identifier for the currently running application.

Returns:
The default scheme identifier (String); never null, but may be empty or point to an undefined scheme.

getDefinedSchemes

public Scheme[] getDefinedSchemes()
Returns the array of defined schemes in the workbench.

Returns:
The array of schemes (Scheme) that are defined; never null, but may be empty.

getLocale

public String getLocale()
Returns the currently active locale.

Returns:
The current locale.

getPartialMatches

public Map getPartialMatches(TriggerSequence trigger)
Returns all of the possible bindings that start with the given trigger (but are not equal to the given trigger).

Parameters:
trigger - The prefix to look for; must not be null.
Returns:
A map of triggers (TriggerSequence) to bindings (Binding). This map may be empty, but it is never null.

getPerfectMatch

public Binding getPerfectMatch(TriggerSequence trigger)
Returns the command identifier for the active binding matching this trigger, if any.

Parameters:
trigger - The trigger to match; may be null.
Returns:
The binding that matches, if any; null otherwise.

getPlatform

public String getPlatform()
Returns the currently active platform.

Returns:
The current platform.

getScheme

public Scheme getScheme(String schemeId)
Retrieves the scheme with the given identifier. If no such scheme exists, then an undefined scheme with the given id is created.

Parameters:
schemeId - The identifier to find; must not be null.
Returns:
A scheme with the given identifier, either defined or undefined.

isKeyFilterEnabled

public boolean isKeyFilterEnabled()
Tests whether the global key binding architecture is currently active.

Returns:
true if the key bindings are active; false otherwise.

isPartialMatch

public boolean isPartialMatch(TriggerSequence trigger)
Returns whether the given trigger sequence is a partial match for the given sequence.

Parameters:
trigger - The sequence which should be the prefix for some binding; should not be null.
Returns:
true if the trigger can be found in the active bindings; false otherwise.

isPerfectMatch

public boolean isPerfectMatch(TriggerSequence trigger)
Returns whether the given trigger sequence is a perfect match for the given sequence.

Parameters:
trigger - The sequence which should match exactly; should not be null.
Returns:
true if the trigger can be found in the active bindings; false otherwise.

openKeyAssistDialog

public void openKeyAssistDialog()
Opens the key assistant dialog positioned near the key binding entry in the status bar.


readRegistryAndPreferences

public void readRegistryAndPreferences(ICommandService commandService)

Reads the binding information from the registry and the preferences. This will overwrite any of the existing information in the binding service. This method is intended to be called during start-up. When this method completes, this binding service will reflect the current state of the registry and preference store.

Parameters:
commandService - The command service for the workbench; must not be null. This is used to locate command instances when constructing bindings.

savePreferences

public void savePreferences(Scheme activeScheme,
                            Binding[] bindings)
                     throws IOException

Writes the given active scheme and bindings to the preference store. Only the bindings that are of the Binding.USER type will be written; the others will be ignored. This should only be used by applications trying to persist user preferences. If you are trying to change the active scheme as an RCP application, then you should be using the plugin_customization.ini file. If you are trying to switch between groups of bindings dynamically, you should be using contexts.

This method also updates the active scheme and bindings in the system to match those written to the preference store.

Parameters:
activeScheme - The scheme which should be persisted; may be null.
bindings - The bindings which should be persisted; may be null.
Throws:
IOException - If something goes wrong while writing to the preference store.
See Also:
IWorkbenchPreferenceConstants, IContextService

setKeyFilterEnabled

public void setKeyFilterEnabled(boolean enabled)

Enables or disables the global key binding architecture. The architecture should be enabled by default.

When enabled, keyboard shortcuts are active, and that key events can trigger commands. This also means that widgets may not see all key events (as they might be trapped as a keyboard shortcut).

When disabled, no key events will trapped as keyboard shortcuts, and that no commands can be triggered by keyboard events. (Exception: it is possible that someone listening for key events on a widget could trigger a command.)

Parameters:
enabled - Whether the key filter should be enabled.

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

Copyright (c) IBM Corp. and others 2000, 2005. All rights reserved.