Class BindingManager
- java.lang.Object
-
- org.eclipse.core.commands.common.EventManager
-
- org.eclipse.core.commands.common.HandleObjectManager
-
- org.eclipse.jface.bindings.BindingManager
-
- All Implemented Interfaces:
IContextManagerListener
,ISchemeListener
public final class BindingManager extends HandleObjectManager 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
Fields Modifier and Type Field Description static boolean
DEBUG
This flag can be set totrue
if the binding manager should print information toSystem.out
when certain boundary conditions occur.-
Fields inherited from class org.eclipse.core.commands.common.HandleObjectManager
definedHandleObjects, handleObjectsById
-
-
Constructor Summary
Constructors Constructor Description BindingManager(ContextManager contextManager, CommandManager commandManager)
Constructs a new instance ofBindingManager
.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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[]
getActiveBindingsDisregardingContextFor(ParameterizedCommand parameterizedCommand)
Returns the active bindings for a particular command identifier, but discounting the current contexts.TriggerSequence[]
getActiveBindingsFor(String commandId)
Returns the active bindings for a particular command identifier.TriggerSequence[]
getActiveBindingsFor(ParameterizedCommand parameterizedCommand)
Returns the active bindings for a particular command identifier.Scheme
getActiveScheme()
Gets the currently active scheme.TriggerSequence
getBestActiveBindingFor(String commandId)
Gets the best active binding for a command.TriggerSequence
getBestActiveBindingFor(ParameterizedCommand command)
String
getBestActiveBindingFormattedFor(String commandId)
Gets the formatted string representing the best active binding for a command.Binding[]
getBindings()
Returns the set of all bindings managed by this class.Collection
getConflictsFor(TriggerSequence sequence)
Provides the current conflicts in the keybindings for the given TriggerSequence as aCollection
ofBinding
Map
getCurrentConflicts()
Provides the current conflicts in the bindings as a Map The key will beTriggerSequence
and the value will be theCollection
ofBinding
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 schemeId)
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
removeBinding(Binding binding)
Remove the specific binding by identity.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 org.eclipse.core.commands.common.HandleObjectManager
checkId, getDefinedHandleObjectIds
-
Methods inherited from class org.eclipse.core.commands.common.EventManager
addListenerObject, clearListeners, getListeners, isListenerAttached, removeListenerObject
-
-
-
-
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 benull
.commandManager
- The command manager that will support this binding manager. This value must not benull
.
-
-
Method Detail
-
addBinding
public 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 benull
.
-
addBindingManagerListener
public 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 benull
.
-
contextManagerChanged
public 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 interfaceIContextManagerListener
- Parameters:
contextManagerEvent
- the context manager event. Guaranteed not to benull
.
-
getActiveBindingsDisregardingContext
public 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)
, wheren
is the number of bindings.- Returns:
- A map of trigger (
TriggerSequence
) to bindings (Collection
containingBinding
). This map may be empty, but it is nevernull
.
-
getActiveBindingsDisregardingContextFlat
public 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)
, wheren
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 nevernull
.
-
getActiveBindingsDisregardingContextFor
public TriggerSequence[] getActiveBindingsDisregardingContextFor(ParameterizedCommand parameterizedCommand)
Returns the active bindings for a particular command identifier, but discounting the current contexts. 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 inO(nn)
, wheren
is the number of bindings.- Parameters:
parameterizedCommand
- The fully-parameterized command whose bindings are requested. This argument may benull
.- Returns:
- The array of active triggers (
TriggerSequence
) for a particular command identifier. This value is guaranteed to never benull
, but it may be empty. - Since:
- 3.2
-
getActiveBindingsFor
public 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 inO(nn)
, wheren
is the number of bindings.- Parameters:
parameterizedCommand
- The fully-parameterized command whose bindings are requested. This argument may benull
.- Returns:
- The array of active triggers (
TriggerSequence
) for a particular command identifier. This value is guaranteed to never benull
, but it may be empty.
-
getActiveBindingsFor
public 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 inO(nn)
, wheren
is the number of bindings.- Parameters:
commandId
- The identifier of the command whose bindings are requested. This argument may benull
. 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 benull
, but it may be empty.
-
getActiveScheme
public 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.
-
getBestActiveBindingFor
public 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 thanCtrl
).- Parameters:
commandId
- The identifier of the command for which the best active binding should be retrieved; must not benull
.- Returns:
- The trigger sequence for the best binding; may be
null
if no bindings are active for the given command. - Since:
- 3.2
-
getBestActiveBindingFor
public TriggerSequence getBestActiveBindingFor(ParameterizedCommand command)
- Parameters:
command
- the command to get trigger for sequence- Returns:
- a trigger sequence, or
null
- Since:
- 3.4
-
getBestActiveBindingFormattedFor
public 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 thanCtrl
).- Parameters:
commandId
- The identifier of the command for which the best active binding should be retrieved; must not benull
.- Returns:
- The formatted string for the best binding; may be
null
if no bindings are active for the given command. - Since:
- 3.2
-
getBindings
public 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 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 or
null
.
-
getLocale
public 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 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 inO(n)
, wheren
is the number of bindings.- Parameters:
trigger
- The prefix to look for; must not benull
.- Returns:
- A map of triggers (
TriggerSequence
) to bindings (Binding
). This map may be empty, but it is nevernull
.
-
getPerfectMatch
public 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 inO(n)
, wheren
is the number of bindings.- Parameters:
trigger
- The trigger to match; may benull
.- Returns:
- The binding that matches, if any;
null
otherwise.
-
getPlatform
public 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 Scheme getScheme(String schemeId)
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:
schemeId
- The identifier for the scheme to retrieve; must not benull
.- Returns:
- A scheme with the given identifier.
-
isPartialMatch
public 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 inO(n)
, wheren
is the number of bindings.- Parameters:
trigger
- The sequence which should be the prefix for some binding; should not benull
.- 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.
This method completes in
O(1)
. If the bindings aren't currently computed, then this completes inO(n)
, wheren
is the number of bindings.- Parameters:
trigger
- The sequence which should match exactly; should not benull
.- Returns:
true
if the trigger can be found in the active bindings;false
otherwise.
-
removeBinding
public void removeBinding(Binding binding)
Remove the specific binding by identity. Does nothing if the binding is not in the manager.
This method completes in
O(n)
, wheren
is the number of bindings.- Parameters:
binding
- The binding to be removed; must not benull
.- Since:
- 3.2
-
removeBindingManagerListener
public 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 benull
.
-
removeBindings
public 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)
, wheren
is the number of bindings.- Parameters:
sequence
- The sequence to match; may benull
.schemeId
- The scheme id to match; may benull
.contextId
- The context id to match; may benull
.locale
- The locale to match; may benull
.platform
- The platform to match; may benull
.windowManager
- The window manager to match; may benull
. TODO Currently ignored.type
- The type to look for.
-
schemeChanged
public 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 interfaceISchemeListener
- Parameters:
schemeEvent
- An event describing the change in the scheme.
-
getCurrentConflicts
public Map getCurrentConflicts()
Provides the current conflicts in the bindings as a Map The key will beTriggerSequence
and the value will be theCollection
ofBinding
- Returns:
- Read-only
Map
of the current conflicts. If no conflicts, then return an empty map. Nevernull
- Since:
- 3.5
-
getConflictsFor
public Collection getConflictsFor(TriggerSequence sequence)
Provides the current conflicts in the keybindings for the given TriggerSequence as aCollection
ofBinding
- Parameters:
sequence
- The sequence for which conflict info is required- Returns:
- Collection of KeyBinding. If no conflicts,
then returns a
null
- Since:
- 3.5
-
setActiveScheme
public 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)
, wheren
is the height of the context tree.- Parameters:
scheme
- The scheme to become active; must not benull
.- Throws:
NotDefinedException
- If the given scheme is currently undefined.
-
setBindings
public 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)
, wheren
is the number of bindings.- Parameters:
bindings
- The new array of bindings; may benull
. This set is copied into a local data structure.
-
setLocale
public 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 benull
.- See Also:
Locale.getDefault()
-
setPlatform
public 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 benull
.- See Also:
SWT.getPlatform()
,Util.getWS()
-
-