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 function 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>
Contexts are assigned a name and description that are used when showing information about the context to the user. The id of the context is used when binding UI contributions such as commands to a particular 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>
The parent context defines the more general context of working within a window. Its parent defines an even more general context of working within a window or a dialog. 

<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: 


<keyBinding
    commandId="org.eclipse.ui.edit.cut"
    contextId="org.eclipse.ui.contexts.dialogAndWindow"
    keySequence="M1+X"
    keyConfigurationId="org.eclipse.ui.defaultAcceleratorConfiguration">
</keyBinding>

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 IWorkbenchContextSupport. Plug-ins can obtain the context support instance from the workbench. 

IWorkbenchContextSupport workbenchContextSupport = PlatformUI.getWorkbench().getContextSupport();
The workbench context support API can be used to add or remove an EnabledSubmission, which describes criteria that should cause a particular context to become enabled. Criteria include information such as the active part or active shell. The workbench support also provides access to an IContextManager. 
IContextManager contextManager = workbenchContextSupport.getContextManager();

IContextManager defines protocol for getting all defined or enabled context ids, and for getting the associated IContext 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.ui.contexts for more information.