| <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><HTML> |
| <HEAD> |
| |
| <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2005. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." > |
| |
| <META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1"> |
| <META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css"> |
| |
| <LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css"> |
| <script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js"></script> |
| <TITLE>Activities</TITLE> |
| |
| <link rel="stylesheet" type="text/css" HREF="../book.css"> |
| </HEAD> |
| <BODY BGCOLOR="#ffffff"> |
| |
| <h3> |
| Activities</h3> |
| <P > |
| An <b>activity</b> is a logical grouping of function that is centered around a certain kind of task. For |
| example, developing Java software is an activity commonly performed by users of the platform, and the JDT |
| defines many UI contributions (views, editors, perspectives, preferences, etc.) that are only useful when performing |
| this activity. Before we look at the mechanics for defining an activity, let's look at how they are used to help |
| "declutter" the UI. |
| </P> |
| <p> |
| The concept of an activity is exposed to the user, although perhaps not apparent to a new user. When an activity |
| is enabled in the platform, the UI contributions associated with that activity are shown. When an activity is disabled |
| in the platform, its UI contributions are not shown. Users can enable and disable activities as needed using the |
| |
| <a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.sdk.capabilities)")'> |
| <img src="PLUGINS_ROOT/org.eclipse.help/command_link.png"> |
| <b>General > Capabilities</b></a> |
| |
| preference page. (Activities are referred to as "capabilities" in the user interface, |
| even though we use activity terminology in the API). |
| </p> |
| <p>Certain user |
| operations serve as <b>trigger points</b> for enabling an activity. For example, creating a new Java project could |
| trigger the enabling of the Java development activity. In this way, users are exposed to new function as they need it, and |
| gradually learn about the activities that are available to them and how they affect the UI. When a user first starts the |
| platform, it is desirable for as many activities as possible to be disabled, so that the application is as simple as |
| possible. Choices made in the welcome page can help determine what activities should be enabled. |
| </p> |
| <h3>Activities vs. perspectives</h3> |
| <p> |
| We've seen (in <a href="workbench_perspectives.htm">Perspectives</a>) how perspectives are used to organize different |
| view layouts and action sets into tasks. Why do we need activities? While perspectives and activities define similar |
| kinds of tasks, the main difference is how the UI contributions for a plug-in are associated with them. UI |
| contributions are associated with perspectives in the extension definition of the contribution. That is, a plug-in is |
| in charge of determining what perspectives its views and action sets belong to. Plug-ins are also free to define their |
| own perspectives. Even when a perspective is not active, the user can access the views and actions associated with the |
| perspective through commands such as <b>Show View</b>. |
| </p> |
| <p>Activities are a higher level of organization. Individual UI contributions are not aware of activities and |
| do not refer to the activities in their extension definitions. Rather, the activities are expected to be configured |
| at a higher level such as platform integration/configuration or product install. Individual plug-ins typically do not define new activities, |
| unless the plug-in is a systems-level plug-in defined by a systems integrator. In a typical scenario, a systems |
| integrator determines how function is grouped into activities and which ones are enabled by default. Activities are |
| associated with UI contributions using <b>activity pattern bindings</b>, patterns that are matched |
| against the id of the UI contributions made by plug-ins. An example will help demonstrate these concepts. |
| </p> |
| <h4>Defining an activity</h4> |
| <p> |
| Activities are defined using the |
| <b><a href="../reference/extension-points/org_eclipse_ui_activities.html">org.eclipse.ui.activities</a></b> |
| extension point. Let's look at a simplified version of how the Eclipse SDK plug-in defines two activities - |
| one for developing Java software and one for developing plug-ins:</p> |
| <pre><extension |
| point="org.eclipse.ui.activities"> |
| <activity |
| name="Java Activity" |
| description="Developing Java Software" |
| id="org.eclipse.javaDevelopment"> |
| </activity> |
| |
| <activity |
| name="Plug-in Activity" |
| description="Developing Eclipse Plug-ins" |
| id="org.eclipse.plugInDevelopment"> |
| </activity> |
| ... |
| </pre> |
| <p>Activities are assigned a name and description that can be shown to the user whenever the user is enabling and disabling |
| activities, or otherwise shown information about an activity. The id of the activity is used when defining |
| pattern bindings or other relationships between activities. For example, we can decide that one activity requires |
| another activity.</p> |
| <pre><activityRequirementBinding |
| activityId="org.eclipse.plugInDevelopment" |
| requiredActivityId="org.eclipse.javaDevelopment"> |
| </activityRequirementBinding> |
| </pre> |
| <p>The requirement binding states that the plug-in development activity can only be enabled when the Java development |
| activity is enabled. Related activities can also be bound into <b>categories</b>, that are shown to the user when |
| the user is working with activities.</p> |
| <pre><category |
| name="Development" |
| description="Software Development" |
| id="org.eclipse.categories.developmentCategory"> |
| </category> |
| |
| <categoryActivityBinding |
| activityId="org.eclipse.javaDevelopment" |
| categoryId="org.eclipse.categories.developmentCategory"> |
| </categoryActivityBinding> |
| |
| <categoryActivityBinding |
| activityId="org.eclipse.plugInDevelopment" |
| categoryId="org.eclipse.categories.developmentCategory"> |
| </categoryActivityBinding> |
| </pre> |
| <p>The category groups the related development activities together. This category is shown to the user when the user |
| manually configures activities.</p> |
| <h4>Binding activities to UI contributions</h4> |
| <p> |
| Activities are associated with UI contributions using pattern matching. The pattern matching used in |
| activity pattern bindings follows the rules described in the <b>java.util.regex</b> package for regular expressions. |
| The patterns used by the workbench are composed of two parts. The first part uses the identifier of the plug-in |
| that is contributing the UI extension. The second part is the id used by plug-in itself when defining |
| the contribution (which may or may not also include the plug-in id as part of the identifier). |
| The following format is used: |
| </p> |
| <pre> |
| plug-in-identifier + "/" + local-identifier |
| </pre> |
| For example, the following activity pattern binding states that a UI contribution from any |
| JDT plug-in id (<tt>org.eclipse.jdt.*</tt>) is associated with the Java development activity regardless |
| of its local identifier (<tt>.*</tt>). |
| <pre> |
| <activityPatternBinding |
| activityId="org.eclipse.javaDevelopment" |
| pattern="org\.eclipse\.jdt\..*/.*"> |
| </activityPatternBinding> |
| </pre> |
| The next binding is more specific. It states that the contribution named <tt>javanature</tt> defined in the |
| JDT core (<tt>org.eclipse.jdt.core</tt>) is associated with the Java development activity. |
| <pre> |
| <activityPatternBinding |
| activityId="org.eclipse.javaDevelopment" |
| pattern="org\.eclipse\.jdt\.core/javanature"> |
| </activityPatternBinding> |
| </pre> |
| As you can see, activity pattern bindings can be used to associate large groups of contributions with a particular activity, |
| or to associate very specific contributions to an activity. The following contributions are affected by activities: |
| <ul> |
| <li>Views and editors</li> |
| <li>Perspectives</li> |
| <li>Preference and property pages</li> |
| <li>Menus and toolbars</li> |
| <li>New project wizard</li> |
| </ul> |
| |
| <p>The convention used by the workbench (plug-in id + local id) allows easy binding to plug-ins that do not |
| necessarily follow the naming practice of prefixing their UI contribution identifiers with their plug-in's identifier. |
| Plug-ins that directly interact with the activity API are free to use their own format for identifying |
| contributions and for pattern-matching against those names. |
| </p> |
| <h4>Binding activities to help contributions</h4> |
| <p> |
| Activities are associated with help contributions using the same pattern matching scheme used |
| for UI contributions. The second part of the identifier (the local identifier) |
| indicates the name of the table of contents (TOC) file. |
| For example, the following activity pattern binding associates all TOC files |
| contributed by JDT plug-ins (org.eclipse.jdt.*) with the Java development activity: |
| </p> |
| <pre> |
| <activityPatternBinding |
| activityId="org.eclipse.javaDevelopment" |
| pattern="org\.eclipse\.jdt\..*/.*"> |
| </activityPatternBinding> |
| </pre> |
| When the Java development activity is disabled, help books contributed by JDT plug-ins, |
| or any sub-books (TOCs linked to, or linked by JDT books), even if contributed |
| by a different plug-in, will not show in the help UI. The topics defined in these books |
| will also not show in the search results. In the case where JDT TOCs were not displayed |
| as primary TOCs, but were instead linked from another TOC to appear as sub-trees in a book, |
| disabling the JDT activity has the effect of hiding the sub-trees. The containing book will |
| appear to define less topics in the UI. |
| |
| <p> |
| Using more specific binding, it is possible to associate activities with selected TOCs from plug-ins |
| that contribute multiple TOCs to the help system. For example, the following |
| activity pattern binding associates the "Examples" TOC with the Java development examples activity. |
| </p> |
| <pre> |
| <activityPatternBinding |
| activityId="org.eclipse.javaDevelopmentExamples" |
| pattern="org\.eclipse\.jdt\.doc\.isv\.topics_Samples.xml"> |
| </activityPatternBinding> |
| </pre> |
| With such pattern binding, disabling the Java development examples activity will |
| hide the "Examples" section from the "JDT Plug-in Developer Guide" book. |
| |
| <h4>Using the activities API</h4> |
| <p> |
| The workbench activity support includes an API for working with the defined activities and changing their |
| enabled state. Most plug-ins need not be concerned with this API, but it is useful when implementing function that |
| allows the user to work with activities, or for implementing the trigger points that enable a particular activity. |
| It is assumed that any plug-in that is manipulating activities through API is quite aware of the ways that activities |
| are configured for a particular product. For example, the workbench itself uses the API to trigger the enablement of |
| activities such as Java development. We'll look at how the workbench uses the generic activity API to implement |
| triggers. |
| </p> |
| <p> |
| The hub of all activity in the workbench is <a href="../reference/api/org/eclipse/ui/activities/IWorkbenchActivitySupport.html"><b>IWorkbenchActivitySupport</b></a>. |
| The activity support works in tandem with an |
| <a href="../reference/api/org/eclipse/ui/activities/IActivityManager.html"><b>IActivityManager</b></a>. |
| Plug-ins can obtain the activity support instance from the workbench, and the activity manager from there. |
| </p> |
| <pre> |
| IWorkbenchActivitySupport workbenchActivitySupport = PlatformUI.getWorkbench().getActivitySupport(); |
| IActivityManager activityManager = workbenchActivitySupport.getActivityManager(); |
| </pre> |
| The following snippet enables the Java development activity (if it is not already enabled). It shows a |
| simplified version of a trigger. |
| <pre> |
| ... |
| //the user did something Java related. Enable the Java activity. |
| Set enabledActivityIds = new HashSet(activityManager.getEnabledActivityIds()); |
| if (enabledIds.add("org.eclipse.javaDevelopment")) |
| workbenchActivitySupport.setEnabledActivityIds(enabledActivityIds); |
| </pre> |
| <p> |
| <a href="../reference/api/org/eclipse/ui/activities/IActivityManager.html"><b>IActivityManager</b></a> also defines |
| protocol for getting all defined activity and category ids, and for getting the associated |
| <a href="../reference/api/org/eclipse/ui/activities/IActivity.html"><b>IActivity</b></a> or |
| <a href="../reference/api/org/eclipse/ui/activities/IActivity.html"><b>ICategory</b></a> for a particular id. |
| These objects can be used to traverse the definition for an activity or category in API, such as getting the |
| pattern bindings or requirement bindings. Listeners can be registered on the activity manager or on the activities |
| and categories themselves to detect changes in the definition of a particular activity or in the activity manager |
| itself. See the package <b><a href="../reference/api/org/eclipse/ui/activities/package-summary.html">org.eclipse.ui.activities</a></b> |
| for more information. |
| </p> |
| |
| |
| </BODY> |
| </HTML> |
