Eclipse Platform Release 3.7

## org.eclipse.ui.keys
Interface IBindingService

All Superinterfaces:
  IDisposable

    public interface IBindingService

extends IDisposable

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 service can be acquired from your service locator:

            IBindingService service = (IBindingService) getSite().getService(IBindingService.class);

- This service is available globally.

Since:
  3.1
Restriction:
  This interface is not intended to be implemented by clients.
Restriction:
  This interface is not intended to be extended by clients.

Field Summary
`static String` `DEFAULT_DEFAULT_ACTIVE_SCHEME_ID` The default default value for the active scheme id.

Method Summary
`void` `addBindingManagerListener(IBindingManagerListener listener)` Adds a listener to this binding service.
`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.
`TriggerSequence` `getBestActiveBindingFor(ParameterizedCommand command)` Gets the best active binding for a command.
`TriggerSequence` `getBestActiveBindingFor(String commandId)` Gets the best active binding for a command.
`String` `getBestActiveBindingFormattedFor(String commandId)` Gets the formatted string representing the best active binding for a command.
`Binding[]` `getBindings()` Returns the current set of bindings.
`TriggerSequence` `getBuffer()` Returns the current state of the key binding buffer.
`Collection` `getConflictsFor(TriggerSequence sequence)` Provides the current conflicts in the keybindings for the given TriggerSequence as a `Collection` of `Binding`
`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` `removeBindingManagerListener(IBindingManagerListener listener)` Removes a listener from this binding service.
`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.

Methods inherited from interface org.eclipse.ui.services.IDisposable
`dispose`

Field Detail

### DEFAULT_DEFAULT_ACTIVE_SCHEME_ID

    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

### addBindingManagerListener

    void addBindingManagerListener(IBindingManagerListener listener)

  Adds a listener to this binding service. The listener will be notified when the set of defined schemes or bindings changes. This can be used to track the global appearance and disappearance of bindings.

  This method completes in amortized constant time (`O(1)`).

  Parameters:
    `listener` - The listener to attach; must not be `null`.
  Since:
    3.5

### removeBindingManagerListener

    void removeBindingManagerListener(IBindingManagerListener listener)

  Removes a listener from this binding service.

  This method completes in amortized `O(1)`.

  Parameters:
    `listener` - The listener to be removed; must not be `null`.
  Since:
    3.5

### getActiveBindingsFor

    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

    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

    Scheme getActiveScheme()

  Returns the currently active scheme.

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

### getBestActiveBindingFor

    TriggerSequence getBestActiveBindingFor(ParameterizedCommand command)

  Gets the best active binding for a command. The best binding is the one that would be most appropriate to show in a menu. Bindings which belong to a child scheme are given preference over those in a parent scheme. Bindings which belong to a particular locale or platform are given preference over those that do not. The rest of the calculation is based most on various concepts of "length", as well as giving some modifier keys preference (e.g., `Alt` is less likely to appear than `Ctrl`).

  Parameters:
    `command` - The command for which the best active binding should be retrieved; must not be `null`.
  Returns:
    The trigger sequence for the best binding; may be `null` if no bindings are active for the given command.
  Since:
    3.4

### getBestActiveBindingFor

    TriggerSequence getBestActiveBindingFor(String commandId)

  Gets the best active binding for a command. The best binding is the one that would be most appropriate to show in a menu. Bindings which belong to a child scheme are given preference over those in a parent scheme. Bindings which belong to a particular locale or platform are given preference over those that do not. The rest of the calculaton is based most on various concepts of "length", as well as giving some modifier keys preference (e.g., `Alt` is less likely to appear than `Ctrl`).

  Parameters:
    `commandId` - The identifier of the command for which the best active binding should be retrieved; must not be `null`.
  Returns:
    The trigger sequence for the best binding; may be `null` if no bindings are active for the given command.
  Since:
    3.2
  See Also:
    `getBestActiveBindingFor(ParameterizedCommand)`

### getBestActiveBindingFormattedFor

    String getBestActiveBindingFormattedFor(String commandId)

  Gets the formatted string representing the best active binding for a command. The best binding is the one that would be most appropriate to show in a menu. Bindings which belong to a child scheme are given preference over those in a parent scheme. The rest of the calculaton is based most on various concepts of "length", as well as giving some modifier keys preference (e.g., `Alt` is less likely to appear than `Ctrl`).

  Parameters:
    `commandId` - The identifier of the command for which the best active binding should be retrieved; must not be `null`.
  Returns:
    The formatted string for the best binding; may be `null` if no bindings are active for the given command.
  Since:
    3.2
  See Also:
    `getBestActiveBindingFor(ParameterizedCommand)`

### getBindings

    Binding[] getBindings()

  Returns the current set of bindings.

  Returns:
    The current array of bindings (`Binding`).

### getBuffer

    TriggerSequence getBuffer()

  Returns the current state of the key binding buffer. This will contain all of the keys currently awaiting processing. If the system is currently executing a command (as a result of a key press), then this will contain the trigger sequence used to execute the command. If the key binding architecture has seen part of multi-key binding, then this will contain the part that it has seen. Otherwise, this will return nothing.

  Returns:
    The trigger sequence indicating the current state of the key binding buffer; never `null`, but may be empty if there is nothing in the buffer.
  Since:
    3.2

### getDefaultSchemeId

    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

    Scheme[] getDefinedSchemes()

  Returns the array of defined schemes in the workbench.

  Returns:
    The array of schemes (`Scheme`) that are defined; it may be `null`, and it may be empty.

### getLocale

    String getLocale()

  Returns the currently active locale.

  Returns:
    The current locale.

### getPartialMatches

    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

    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

    String getPlatform()

  Returns the currently active platform.

  Returns:
    The current platform.

### getScheme

    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

    boolean isKeyFilterEnabled()

  Tests whether the global key binding architecture is currently active.

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

### isPartialMatch

    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

    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

    void openKeyAssistDialog()

  Opens the key assistant dialog positioned near the key binding entry in the status bar.

### readRegistryAndPreferences

    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` - Ignored.

### savePreferences

    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

    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.

### getConflictsFor

    Collection getConflictsFor(TriggerSequence sequence)

  Provides the current conflicts in the keybindings for the given TriggerSequence as a `Collection` of `Binding`

  Parameters:
    `sequence` - The sequence for which conflict info is required
  Returns:
    Collection of Bindings. If no conflicts, then returns a `null`
  Since:
    3.5

Eclipse Platform Release 3.7

Guidelines for using Eclipse APIs.

Copyright (c) Eclipse contributors and others 2000, 2011. All rights reserved.