UI reduction utilizes the Eclipse capabilities functionality and is a means to reduce the available interface tooling based on the current workbench selection. Every time a new selection is made in the workbench, UI reduction computes a set of capabilities to enable.
Whether the active selection contains a single or multiple selected objects, the basic computations are the same.
If a single object is selected, then the enabled capabilities will be derived from the active viewpoint and the capabilities annotated on the model. If there are no capabilities annotated on the model, then the workbench capabilities are used.
When multiple objects are selected, the selection may contain objects from different models or non-modeling related objects. In such a case, the intersection of all capabilities from the selected model objects and the workbench capabilities, for those non-modeling related objects, is computed. The enabled capabilities will then be derived from the intersection of the resulting list of capabilities and the active viewpoint.
A viewpoint is a set of capabilities which allow the user to quickly enable / disable various product components. A viewpoint may be pre-defined or user-defined. Pre-defined viewpoints are installed in the Eclipse configuration preference store or contributed through an extension point and are read only. User defined viewpoints are created through the viewpoint preference page and are stored in the instance preference store.
When working within a model with associated capabilities, the viewpoint enabled capabilities will be filtered to the intersection of the model enabled capabilities. For example, this means that if the ATM capability is enabled within the viewpoint but the model capabilities do not include the ATM capability, then this capability will be disabled. Similarly if the model does include the ATM capability, it would be enabled. This filtering occurs whenever the selection within the workbench has changed.
There is a single pre-defined viewpoint which provides unique functionality; the Model viewpoint.
When the Model viewpoint is active, the enabled capabilities will be taken from the model which the user is currently working with. If the user is not working with a model, then the workbench capabilities are used.
The first step is to determine what UI tools (menus, context menus, toolbar actions, palette entries, etc...) will participate in UI reduction. The chosen tools should each be given an ID such that they can be referenced as a group, or individually. This is because the way Eclipse capabilities work is by matching the capability pattern bindings to the tool item ID.
For simplicity, if all tools declared within a given plug-in will participate in UI reduction, then
all the tool item IDs should start with a common string; such as the plug-in namespace
(eg. com.ibm.xtools.examples.myTool1, com.ibm.xtools.examples.myTool2). In doing this
the capability requirement pattern could match a single pattern of "com\.ibm\.xtools\.examples\..*".
The resulting capability definition using the
org.eclipse.ui.activities extension-point would be as follows.
Note that non UI reduction capabilities should never have a requirement binding to a UI reduction capability.
<extension
point="org.eclipse.ui.activities">
<activity
id="com.ibm.xtools.examples.mainUIReductionActivity"
name="Example Capability"/>
<category
id="com.ibm.xtools.examples.category"
name="Example Category"/>
<categoryActivityBinding
activityId="com.ibm.xtools.examples.mainUIReductionActivity"
categoryId="com.ibm.xtools.examples.category"/>
<activityPatternBinding
activityId="com.ibm.xtools.examples.mainUIReductionActivity"
pattern="com\.ibm\.xtools\.examples\..*"/>
</extension>
To register a capability with UI reduction, extend the
com.ibm.xtools.common.ui.editingCapabilities extension-point.
The capabilities are specified by adding activity elements.
Capabilities can be referenced in two different ways. To reference a single
capability by ID, set match to "equals" and set ref
to be the ID of the capability. To reference multiple capabilities using a pattern match against the capability ID,
set match to "pattern" and set ref
to be a regular expression pattern.
<extension
point="com.ibm.xtools.common.ui.reduction.editingCapabilities">
<activity
match="equals"
ref="com.ibm.examples.mainUIReductionActivity">
</activity>
</extension>
Editing capability providers are registered with the framework and are consulted every time a selection event is fired from the workbench. The purpose of the provider is to return the capabilities associated with the selected object.
The default editing capabilities provider makes use of the
EditingCapabilitiesUtil to find capabilities associated with a given model object. The
EditingCapabilitiesUtil can be used to annotate capabilities to any
EObject. The developer may use the
EditingCapabilitiesUtil to programmatically add or remove capabilities from a model
element.
The default editing capabilities provider implementation first checks if the context object is adaptable to
View and if so travels up the view containment hierarchy
to find the first view which has editing capabilities. This traversal will stop
once the diagram element is reached. Afterwards, whether or not editing capabilities were found for a view, the context
object is adapted to the semantic
EObject and once again
travels up its containment hierarchy of the given to find the first
element which has editing capabilities.
The enabled editing capabilities of the view and semantic elements are intersected,
while the required editing capabilities of the view and semantic elements are unioned.
To contribute an editing capabilities providers extend the
com.ibm.xtools.common.ui.reduction.editingCapabilitiesProviders extension-point
and set the editingCapabilitiesProvider class to be a class which implements
com.ibm.xtools.common.ui.reduction.IEditingCapabilitiesProvider. Set the priority
and optionally provide enablement criteria.
<extension
point="com.ibm.xtools.common.ui.reduction.editingCapabilitiesProviders">
<editingCapabilitiesProvider
class="com.ibm.xtools.examples.MyEditingCapabilitiesProvider">
<Priority
name="Medium">
</Priority>
<enablement>
<or>
<instanceof
value="com.ibm.xtools.examples.MyContextObject">
</instanceof>
</or>
</enablement>
</editingCapabilitiesProvider>
</extension>
Optionally the provider may extend
com.ibm.xtools.common.ui.reduction.AbstractEditingCapabilitiesProvider which has a utility
method to get an
EObject from the context object.
To implement the provider, override
provides(IOperation operation)
to only provide for an object of interest and override
getEditingCapabilities(Object context)
to return an
EditingCapabilities instance containing the enabled and required capabilities.
The
EditingCapabilitiesUtil utility can be used to retrieve enabled and required capabilities
from the context object. Optionally the provider may simply provide a static
list of enabled and/or required capabilities.
public class MyEditingCapabilitiesProvider
extends AbstractEditingCapabilitiesProvider {
public EditingCapabilities getEditingCapabilities(Object context) {
EObject eObject = getElement(context);
Set enabled = EditingCapabilitiesUtil.getEnabledActivityIds(eObject);
Set required = EditingCapabilitiesUtil.getRequiredActivityIds(eObject);
return new EditingCapabilities(enabled, required);
}
public boolean provides(IOperation operation) {
if (operation instanceof GetEditingCapabilitiesOperation) {
EObject eObject = getElement(((GetEditingCapabilitiesOperation)operation).getContext());
return eObject != null && UMLPackage.eINSTANCE == eObject.eClass().getEPackage();
}
return false;
}
}
The user can switch between viewpoints using the viewpoint toolbar action. The following screenshot describes the viewpoint toolbar dropdown menu.
The viewpoint toolbar action is not visible by default. The user must change the visibility of the action
by customizing the perspective. If a developer wants to change the default visibility of the action for their
perspectives, then they must contribute a persective extension as follows. The action set ID of the viewpoint
toolbar action is com.ibm.xtools.common.ui.reduction.modelingViewpointsActionSet.
<extension point="org.eclipse.ui.perspectiveExtensions">
<perspectiveExtension
targetID="com.ibm.xtools.examples.myPerspectiveId">
<actionSet id="com.ibm.xtools.common.ui.reduction.modelingViewpointsActionSet"/>
</perspectiveExtension>
</extension>
Using the viewpoints preference page, users can create and edit their own viewpoints. Pre-defined viewpoints can only be contributed through an extension-point or through the preference store configuration scope and cannot be editing using the viewpoint preference page as they are considered to be read only.
To contribute pre-defined viewpoints through the preference store configuration scope,
create the desired viewpoints using the viewpoint preference page and copy the
{$workspace}/.metadata/.plugins/org.eclipse.core.runtime/.settings/com.ibm.xtools.common.ui.reduction.prefs
preference file into the {$eclipse_home}/configuration/.settings/ folder. The framework reads the viewpoint
data from the configuration preference store and constructs pre-defined viewpoints which will be read only.
To contribute pre-defined viewpoints through an extension-point extend the
com.ibm.xtools.common.ui.reduction.editingCapabilities extension-point
and create a viewpoint element with a name and unique id.
To include UI reduction capabilities in the viewpoint add
activity references similar to registering capabilities
with UI reduction.
<extension
point="com.ibm.xtools.common.ui.reduction.editingCapabilities">
<viewpoint
name="My Viewpoint1"
id="com.ibm.xtools.example.viewpoint1">
<activity
match="equals"
ref="com.ibm.examples.mainUIReductionActivity">
</activity>
</viewpoint>
</extension>
It is suggested that viewpoints be categorized when contributing several viewpoints for an single application. This ensures that the viewpoints can be easily accessible by the user when the viewpoints dropdown menu is opened. If a viewpoint is uncategorized, then the viewpoint will show up, ordered alphabetically, underneath the categories.
To contribute a viewpoint category extend the
com.ibm.xtools.common.ui.reduction.editingCapabilities extension-point and create a
viewpointCategory element with a unique id and a label to be displayed in the dropdown menu.
<extension
point="com.ibm.xtools.common.ui.reduction.editingCapabilities">
<viewpointCategory
id="com.ibm.xtools.example.viewpointCategory"
label="My Viewpoint Category">
</viewpointCategory>
</extension>
The next step is to bind a viewpoint to the new category.
To to accomplish this, extend the
com.ibm.xtools.common.ui.reduction.editingCapabilities extension-point and create a
viewpointCategoryBinding element. Set the viewpointRef to be the ID of the viewpoint
to bind, and set the categoryRef to be the ID of the
category for which the viewpoint will be bound to.
<extension
point="com.ibm.xtools.common.ui.reduction.editingCapabilities">
<viewpointCategoryBinding
categoryRef="com.ibm.xtools.example.viewpointCategory"
viewpointRef="com.ibm.xtools.example.viewpoint1">
</viewpointCategoryBinding>
</extension>
