org.eclipse.jface.bindings
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
|
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. |
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[]
|
getActiveBindingsDisregardingContextFor
(
ParameterizedCommand parameterizedCommand)
Returns the active bindings for a particular command identifier, but
discounting 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. |
TriggerSequence
|
getBestActiveBindingFor
(
ParameterizedCommand 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 set of all bindings managed by this class. |
Collection
|
getConflictsFor
(
TriggerSequence sequence)
Provides the current conflicts in the keybindings for the given
TriggerSequence as a
Collection
of
Binding
|
Map
|
getCurrentConflicts
()
Provides the current conflicts in the bindings as a Map The key will
be
TriggerSequence and the value will be the
Collection
of
Binding
|
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 java.lang.
Object
|
clone,
equals,
finalize,
getClass,
hashCode,
notify,
notifyAll,
toString,
wait,
wait,
wait
|
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.
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
.
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
.
getActiveBindingsDisregardingContextFor
public final
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 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. -
Since:
- 3.2
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.
getBestActiveBindingFor
public final
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
getBestActiveBindingFor
public final
TriggerSequence getBestActiveBindingFor(
ParameterizedCommand command)
-
-
-
Parameters:
-
command
-
-
Returns:
- a trigger sequence, or
null
-
Since:
- 3.4
getBestActiveBindingFormattedFor
public final
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
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 or
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 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 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.
removeBinding
public final 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)
, where n
is
the number of bindings.
-
-
-
Parameters:
-
binding
- The binding to be removed; must not be null
. -
Since:
- 3.2
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.
getCurrentConflicts
public
Map getCurrentConflicts()
- Provides the current conflicts in the bindings as a Map The key will
be
TriggerSequence
and the value will be the
Collection
of
Binding
-
-
-
Returns:
- Read-only
Map
of the current conflicts. If no conflicts,
then return an empty map. Never null
-
Since:
- 3.5
getConflictsFor
public
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 KeyBinding. If no conflicts,
then returns a
null
-
Since:
- 3.5
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()
,
Util.getWS()
Guidelines for using Eclipse APIs.
Copyright (c) Eclipse contributors and others 2000, 2008. All rights reserved.