Contribution Item Providers Extension Point

Identifier:
org.eclipse.gmf.runtime.common.ui.services.action.contributionItemProviders

Description:

This extension point is used to register providers that contribute to different workbench part's contribution managers. The contributions described in this extension point could be for a workbench part's action bars (referred to as part contributions) or for a workbench part's popup menu (referred to as popup contributions). This extension point provides an XML description of those contributions to be read by the described providers. The extension point provides an alternative to the following Eclipse extension points:

However, this extension point focuses on distinguishing the contribution criteria from the enablement and visibility of the described contributions. The description of each contribution has the following minimum information:

Configuration Markup:

<!ELEMENT extension (contributionItemProvider+)>

<!ATTLIST extension

point CDATA #REQUIRED

id    CDATA #IMPLIED

name  CDATA #IMPLIED>


<!ELEMENT contributionItemProvider (Priority , (partContribution* , popupContribution*))>

<!ATTLIST contributionItemProvider

class             CDATA #REQUIRED

checkPluginLoaded (true | false) "true">

This element is used to describe a contribution item provider that will contribute actions and toolbar items to a view's popup menus or action bars.



<!ELEMENT Priority EMPTY>

<!ATTLIST Priority

name (Lowest|Low|Medium|High|Highest) >

This element is used to specify the priority that this provider has relative to other contribution item providers that are registered to provide the same kind of contribution to the same menu or toolbar. All providers have the opportunity to make their contributions. The provider with the lowest priority will be chosen as the first contributor, while the provider with the highest priority will be chosen as the last contributor. This means that a provider wishing to add contributions to menus or groups contributed by another provider must have the higher priority so that the menu or group has already been contributed by the time it is asked to make its own contributions.



<!ELEMENT partContribution (partMenu* , partMenuGroup* , partAction* , partCustom* , partActionGroup*)>

<!ATTLIST partContribution

id    CDATA #IMPLIED

class CDATA #IMPLIED>

This element is used to add a group of menus, groups, actions, and/or toolbar items to a workbench part. At least one of the two attributes id or class must be specified for this element.



<!ELEMENT popupContribution ((popupStructuredContributionCriteria | popupTextContributionCriteria | popupMarkContributionCriteria)* , popupMenu* , popupMenuGroup* , popupAction* , popupCustom* , popupActionGroup* , popupPredefinedItem*)>

<!ATTLIST popupContribution

id    CDATA #IMPLIED

class CDATA #IMPLIED>

This element is used to add a group of menus, groups, actions, and/or custom items to a context menu. At least one of the two attributes id or class must be specified for this element.

Criteria for the visibility of this group of contributions can be specified by any number of the same kind of criteria elements from among:



<!ELEMENT partMenu EMPTY>

<!ATTLIST partMenu

id          CDATA #REQUIRED

menubarPath CDATA #IMPLIED

toolbarPath CDATA #IMPLIED>

This element is used to add menu to a workbench part's action bars.



<!ELEMENT partMenuGroup EMPTY>

<!ATTLIST partMenuGroup

id          CDATA #REQUIRED

menubarPath CDATA #IMPLIED

toolbarPath CDATA #IMPLIED

separator   (true | false) "true">

A description for a menu group contribution to be contributed to a workbench part's action bars.



<!ELEMENT partAction EMPTY>

<!ATTLIST partAction

id          CDATA #REQUIRED

menubarPath CDATA #IMPLIED

toolbarPath CDATA #IMPLIED

global      (true | false) "false">

A description for an action contribution to be contributed to a workbench part's action bars.



<!ELEMENT partCustom EMPTY>

<!ATTLIST partCustom

id          CDATA #REQUIRED

menubarPath CDATA #IMPLIED

toolbarPath CDATA #IMPLIED>

A description for a custom contribution to be contributed to a workbench part's action bars.



<!ELEMENT popupMenu EMPTY>

<!ATTLIST popupMenu

id   CDATA #REQUIRED

path CDATA "/additionsGroup">

A description for a menu contribution to be contributed to a workbench part's popup menu.



<!ELEMENT popupMenuGroup EMPTY>

<!ATTLIST popupMenuGroup

id        CDATA #REQUIRED

path      CDATA "/"

separator (true | false) "true">

A description for a menu group contribution to be contributed to a workbench part's popup menu.



<!ELEMENT popupAction EMPTY>

<!ATTLIST popupAction

id   CDATA #REQUIRED

path CDATA "/additionsGroup">

A description for an action contribution to be contributed to a workbench part's popup menu.



<!ELEMENT popupCustom EMPTY>

<!ATTLIST popupCustom

id   CDATA #REQUIRED

path CDATA "/additionsGroup">

A description for a custom contribution to be contributed to a workbench part's popup menu.



<!ELEMENT popupStructuredContributionCriteria (method* , staticMethod*)>

<!ATTLIST popupStructuredContributionCriteria

objectCount CDATA #IMPLIED

objectClass CDATA #IMPLIED

policyClass CDATA #IMPLIED>

A description for a structured selection contribution criteria for a workbench part's popup menu contribution. The criteria can have an optional set of methods to call on the "selected objects"



<!ELEMENT staticMethod (value* , notValue*)>

<!ATTLIST staticMethod

name     CDATA #REQUIRED

value    CDATA #IMPLIED

notValue CDATA #IMPLIED>

A static method to call by reflection on the class. The static method has a name and a value. The value could be described by its string representation (value & notValue), or as an object "value" or "notValue". The rules of evaluation are as follows: 1- The return value string has to be in the "value" string set. 2- The return value string has to be not in the "notValue" string set. 3- The return value object has to be in the "value" object set. 4- The return value object has to be not in the "notValue" object set.



<!ELEMENT popupTextContributionCriteria EMPTY>

<!ATTLIST popupTextContributionCriteria

text        CDATA #IMPLIED

policyClass CDATA #IMPLIED>

A description for a text selection contribution criteria for a workbench part's popup menu contribution.



<!ELEMENT popupMarkContributionCriteria (method*)>

<!ATTLIST popupMarkContributionCriteria

documentClass CDATA #IMPLIED

policyClass   CDATA #IMPLIED>

A description for a mark selection contribution criteria for a workbench part's popup menu contribution.



<!ELEMENT method (value* , notValue*)>

<!ATTLIST method

name     CDATA #REQUIRED

value    CDATA #IMPLIED

notValue CDATA #IMPLIED>

A method to call by reflection on the object. The method has a name and a value. The value could be described by its string representation (value & notValue), or as an object "value" or "notValue". The rules of evaluation are as follows:

  1. The return value string has to be in the "value" string set.
  2. The return value string has to be not in the "notValue" string set.
  3. The return value object has to be in the "value" object set.
  4. The return value object has to be not in the "notValue" object set.



<!ELEMENT value (method*)>

<!ATTLIST value

class CDATA #IMPLIED>

A descriptor of an object that represents a method's returned value. The descriptor can include an optional set of methods to call on the "value" object.



<!ELEMENT notValue (method*)>

<!ATTLIST notValue

class CDATA #IMPLIED>

A descriptor of an object that represents a method's returned value that is not required. The descriptor can include an optional set of methods to call on the "notValue" object.



<!ELEMENT popupActionGroup EMPTY>

<!ATTLIST popupActionGroup

id   CDATA #REQUIRED

path CDATA #IMPLIED>

A description for a action group contribution to be contributed to a workbench part's popup menu.



<!ELEMENT partActionGroup EMPTY>

<!ATTLIST partActionGroup

id CDATA #REQUIRED>

A description for an Action Group contribution to be contributed to a workbench part's action bars.



<!ELEMENT popupPredefinedItem EMPTY>

<!ATTLIST popupPredefinedItem

id     CDATA #REQUIRED

path   CDATA #IMPLIED

remove (true | false) >

Reference to a previously defined contribution to a workbench part's popup menu. The referenced contributed must be defined in a lower priority provider.



Examples:
The following is an example of a provider extension

 <extension
         id="PresentationContributionItemProvider"
         name="%ext.contributionItemProvider"
          point="org.eclipse.gmf.runtime.common.ui.services.action.contributionItemProviders">
      <contributionItemProvider
            class="org.eclipse.test.project.ui.providers.PresentationContributionItemProvider">
         <Priority
               name="Lowest">
         </Priority>
         <partContribution
               class="org.eclipse.gmf.runtime.diagram.ui.parts.IDiagramEditorPart">
            <partMenu
                  menubarPath="/additions"
                  id="diagramMenu">
            </partMenu>
            <partMenuGroup
                  menubarPath="/diagramMenu/"
                  toolbarPath="/"
                  id="viewGroup">
            </partMenuGroup>
            <partMenu
                  menubarPath="/diagramMenu/viewGroup"
                  toolbarPath="/viewGroup"
                  id="selectMenu">
            </partMenu>
            <partMenuGroup
                  menubarPath="/diagramMenu/selectMenu/"
                  toolbarPath="/selectMenu/"
                  id="selectGroup">
            </partMenuGroup>
            <partAction
                  global="true"
                  menubarPath="/diagramMenu/selectMenu/selectGroup"
                  toolbarPath="/selectMenu/selectGroup"
                  id="selectAll">
            </partAction>
            <partAction
                  menubarPath="/diagramMenu/selectMenu/selectGroup"
                  toolbarPath="/selectMenu/selectGroup"
                  id="selectAllShapesAction">
            </partAction>
            <partAction
                  menubarPath="/diagramMenu/selectMenu/selectGroup"
                  toolbarPath="/selectMenu/selectGroup"
                  id="selectAllConnectorsAction">
            </partAction>
            <partCustom
                  menubarPath="/diagramMenu/viewGroup"
                  toolbarPath="/viewGroup"
                  id="zoomContributionItem">
            </partCustom>
         </partContribution>
         <popupContribution
               id="org.eclipse.gmf.runtime.diagram.ui.DiagramEditorContextMenu">
            <popupMenuGroup
                  id="viewGroup">
            </popupMenuGroup>
            <popupMenu
                  path="/viewGroup"
                  id="selectMenu">
            </popupMenu>
            <popupMenuGroup
                  path="/selectMenu/"
                  id="selectGroup">
            </popupMenuGroup>
            <popupAction
                  path="/selectMenu/selectGroup"
                  id="selectAll">
            </popupAction>
            <popupAction
                  path="/selectMenu/selectGroup"
                  id="selectAllShapesAction">
            </popupAction>
            <popupAction
                  path="/selectMenu/selectGroup"
                  id="selectAllConnectorsAction">
            </popupAction>
            <popupCustom
                  path="/viewGroup"
                  id="zoomContributionItem">
            </popupCustom>
         </popupContribution>
         <popupContribution
               class="org.eclipse.gmf.runtime.diagram.ui.internal.parts.DiagramContextMenuProvider">
            <popupStructuredContributionCriteria
                 objectCount="2"                  
                 objectClass="org.eclipse.gmf.runtime.diagram.ui.editparts.IGraphicalEditPart">
            </popupStructuredContributionCriteria>
            <popupAction
                  path="/alignMenu/alignVerticalGroup"
                  id="alignTopAction">
            </popupAction>
            <popupPredefinedItem
                  id="autoSizeAction"
                  path="/formatMenu/"
                  remove="true"/>
            </popupContribution>
      </contributionItemProvider>
   </extension>


Copyright (c) 2003, 2005 IBM Corporation and others.
All rights reserved. This program and the accompanying materials are made available under the terms of the Eclipse Public License v1.0 which accompanies this distribution, and is available at http://www.eclipse.org/legal/epl-v10.html