Eclipse Platform
Release 3.1

org.eclipse.jface.bindings
Class BindingManager

java.lang.Object
  extended byorg.eclipse.jface.bindings.BindingManager
All Implemented Interfaces:
IContextManagerListener, ISchemeListener

public final class BindingManager
extends Object
implements IContextManagerListener, ISchemeListener

A central repository for bindings -- both in the defined and undefined states. Schemes and bindings can be created and retrieved using this manager. It is possible to listen to changes in the collection of schemes and bindings by adding a listener to the manager.

The binding manager is very sensitive to performance. Misusing the manager can render an application unenjoyable to use. As such, each of the public methods states the current run-time performance. In future releases, it is guaranteed that the method will run in at least the stated time constraint -- though it might get faster. Where possible, we have also tried to be memory efficient.

Since:
3.1

Field Summary
static boolean DEBUG
          This flag can be set to true if the binding manager should print information to System.out when certain boundary conditions occur.
 
Constructor Summary
BindingManager(ContextManager contextManager, CommandManager commandManager)
           Constructs a new instance of BindingManager.
 
Method Summary
 void addBinding(Binding binding)
           Adds a single new binding to the existing array of bindings.
 void addBindingManagerListener(IBindingManagerListener listener)
           Adds a listener to this binding manager.
 void contextManagerChanged(ContextManagerEvent contextManagerEvent)
           Notifies this manager that the context manager has changed.
 Map getActiveBindingsDisregardingContext()
           Computes the bindings for the current state of the application, but disregarding the current contexts.
 Collection getActiveBindingsDisregardingContextFlat()
           Computes the bindings for the current state of the application, but disregarding the current contexts.
 TriggerSequence[] getActiveBindingsFor(ParameterizedCommand parameterizedCommand)
           Returns the active bindings for a particular command identifier.
 TriggerSequence[] getActiveBindingsFor(String commandId)
           Returns the active bindings for a particular command identifier.
 Scheme getActiveScheme()
           Gets the currently active scheme.
 Binding[] getBindings()
           Returns the set of all bindings managed by this class.
 Scheme[] getDefinedSchemes()
           Returns the array of schemes that are defined.
 String getLocale()
           Returns the active locale for this binding manager.
 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 active platform for this binding manager.
 Scheme getScheme(String identifier)
           Gets the scheme with the given identifier.
 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 removeBindingManagerListener(IBindingManagerListener listener)
           Removes a listener from this binding manager.
 void removeBindings(TriggerSequence sequence, String schemeId, String contextId, String locale, String platform, String windowManager, int type)
           Removes any binding that matches the given values -- regardless of command identifier.
 void schemeChanged(SchemeEvent schemeEvent)
           Notifies this manager that a scheme has changed.
 void setActiveScheme(Scheme scheme)
           Selects one of the schemes as the active scheme.
 void setBindings(Binding[] bindings)
           Changes the set of bindings for this binding manager.
 void setLocale(String locale)
           Changes the locale for this binding manager.
 void setPlatform(String platform)
           Changes the platform for this binding manager.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

DEBUG

public static boolean DEBUG
This flag can be set to true if the binding manager should print information to System.out when certain boundary conditions occur.

Constructor Detail

BindingManager

public BindingManager(ContextManager contextManager,
                      CommandManager commandManager)

Constructs a new instance of BindingManager.

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

Parameters:
contextManager - The context manager that will support this binding manager. This value must not be null.
commandManager - The command manager that will support this binding manager. This value must not be null.
Method Detail

addBinding

public final void addBinding(Binding binding)

Adds a single new binding to the existing array of bindings. If the array is currently null, then a new array is created and this binding is added to it. This method does not detect duplicates.

This method completes in amortized O(1).

Parameters:
binding - The binding to be added; must not be null.

addBindingManagerListener

public final void addBindingManagerListener(IBindingManagerListener listener)

Adds a listener to this binding manager. 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.

contextManagerChanged

public final void contextManagerChanged(ContextManagerEvent contextManagerEvent)

Notifies this manager that the context manager has changed. This method is intended for internal use only.

This method completes in O(1).

Specified by:
contextManagerChanged in interface IContextManagerListener
Parameters:
contextManagerEvent - the context manager event. Guaranteed not to be null.

getActiveBindingsDisregardingContext

public final Map getActiveBindingsDisregardingContext()

Computes the bindings for the current state of the application, but disregarding the current contexts. This can be useful when trying to display all the possible bindings.

This method completes in O(n), where n is the number of bindings.

Returns:
A map of trigger (TriggerSequence) to bindings ( Collection containing Binding). This map may be empty, but it is never null.

getActiveBindingsDisregardingContextFlat

public final Collection getActiveBindingsDisregardingContextFlat()

Computes the bindings for the current state of the application, but disregarding the current contexts. This can be useful when trying to display all the possible bindings.

This method completes in O(n), where n is the number of bindings.

Returns:
All of the active bindings (Binding), not sorted in any fashion. This collection may be empty, but it is never null.

getActiveBindingsFor

public final TriggerSequence[] getActiveBindingsFor(ParameterizedCommand parameterizedCommand)

Returns the active bindings for a particular command identifier. This method operates in O(n) time over the number of bindings.

This method completes in O(1). If the active bindings are not yet computed, then this completes in O(nn), where n is the number of bindings.

Parameters:
parameterizedCommand - The fully-parameterized command whose bindings are requested. This argument may be null.
Returns:
The array of active triggers (TriggerSequence) for a particular command identifier. This value is guaranteed to never be null, but it may be empty.

getActiveBindingsFor

public final TriggerSequence[] getActiveBindingsFor(String commandId)

Returns the active bindings for a particular command identifier. This method operates in O(n) time over the number of bindings.

This method completes in O(1). If the active bindings are not yet computed, then this completes in O(nn), where n is the number of bindings.

Parameters:
commandId - The identifier of the command whose bindings are requested. This argument may be null. It is assumed that the command has no parameters.
Returns:
The array of active triggers (TriggerSequence) for a particular command identifier. This value is guaranteed not to be null, but it may be empty.

getActiveScheme

public final Scheme getActiveScheme()

Gets the currently active scheme.

This method completes in O(1).

Returns:
The active scheme; may be null if there is no active scheme. If a scheme is returned, it is guaranteed to be defined.

getBindings

public final Binding[] getBindings()

Returns the set of all bindings managed by this class.

This method completes in O(1).

Returns:
The array of all bindings. This value may be null and it may be empty.

getDefinedSchemes

public final Scheme[] getDefinedSchemes()

Returns the array of schemes that are defined.

This method completes in O(1).

Returns:
The array of defined schemes; this value may be empty, and it may be null.

getLocale

public final String getLocale()

Returns the active locale for this binding manager. The locale is in the same format as Locale.getDefault().toString().

This method completes in O(1).

Returns:
The active locale; never null.

getPartialMatches

public final Map getPartialMatches(TriggerSequence trigger)

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

This method completes in O(1). If the bindings aren't currently computed, then this completes in O(n), where n is the number of bindings.

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 final Binding getPerfectMatch(TriggerSequence trigger)

Returns the command identifier for the active binding matching this trigger, if any.

This method completes in O(1). If the bindings aren't currently computed, then this completes in O(n), where n is the number of bindings.

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

getPlatform

public final String getPlatform()

Returns the active platform for this binding manager. The platform is in the same format as SWT.getPlatform().

This method completes in O(1).

Returns:
The active platform; never null.

getScheme

public final Scheme getScheme(String identifier)

Gets the scheme with the given identifier. If the scheme does not already exist, then a new (undefined) scheme is created with that identifier. This guarantees that schemes will remain unique.

This method completes in amortized O(1).

Parameters:
identifier - The identifier for the scheme to retrieve; must not be null.
Returns:
A scheme with the given identifier.

isPartialMatch

public final boolean isPartialMatch(TriggerSequence trigger)

Returns whether the given trigger sequence is a partial match for the given sequence.

This method completes in O(1). If the bindings aren't currently computed, then this completes in O(n), where n is the number of bindings.

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 final boolean isPerfectMatch(TriggerSequence trigger)

Returns whether the given trigger sequence is a perfect match for the given sequence.

This method completes in O(1). If the bindings aren't currently computed, then this completes in O(n), where n is the number of bindings.

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.

removeBindingManagerListener

public final void removeBindingManagerListener(IBindingManagerListener listener)

Removes a listener from this binding manager.

This method completes in amortized O(1).

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

removeBindings

public final void removeBindings(TriggerSequence sequence,
                                 String schemeId,
                                 String contextId,
                                 String locale,
                                 String platform,
                                 String windowManager,
                                 int type)

Removes any binding that matches the given values -- regardless of command identifier.

This method completes in O(n), where n is the number of bindings.

Parameters:
sequence - The sequence to match; may be null.
schemeId - The scheme id to match; may be null.
contextId - The context id to match; may be null.
locale - The locale to match; may be null.
platform - The platform to match; may be null.
windowManager - The window manager to match; may be null. TODO Currently ignored.
type - The type to look for.

schemeChanged

public final void schemeChanged(SchemeEvent schemeEvent)

Notifies this manager that a scheme has changed. This method is intended for internal use only.

This method calls out to listeners, and so the time it takes to complete is dependent on third-party code.

Specified by:
schemeChanged in interface ISchemeListener
Parameters:
schemeEvent - An event describing the change in the scheme.

setActiveScheme

public final void setActiveScheme(Scheme scheme)
                           throws NotDefinedException

Selects one of the schemes as the active scheme. This scheme must be defined.

This method completes in O(n), where n is the height of the context tree.

Parameters:
scheme - The scheme to become active; must not be null.
Throws:
NotDefinedException - If the given scheme is currently undefined.

setBindings

public final void setBindings(Binding[] bindings)

Changes the set of bindings for this binding manager. Changing the set of bindings all at once ensures that: (1) duplicates are removed; and (2) avoids unnecessary intermediate computations. This method clears the existing bindings, but does not trigger a recomputation (other method calls are required to do that).

This method completes in O(n), where n is the number of bindings.

Parameters:
bindings - The new array of bindings; may be null. This set is copied into a local data structure.

setLocale

public final void setLocale(String locale)

Changes the locale for this binding manager. The locale can be used to provide locale-specific bindings. If the locale is different than the current locale, this will force a recomputation of the bindings. The locale is in the same format as Locale.getDefault().toString().

This method completes in O(1).

Parameters:
locale - The new locale; must not be null.
See Also:
Locale.getDefault()

setPlatform

public final void setPlatform(String platform)

Changes the platform for this binding manager. The platform can be used to provide platform-specific bindings. If the platform is different than the current platform, then this will force a recomputation of the bindings. The locale is in the same format as SWT.getPlatform().

This method completes in O(1).

Parameters:
platform - The new platform; must not be null.
See Also:
SWT.getPlatform()

Eclipse Platform
Release 3.1

Guidelines for using Eclipse APIs.

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