Contexts

A context can be used to influence what commands are available to the user at any given moment. Contexts are much more dynamic than activities. While an activity represents a broad set of functionality that is available to the user most of the time, contexts describe a focus of the user at a specific point in time. For example, the commands available to a user while editing text might be different than those available to a user while editing Java text or browsing packages in the package explorer.

Defining a context

Contexts are declared in the org.eclipse.ui.contexts extension point. Consider the following context which is defined for editing text:

<extension
	point="org.eclipse.ui.contexts">
	<context
		name="%context.editingText.name"
		description="%context.editingText.description"
		id="org.eclipse.ui.textEditorScope"
		parentId="org.eclipse.ui.contexts.window">
	</context>

Context hierarchies

Contexts are hierarchical in nature. When a context is active, the commands available in the context and in its parent contexts are also available. This is useful for defining levels of contexts that move from very general situations down to more specific contexts. In the context definition above, note that there is an id of a parent assigned to the context:

	<context
		name="%context.editingText.name"
		description="%context.editingText.description"
		id="org.eclipse.ui.textEditorScope"
		parentId="org.eclipse.ui.contexts.window">
	</context>

<context
	name="%context.window.name"
	description="%context.window.description"
	id="org.eclipse.ui.contexts.window"
	parentId="org.eclipse.ui.contexts.dialogAndWindow">
</context>
<context
	name="%context.dialogAndWindow.name"
	description="%context.dialogAndWindow.description"
	id="org.eclipse.ui.contexts.dialogAndWindow">
</context>

Associating a contribution with a context

So far, all we've done is define a hierarchy of contexts. The context becomes useful when it is referenced in the description of another UI contribution. The most common use of contexts is in key bindings. When a context is associated with a key binding, the key binding will only be active when the user is in that context. For example, the following markup specifies the root dialog and window context as the context for a key binding:

<extension
         point="org.eclipse.ui.bindings">
      <key
            sequence="M1+X"
            contextId="org.eclipse.ui.contexts.dialogAndWindow"
            commandId="org.eclipse.ui.edit.cut"
            schemeId="org.eclipse.ui.defaultAcceleratorConfiguration"/>
</extension>

Using Context API

The workbench context support includes an API for working with the defined contexts and defining criteria under which a particular context should become enabled. Most plug-ins need not be concerned with this API, but it is useful when defining specialized views or editors that define new contexts.

The starting point for working with contexts in the workbench is IContextService. Plug-ins can obtain the global context support instance from the workbench.

IContextService contextService = (IContextService)PlatformUI.getWorkbench()
	.getService(IContextService.class);

Services like IContextService, IHandlerService, and IBindingService can be retrieved using an IServiceLocator. IWorkbench, IWorkbenchWindow, and IWorkbenchSite are all IServiceLocator.

IContextService defines protocol for getting all defined or enabled context ids, and for getting the associated Context for a particular id. These objects can be used to traverse the definition for a context in API, such as getting the id, name, or id of the parent context. Listeners can be registered on the context manager or on the contexts themselves to detect changes in the definition of a particular context or in the context manager itself. See the package org.eclipse.core.commands.contexts for more information.

Contexts can be enabled programmatically:

IContextActivation activation = contextService.activateContext("org.eclipse.ui.textEditorScope");

The IContextActivation is a token that can be used to deactivate an active context. You should ensure that you only activate defined Contexts.

If you are activating a more specific Context within your part (either View or Editor) you can use the part site service locator to active your Context. The part's IContextService will take care of activating and deactivating the Context as your part is activated or deactivated. It will also dispose the Context when the part is disposed.