Interface IContextService
- All Superinterfaces:
IDisposable
,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);
- 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
Modifier and TypeFieldDescriptionstatic final String
The identifier for the context that is active when a shell registered as a dialog.static final String
The identifier for the context that is active when a shell is registered as either a window or a dialog.static final String
The identifier for the context that is active when a shell is registered as a window.static final String
The identifier for the context that is active when a workbench is active.static final int
The type used for registration indicating that the shell should be treated as a dialog.static final int
The type used for registration indicating that the shell should not receive any key bindings be default.static final int
The type used for registration indicating that the shell should be treated as a window. -
Method Summary
Modifier and TypeMethodDescriptionactivateContext
(String contextId) Activates the given context within the context of this service.activateContext
(String contextId, Expression expression) Activates the given context within the context of this service.activateContext
(String contextId, Expression expression, boolean global) Activates the given context within the context of this service.activateContext
(String contextId, Expression expression, int sourcePriorities) Deprecated.void
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.Returns the set of active context identifiers.getContext
(String contextId) Retrieves the context with the given identifier.Returns the collection of the identifiers for all of the defined contexts in the workbench.Context[]
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
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
Removes a listener from this context service.boolean
unregisterShell
(Shell shell) Unregisters a shell that was previously registered.Methods inherited from interface org.eclipse.ui.services.IDisposable
dispose
Methods inherited from interface org.eclipse.ui.services.IServiceWithSources
addSourceProvider, removeSourceProvider
-
Field Details
-
CONTEXT_ID_WORKBENCH_MENU
The identifier for the context that is active when a workbench is active.- Since:
- 3.7
- See Also:
-
CONTEXT_ID_DIALOG
The identifier for the context that is active when a shell registered as a dialog.- See Also:
-
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.- See Also:
-
CONTEXT_ID_WINDOW
The identifier for the context that is active when a shell is registered as a window.- See Also:
-
TYPE_DIALOG
static final int TYPE_DIALOGThe type used for registration indicating that the shell should be treated as a dialog. When the given shell is active, the "In Dialogs" context should also be active.- See Also:
-
TYPE_NONE
static final int TYPE_NONEThe type used for registration indicating that the shell should not receive any key bindings be default. When the given shell is active, we should not provide anyEnabledSubmission
instances for the "In Dialogs" or "In Windows" contexts.- See Also:
-
TYPE_WINDOW
static final int TYPE_WINDOWThe type used for registration indicating that the shell should be treated as a window. When the given shell is active, the "In Windows" context should also be active.- See Also:
-
-
Method Details
-
activateContext
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.- Parameters:
contextId
- The identifier for the context which should be activated; must not benull
.- Returns:
- A token which can be used to later cancel the activation. Only someone with access to this token can cancel the activation. The activation will automatically be cancelled if the context from which this service was retrieved is destroyed.
-
activateContext
Activates the given context within the context of this service. The context becomes active when
expression
evaluates totrue
. This is the same as callingactivateContext(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.- Parameters:
contextId
- The identifier for the context which should be activated; must not benull
.expression
- This expression must evaluate totrue
before this context will really become active. The expression may benull
if the context should always be active.- Returns:
- A token which can be used to later cancel the activation. Only someone with access to this token can cancel the activation. The activation will automatically be cancelled if the context from which this service was retrieved is destroyed.
- Since:
- 3.2
- See Also:
-
activateContext
Activates the given context within the context of this service. The context becomes active when
expression
evaluates totrue
. 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.- Parameters:
contextId
- The identifier for the context which should be activated; must not benull
.expression
- This expression must evaluate totrue
before this context will really become active. The expression may benull
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.- Returns:
- A token which can be used to later cancel the activation. Only someone with access to this token can cancel the activation. The activation will automatically be cancelled if the context from which this service was retrieved is destroyed.
- Since:
- 3.2
- See Also:
-
activateContext
@Deprecated IContextActivation activateContext(String contextId, Expression expression, int sourcePriorities) Deprecated.UseactivateContext(String, Expression)
instead.Activates the given context within the context of this service. The context becomes active when
expression
evaluates totrue
.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.- Parameters:
contextId
- The identifier for the context which should be activated; must not benull
.expression
- This expression must evaluate totrue
before this context will really become active. The expression may benull
if the context should always be active.sourcePriorities
- The source priorities for the expression.- Returns:
- A token which can be used to later cancel the activation. Only someone with access to this token can cancel the activation. The activation will automatically be cancelled if the context from which this service was retrieved is destroyed.
- See Also:
-
addContextManagerListener
Adds a listener to this context service. The listener will be notified when the set of defined contexts changes. This can be used to track the global appearance and disappearance of contexts.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.
- Parameters:
listener
- The listener to attach; must not benull
.- Since:
- 3.2
- See Also:
-
deactivateContext
Deactivates the given context within the context of this service. If the handler was context with a different service, then it must be deactivated from that service instead. It is only possible to retract a context activation with this method. That is, you must have the sameIContextActivation
used to activate the context.- Parameters:
activation
- The token that was returned from a call toactivateContext
; must not benull
.
-
deactivateContexts
Deactivates the given contexts within the context of this service. If the contexts were activated with a different service, then they must be deactivated from that service instead. It is only possible to retract context activations with this method. That is, you must have the sameIContextActivation
instances used to activate the contexts.- Parameters:
activations
- The tokens that were returned from a call toactivateContext
. This collection must only contain instances ofIContextActivation
. The collection must not benull
.
-
getActiveContextIds
Collection getActiveContextIds()Returns the set of active context identifiers.- Returns:
- The set of active context identifiers; this value may be
null
if no active contexts have been set yet. If the set is notnull
, then it contains only instances ofString
. - Since:
- 3.2
-
getContext
Retrieves the context with the given identifier. If no such context exists, then an undefined context with the given id is created.- Parameters:
contextId
- The identifier to find; must not benull
.- Returns:
- A context with the given identifier, either defined or undefined.
-
getDefinedContexts
Context[] getDefinedContexts()Returns the collection of all of the defined contexts in the workbench.- Returns:
- The collection of contexts (
Context
) that are defined; nevernull
, but may be empty. - Since:
- 3.2
-
getDefinedContextIds
Collection getDefinedContextIds()Returns the collection of the identifiers for all of the defined contexts in the workbench.- Returns:
- The collection of context identifiers (
String
) that are defined; nevernull
, but may be empty.
-
getShellType
Returns the shell type for the given shell.- Parameters:
shell
- The shell for which the type should be determined. If this value isnull
, thenIContextService.TYPE_NONE
is returned.- Returns:
IContextService.TYPE_WINDOW
,IContextService.TYPE_DIALOG
, orIContextService.TYPE_NONE
.
-
readRegistry
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.
-
registerShell
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 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.
- Parameters:
shell
- The shell to register for key bindings; must not benull
.type
- The type of shell being registered. This value must be one of the constants given in this interface.- Returns:
true
if the shell had already been registered (i.e., the registration has changed);false
otherwise.
-
removeContextManagerListener
Removes a listener from this context service.- Parameters:
listener
- The listener to be removed; must not benull
.- Since:
- 3.2
-
unregisterShell
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 returnsfalse
and does nothing.- Parameters:
shell
- The shell to be unregistered; does nothing if this value isnull
.- Returns:
true
if the shell had been registered;false
otherwise.
-
deferUpdates
void deferUpdates(boolean defer) Informs the service that a batch operation has started.Note: You must insure that if you call
deferUpdates(true)
that nothing in your batched operation will prevent the matching call todeferUpdates(false)
.- Parameters:
defer
- true when starting a batch operation false when ending the operation- Since:
- 3.5
-
activateContext(String, Expression)
instead.