-When a plug-in contributes an action to the workbench UI using one of the menu -extension points, it can specify the conditions under which the menu item is -visible and/or enabled in the menu. In addition to supplying simple enabling -conditions, such as selection counts and selection classes, plug-ins can use boolean -expressions for more flexibility in determining when an action should be visible or enabled.
- - -Boolean expressions can contain the boolean operators (NOT, AND, OR) combined with a predefined syntax -for evaluating certain conditions. Many of these conditions test a particular object. The identity of the -"object in focus" (the object being tested) depends upon the specific context of the enablement expression: -
--When specifying a value to be tested against any of these expressions, the value is assumed to be a string except for when -the following conversions are successful: -
-A complete definition of enablement XML syntax can be found in the extension point reference documentation for any -extension that defines an enablement element, such as - org.eclipse.ui.popupMenus. -
-Prior to R3.0, these generalized boolean expressions were not available. The following predefined expressions were used to -evaluate certain conditions without building a general expression. Note that any of these expressions could now be expressed with -the more generalized syntax. The predefined expressions can still be used as follows:
-objectClass - true if each object in the - selection subclasses or implements the class.
-objectState - true if the named attribute equals the specified value. IActionFilter - assists in evaluating the expression. An action filter dynamically computes the enablement -criteria for an action based on the target selection and the value of named -attributes.
-systemProperty - true if the named system - property equals the specified value.
-pluginState - specifies whether the specified - plug-in (by id) should be installed or activated
-For example, the following snippets represent enablement - expressions that could be used on a hypothetical action in an action set:
-<action id="org.eclipse.examples.actionEnablement.class" - label="Red Element" - menubarPath="additions" - class="org.eclipse.examples.actionEnablement.ObjectTestAction"> - <enablement> - <and> - <objectClass name="org.eclipse.examples.actionEnablement.TestElement"/> - <objectState name="name" value="red"/> - </and> - </enablement> -</action>-
<action id="org.eclipse.examples.actionEnablement.property" - label="Property" - menubarPath="additions" - class="org.eclipse.examples.actionEnablement.PropertyTestAction"> - <enablement> - <systemProperty name="MyTestProperty" value="puppy"/> - </enablement> -</action>-
<action id="org.eclipse.examples.actionEnablement.pluginState" - label="Installed" - menubarPath="additions" - class="org.eclipse.examples.actionEnablement.PluginTestAction"> - <enablement> - <pluginState id="x.y.z.anotherPlugin" value="installed"/> - </enablement> -</action>-
See the reference documentation of the extension points -for more elaborate samples of these expressions and a complete description of -the XML.
- - --The following table lists extension points that contribute actions and -summarizes how XML markup attributes and boolean expressions can be used to -affect enablement.
- - -|
- -Extension point name - |
-
- -Attributes affecting enablement - |
-
- -Boolean expressions - |
-
|---|---|---|
|
- - - -viewActions, - - - |
-
- -enablesFor - specifies the selection count that must be met for the -action to be enabled --selection class - the class that the selected objects must -subclass or implement in order for the action to be enabled --selection name - a wild card filter that can be applied to the -objects in the selection. - |
-
- -visibility - a boolean expression. Controls whether the menu item -is visible in the menu. --enablement - a boolean expression. Controls whether the menu item -is enabled in the menu. The enablesFor attribute and the selection class -and name, and must be -satisfied before applying the enablement expression. - |
-
|
- - - -popupMenus - |
-
- -(For object contributions only.) --objectClass - specifies the class that objects in the selection must -subclass or implement --(For both object and viewer contributions) --enablesFor - specifies the selection count that must be met for the -action to be enabled --selection class - the class that the selected objects must -subclass or implement to enable the action --selection name - a wild card filter that can be applied to the -objects in the selection. -- - |
-
- -(For both object and viewer contributions) --visibility - a boolean expression. Controls whether the menu item -is visible in the menu. -enablement - a boolean expression. Controls -whether the menu item is enabled in the menu. -The enablesFor attribute and the selection class and name, and must be -satisfied before applying the enablement expression. - |
-
The ability to define content types (see Content types) can be combined -with boolean expressions to define very specific enablement or visibility conditions based on -the content type of a resource. For example, the following snippet makes a popup menu item visible only if the -selected file's content matches the plug-in's specialized content types. -
--<extension point="org.eclipse.ui.popupMenus"> - <objectContribution - id="com.example.objectContributions" - objectClass="org.eclipse.core.resources.IFile" - nameFilter="*.xml"> - <visibility> - <or> - <objectState - name="contentTypeId" - value="com.example.employeeRecordContentType"/> - <objectState - name="contentTypeId" - value="com.example.customerRecordContentType"/> - </or> - </visibility> - <action id="com.example.action1" - ... --The contentTypeId attribute can be used in an objectState expression to check the content type of -the selected xml file. This allows a plug-in to apply very specific content checking before enabling or showing -menu actions related to specific types of files. See Content types for more detail -about the content type extension. - - - - - Index: guide/workbench_basicext.htm =================================================================== RCS file: guide/workbench_basicext.htm diff -N guide/workbench_basicext.htm --- guide/workbench_basicext.htm 24 Mar 2009 13:59:54 -0000 1.27 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,55 +0,0 @@ - - - - - - - - - -
-The workbench defines extension points that allow plug-ins to contribute -behaviors to existing views and editors or to provide implementations for -new views and editors. Using commands is covered in the Basic workbench extension points using commands section. Here we are - going to take a look at the -contributions to these extension points from one of the workbench sample applications, the readme tool.
--The readme tool is a plug-in that provides custom editing and navigation for a specific resource -, a - .readme file. The example shows many typical (but simplified) ways that extensions can be used to provide specialized tools.
--The readme tool contributes to the menus of the navigator view, adds editor related actions to the workbench menus and -tool bar, defines a custom view and content outliner, and defines markers -and marker resolutions. The figure below shows some of the -customized features added to the workbench by the readme tool.
-
-
-The readme tool also contributes preference and properties pages to the workbench. Later we'll also look -at some wizard contributions in - Dialogs and wizards.
--The readme tool is located in the org.eclipse.ui.examples.readmetool package. The - readmetool.jar and plugin.xml can be found in the - org.eclipse.ui.examples.readmetool directory underneath the - plugins directory. To follow along, you will need to make sure that -you have installed the platform examples. (See the Examples -Guide for more information.)
--The readme -tool implements many different workbench extensions. We will start -with one of the simplest workbench extension points, a view. We'll -continue by looking at additional readme tool extensions.
- - - Index: guide/workbench_basicext_actionSetPartAssociations.htm =================================================================== RCS file: guide/workbench_basicext_actionSetPartAssociations.htm diff -N guide/workbench_basicext_actionSetPartAssociations.htm --- guide/workbench_basicext_actionSetPartAssociations.htm 2 Jun 2011 15:20:56 -0000 1.18.6.1 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,72 +0,0 @@ - - - - - - - - - - --Once your plug-in defines an action -set, it can use the - org.eclipse.ui.actionSetPartAssociations -extension point to specify that an action set should be made visible when a -particular view or editor is active.
- -
- Ultimately, the user controls the
-appearance of action sets using
-
-
-
-Window > Customize Perspectives...
-
-in
-the workbench menu. If the user marks an action set visible, it will always be visible when the
-perspective is active, regardless of
-the active view or editor. Likewise, if the user marks the action set as hidden, it will always be hidden when the perspective is active. If the user does not change the state of
-an action set in this dialog, then the action set part associations are used to
-determine the visibility of the action set.
-The markup for an action set part association is straightforward. The -following example comes from the Java development tools (JDT) UI plug-in.
-- <extension point="org.eclipse.ui.actionSetPartAssociations"> - <actionSetPartAssociation - targetID="org.eclipse.jdt.ui.CodingActionSet"> - <part id="org.eclipse.jdt.ui.PackageExplorer"/> - <part id="org.eclipse.jdt.ui.TypeHierarchy" /> - <part id="org.eclipse.jdt.ui.CompilationUnitEditor"/> - <part id="org.eclipse.jdt.ui.ClassFileEditor"/> - <part id="org.eclipse.jdt.ui.ProjectsView"/> - <part id="org.eclipse.jdt.ui.PackagesView"/> - <part id="org.eclipse.jdt.ui.TypesView"/> - <part id="org.eclipse.jdt.ui.MembersView"/> - </actionSetPartAssociation> -</extension> --
The targetID specifies the action set. (The CodingActionSet was -previously defined in the JDT plug-in manifest.) One or more part -attributes can be specified to indicate which views and editors will cause the -action set to become visible in the menus and toolbar. The effect of this extension -contribution is that the actions associated with writing Java code will only be -visible when one of the specified views is active.
- - - - - - - Index: guide/workbench_basicext_actionSets.htm =================================================================== RCS file: guide/workbench_basicext_actionSets.htm diff -N guide/workbench_basicext_actionSets.htm --- guide/workbench_basicext_actionSets.htm 2 Jun 2011 15:20:56 -0000 1.32.6.1 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,158 +0,0 @@ - - - - - - - - - - --Your plug-in can contribute menus, menu items, and tool bar items to the workbench menus and toolbar -by using the - org.eclipse.ui.actionSets -extension point. In order to reduce the clutter that would be caused by having every plug-in's menu contributions shown at once, the contributions are grouped into action sets which can be made visible by user preference.
-
-You can see which action sets have been contributed to your workbench by choosing
-
-
-
-Window > Customize Perspective...
-
-from the workbench menu. This option will show you a dialog that lists
-action sets as groups of commands. A checkmark by a command group means that the menu and tool bar actions are visible in the workbench.
-You can select the name of the command group to see the list of available menu and toolbar actions to the right. The figure below shows the
-list of command groups available in our workbench. (Your workbench may look different depending on which plug-ins you have
-installed and which perspective is active.)
-
-
--The readme tool uses an action set to contribute several different "Open Readme -Browser" actions to the workbench menu. (We contributed a similar -action to the popup menu of the resource navigator.) The markup follows:
--<extension point = "org.eclipse.ui.actionSets"> - <actionSet id="org_eclipse_ui_examples_readmetool_actionSet" - label="%ActionSet.name" - visible="true"> - <menu id="org_eclipse_ui_examples_readmetool" - label="%ActionSet.menu" - path="window/additions"> - <separator name="slot1"/> - <separator name="slot2"/> - <separator name="slot3"/> - </menu> - <action id="org.eclipse.ui.examples.readmetool.readmeAction" - menubarPath="window/org_eclipse_ui_examples_readmetool/slot1" - toolbarPath="readme" - label="%ReadmeAction.label" - tooltip="%ReadmeAction.tooltip" - helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context" - icon="icons/ctool16/openbrwsr.png" - class="org.eclipse.ui.examples.readmetool.WindowActionDelegate" - definitionId="org.eclipse.ui.examples.readmetool.readmeAction" - enablesFor="1"> - <selection class="org.eclipse.core.resources.IFile" - name="*.readme"> - </selection> - </action> - ... - </actionSet> - </extension>-
-Wow, there's a lot going on here! Let's take it a step at a time, looking -only at the first action for now.
--First, the action set is declared and given a label. -The label "ReadMe Actions" (defined for %ActionSet.name key in the plug-in's -properties file) is used to display the action set in the -dialog shown above. Since we set visible to true, the workbench will initially have the action set -checked in the action set list and the actions will be visible.
--The rest of the action set declaration is concerned with defining the menu in -which the actions appears and the actions themselves.
--We define a menu whose label appears in the workbench menus. The menu's path -tells the workbench to place the new menu in the additions -slot of the window menu. (For a discussion -of menu paths and slots, see Menu and toolbar paths.) -We also define some slots in our new menu so that actions can be inserted at specific locations in our menu.
--This markup alone is enough to cause the menu to appear in the workbench Window -menu.
-
-
-Next, we define the actions themselves.
--The action definition (id, -label, icon, class) is -similar to the other actions we've seen in views, editors, and popups. -We'll focus here on what's different: where does the action go? We -use menubarPath and toolbarPath -to indicate its location. First, we define the menubarPath to add the -action to a slot in the menu -that we just defined ( "window/org_eclipse_ui_examples_readmetool/slot1").
-
-
-Then, we define a new toolbarPath to insert our actions in the workbench tool -bar. Since we've defined a new tool path, "readme", the workbench will decide where it goes -relative to other plug-in's toolbar contributions.
-
-
-What happens when the action is selected by the user? The action is -implemented by the class specified in the class -attribute. The action class must implement - IWorkbenchWindowActionDelegate, -or - IWorkbenchWindowPulldownDelegate -if the action will be shown as a pull-down tool item in the tool bar. Since we are not -creating a pull-down tool item, we provide WindowActionDelegate. -This class is similar to ObjectActionDelegate. -It launches the readme sections dialog when the user chooses the action. (We'll -discuss the sections dialog in Application -dialogs.)
- - --The action also supplies enabling conditions for its menu item and tool bar -item. The menu and tool bar items will only be enabled when a single (enablesFor="1") -readme file (selectionClass ="org.eclipse.core.resources.IFile" -name="*.readme") is selected. This action's menu and toolbar -item appear and are enabled by virtue of the markup -in the plugin.xml file. None of the -plug-in code will execute until the user chooses the action and the workbench -runs the action class.
- -The definitionId allows the action to be linked to a command created by the -org.eclipse.ui.commands -extension, which can be used for keybindings. All actions in an actionSets -should be linked to a command, either existing commands provided by the workbench or -commands created by the contributing plugin. -See Associating actions to commands -and org.eclipse.ui.commands for -defining commands.
- --We'll look at the other two actions later in the context of retargetable -actions.
- - - - - - - Index: guide/workbench_basicext_editorActions.htm =================================================================== RCS file: guide/workbench_basicext_editorActions.htm diff -N guide/workbench_basicext_editorActions.htm --- guide/workbench_basicext_editorActions.htm 24 Mar 2009 13:59:43 -0000 1.27 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,77 +0,0 @@ - - - - - - - - - --We've just seen how editors -can contribute their own actions to the workbench menus and tool bar when they -become active. The org.eclipse.ui.editorActions extension -point allows a plug-in to add -to the workbench menus and tool bar when another plug-in's editor becomes active.
--In the readme example, the plug-in uses the editorActions -extension point to contribute additional actions to the menu contributed by the -readme editor. The definition in our - plugin.xml should look pretty familiar by now.
--<extension - point = "org.eclipse.ui.editorActions"> - <editorContribution - id="org.eclipse.ui.examples.readmetool.ec1" - targetID="org.eclipse.ui.examples.readmetool.ReadmeEditor"> - <action id="org.eclipse.ui.examples.readmetool.ea1" - label="%Editors.Action.label" - toolbarPath="ReadmeEditor" - icon="icons/obj16/editor.png" - tooltip="%Editors.Action.tooltip" - class="org.eclipse.ui.examples.readmetool.EditorActionDelegate" - definitionId="org.eclipse.ui.examples.readmetool.ea1" - /> - </editorContribution> - </extension>-
Similar to a view action, the extension must specify the targetID of the -editor to which it is contributing actions. The action itself is very -similar to a view action (id, label, icon, toolbarPath, -...), except that the specified class -must implement IEditorActionDelegate -and a definitionId can be specified to link this action to a Command specified -by the org.eclipse.ui.commands -extension, which is important for keybinding. -See Associating actions to commands -and org.eclipse.ui.commands for -defining commands.
-Note that a menu bar path is not specified in this markup. Therefore, -the action will appear in the workbench tool bar when the editor is active, -but not in the workbench menu bar. (See Menu and toolbar paths for a discussion of toolbar and menu paths.)
-Sure enough, when the editor is active, we see our editor action on the tool -bar next to the actions that were contributed by the editor itself.
-
-The readme tool supplies EditorActionDelegate -to implement the action. This class is very similar to the view action delegate -we saw earlier.
- -
-public void run(IAction action) {
- MessageDialog.openInformation(editor.getSite().getShell(),
- MessageUtil.getString("Readme_Editor"),
- MessageUtil.getString("Editor_Action_executed"));
-}
-
-
-
-
-
Index: guide/workbench_basicext_editors.htm
===================================================================
RCS file: /cvsroot/eclipse/org.eclipse.platform.doc.isv/guide/workbench_basicext_editors.htm,v
retrieving revision 1.30
diff -u -r1.30 workbench_basicext_editors.htm
--- guide/workbench_basicext_editors.htm 24 Mar 2009 13:59:55 -0000 1.30
+++ guide/workbench_basicext_editors.htm 9 Jun 2011 12:43:45 -0000
@@ -1,7 +1,7 @@
-
+
@@ -28,7 +28,8 @@
editor on the same file from a different workbench window or perspective).
Unlike views, however, the same editor type, such as a text editor, may be open
many times
-within one workbench page for different inputs.
+within one workbench page for different inputs. The editor input can also be a path
+to an in memory model, as in the InfoEditor example.
The workbench extension point org.eclipse.ui.editors is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor @@ -36,8 +37,9 @@ for the editor. Some of the editor information, such as the implementation class and the name and the icon to be used in the workbench menus and -labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands. Editors can also define a - contributorClass, which is a class that adds actions to workbench menus and tool bars when the editor is active.
+labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands. +Editors also use org.eclipse.ui.commands and org.eclipse.ui.menus +to contribute to the workbench menus and toolbars when that editor is active.The interface for editors is defined in IEditorPart, but plug-ins can choose to extend the @@ -50,110 +52,56 @@ are implemented using IEditorPart.
-The readme tool provides a custom editor primarily for the purpose of contributing its own content outliner page to the +The editor can contribute its own content outliner page to the workbench outline view.
The configuration for the editor extension is defined as follows.
<extension
point = "org.eclipse.ui.editors">
- <editor
- id = "org.eclipse.ui.examples.readmetool.ReadmeEditor"
- name="%Editors.ReadmeEditor"
- icon="icons/obj16/editor.png"
- class="org.eclipse.ui.examples.readmetool.ReadmeEditor"
- extensions="readme"
- contributorClass="org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor">
- </editor>
+ <editor
+ class="org.eclipse.ui.examples.contributions.editor.InfoEditor"
+ icon="icons/editor.gif"
+ id="org.eclipse.ui.examples.contributions.editor"
+ name="%contributions.editor.name">
+ </editor>
</extension>
We see the familiar configuration markup for id, name, -icon, and class. The extensions attribute -describes the file types that the editor understands. (You could also +icon (which must be specified when specifying class), +and class. You could use the extensions attribute +describes the file types that the editor understands, like extensions="person", +although this example doesn't need it. +(You could also specify filenames if you need to be more specific.) The class -implements the editor, and the contributorClass is responsible for -providing editor-related actions. The contributor is not normally used to -contribute commands or handlers to the workbench menu or toolbar, that's done -via org.eclipse.ui.menus. -Let's look at the contributor that's used for actions in more -detail.
+implements the editor. --The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the - IEditorActionBarContributor interface. The contributor is -separate from the editor itself since any given workbench page can have multiple editors of the same type. -A single contributor is shared by all the editors of a specific type, rather than -having each instance of an editor create actions and images.
--In ReadmeEditorActionBarContributor, we contribute three actions, -"Editor Action1," "Editor Action2," and "Editor Action3." -These are set up in the constructor.
-
- public ReadmeEditorActionBarContributor() {
- ...
- action1 = new EditorAction(MessageUtil.getString("Editor_Action1"));
- action1.setToolTipText(MessageUtil.getString("Readme_Editor_Action1"));
- action1.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_DISABLE);
- action1.setImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_ENABLE);
- ...
- action2 = new RetargetAction(IReadmeConstants.RETARGET2, MessageUtil.getString("Editor_Action2"));
- action2.setToolTipText(MessageUtil.getString("Readme_Editor_Action2"));
- action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
- action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
- ...
- action3 = new LabelRetargetAction(IReadmeConstants.LABELRETARGET3, MessageUtil.getString("Editor_Action3"));
- action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
- action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
- ...
- }
-
--The names and icons for the actions are set up in the code rather than in the plugin.xml. -(We'll ignore the differences in the action classes for now until we look at retargetable -actions.)
-Note how similar the action information is to the - viewActions information we saw in the markup -for the view action. The actions are set up in code since we have to -manage the sharing of the actions among different instances of the same editor. -When the actions are created in the constructor, they are independent of any -particular instance of the editor.
- When an editor becomes active and it has actions that need to be installed in the workbench menus and tool bar, the setActiveEditor -message is sent to the contributor. The contributor connects the editor actions to a specific editor.
+Editor menus and editor toolbars are placed in the main menu and main toolbar. See +org.eclipse.ui.menus for how to use the +locationURI to place the commands correctly. +
++These menu and tool bar items can be shown only when the editor is active using core expressions. +To define a re-usable core expression for your editor, use +org.eclipse.core.expressions.definitions
- public void setActiveEditor(IEditorPart editor) {
- ...
- action1.setActiveEditor(editor);
- ...
- }
-
--As you can see, the actions show up in the workbench menu and tool bar when a readme editor is active.
- -
-
-
-
-
-These menu and tool bar items are only shown when the editor is active. The location for the menu and tool bar items can be specified as described in -Menu and toolbar paths.
- - +<extension + point = "org.eclipse.core.expressions.definitions"> + <definition id="org.eclipse.ui.examples.contributions.view.activeEditor"> + <with variable="activeEditorId"> + <equals value="org.eclipse.ui.examples.contributions.editor"/> + </with> + </definition> +</extension>-The readme editor itself, ReadmeEditor, is not very complicated. It extends the - TextEditor class so that it can contribute a customized content outliner page -to the outline view when a readme file is being edited. It does not change any behavior inside the text editor.
-
-Editors often have corresponding content outliners that provide a structured +Although the Info Editor does not, editors often have corresponding content outliners +that provide a structured view of the editor's contents and assist the user in navigating through the contents of the editor. See Content outliners for more detail.
@@ -164,8 +112,5 @@ editors and platform text. - - - Index: guide/workbench_basicext_popupMenus.htm =================================================================== RCS file: guide/workbench_basicext_popupMenus.htm diff -N guide/workbench_basicext_popupMenus.htm --- guide/workbench_basicext_popupMenus.htm 14 Apr 2010 19:11:30 -0000 1.28 +++ /dev/null 1 Jan 1970 00:00:00 -0000 @@ -1,138 +0,0 @@ - - - - - - - - - --The org.eclipse.ui.popupMenus extension -point allows a plug-in to contribute to the popup menus of other -views and editors.
--You can contribute an action to a specific popup menu by its id (viewerContribution), or -by associating it with a particular object type (objectContribution).
--You can add commands to context menus for a similar result, see the -Contributing to popup menus section in -org.eclipse.ui.menus. -
--The readme tool defines both. Let's look at the object contribution -first.
--<extension point = "org.eclipse.ui.popupMenus"> - <objectContribution - id="org.eclipse.ui.examples.readmetool" - objectClass="org.eclipse.core.resources.IFile" - nameFilter="*.readme"> - <action id="org.eclipse.ui.examples.readmetool.action1" - label="%PopupMenus.action" - icon="icons/ctool16/openbrwsr.png" - menubarPath="additions" - helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context" - class="org.eclipse.ui.examples.readmetool.PopupMenuActionDelegate" - definitionId="org.eclipse.ui.examples.readmetool.action1" - enablesFor="1"> - </action> - </objectContribution> - ... -
-The action "Show Readme Action" is contributed for the object class IFile. This means that any view containing -IFile -objects will show the contribution if IFile -objects are selected. We see that the selection criteria is restricted further with a name filter -(nameFilter="*.readme") and for single selections (enablesFor="1"). As we've discussed before, the registration of this menu does not run any code from our plug-in until the menu item is actually selected.
--When the menu item is selected, the workbench will run the specified class. -Since the popup is declared as an objectContribution, -the supplied class must implement IObjectActionDelegate.
--The action is implemented in PopupMenuActionDelegate.
-
- public void run(IAction action) {
- MessageDialog.openInformation(
- this.part.getSite().getShell(),
- "Readme Example",
- "Popup Menu Action executed");
- }
-
--We can see the popup menu contribution when we select a readme file from the resource navigator.
- -
--A viewer contribution is used to contribute to a specific view or editor's popup menu -by using its id. -Here is the readme tool's viewer contribution:
-... - <viewerContribution - id="org.eclipse.ui.examples.readmetool2" - targetID="org.eclipse.ui.examples.readmetool.outline"> - <action id="org.eclipse.ui.examples.readmetool.action1" - label="%PopupMenus.action" - icon="icons/ctool16/openbrwsr.png" - menubarPath="additions" - helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context" - definitionId="org.eclipse.ui.examples.readmetool.action1" - class="org.eclipse.ui.examples.readmetool.ViewActionDelegate"> - </action> - </viewerContribution> -</extension>-
-Note: The name viewerContribution is somewhat misleading, as it does not relate to JFace viewers. A better name would -be popupMenuContribution.-
-When the extension is a viewerContribution, the -supplied class must implement the - IEditorActionDelegate or - IViewActionDelegate interface, depending on whether the -action is contributed to an editor's or view's popup menu.
- - -
-The targetID specifies the popup menu that will be altered. If not specified
-in the call to getSite().registerContextMenu(*) the popup menu's ID will default to the view or editor ID. In this
-case, we are adding an action to one of the readme tool views, the
-outliner. The action itself is similar to others that we've seen. We specify the id,
-definitionId, label, and icon of the action, and
-the path within the popup for our contribution. The action will be
-shown only in the readme outline view's popup menu.
-
-It is common for plug-ins to contribute behavior to views that already exist in the workbench. This is done through the - org.eclipse.ui.viewActions -extension point. This extension point allows plug-ins to contribute menu items, submenus and tool bar entries to an -existing view's local -pull-down menu and local tool bar.
--Contributing menu items to views is also done using the -org.eclipse.ui.menus -extension point. This allows command targeted at a view to be contributed to -an existing view's local pull-down menu and local tool bar, as in the Contribution location section -covering the Info View of org.eclipse.ui.menus. -
--You may have noticed an item in the project explorer's local tool bar that becomes -enabled whenever a readme file is selected. This item also appears in the -project explorer's local -pull-down menu. These actions appear because the readme tool plug-in contributes -them using the - viewActions extension.
- -
--The relevant plugin.xml contribution is below.
--<extension - point = "org.eclipse.ui.viewActions"> - <viewContribution - id="org.eclipse.ui.examples.readmetool.vc1" - targetID="org.eclipse.ui.navigator.ProjectExplorer"> - <action id="org.eclipse.ui.examples.readmetool.va1" - label="%PopupMenu.ResourceNav.label" - menubarPath="additions" - toolbarPath="additions" - icon="icons/obj16/editor.png" - tooltip="%PopupMenu.ResourceNav.tooltip" - helpContextId="org.eclipse.ui.examples.readmetool.view_action_context" - class="org.eclipse.ui.examples.readmetool.ViewActionDelegate" - enablesFor="1"> - <selection class="org.eclipse.core.resources.IFile" name="*.readme"/> - </action> - </viewContribution> - </extension> --
-A view contribution with a unique id is specified. The view to which we are adding -the action is specified in the - targetID. We are contributing to the Project -Explorer's menu. We specify the label and the menu bar and -tool bar locations for the new action. (For a complete discussion of menu and toolbar locations, see - Menu and toolbar paths).
--We also specify the conditions under which the action should be enabled. You can see that this action will be enabled when there is one selection -(enablesFor="1") of type -IFile -(class="org.eclipse.core.resources.IFile"), whose name has -".readme" in the file extension (name="*.readme"). Sure enough, that's exactly what happens when you click around in the Project Explorer.
--The information in the plugin.xml is all that's needed to add items to menus and tool -bars since plug-in code will only run when the action is actually selected from the menu or toolbar. -To provide the action behavior, the implementation class specified in the - plugin.xml must implement the IViewActionDelegate interface.
--In this example, the readme plug-in supplies ViewActionDelegate to implement the action. If you browse this class you will see that it includes methods for -remembering its view, handling selection changes, and invoking its action. -When invoked the action itself simply launches a dialog that announces it was executed.
-
-public void run(org.eclipse.jface.action.IAction action) {
- MessageDialog.openInformation(view.getSite().getShell(),
- MessageUtil.getString("Readme_Editor"),
- MessageUtil.getString("View_Action_executed"));
-}
--Although this action is simple, we can imagine how using selections and more -functional dialogs could make this action do something more interesting.
- - - - - - - Index: guide/workbench_basicext_views.htm =================================================================== RCS file: /cvsroot/eclipse/org.eclipse.platform.doc.isv/guide/workbench_basicext_views.htm,v retrieving revision 1.27.6.1 diff -u -r1.27.6.1 workbench_basicext_views.htm --- guide/workbench_basicext_views.htm 2 Jun 2011 15:20:57 -0000 1.27.6.1 +++ guide/workbench_basicext_views.htm 9 Jun 2011 12:43:45 -0000 @@ -27,7 +27,7 @@The extension point org.eclipse.ui.views allows plug-ins to add views to the workbench. Plug-ins that contribute a view must register the view in their - plugin.xml file and provide configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.
+ plugin.xml file and provide configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.The interface for views is defined in IViewPart, but plug-ins can choose to extend the @@ -39,27 +39,25 @@ let's take a look at the declaration of the extension in the plugin.xml.
<extension
point="org.eclipse.ui.views">
- <category
- id="org.eclipse.ui.examples.readmetool"
- name="%Views.category">
- </category>
- <view
- id="org.eclipse.ui.examples.readmetool.views.SectionsView"
- name="%Views.ReadmeSections"
- icon="icons/view16/sections.png"
- category="org.eclipse.ui.examples.readmetool"
- class="org.eclipse.ui.examples.readmetool.ReadmeSectionsView">
- </view>
+ <category
+ id="org.eclipse.ui.examples.contributions.viewCategory"
+ name="%contributions.viewCategory.name">
+ </category>
+ <view
+ category="org.eclipse.ui.examples.contributions.viewCategory"
+ class="org.eclipse.ui.examples.contributions.view.InfoView"
+ id="org.eclipse.ui.examples.contributions.view"
+ name="%contributions.view.name">
+ </view>
</extension>
-This should look pretty familiar. We see that a new view, ReadmeSectionsView, is contributed to the workbench. The +This should look pretty familiar. We see that a new view, InfoView, is contributed to the workbench. The view id, name, and - category are specified as we've seen before. An icon is also provided -for the view, using a path relative to the plug-in's installation directory.
+ category are specified as we've seen before.-Let's look at the ReadmeSectionsView. You can show any view in the +Let's look at the InfoView. You can show any view in the workbench by choosing @@ -68,14 +66,10 @@ and selecting the view from the Show View list.
-When we show the ReadmeSectionsView, a view with a list in it pops up. -The list is empty unless we click on a file with an extension of .readme, in which case -the list is populated with sections from the readme file.
+When we show the InfoView, a view with a list in it pops up. +The list is pre-populated with some data. -
--How does the plug-in recognize the readme file and how did it know about selection changes? If we can track down -the answers to these questions, we are well on our way to understanding how to build integrated workbench plug-ins.
+
We'll start with the familiar createPartControl method. As we saw in the Hello World example, this is where the widgets @@ -84,74 +78,37 @@
public void createPartControl(Composite parent) {
viewer = new ListViewer(parent);
+ viewer.setContentProvider(new ContentProvider());
+ viewer.setLabelProvider(new LabelProvider());
+ viewer.addDoubleClickListener(new IDoubleClickListener() {
+ public void doubleClick(DoubleClickEvent event) {
+ editSelection();
+ }
+ });
+ // A service will be providing our input
+ IPersonService service = (IPersonService) getSite().getService(
+ IPersonService.class);
+ viewerInput = new ArrayList(service.getPeople());
+ viewer.setInput(viewerInput);
...
- // add myself as a global selection listener
- getSite().getPage().addSelectionListener(this);
-
- // prime the selection
- selectionChanged(null, getSite().getPage().getSelection());
+ // register myself as a selection provider for this view
+ getSite().setSelectionProvider(viewer);
}
-The view creates and stores a ListViewer and registers itself as a selection listener -on its page. It obtains the page from an +The view creates and stores a ListViewer and sets the content and label provides. +It also registers itself as the selection +provider for this view. +(The concept of selection provider, label provider, and content provider come + from JFace viewers.) +It obtains the service from its IViewSite, which contains information about the view's context, such as its workbench window, -its containing page, its local services, and its plug-in. When we are notified of a selection change, what happens? -The following code is executed:
-
- public void selectionChanged(IWorkbenchPart part, ISelection sel) {
- //if the selection is a readme file, get its sections.
- AdaptableList input = ReadmeModelFactory.getInstance().getSections(sel);
- viewer.setInput(input);
- }
-
--It looks like the ReadmeModelFactory class is responsible for turning the selection into readme -sections and these sections are input for -the viewer that we created in the createPartControl -method.
--But how did the viewer populate its list widgets? For now, let's assume that once the viewer was told its input element, it knew how to populate -its list widget with the information - it is a ListViewer, after all. If you must know right now what this viewer is all about, go to Viewers.
--We still do not know how readme files are detected or where the file's section -information comes from. A quick look at the - ReadmeModelFactory sheds some light.
-
- public AdaptableList getSections(ISelection sel) {
- // If sel is not a structured selection just return.
- if (!(sel instanceof IStructuredSelection))
- return null;
- IStructuredSelection structured = (IStructuredSelection)sel;
-
- //if the selection is a readme file, get its sections.
- Object object = structured.getFirstElement();
- if (object instanceof IFile) {
- IFile file = (IFile) object;
- String extension = file.getFileExtension();
- if (extension != null && extension.equals(IReadmeConstants.EXTENSION)) {
- return getSections(file);
- }
- }
-
- //the selected object is not a readme file
- return null;
- }
-
-We check the selection to see if it is a structured (multiple) -selection. (The concept of a structured selection comes from JFace viewers.) -For the first object in the selection, we check to see whether it is a file (IFile) -resource. If it is, we check its extension to see if it matches the ".readme" -extension. Once we know we have a readme file, we can use other methods to -parse the sections. You can browse the rest of ReadmeModelFactory, -MarkElement, and DefaultSectionsParser for the -details about the file parsing.
+its containing page, its local services, and its plug-in. ++
We've covered a lot of common workbench concepts by studying this extension. Now we'll move on to some other workbench extensions and examine how your plug-in can further contribute to the workbench UI.
- - -