Capabilities

Description: 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.

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 project's 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.

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.

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.

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.

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.

The categories defined by one plug-in can be referenced by other plug-ins using the category attribute.

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.

Since: Release 2.0

Configuration Markup:

   <!ELEMENT category EMPTY>
   <!ATTLIST category
      id             CDATA #REQUIRED
      name           CDATA #REQUIRED
   >

• id - a unique name that can be used to identify this category.
• name - a translatable name of the category to be presented to the user.

• id - a unique name that can be used to identify this capability.
• natureId - a unique identifier of the nature associated with this capability (see org.eclipse.core.resources.natures extension point).
• category - an optional attribute which references a previously defined category ID. If omitted, this capability will be added to the "Other" category.
• icon - 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.
• installWizard - a fully qualified name of the Java class implementing org.eclipse.ui.ICapabilityInstallWizard 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.
• installDetails - an optional but highly recommended attribute which decribes to the users what will be required of them by the install wizard for this capability.
• uninstallWizard - a fully qualified name of the Java class implementing org.eclipse.ui.ICapabilityUninstallWizard 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.
• uninstallDetails - an optional but highly recommended attribute which decribes to the users what will be required of them by the uninstall wizard for this capability.
• description - an optional but highly recommended attribute which consists of a short description of what functionality/ability this capability adds to a project.
• handleUI - an optional sub-element that contains a unique identifier of another capability whose UI will be controlled by the this capability.
• perspectiveChoice - an optional sub-element that contains a unique identifier of a perspective that will be presented to the user to choose from.

• id - the unique identifier of another capability for which its UI will be handled.

• id - the unique identifier of a perspective the user can switch to.

Following is an example of capability configuration:

   <extension point="org.eclipse.ui.capabilities">
      <category
        id="com.xyz.weather"
        name="Weather Elements">
      </category>
      <capability
          id="com.xyz.snowCapability"
          natureId="com.xyz.snowNature"
          category="com.xyz.weather"
          icon="./icons/snowCapability.gif"
          installWizard="com.xyz.SnowCapabilityWizard">
          installDetails="You will be asked to supply a locale id.">
          description="Turn your project into a winter wonderland!">
          <handleUI
              id="com.xyz.waterCapability"
          </handleUI>
          <perspectiveChoice
              id="com.xyz.skiPerspective"
          </perspectiveChoice>
          <perspectiveChoice
              id="com.xyz.rainPerspective"
          </perspectiveChoice>
      </capability>
      <capability
          id="com.xyz.waterCapability"
          natureId="com.xyz.waterNature"
          category="com.xyz.weather"
          icon="./icons/waterCapability.gif"
          installWizard="com.xyz.WaterCapabilityWizard">
          installDetails="You will be asked to supply a locale id.">
          description="Turn your project into a watery wonderland!">
          <perspectiveChoice
              id="com.xyz.rainPerspective"
          </perspectiveChoice>
          <perspectiveChoice
              id="com.xyz.drinkPerspective"
          </perspectiveChoice>
      </capability>
   </extension>

API Information: The value of the installWizard attribute must represent a class that implements org.eclipse.ui.ICapabilityInstallWizard 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.

The value of the uninstallWizard attribute must represent a class that implements org.eclipse.ui.ICapabilityUninstallWizard 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.

Supplied Implementation: The workbench does not provide any capabilities.