View All Attachments for Bug 228956

Attachment #100978
Update of the help for activities	text/html	2008-05-19 18:56:44 EDT	23.23 KB	no flags	Details

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">

<html>
<head>
  <meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2008. 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=us-ascii">
  <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" type="text/javascript">
</script>

  <title>Activities</title>
  <link rel="stylesheet" type="text/css" href="../book.css">
</head>

<body bgcolor="#ffffff">
  <h3>Activities</h3>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. The activities give
  the developers also the power to easily implement relative safe authorization
  for specific UI elements.<br>
  So there are two main different targets for activities:

  <ul>
    <li>One to <strong>declutter</strong> the user desktop from unnecessary UI
    elements.<br>The activities used for this&nbsp;will be called <em><strong>conventional activities</strong></em> in this document. 

    <li>One&nbsp;to <strong>provide an authorization mechanism</strong> .<br>
    To prevent the users from using UI elements which are forbidden for their
    rights-level.<br>
    They will be called <strong><em>expression enabled activities</em></strong>
    in this document.</li>
  </ul>

  <h4>Conventional activities</h4>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 a activity is disabled in the platform, its UI contributions
  are not shown <em>(</em>applies to <em>conventional</em> and <em>expression
  enabled activities</em>)<em>.</em> But its UI&nbsp;contributions can still be
  reached through the Eclipse API and through special Eclipse Shortcuts - this
  is&nbsp;the major difference to <em>expression enabled activities</em>. Users
  can enable and disable these <em>conventional activities</em>as needed using
  the <A class=command-link href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.sdk.capabilities)")'  org.eclipse.ui.window.preferences(preferencePageId="org.eclipse.sdk.capabilities)&quot;)'&quot;" preferencepageid='org.eclipse.sdk.capabilities)")&amp;apos;"' org.eclipse.ui.window.preferences="" ><IMG height=32 src="PLUGINS_ROOT/org.eclipse.help/command_link.png" width=28> <b>General &gt;        
  Capabilities</b></a> preference page (and only the <em>conventional</em> ).
  (Activities are referred to as "capabilities" in the user
  interface, even though we use activity terminology in the API). 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.

  <h4>Expression enabled activities</h4><i>Expression enabled activities</i>
  are much like <em>conventional activities</em>, except that they:

  <ul>
    <li>are <b>solely</b> controlled by 
  expressions (see&nbsp;"<SPAN>org.eclipse.core.<SPAN class=resultofText 
  name="resultofMatch"><SPAN><SPAN class=resultofText 
  name="resultofMatch">expressio</SPAN>ns</SPAN></SPAN>.definitions")</SPAN>   
     

    <li>they move an UI contribution completely out of reach for users and
    programmers. It can't even be accessed by direct API calls (let alone
    shortcuts).</li>
  </ul>To explain the part with the solely control in more detail:
  the&nbsp;<em>Expression enabled activity</em> is only controlled by the
  expression of that activity. All other declarations related to such an
  activity will be ignored and are therefore superfluous:
  "categories", "default enabled activities" and
  "requirement bindings".

  <h3>Conventional Activities vs. perspectives</h3>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>. 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.

  <h3>Defining activities</h3>Activities are defined using the <b><A href="../reference/extension-points/org_eclipse_ui_activities.html">org.eclipse.ui.activities</a></b>
  extension point.<br>
  Let's look at first at a simplified version of how the Eclipse SDK
  plug-in defines two&nbsp;<em>conventional activities</em> &nbsp;- one for
  developing Java software and one for developing plug-ins:
  <pre>&lt;extension
  point="org.eclipse.ui.activities"&gt;
  &lt;activity
    name="Java Activity"
    description="Developing Java Software"
    id="org.eclipse.javaDevelopment"&gt;
  &lt;/activity&gt;
  
  &lt;activity
    name="Plug-in Activity"
    description="Developing Eclipse Plug-ins"
    id="org.eclipse.plugInDevelopment"&gt;
  &lt;/activity&gt;
  ...
</pre>Activities, <em>conventional</em> and <em>expression enabled</em>, are
assigned a name and description. This name and description can be shown to the
user whenever the user is enabling and disabling <em>conventional
activities</em>, 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, at <em>conventional activities</em> it is
possible&nbsp;to declare that one activity requires another activity.
  <pre>&lt;activityRequirementBinding
  activityId="org.eclipse.plugInDevelopment"
  requiredActivityId="org.eclipse.javaDevelopment"&gt;
&lt;/activityRequirementBinding&gt;
</pre><br>
  The requirement binding states that the plug-in development activity can only
  be enabled when the Java development activity is enabled. Related
  <em>conventional activities</em> can also be bound into <b>categories</b>,
  that are shown to the user when the user is working with activities.
  <pre>&lt;category
  name="Development"
  description="Software Development"
  id="org.eclipse.categories.developmentCategory"&gt;
&lt;/category&gt;

&lt;categoryActivityBinding
  activityId="org.eclipse.javaDevelopment"
  categoryId="org.eclipse.categories.developmentCategory"&gt;
&lt;/categoryActivityBinding&gt;
      
&lt;categoryActivityBinding
  activityId="org.eclipse.plugInDevelopment"
  categoryId="org.eclipse.categories.developmentCategory"&gt;
&lt;/categoryActivityBinding&gt;
</pre><br>
  The category groups the related development <em>conventional activities</em>
  together. This category is shown to the user when the user manually
  configures <em>conventional activities</em>. As short annotation:
  <em>expression enabled activities</em> can be also added to categories, but
  they are ignored when the user changes&nbsp;states of these categories.

  <h4>Binding activities to UI contributions</h4>Activities can be associated
  with UI contributions using straight string matching or 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:
  <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>&lt;activityPatternBinding
  activityId="org.eclipse.javaDevelopment"
  pattern="org\.eclipse\.jdt\..*/.*"&gt;
&lt;/activityPatternBinding&gt;
</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>&lt;activityPatternBinding
  activityId="org.eclipse.javaDevelopment"
  pattern="org\.eclipse\.jdt\.core/javanature"&gt;
&lt;/activityPatternBinding&gt;
</pre>If you want a more straight forward declaration without the, in this
case, superfluous cumbersomely pattern, you can set the attribute
<tt>isEqualityPattern</tt> to <tt>true</tt>. Which is really recommended at
longer, more complicated names where you can more easily make mistakes with the
regular expression declaration.<br>
  The following xml code block shows the former example with the
  <tt>isEqualityPattern</tt> set to <tt>true</tt>.<br>
  <tt><br>
  &lt;activityPatternBinding<br>&nbsp; activityId="org.eclipse.javaDevelopment"<br>&nbsp; pattern="org.eclipse.jdt.core/javanature"<br>&nbsp; isEqualityPattern="true"&gt;<br>
  &lt;/activityPatternBinding&gt;<br>
  <br></tt>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 with an activity. The following contributions are
  affected by activities:

  <ul>
    <li>Views and editors 

    <li>Perspectives 

    <li>Preference and property pages 

    <li>Menus and toolbars 

    <li>New project wizard</li>
  </ul>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.

  <h4>Binding activities to help contributions</h4>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:
  <pre>&lt;activityPatternBinding
  activityId="org.eclipse.javaDevelopment"
  pattern="org\.eclipse\.jdt\..*/.*"&gt;
&lt;/activityPatternBinding&gt;
</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. 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.
  <pre>&lt;activityPatternBinding
  activityId="org.eclipse.javaDevelopmentExamples"
  pattern="org\.eclipse\.jdt\.doc\.isv\.topics_Samples.xml"&gt;
&lt;/activityPatternBinding&gt;
</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>The workbench activity 
support includes an API for working
  with all defined activities (to some limit also&nbsp; <em>expression enabled
  activities</em> ) and changing the enabled state of <em>conventional
  activities</em>. 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
  <em>conventional activity</em>. 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 <em>conventional
  activities</em> such as Java development. We'll look at how the workbench
  uses the generic activity API to implement triggers. 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.
  <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>(Remember that you can do this also with <em>expression enabled
activities</em> without warnings, but your actions will be completely
ignored.)<br>
  <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.<br>
  <br>

  <h4>Using expression enabled activities</h4>Here is&nbsp;a 
short explanation how to control a view with an <em>expression enabled 
activity</em>.<br><br>
  The expression controlled activity:<br>
     
  <tt>&lt;activity <br>&nbsp;id="forbiddenViewActivityId" name="Forbidden View Activity"&gt;<br>&nbsp;&nbsp;&lt;enabledWhen&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&lt;with variable="rightsVariable"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
  &lt;iterate ifEmpty="false" operator="or"&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; &nbsp; 
  &lt;equals value="showForbiddenRight" /&gt;<br>&nbsp;&nbsp;&nbsp;&nbsp; &nbsp;&lt;/iterate&gt;<br>&nbsp;&nbsp;&nbsp;                     
  &lt;/with&gt;<br>               
  &nbsp;&nbsp;&lt;/enabledWhen&gt;<br>
  &lt;/activity&gt;
  </tt><br><br>
  
  The binding of this activity to a view:<br>
  <tt>&lt;activityPatternBinding <br>&nbsp;activityId="forbiddenViewActivityId" <br><br>&nbsp;<font color="green">&lt;!-- Switches the interpretation of the pattern 
     as regular expression off --&gt;</font> <br>&nbsp;isEqualityPattern="true" <br>&nbsp;pattern="DemoRCP/demorcp.views.ForbiddenView"&gt; <br>
  &lt;/activityPatternBinding&gt;
  </tt>

   <br><br>Now are some code snippets shown, 
how to control the variable "rightsVariable" which controls the expression, 
which itself controls the view.<br> The easiest way 
should be to implement a child class of "AbstractSourceProvider". <br>        
     <br>

   <td nowrap="nowrap" valign="top" align="left">
    <code>
<font color="#7f0055"><b>import&nbsp;</b></font><font color="#000000">java.util.HashMap;<br>...</font><br>
<font color="#7f0055"><b>import&nbsp;</b></font><font color="#000000">org.eclipse.ui.AbstractSourceProvider;</font><br>
<font color="#7f0055"><b>import&nbsp;</b></font><font color="#000000">org.eclipse.ui.PlatformUI;</font><br>
<font color="#7f0055"><b>import&nbsp;</b></font><font color="#000000">org.eclipse.ui.handlers.IHandlerService;</font><br>
<font color="#7f0055"><b>import&nbsp;</b></font><font color="#000000">org.eclipse.ui.services.IEvaluationService;</font><br>
<font color="#ffffff"></font><br>
<font color="#7f0055"><b>public&nbsp;class&nbsp;</b></font><font color="#000000">RightsSourceProvider&nbsp;</font><font color="#7f0055"><b>extends&nbsp;</b></font><font color="#000000">AbstractSourceProvider&nbsp;</font><font color="#000000">{</font><br>
<font color="#ffffff"></font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>public&nbsp;final&nbsp;static&nbsp;</b></font><font color="#000000">String&nbsp;RIGHT_FORBIDDEN&nbsp;=&nbsp;<font color="#2a00ff">"showForbiddenRight"</font><font color="#000000">;</font></font><br>
<font color="#ffffff"></font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>public&nbsp;final&nbsp;static&nbsp;</b></font><font color="#000000">String&nbsp;RIGHTS_VARIABLE&nbsp;=&nbsp;</font><font color="#2a00ff">"rightsVariable"</font><font color="#000000">;</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>private&nbsp;final&nbsp;static&nbsp;</b></font><font color="#000000">String</font><font color="#000000">[]&nbsp;</font><font color="#000000">PROVIDED_SOURCE_NAMES&nbsp;=&nbsp;</font><font color="#7f0055"><b>new&nbsp;</b></font><font color="#000000">String</font><font color="#000000">[]&nbsp;{&nbsp;</font><font color="#000000">RIGHTS_VARIABLE&nbsp;</font><font color="#000000">}</font><font color="#000000">;</font><br>
<font color="#ffffff"></font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>private&nbsp;final&nbsp;static&nbsp;</b></font><font color="#000000">Map&lt;String,&nbsp;List&lt;String&gt;&gt;&nbsp;stateMap&nbsp;=&nbsp;</font><font color="#7f0055"><b>new&nbsp;</b></font><font color="#000000">HashMap&lt;String,&nbsp;List&lt;String&gt;&gt;</font><font color="#000000">()</font><font color="#000000">;</font><br>
<font color="#ffffff"></font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#646464">@SuppressWarnings</font><font color="#000000">(</font><font color="#2a00ff">"unchecked"</font><font color="#000000">)</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#646464">@Override</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>public&nbsp;</b></font><font color="#000000">Map&nbsp;getCurrentState</font><font color="#000000">()&nbsp;{<BR>&nbsp;&nbsp;&nbsp;&nbsp;<FONT 
color=#008000>/*&nbsp;"YourRightsHandler" is here just an example for&nbsp;a 
static class<BR>&nbsp;&nbsp;&nbsp;&nbsp; * which returns the list of 
rights&nbsp;as&nbsp;a list of strings. */</FONT></font><br>
<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#000000">stateMap.put</font><font color="#000000">(</font><font color="#000000">RIGHTS_VARIABLE,&nbsp;<EM>YourRightsHandler</EM>.getUserRights</font><font color="#000000">())</font><font color="#000000">;</font><br>
<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#7f0055"><b>return&nbsp;</b></font><font color="#000000">stateMap;</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#000000">}</font><br><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#646464">@Override</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>public&nbsp;</b></font><font color="#000000">String</font><font color="#000000">[]&nbsp;</font><font color="#000000">getProvidedSourceNames</font><font color="#000000">()&nbsp;{</font><br>
<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#7f0055"><b>return&nbsp;</b></font><font color="#000000">PROVIDED_SOURCE_NAMES;</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#000000">}</font><br><BR>&nbsp;&nbsp;<FONT 
color=#008000>/*&nbsp;This triggers an update of the rights variable state, and 
will update also all&nbsp;<BR>&nbsp;&nbsp; * listeners to the evaluation 
service. So that every menu point, which is also <BR>&nbsp;&nbsp; * expression 
controlled, gets updated too. */</FONT><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#7f0055"><b>public&nbsp;</b></font><font color="#7f0055"><b>void&nbsp;</b></font><font color="#000000">updateRights</font><font color="#000000">()&nbsp;{</font><br>
<font color="#ffffff">&nbsp;&nbsp;&nbsp;&nbsp;</font><font color="#000000">fireSourceChanged</font><font color="#000000">(</font><font color="#990000">0</font><font color="#000000">,&nbsp;getCurrentState</font><font color="#000000">())</font><font color="#000000">;</font><br>
<font color="#ffffff">&nbsp;&nbsp;</font><font color="#000000">}</font><br><BR>&nbsp; // ...<br>
<font color="#000000">}</font></code>    
   </td>
   
</body>
</html>

Attachment #101973
Tiny update of the javadoc documentation of IViewRegistry	patch	2008-05-26 09:11:58 EDT	948 bytes	no flags	Details