public interface IContextService extends IServiceWithSources
Provides services related to contexts in the Eclipse workbench. This provides access to contexts.
This service can be acquired from your service locator:
IContextService service = (IContextService) getSite().getService(IContextService.class);
Modifier and Type | Field and Description |
---|---|
static String |
CONTEXT_ID_DIALOG
The identifier for the context that is active when a shell registered as
a dialog.
|
static String |
CONTEXT_ID_DIALOG_AND_WINDOW
The identifier for the context that is active when a shell is registered
as either a window or a dialog.
|
static String |
CONTEXT_ID_WINDOW
The identifier for the context that is active when a shell is registered
as a window.
|
static String |
CONTEXT_ID_WORKBENCH_MENU
The identifier for the context that is active when a workbench is active.
|
static int |
TYPE_DIALOG
The type used for registration indicating that the shell should be
treated as a dialog.
|
static int |
TYPE_NONE
The type used for registration indicating that the shell should not
receive any key bindings be default.
|
static int |
TYPE_WINDOW
The type used for registration indicating that the shell should be
treated as a window.
|
Modifier and Type | Method and Description |
---|---|
IContextActivation |
activateContext(String contextId)
Activates the given context within the context of this service.
|
IContextActivation |
activateContext(String contextId,
Expression expression)
Activates the given context within the context of this service.
|
IContextActivation |
activateContext(String contextId,
Expression expression,
boolean global)
Activates the given context within the context of this service.
|
IContextActivation |
activateContext(String contextId,
Expression expression,
int sourcePriorities)
Deprecated.
Use
activateContext(String, Expression)
instead. |
void |
addContextManagerListener(IContextManagerListener listener)
Adds a listener to this context service.
|
void |
deactivateContext(IContextActivation activation)
Deactivates the given context within the context of this service.
|
void |
deactivateContexts(Collection activations)
Deactivates the given contexts within the context of this service.
|
void |
deferUpdates(boolean defer)
Informs the service that a batch operation has started.
|
Collection |
getActiveContextIds()
Returns the set of active context identifiers.
|
Context |
getContext(String contextId)
Retrieves the context with the given identifier.
|
Collection |
getDefinedContextIds()
Returns the collection of the identifiers for all of the defined contexts
in the workbench.
|
Context[] |
getDefinedContexts()
Returns the collection of all of the defined contexts in the workbench.
|
int |
getShellType(Shell shell)
Returns the shell type for the given shell.
|
void |
readRegistry()
Reads the context information from the registry and the preferences.
|
boolean |
registerShell(Shell shell,
int type)
Registers a shell to automatically promote or demote some basic types of
contexts.
|
void |
removeContextManagerListener(IContextManagerListener listener)
Removes a listener from this context service.
|
boolean |
unregisterShell(Shell shell)
Unregisters a shell that was previously registered.
|
addSourceProvider, removeSourceProvider
dispose
static final String CONTEXT_ID_WORKBENCH_MENU
static final String CONTEXT_ID_DIALOG
static final String CONTEXT_ID_DIALOG_AND_WINDOW
static final String CONTEXT_ID_WINDOW
static final int TYPE_DIALOG
static final int TYPE_NONE
EnabledSubmission
instances for the
"In Dialogs" or "In Windows" contexts.static final int TYPE_WINDOW
IContextActivation activateContext(String contextId)
Activates the given context within the context of this service. If this service was retrieved from the workbench, then this context will be active globally. If the service was retrieved from a nested component, then the context will only be active within that component.
Also, it is guaranteed that the contexts submitted through a particular
service will be cleaned up when that services is destroyed. So, for
example, a service retrieved from a IWorkbenchPartSite
would deactivate all of its contexts when the site is destroyed.
contextId
- The identifier for the context which should be activated; must
not be null
.IContextActivation activateContext(String contextId, Expression expression)
Activates the given context within the context of this service. The
context becomes active when expression
evaluates to
true
. This is the same as calling
activateContext(String, Expression, boolean)
with global==false
.
Also, it is guaranteed that the context submitted through a particular
service will be cleaned up when that services is destroyed. So, for
example, a service retrieved from a IWorkbenchPartSite
would deactivate all of its handlers when the site is destroyed.
contextId
- The identifier for the context which should be activated; must
not be null
.expression
- This expression must evaluate to true
before
this context will really become active. The expression may be
null
if the context should always be active.ISources
IContextActivation activateContext(String contextId, Expression expression, boolean global)
Activates the given context within the context of this service. The
context becomes active when expression
evaluates to
true
. If global==false
then this service
must also be the active service to activate the context.
Also, it is guaranteed that the context submitted through a particular
service will be cleaned up when that services is destroyed. So, for
example, a service retrieved from a IWorkbenchPartSite
would deactivate all of its handlers when the site is destroyed.
contextId
- The identifier for the context which should be activated; must
not be null
.expression
- This expression must evaluate to true
before
this context will really become active. The expression may be
null
if the context should always be active.global
- Indicates that the handler should be activated irrespectively
of whether the corresponding workbench component (e.g.,
window, part, etc.) is active.ISources
@Deprecated IContextActivation activateContext(String contextId, Expression expression, int sourcePriorities)
activateContext(String, Expression)
instead.
Activates the given context within the context of this service. The
context becomes active when expression
evaluates to
true
.
Also, it is guaranteed that the context submitted through a particular
service will be cleaned up when that services is destroyed. So, for
example, a service retrieved from a IWorkbenchPartSite
would deactivate all of its handlers when the site is destroyed.
contextId
- The identifier for the context which should be activated; must
not be null
.expression
- This expression must evaluate to true
before
this context will really become active. The expression may be
null
if the context should always be active.sourcePriorities
- The source priorities for the expression.ISources
void addContextManagerListener(IContextManagerListener listener)
Note: listeners should be removed when no longer necessary. If not, they will be removed when the IServiceLocator used to acquire this service is disposed.
listener
- The listener to attach; must not be null
.removeContextManagerListener(IContextManagerListener)
void deactivateContext(IContextActivation activation)
IContextActivation
used to activate the context.activation
- The token that was returned from a call to
activateContext
; must not be null
.void deactivateContexts(Collection activations)
IContextActivation
instances used to activate the
contexts.activations
- The tokens that were returned from a call to
activateContext
. This collection must only
contain instances of IContextActivation
. The
collection must not be null
.Collection getActiveContextIds()
null
if no active contexts have been set yet. If
the set is not null
, then it contains only
instances of String
.Context getContext(String contextId)
contextId
- The identifier to find; must not be null
.Context[] getDefinedContexts()
Context
) that are
defined; never null
, but may be empty.Collection getDefinedContextIds()
String
)
that are defined; never null
, but may be empty.int getShellType(Shell shell)
shell
- The shell for which the type should be determined. If this
value is null
, then
IContextService.TYPE_NONE
is returned.IContextService.TYPE_WINDOW
,
IContextService.TYPE_DIALOG
, or
IContextService.TYPE_NONE
.void readRegistry()
Reads the context information from the registry and the preferences. This will overwrite any of the existing information in the context service. This method is intended to be called during start-up. When this method completes, this context service will reflect the current state of the registry and preference store.
boolean registerShell(Shell shell, int type)
Registers a shell to automatically promote or demote some basic types of contexts. The "In Dialogs" and "In Windows" contexts are provided by the system. This a convenience method to ensure that these contexts are promoted when the given is shell is active.
If a shell is registered as a window, then the "In Windows" context is enabled when that shell is active. If a shell is registered as a dialog -- or is not registered, but has a parent shell -- then the "In Dialogs" context is enabled when that shell is active. If the shell is registered as none -- or is not registered, but has no parent shell -- then the neither of the contexts will be enabled (by us -- someone else can always enabled them).
If the provided shell has already been registered, then this method will change the registration.
shell
- The shell to register for key bindings; must not be
null
.type
- The type of shell being registered. This value must be one of
the constants given in this interface.true
if the shell had already been registered
(i.e., the registration has changed); false
otherwise.void removeContextManagerListener(IContextManagerListener listener)
listener
- The listener to be removed; must not be null
.boolean unregisterShell(Shell shell)
Unregisters a shell that was previously registered. After this method completes, the shell will be treated as if it had never been registered at all. If you have registered a shell, you should ensure that this method is called when the shell is disposed. Otherwise, a potential memory leak will exist.
If the shell was never registered, or if the shell is null
,
then this method returns false
and does nothing.
shell
- The shell to be unregistered; does nothing if this value is
null
.true
if the shell had been registered;
false
otherwise.void deferUpdates(boolean defer)
Note: You must insure that if you call
deferUpdates(true)
that nothing in your batched operation
will prevent the matching call to deferUpdates(false)
.
defer
- true when starting a batch operation false when ending the
operation
Copyright (c) 2000, 2015 Eclipse Contributors and others. All rights reserved.Guidelines for using Eclipse APIs.