[platform-ui-dev] Release Notes: Plugin Actions

[David_Springgay@xxxxxxx]

I have released two changes to plugin action support in the workbench.
The xml grammar for action enablement and visibility has been extended.  In
addition, the IStructuredSelection limitations for plugin action enablement
have been removed.  Now, the workbench can enable actions which work with
non-IStructuredSelection objects.

Action Enablement
----------------------------------

In version 1 of Eclipse the enablement and visibility of window, view,
editor and popup menu action extensions was defined using a limited set of
elements in xml.  The existing tags cannot adequately describe the
conditions when an action should be enabled or visible.  To resolve these
issues, the following approach has been implemented:

- a refreshPluginActions() has been added to AbstractUIPlugin.  The
AbtractUIPlugin.startup method will call this to trigger the creation of
the action delegates for the plugin.
- a new enablement element has been added to the action markup for action
sets, views, editors, and popup menus.  This can be used to define the
enablement criteria for any action, and is a sub element of the action
element.
- a new visibility element has been added to popup menu extension action
markup.  This can be used to define the visibility criteria for the action,
and is a sub element of the object contribution element.

The new xml extends the existing markup, and do not replace it.

The xml format for visibility and enablement criteria is defined in
actionExpressions.html, in the org.eclipse.ui doc directory.  This doc is
referenced from the popup menu, view, editor, and action set documents.

IStructuredSelection Limitations
------------------------------------------------------

In the past, the workbench plugin action enablement code could only handle
IStructuredSelection objects.  If a non-IStructuredSelection object was
selected, the workbench would disable most of the plugin actions (in the
view, editor, or action set) and drop the selection on the floor.  This
limitation has been removed.  Regardless of selection type, the workbench
plugin action enablement code will now forward the selection to the action
delegate (once it has been instantiated).

The action enablement code has also been modified to support non
IStructuredSelections.  According to one dictionary, a selection is "one
that is selected" or "a collection of selected things".  In reflection of
this definition, the workbench will treat an IStructuredSelection as a
collection of selected things, and any other selection type as one thing.

For instance, suppose you add an action to the window (via an action set),
and it should be enabled if some text is selected in an editor.  You can
use the following declaration to enable the action.

        <action id="org.eclipse.ui.tests.internal.as_1"
            label="anyText"
            menubarPath
="org.eclipse.ui.tests.internal.TextSelectionMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate"
          enablesFor="1">
            <selection class="org.eclipse.jface.text.ITextSelection"/>
        </action>

If you want to add an action to the window which is enabled when an IFile
with extension .txt is selected, you can use the following declaration
(shown with the new enablement block).  In this case, the IFile will be
exposed in an IStructuredSelection, but there is no need to mention the
IStructuredSelection in the action declaration.  The workbench treats
IStructuredSelection as a container for the important data inside.

        <action id="org.eclipse.ui.tests.internal.as_2"
            label="anyTextFile"
            menubarPath
="org.eclipse.ui.tests.internal.TextSelectionMenu/group1"
            class="org.eclipse.ui.tests.api.MockActionDelegate">
            <enablement>
               <objectClass name="org.eclipse.core.IFile"/>
               <objectState name="extension" value="txt"/>
            </enablement>
        </action>