Capabilities

Identifier: org.eclipse.ui.capabilities

Since: Release 2.0

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 capabilities 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.

Configuration Markup:

   <!ELEMENT extension (category* , capability*)>

   <!ATTLIST extension
     point CDATA #REQUIRED
     id    CDATA #IMPLIED
     name  CDATA #IMPLIED
   >

   <!ELEMENT category EMPTY>

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

   <!ELEMENT capability (handleUI* , perspectiveChoice*)>

   <!ATTLIST capability
     id               CDATA #REQUIRED
     natureId         CDATA #REQUIRED
     category         CDATA #IMPLIED
     icon             CDATA #IMPLIED
     installWizard    CDATA #REQUIRED
     installDetails   CDATA #IMPLIED
     uninstallWizard  CDATA #REQUIRED
     uninstallDetails CDATA #IMPLIED
     description      CDATA #IMPLIED
   >

   <!ELEMENT handleUI EMPTY>

   an optional sub-element that contains a unique identifier of another capability whose UI willl be controlled by this capability.

   <!ATTLIST handleUI
     id CDATA #REQUIRED
   >

   <!ELEMENT perspectiveChoice EMPTY>

   an optional sub-element that contains a unique identifier of a perspective that will be presented to the user to choose from.

   <!ATTLIST perspectiveChoice
     id CDATA #REQUIRED
   >
Examples: Following is an example of capability configuration:

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

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