| <!doctype html public "-//w3c//dtd html 4.0 transitional//en"> | |
| <html> | |
| <head> | |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> | |
| <meta name="GENERATOR" content="Mozilla/4.75 [en] (Windows NT 5.0; U) [Netscape]"> | |
| <title>Eclipse Workbench Extension Point: Capabilities</title> | |
| </head> | |
| <body link="#0000FF" vlink="#800080"> | |
| <center> | |
| <h1> | |
| Capabilities</h1></center> | |
| <b><i>Identifier: </i></b>org.eclipse.ui.capabilities | |
| <p><b><i>Description: </i></b>This extension point is used to register | |
| project capability extensions. Capabilities are the UI equivalent of CORE's | |
| project natures, and have a one-to-one relationship with project natures. | |
| The workbench allows the user to add and remove capabilities from a project | |
| at any time using the properties dialog or in the new project wizard. | |
| <p>Capabilities represent particular abilities of a project. For example, | |
| a project may have a Java capability that allows the project's *.java | |
| files to be compiled using a Java compiler. If the role of the project | |
| changes over time, the projects capabilities can be modified to suit the | |
| new needs. For example, a project may start as a simple Java capability, | |
| but may later gain a new requirement to use JNI to some legacy library. | |
| The user may then add a C++" capability (if one exists) to the project | |
| to meet this new requirement. | |
| <p>Some capabilities may wish to handle the user interface for other capabilities. | |
| This generally occurs when a capability requires a number of other capabilities | |
| (note that prerequisite information is derived from the org.eclipse.core.resources.natures | |
| extension point). For example, a "Web" capability needs the "Java" capability | |
| to compile servlets, but may want to present a much more simpler page to | |
| configure the "Java" capability or maybe not even present any pages about | |
| the "Java" capability and just add it with appropriate defaults. | |
| <p>The install wizard for a capability is responsible for collecting the | |
| necessary information from the user in order to add its nature and the | |
| natures of any capabilities it handles the UI for. The install wizard must | |
| handle the situation where some or all of the required capabilites are | |
| already installed and configured. | |
| <p>The uninstall wizard for a capability is responsible for collecting | |
| the necessary information from the user in order to remove its nature. | |
| Also must remove any other natures from capabilities that the user wants | |
| removed and the capability handles the UI for. These other capabilities | |
| that the user wants removed will be provided in the init method. | |
| <p>Capabilities can specify which perspectives a user can switch to when | |
| added to the project. This allows the user to discover new perspectives | |
| that can take advantage of the new capabilities. Capabilities that handle | |
| the user interface for other capabilities also control the list of perspectives | |
| for these capabilities. For example, the "Web" capability handles the user | |
| interface for the "Java" capability it requires. The "Web" capability can | |
| choose to include the various Java perspectives, or not. | |
| <p>The categories defined by one plug-in can be referenced by other plug-ins | |
| using the | |
| <tt>category</tt> attribute. | |
| <p>Note the capability name presented to the user comes from the attribute | |
| "name" in the extension element of the org.eclipse.core.resources.natures | |
| extension point. | |
| <p><b><i>Since:</i></b> Release 2.0 | |
| <p><b><i>Configuration Markup:</i></b> | |
| <p><tt> <!ELEMENT category EMPTY></tt> | |
| <br><tt> <!ATTLIST category</tt> | |
| <br><tt> id | |
| CDATA #REQUIRED</tt> | |
| <br><tt> name | |
| CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id -</b> a unique name that can be used to identify this category.</li> | |
| <li> | |
| <b>name</b> - a translatable name of the category to be presented to the | |
| user.</li> | |
| </ul> | |
| <tt> <!ELEMENT capability (handleUI)* (perspectiveChoice)*></tt> | |
| <br><tt> <!ATTLIST capability</tt> | |
| <br><tt> id | |
| CDATA #REQUIRED</tt> | |
| <br><tt> natureId | |
| CDATA #REQUIRED</tt> | |
| <br><tt> category | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> icon | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> installWizard | |
| CDATA #REQUIRED</tt> | |
| <br><tt> installDetails | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> uninstallWizard | |
| CDATA #IMPLIED</tt> | |
| <br><tt> uninstallDetails CDATA | |
| #IMPLIED</tt> | |
| <br><tt> description | |
| CDATA #OPTIONAL</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id</b> - a unique name that can be used to identify this capability.</li> | |
| <li> | |
| <b>natureId</b> - a unique identifier of the nature associated with this | |
| capability (see org.eclipse.core.resources.natures extension point).</li> | |
| <li> | |
| <b>category</b> - an optional attribute which references a previously defined | |
| category ID. If omitted, this capability will be added to the "Other" category.</li> | |
| <li> | |
| <b>icon</b> - an optional attribute which defines a relative path of the | |
| icon that may be used to represent this capability. If omitted, no icon | |
| will be displayed.</li> | |
| <li> | |
| <b>installWizard</b> - a fully qualified name of the Java class implementing | |
| <tt>org.eclipse.ui.ICapabilityInstallWizard</tt> | |
| interface. The wizard is responsible for collecting any necessary information | |
| from the user and adding this capability's nature along with all other | |
| natures from capabilities this capability handles the UI for.</li> | |
| <li> | |
| <b>installDetails</b> - an optional but highly recommended attribute which | |
| decribes to the users what will be required of them by the install wizard | |
| for this capability.</li> | |
| <li> | |
| <b>uninstallWizard</b> - a fully qualified name of the Java class implementing | |
| <tt>org.eclipse.ui.ICapabilityUninstallWizard</tt> | |
| interface. The wizard is responsible for collecting any necessary information | |
| from the user and removing this capability's nature along with any other | |
| natures from capabilities that the user wants removed and this capability | |
| handles the UI for. If omitted, the workbench will provide a wizard that | |
| will remove this capability's nature from the project along with any other | |
| natures from capabilities that the user wants removed and this capability | |
| handles the UI for.</li> | |
| <li> | |
| <b>uninstallDetails</b> - an optional but highly recommended attribute | |
| which decribes to the users what will be required of them by the uninstall | |
| wizard for this capability.</li> | |
| <li> | |
| <b>description</b> - an optional but highly recommended attribute which | |
| consists of a short description of what functionality/ability this capability | |
| adds to a project.</li> | |
| <li> | |
| <b>handleUI</b> - an optional sub-element that contains a unique identifier | |
| of another capability whose UI will be controlled by the this capability.</li> | |
| <li> | |
| <b>perspectiveChoice</b> - an optional sub-element that contains a unique | |
| identifier of a perspective that will be presented to the user to choose | |
| from.</li> | |
| </ul> | |
| <tt> <!ELEMENT handleUI EMPTY></tt> | |
| <br><tt> <!ATTLIST handleUI</tt> | |
| <br><tt> id CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id</b> - the unique identifier of another capability for which its UI | |
| will be handled.</li> | |
| </ul> | |
| <tt> <!ELEMENT perspectiveChoice EMPTY></tt> | |
| <br><tt> <!ATTLIST perspectiveChoice</tt> | |
| <br><tt> id CDATA #REQUIRED</tt> | |
| <br><tt> ></tt> | |
| <ul> | |
| <li> | |
| <b>id</b> - the unique identifier of a perspective the user can switch | |
| to.</li> | |
| </ul> | |
| <b><i>Examples:</i></b> | |
| <p>Following is an example of capability configuration: | |
| <p><tt> <extension point="org.eclipse.ui.capabilities"></tt> | |
| <br><tt> <category</tt> | |
| <br><tt> id="com.xyz.weather"</tt> | |
| <br><tt> name="Weather Elements"></tt> | |
| <br><tt> </category></tt> | |
| <br><tt> <capability</tt> | |
| <br><tt> id="com.xyz.snowCapability"</tt> | |
| <br><tt> natureId="com.xyz.snowNature"</tt> | |
| <br><tt> category="com.xyz.weather"</tt> | |
| <br><tt> icon="./icons/snowCapability.gif"</tt> | |
| <br><tt> installWizard="com.xyz.SnowCapabilityWizard"></tt> | |
| <br><tt> installDetails="You | |
| will be asked to supply a locale id."></tt> | |
| <br><tt> description="Turn | |
| your project into a winter wonderland!"></tt> | |
| <br><tt> <handleUI</tt> | |
| <br><tt> | |
| id="com.xyz.waterCapability"</tt> | |
| <br><tt> </handleUI></tt> | |
| <br><tt> <perspectiveChoice</tt> | |
| <br><tt> | |
| id="com.xyz.skiPerspective"</tt> | |
| <br><tt> </perspectiveChoice></tt> | |
| <br><tt> <perspectiveChoice</tt> | |
| <br><tt> | |
| id="com.xyz.rainPerspective"</tt> | |
| <br><tt> </perspectiveChoice></tt> | |
| <br><tt> </capability></tt> | |
| <br><tt> <capability</tt> | |
| <br><tt> id="com.xyz.waterCapability"</tt> | |
| <br><tt> natureId="com.xyz.waterNature"</tt> | |
| <br><tt> category="com.xyz.weather"</tt> | |
| <br><tt> icon="./icons/waterCapability.gif"</tt> | |
| <br><tt> installWizard="com.xyz.WaterCapabilityWizard"></tt> | |
| <br><tt> installDetails="You | |
| will be asked to supply a locale id."></tt> | |
| <br><tt> description="Turn | |
| your project into a watery wonderland!"></tt> | |
| <br><tt> <perspectiveChoice</tt> | |
| <br><tt> | |
| id="com.xyz.rainPerspective"</tt> | |
| <br><tt> </perspectiveChoice></tt> | |
| <br><tt> <perspectiveChoice</tt> | |
| <br><tt> | |
| id="com.xyz.drinkPerspective"</tt> | |
| <br><tt> </perspectiveChoice></tt> | |
| <br><tt> </capability></tt> | |
| <br><tt> </extension></tt> | |
| <p><b><i>API Information</i>: </b>The value of the <tt>installWizard</tt> | |
| attribute must represent a class that implements <tt>org.eclipse.ui.ICapabilityInstallWizard</tt> | |
| interface. The IProject passed in the init method will exist and can be | |
| queried for the existance of other natures. The capability install wizard | |
| must not close nor delete the project passed in the init method. | |
| <p>The value of the un<tt>installWizard</tt> attribute must represent a | |
| class that implements <tt>org.eclipse.ui.ICapabilityUninstallWizard</tt> | |
| interface. The IProject passed in the init method will exist and can be | |
| queried for the existance of other natures. The capability uninstall wizard | |
| must not close nor delete the project passed in the init method. | |
| <p><b><i>Supplied Implementation: </i></b>The workbench does not provide | |
| any capabilities. | |
| <p><a href="hglegal.htm"><img SRC="ngibmcpy.gif" ALT="Copyright IBM Corp. 2000, 2001. All Rights Reserved." BORDER=0 height=12 width=195></a> | |
| </body> | |
| </html> |