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:
- org.eclipse.ui.editorActions
- org.eclipse.ui.viewActions
- org.eclipse.ui.popupMenus (viewerContribution)
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:
- Information to create the contribution (e.g., id)
- Information to perform the contribution (e.g., path within manager)
- Information to consider the contribution (e.g., target id, class)
Configuration Markup:
<!ELEMENT extension (
contributionItemProvider+)>
<!ATTLIST extension
point CDATA #REQUIRED
id CDATA #IMPLIED
name CDATA #IMPLIED
>
-
point - a fully qualified identifier of the target extension point, in this case, org.eclipse.gmf.runtime.common.ui.services.action.contributionItemsProviders
-
id - an optional identifier of the extension instance
-
name - an optional human readable name of the extension instance
<!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.
-
class - the name of a fully qualified class that extends the the org.eclipse.gmf.runtime.common.ui.services.action.contributionitem.AbstractContributionItemProvider and org.eclipse.gmf.runtime.common.core.service.IProvider interfaces
-
checkPluginLoaded - indicates whether or not the service should only consider contributions from this provider if the declaring plugin is already loaded (either true or false). Default value is true.
<!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.
-
name - the name of the provider priority, one of Lowest, Low, Medium, High, or Highest
<!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.
-
id - an optional unique identifier of a registered workbench part that is the target of this contribution
-
class - an optional name of a fully qualified class or interface. Contributions will be made to all workbench parts that subclass or implement this type.
<!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:
- popupStructuredContributionCriteria
- popupTextContributionCriteria
- popupMarkContributionCriteria
-
id - an optional unique identifier of a registered context menu that is the target of this contribution
For a given part, there could be one or more context menus. This id is used to specify the one the contributions are for.
-
class - an optional name of a fully qualified class or interface. Contributions will be made to all context menus that subclass or implement this type.
<!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.
-
id - The id of the part menu group contribution. The id is unique within a provider.
-
menubarPath - The contribution path of this menu group within the part's menubar. The path is a '/' delimited string in the following format:
/<submenu_id/>*
It has to start with a '/' indicating the root of the contribution manager. Following that there could be submenu_id path that is also '/' delimited. There should be a '/' at the end of the path. The menu group is inserted to the end of the last submenu in the path. If the field was omitted, the contribution will not take place to the menubar.
-
toolbarPath - The contribution path of this menu group within the part's toolbar. The path is a '/' delimited string in the following format:
/<submenu_id/>*
It has to start with a '/' indicating the root of the contribution manager. Following that there could be submenu_id path that is also '/' delimited. There should be a '/' at the end of the path. The menu group is inserted to the end of the last submenu in the path. If the field was omitted, the contribution will not take place to the toolbar.
-
separator - A flag indicating whether the menu group is a separator (default) or a group marker .
<!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.
-
id - The id of the popup menu group contribution. The id is unique within a provider.
-
path - The contribution path of this menu group within the popup menu. The path is a '/' delimited string in the following format:
/<submenu_id/>*
It has to start with a '/' indicating the root of the contribution manager. Following that there could be submenu_id path that is also '/' delimited. There should be a '/' at the end of the path. The menu group is inserted to the end of the last submenu in the path. If the field was omitted, the contribution will not take place to the popup menu.
-
separator - A flag indicating whether the menu group is a separator (true) (default) or a group marker (false).
<!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"
-
objectCount - The number of objects in the selection that this contribution applies to.
-
objectClass - The fully qualified name of a class/interface who is assignable or adaptable from the classes of objects in the selection. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is:
className<(plugin id)>?
-
policyClass - The fully qualified name of a contribution policy class (that usually resides in a different plugin/fragment that is assumed to be loaded) to be used to determine wether this contributon should be considered or not. The class has to implement the
IPopupMenuContributionPolicy
interface.
<!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.
-
name - The name of the Static Method, the format should be PluginID\ClassName.method followed by an optional paramter set between paranthesis "()". The parameter set can contain any number of primitive parameters or %Context(pluginID/className) to use the context object as a parameter . other param types are not supported. The method name could contain nested calling separated by "." The general format for this method name is : *>?).<*>?)>*
-
value - A comma-separated (",") list of string representations of the method return value. The string representation of the value is expected to be "one" of those in the list. The syntax to use is the following:
<,>*
If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
-
notValue - A comma-separated (",") list of string representations of the method return value that is not expected (the execulsion set). The string representation of the value is expected "not" to be "one" of those in the list. The syntax to use is the following:
<,>*
If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
<!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.
-
text - The text in the selection. This is an optional field
-
policyClass - The fully qualified name of a contribution policy class (that usually resides in a different plugin/fragment that is assumed to be loaded) to be used to determine wether this contributon should be considered or not. The class has to implement the
IPopupMenuContributionPolicy
interface.
<!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.
-
documentClass - The fully qualified name of a class/interface who is assignable or adaptable from the document of the mark selection. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is:
className<(plugin id)>?
-
policyClass - The fully qualified name of a contribution policy class (that usually resides in a different plugin/fragment that is assumed to be loaded) to be used to determine wether this contributon should be considered or not. The class has to implement the
IPopupMenuContributionPolicy
interface.
<!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:
- The return value string has to be in the "value" string set.
- The return value string has to be not in the "notValue" string set.
- The return value object has to be in the "value" object set.
- The return value object has to be not in the "notValue" object set.
-
name - The name of the method followed by an optional paramter set between paranthesis "()". The parameter set can contain any number of string parameters (literals). other param types are not supported. The method name could contain nested calling separated by "." The general format for this method name is : *>?).<*>?)>*
-
value - A comma-separated (",") list of string representations of the method return value. The string representation of the value is expected to be "one" of those in the list. The syntax to use is the following:
<string>[,<string>]*
If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
-
notValue - A comma-separated (",") list of string representations of the method return value that is not expected (the execulsion set). The string representation of the value is expected "not" to be "one" of those in the list. The syntax to use is the following:
<string>[,<string>]*
If (",") is expected to be in one of the strings, it has to be escaped by a forward slash ("\"). "null" is accepted as a string and it means (a null object).
<!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.
-
class - The fully qualified name of a class/interface that is assignable from or adaptable to the "value" object. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is:
className<(plugin id)>?
<!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.
-
class - The fully qualified name of a class/interface that is assignable from or adaptable to the "value" object. The name could be followed (between paranthesis "()") by the id of a plugin whose classloader is able to load that class. The finaly syntax is:
className<(plugin id)>?
<!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.
-
id - The id of the part action group contribution. The id is unique within a provider.
<!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.
-
id - The id of the previously defined popup action contribution. The id combined with the path is unique within the popup menu.
-
path - The contribution path of this previously defined item within the popup. The path is a '/' delimited string in the following format:
/<submenu_id/>*
It has to start with a '/' indicating the root of the contribution manager. Following that there could be multiple submenu_id paths that are also '/' delimited.
-
remove - If true, an existing contribution item will be removed.
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
https://www.eclipse.org/legal/epl-v10.html