Attachment #197860 for bug #348821

Lines 55-61 Link Here

(-)guide/debug_launch_uishortcuts.htm (-1 / +1 lines)
55	</shortcut>	55	</shortcut>
56	...	56	...
57	</pre>	57	</pre>
58	<p>See <a href="workbench_actionfilters.htm">Boolean expressions and action filters</a> for an explanation of the XML syntax for	58	<p>See <a href="workbench_cmd_expressions.htm">Workbench Command Expressions</a> for an explanation of the XML syntax for
59	enabling conditions. The complete syntax is described in the documentation for	59	enabling conditions. The complete syntax is described in the documentation for
60	<a href="../reference/extension-points/org_eclipse_debug_ui_launchShortcuts.html"><b>org.eclipse.debug.ui.launchShortcuts</b></a>.</p>	60	<a href="../reference/extension-points/org_eclipse_debug_ui_launchShortcuts.html"><b>org.eclipse.debug.ui.launchShortcuts</b></a>.</p>
61		61

Lines 52-58 Link Here

(-)guide/editors_actions.htm (-1 / +1 lines)
52	fTogglePresentation= new PresentationAction();	52	fTogglePresentation= new PresentationAction();
53	}</pre>	53	}</pre>
54	<p>The first two actions are defined as retargetable text editor actions. The	54	<p>The first two actions are defined as retargetable text editor actions. The
55	principle is similar to the <a href="wrkAdv_retarget.htm">retargetable actions</a>	55	principle is similar to the retargetable actions
56	provided by the workbench. Retargetable text editor actions represent menu entries	56	provided by the workbench. Retargetable text editor actions represent menu entries
57	which the action contributor dynamically binds to corresponding actions provided	57	which the action contributor dynamically binds to corresponding actions provided
58	by the active editor. When the active editor changes, the action to which a	58	by the active editor. When the active editor changes, the action to which a

Lines 20-26 Link Here

(-)guide/firstplugin_btb.htm (-1 / +1 lines)
20	Hopefully you've gotten a flavor of how you can contribute code in the form of an extension, and package	20	Hopefully you've gotten a flavor of how you can contribute code in the form of an extension, and package
21	that functionality into a plug-in. From here, you can start diving into more detail:</P>	21	that functionality into a plug-in. From here, you can start diving into more detail:</P>
22	<ul>	22	<ul>
23	<li><a href="workbench_basicext.htm">Basic workbench extension points</a></li>	23	<li><a href="workbench_cmd.htm">Basic workbench extension points</a></li>
24	<li><a href="workbench_menus.htm">Workbench menu contributions</a></li>	24	<li><a href="workbench_menus.htm">Workbench menu contributions</a></li>
25	<li><a href="wrkAdv.htm">Advanced workbench concepts</a></li>	25	<li><a href="wrkAdv.htm">Advanced workbench concepts</a></li>
26	<li><a href="dialogs_wizards_extensions.htm">Workbench wizard extension points</a></li>	26	<li><a href="dialogs_wizards_extensions.htm">Workbench wizard extension points</a></li>

Lines 28-34 Link Here

(-)guide/jface.htm (-1 / +1 lines)
28	Viewers</a></b> handle the drudgery of populating, sorting, filtering, and updating widgets.</li>	28	Viewers</a></b> handle the drudgery of populating, sorting, filtering, and updating widgets.</li>
29	<li>	29	<li>
30	<b><a href="jface_actions.htm">	30	<b><a href="jface_actions.htm">
31	Actions and contributions</a></b> introduce semantics for defining user actions and specifying where to make them available.</li>	31	Actions and contributions (Deprecated)</a></b> introduce semantics for defining user actions and specifying where to make them available.</li>
32	<li>	32	<li>
33	<b><a href="jface_resources.htm">	33	<b><a href="jface_resources.htm">
34	Image and font registries</a></b> provide common patterns for handling UI resources.</li>	34	Image and font registries</a></b> provide common patterns for handling UI resources.</li>

Lines 15-21 Link Here

(-)guide/jface_actions.htm (-1 / +1 lines)
15	</HEAD>	15	</HEAD>
16	<BODY BGCOLOR="#ffffff">	16	<BODY BGCOLOR="#ffffff">
17	<H2>	17	<H2>
18	Actions and contributions</H2>	18	Actions and contributions (Deprecated)</H2>
19	<P >	19	<P >
20	The action classes allow you to define user commands independently from their presentation in the UI. This gives you the flexibility to change the presentation of an action in your plug-in without changing the code that actually performs the command once it has been chosen. The contribution classes are used to manage the actual UI items representing the commands. You don't program to the contribution classes, but you will see them in some of the workbench and JFace API.</P>	20	The action classes allow you to define user commands independently from their presentation in the UI. This gives you the flexibility to change the presentation of an action in your plug-in without changing the code that actually performs the command once it has been chosen. The contribution classes are used to manage the actual UI items representing the commands. You don't program to the contribution classes, but you will see them in some of the workbench and JFace API.</P>
21		21

Lines 70-79 Link Here

(-)guide/rcp_actions.htm (-4 lines)
70	}	70	}
71	};	71	};
72	</pre>	72	</pre>
73	<p>
74	See <a href="wrkAdv_retarget.htm">Retargetable actions</a> for a complete discussion of retargetable actions and how they
75	are defined and implemented.
76	</p>
77		73
78	</BODY>	74	</BODY>
79	</HTML>	75	</HTML>

Lines 77-83 Link Here

(-)guide/team_howto.htm (-1 / +1 lines)
77	<ul>	77	<ul>
78	<li><a href="team_ui_actions.htm">Add your actions to the Team	78	<li><a href="team_ui_actions.htm">Add your actions to the Team
79	menu</a>.</li>	79	menu</a>.</li>
80	<li>Use the <a href="workbench_basicext_popupMenus.htm"><b>popupMenus</b></a>	80	<li>Use the <a href="workbench_cmd_menus.htm"><b>menus</b></a>
81	extension to define the menu items.</li>	81	extension to define the menu items.</li>
82	</ul>	82	</ul>
83	</td>	83	</td>




</ul>
<p>The implementation of an action is largely dependent on your specific
provider.</p>
<p>Commands can be contributed in a similar way:</p>
<pre>
   &lt;extension point="org.eclipse.core.expressions.definitions"&gt;
      &lt;definition id="org.eclipse.ui.example.ccvs.ui.IFileContributions"&gt;
         &lt;iterate ifEmpty="false"&gt;
            &lt;adapt type="org.eclipse.core.resources.IFile"&gt;
               &lt;test <b>property="org.eclipse.core.resources.projectPersistentProperty"</b>
                     <b>value="org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature"</b>/&gt;
            &lt;/adapt&gt;
         &lt;/iterate&gt;
      &lt;/definition&gt;
   &lt;/extension&gt;
   &lt;extension point="org.eclipse.ui.menus"&gt;
      &lt;menuContribution locationURI="popup:<b>team.main?after=group3</b>"&gt;
         &lt;command commandId="org.eclipse.team.ccvs.ui.ignore"
               id="org.eclipse.ui.example.ccvs.ui.ignore"
               style="push"&gt;
            &lt;visibleWhen checkEnabled="false"&gt;
               &lt;or&gt;
                  &lt;with variable="activeMenuSelection"&gt;
                     &lt;reference definitionId="org.eclipse.ui.example.ccvs.ui.IFileContributions"/&gt;
                  &lt;/with&gt;
                  &lt;with variable="activeMenuEditorInput"&gt;
                     &lt;reference definitionId="org.eclipse.ui.example.ccvs.ui.IFileContributions"/&gt;
                  &lt;/with&gt;
               &lt;/or&gt;
            &lt;/visibleWhen&gt;
         &lt;/command&gt;
      &lt;/menuContribution&gt;
   &lt;/extension&gt;
</pre>
<p>
   &nbsp;
</p>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Boolean expressions and action filters
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H2>
Boolean expressions and action filters</H2>
<p>
When a plug-in contributes an action to the workbench UI using one of the menu
extension points, it can specify the conditions under which the menu item is
visible and/or enabled in the menu. In addition to supplying simple enabling
conditions, such as selection counts and selection classes, plug-ins can use <b>boolean
expressions</b> for more flexibility in determining when an action should be visible or enabled.</p>


<h3>Boolean enablement expressions</h3>
<p>Boolean expressions can contain the boolean operators (NOT, AND, OR) combined with a predefined syntax
for evaluating certain conditions.  Many of these conditions test a particular object.  The identity of the
"object in focus" (the object being tested) depends upon the specific context of the enablement expression:
</p>
<ul>
<li><b>instanceof</b> tests whether the type of the object in focus is a subtype of the specified type name.</li>
<li><b>test</b> tests whether the value of a named property of the object in focus matches the specified value.</li>
<li><b>systemTest</b> tests whether the value of a named system property matches the specified value. </li>
<li><b>equals</b> tests whether the object in focus is equal to the specified value.</li>
<li><b>count</b> tests the number of elements in a list.</li>
<li><b>with</b> changes the object in focus to the object referenced by a supplied variable.</li>
<li><b>resolve</b> changes the object in focus to the object referenced by a supplied variable, supplying additional
arguments with the variable.</li>
<li><b>adapt</b> adapts the object in focus to the type specified.</li>
<li><b>iterate</b> iterates over a variable that is a collection and combines the boolean value of each value using AND or OR.</li>
</ul>
<p>
When specifying a value to be tested against any of these expressions, the value is assumed to be a string except for when
the following conversions are successful:
</p>
<ul>
<li>the string "true" is converted into Boolean.TRUE</li>
<li>the string "false" is converted into Boolean.FALSE</li>
<li>if the string contains a dot, the interpreter tries to convert the value into a Float object</li>
<li>if the string only consists of numbers, the interpreter converts the value into an Integer object</li>
<li>the conversion into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes.</li>
</ul>
<p>A complete definition of enablement XML syntax can be found in the extension point reference documentation for any
extension that defines an <b>enablement</b> element, such as
<b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html#e.enablement"> org.eclipse.ui.popupMenus</a></b>.
</p>
<p>Prior to R3.0, these generalized boolean expressions were not available.  The following predefined expressions were used to
evaluate certain conditions without building a general expression.  Note that any of these expressions could now be expressed with
the more generalized syntax.  The predefined expressions can still be used as follows:</p>
<ul>
  <li>
    <p><b>objectClass</b> - true if each object in the
    selection subclasses or implements the class.</p>
  </li>
  <li>
    <p><b>objectState</b> - true if the named attribute equals the specified value.&nbsp; <b><a href="../reference/api/org/eclipse/ui/IActionFilter.html">IActionFilter</a>
    </b>assists in evaluating the expression.&nbsp; An action filter dynamically computes the enablement
criteria for an action based on the target selection and the value of named
attributes.</p>
  </li>
  <li>
    <p><b>systemProperty</b> - true if the named system
    property equals the specified value.</p>
  </li>
  <li>
    <p><b>pluginState</b> - specifies whether the specified
    plug-in (by <b>id</b>) should be <b>installed</b> or <b>activated</b> </p>
  </li>
</ul>
    <p>For example, the following snippets represent enablement
    expressions that could be used on a hypothetical action in an action set: </p>
    <pre>&lt;action id=&quot;org.eclipse.examples.actionEnablement.class&quot; 
       label=&quot;Red Element&quot; 
       menubarPath=&quot;additions&quot; 
       class=&quot;org.eclipse.examples.actionEnablement.ObjectTestAction&quot;&gt; 
       &lt;enablement&gt; 
<b>	 &lt;and&gt;
	   &lt;objectClass name=&quot;org.eclipse.examples.actionEnablement.TestElement&quot;/&gt; 
           &lt;objectState name=&quot;name&quot; value=&quot;red&quot;/&gt; 
	 &lt;/and&gt;
</b>       &lt;/enablement&gt; 
&lt;/action&gt;</pre>
    <pre>&lt;action id=&quot;org.eclipse.examples.actionEnablement.property&quot; 
       label=&quot;Property&quot; 
       menubarPath=&quot;additions&quot; 
       class=&quot;org.eclipse.examples.actionEnablement.PropertyTestAction&quot;&gt; 
       &lt;enablement&gt; 
<b>           &lt;systemProperty name=&quot;MyTestProperty&quot; value=&quot;puppy&quot;/&gt; 
</b>       &lt;/enablement&gt; 
&lt;/action&gt; </pre>
    <pre>&lt;action id=&quot;org.eclipse.examples.actionEnablement.pluginState&quot; 
       label=&quot;Installed&quot; 
       menubarPath=&quot;additions&quot; 
       class=&quot;org.eclipse.examples.actionEnablement.PluginTestAction&quot;&gt; 
       &lt;enablement&gt; 
           <b>&lt;pluginState id=&quot;x.y.z.anotherPlugin&quot; value=&quot;installed&quot;/&gt; </b>
       &lt;/enablement&gt; 
&lt;/action&gt; </pre>
<p>See the reference documentation of the extension points
for more elaborate samples of these expressions and a complete description of
the XML.</p>


<p>
The following table lists extension points that contribute actions and
summarizes how XML markup attributes and boolean expressions can be used to
affect enablement.</p>


<TABLE BORDER="1" width="671">
<TR>
<TH ROWSPAN="1" COLSPAN="1" width="118">
<P CLASS="CellHeading">
Extension point name</p>
</TH>
<TH ROWSPAN="1" COLSPAN="1" width="359">
<P CLASS="CellHeading">
Attributes affecting enablement</p>
</TH>
<TH ROWSPAN="1" COLSPAN="1" width="335">
<P CLASS="CellHeading">
Boolean expressions</p>
</TH>
</TR>
<TR>
<TD width="118">
<p>
<b>
<a href="../reference/extension-points/org_eclipse_ui_viewActions.html">
viewActions</a></b>,</p>
<p><b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">editorActions</a></b>,</p>
<p><b><a href="../reference/extension-points/org_eclipse_ui_actionSets.html">actionSets</a></b></p>
</TD>
<TD width="359">
<p>
<b>enablesFor</b> - specifies the selection count that must be met for the
action to be enabled</p>
<p>
<b>selection</b> <b>class</b> - the class that the selected objects must
subclass or implement in order for the action to be enabled</p>
<p>
<b>selection</b> <b>name</b> - a wild card filter that can be applied to the
objects in the selection.</p>
</TD>
<TD width="335">
<p>
<b>visibility</b> - a boolean expression.&nbsp; Controls whether the menu item
is visible in the menu.</p>
<p>
<b>enablement</b> - a boolean expression.&nbsp; Controls whether the menu item
is enabled in the menu.&nbsp; The <b>enablesFor</b>  attribute and the <b>selection</b> <b>class</b>
and <b>name</b>, and must be
satisfied before applying the enablement expression.</p>
</TD>
</TR>
<TR>
<TD width="118">
<p>
<b>
<a href="../reference/extension-points/org_eclipse_ui_popupMenus.html">
popupMenus</a></b></p>
</TD>
<TD width="359">
<p>
(For object contributions only.)</p>
<p>
<b>objectClass</b> - specifies the class that objects in the selection must
subclass or implement</p>
<p>
(For both object and viewer contributions)</p>
<p>
<b>enablesFor</b> - specifies the selection count that must be met for the
action to be enabled</p>
<p>
<b>selection</b> <b>class</b> - the class that the selected objects must
subclass or implement to enable the action</p>
<p>
<b>selection</b> <b>name</b> - a wild card filter that can be applied to the
objects in the selection.</p>
<p>
&nbsp;</p>
</TD>
<TD width="335">
<p>
(For both object and viewer contributions)</p>
<p>
<b>visibility</b> - a boolean expression.&nbsp; Controls whether the menu item
is visible in the menu.</p>
<p><b>enablement</b> - a boolean expression.&nbsp; Controls
whether the menu item is enabled in the menu.&nbsp;
The <b>enablesFor</b>  attribute and the <b>selection</b> <b>class</b> and <b>name</b>, and must be
satisfied before applying the enablement expression.</p>
</TD>
</TR>
</TABLE>

<h3>Using objectState with content types</h3>
<p>The ability to define content types (see <a href="runtime_content.htm">Content types</a>) can be combined
with boolean expressions to define very specific enablement or visibility conditions based on
the content type of a resource.  For example, the following snippet makes a popup menu item visible only if the
selected file's content matches the plug-in's specialized content types.
</p>
<pre>
&lt;extension point="org.eclipse.ui.popupMenus"&gt;
   &lt;objectContribution
      id="com.example.objectContributions"
      objectClass="org.eclipse.core.resources.IFile"
      nameFilter="*.xml"&gt;
         &lt;visibility&gt;
            &lt;or&gt;
               &lt;objectState
                  <b>name="contentTypeId"</b>
                  value="com.example.employeeRecordContentType"/&gt;
               &lt;objectState
                  <b>name="contentTypeId"</b>
                  value="com.example.customerRecordContentType"/&gt;
            &lt;/or&gt;
         &lt;/visibility&gt;
         &lt;action id="com.example.action1"
         ...
</pre>
The <b>contentTypeId</b> attribute can be used in an objectState expression to check the content type of
the selected xml file.  This allows a plug-in to apply very specific content checking before enabling or showing
menu actions related to specific types of files.  See <a href="runtime_content.htm">Content types</a> for more detail
about the content type extension.



</BODY>
</HTML>

Lines 15-21 Link Here

(-)guide/workbench_advext_activities.htm (-1 / +1 lines)
15	</head>	15	</head>
16		16
17	<body bgcolor="#ffffff">	17	<body bgcolor="#ffffff">
18	<h3>Activities</h3>An <b>activity</b> is a logical grouping of functionality that	18	<h3>Activities (Not currently in 4.1)</h3>An <b>activity</b> is a logical grouping of functionality that
19	is centered around a certain kind of task. For example, developing Java	19	is centered around a certain kind of task. For example, developing Java
20	software is an activity commonly performed by users of the platform, and the	20	software is an activity commonly performed by users of the platform, and the
21	JDT defines many UI contributions (views, editors, perspectives, preferences,	21	JDT defines many UI contributions (views, editors, perspectives, preferences,




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. 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">
<TITLE>
Basic workbench extension points
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H2>
Basic workbench extension points using actions</H2>
<P >
The workbench defines extension points that allow plug-ins to contribute
behaviors to existing views and editors or to provide implementations for
new views and editors. Using commands is covered in the <a href="workbench_cmd.htm" 
class="XRef">Basic workbench extension points using commands</a> section. Here we are
 going to take a look at the
contributions to these extension points from one of the workbench sample applications, the readme tool. </P>
<P >
The readme tool is a plug-in that provides custom editing and navigation for a specific resource
, a
<b> .readme</b> file. The example shows many typical (but simplified) ways that extensions can be used to provide specialized tools.</P>
<P >
The readme tool contributes to the menus of the navigator view, adds editor related actions to the workbench menus and
tool bar, defines a custom view and content outliner, and defines markers
and marker resolutions. The figure below shows some of the
customized features added to the workbench by the readme tool.</P>
<P >
<img src="images/readmeoverview.png" alt="Workbench with readme tool contributing action sets, view and editor actions, custom editors and views, and outliner" border="0"></P>
<P >
The readme tool also contributes preference and properties pages to the workbench.  Later we'll also look
at some wizard contributions in 
<a HREF="dialogs.htm" CLASS="XRef"> Dialogs and wizards</a>.</P>
<P >
The readme tool is located in the <b>org.eclipse.ui.examples.readmetool</b> package. The
<b> readmetool.jar</b> and <b> plugin.xml</b> can be found in the
<b> org.eclipse.ui.examples.readmetool</b> directory underneath the
<b> plugins</b> directory. To follow along, you will need to make sure that
you have installed the platform examples.&nbsp; (See the <a href="../samples/samples.html">Examples
Guide </a> for more information.)&nbsp; </P>
<P >
The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
tool</a> implements many different workbench extensions.&nbsp; We will start
with one of the simplest workbench extension points, a view.&nbsp; We'll
continue by looking at additional readme tool extensions. </P>

</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. 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" type="text/javascript"></script>
<TITLE>Action set part associations</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H2>
Action set part associations</H2>

<P >
Once your plug-in defines an <a href="workbench_basicext_actionSets.htm">action
set</a>, it can use the
<a href="../reference/extension-points/org_eclipse_ui_actionSets.html"><b> org.eclipse.ui.actionSetPartAssociations</b></a> 
extension point to specify that an action set should be made visible when a
particular view or editor is active.&nbsp;&nbsp; </P>

<P >
 Ultimately, the user controls the
appearance of action sets using

<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.customizePerspective")'>
<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png" alt="command link">
<b>Window &gt; Customize Perspectives...</b></a>

in
the workbench menu.&nbsp;If the user marks an action set visible, it will always be visible when the
perspective is active, regardless of
the active view or editor.&nbsp; Likewise, if the user marks the action set as hidden, it will always be hidden when the perspective is active.&nbsp; If the user does not change the state of
an action set in this dialog, then the action set part associations are used to
determine the visibility of the action set.</P>


<P >
The markup for an action set part association is straightforward.&nbsp; The
following example comes from the Java development tools (JDT) UI plug-in.</P>
<pre>
   &lt;extension point=&quot;org.eclipse.ui.actionSetPartAssociations&quot;&gt;
	&lt;actionSetPartAssociation 
		<b>targetID</b>=&quot;org.eclipse.jdt.ui.CodingActionSet&quot;&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.PackageExplorer&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.TypeHierarchy&quot; /&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.CompilationUnitEditor&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.ClassFileEditor&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.ProjectsView&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.PackagesView&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.TypesView&quot;/&gt;
		&lt;part id=&quot;org.eclipse.jdt.ui.MembersView&quot;/&gt;
	&lt;/actionSetPartAssociation&gt;
&lt;/extension&gt;
</pre>
<P >The <b>targetID</b> specifies the action set.&nbsp; (The <b> CodingActionSet</b> was
previously defined in the JDT plug-in manifest.)&nbsp; One or more <b>part</b>
attributes can be specified to indicate which views and editors will cause the
action set to become visible in the menus and toolbar.&nbsp; The effect of this extension
contribution is that the actions associated with writing Java code will only be
visible when one of the specified views is active.</P>





</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. 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" type="text/javascript"></script>
<TITLE>org.eclipse.ui.actionSets</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H3>
org.eclipse.ui.actionSets</H3>

<P >
Your plug-in can contribute menus, menu items, and tool bar items to the workbench menus and toolbar
by using the
<a href="../reference/extension-points/org_eclipse_ui_actionSets.html"><b> org.eclipse.ui.actionSets</b></a> 
extension point. In order to reduce the clutter that would be caused by having every plug-in's menu contributions shown at once, the contributions are grouped into action sets which can be made visible by user preference.</P>
<P >
You can see which action sets have been contributed to your workbench by choosing

<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.customizePerspective")'>
<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png" alt="command link">
<b>Window &gt; Customize Perspective...</b></a>

from the workbench menu. This option will show you a dialog that lists
action sets as groups of commands.  A checkmark by a command group means that the menu and tool bar actions are visible in the workbench. 
You can select the name of the command group to see the list of available menu and toolbar actions to the right. The figure below shows the
list of command groups available in our workbench.&nbsp; (Your workbench may look different depending on which plug-ins you have
installed and which perspective is active.)</P>

<img src="images/actionsets.png" alt="Customize Perspective dialog with action set list" border="0">


<P >
The readme tool uses an action set to contribute several different &quot;Open Readme
Browser&quot; actions to the workbench menu.&nbsp; (We contributed a similar
action to the popup menu of the resource navigator.)&nbsp; The markup follows:</P>
<pre>
&lt;extension point = &quot;org.eclipse.ui.actionSets&quot;&gt;
	   &lt;actionSet id=&quot;org_eclipse_ui_examples_readmetool_actionSet&quot;
		   label=&quot;%ActionSet.name&quot;
		   visible=&quot;true&quot;&gt;
		   &lt;menu id=&quot;org_eclipse_ui_examples_readmetool&quot;
			   label=&quot;%ActionSet.menu&quot;
			   path=&quot;window/additions&quot;&gt; 
			   &lt;separator name=&quot;slot1&quot;/&gt;
			   &lt;separator name=&quot;slot2&quot;/&gt;
			   &lt;separator name=&quot;slot3&quot;/&gt;
		   &lt;/menu&gt;
		   &lt;action id=&quot;org.eclipse.ui.examples.readmetool.readmeAction&quot;
			   menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;
			   toolbarPath=&quot;readme&quot;
			   label=&quot;%ReadmeAction.label&quot;
			   tooltip=&quot;%ReadmeAction.tooltip&quot;
			   helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
			   icon=&quot;icons/ctool16/openbrwsr.png&quot;
			   class=&quot;org.eclipse.ui.examples.readmetool.<b>WindowActionDelegate</b>&quot;
			   definitionId=&quot;org.eclipse.ui.examples.readmetool.readmeAction&quot;
			   enablesFor=&quot;1&quot;&gt;
			   &lt;selection class=&quot;org.eclipse.core.resources.IFile&quot;
					name=&quot;*.readme&quot;&gt;
			   &lt;/selection&gt;
		   &lt;/action&gt;
		   ...
	   &lt;/actionSet&gt;
   &lt;/extension&gt;</pre>
<P >
Wow, there's a lot going on here!&nbsp; Let's take it a step at a time, looking
only at the first action for now.&nbsp;&nbsp;</P>
<P >
First, the action set is declared and given a <b>label</b>.&nbsp;
The label &quot;ReadMe Actions&quot; (defined for <b> %ActionSet.name</b>  key in the plug-in's
properties file) is used to display the action set in the
dialog shown above.&nbsp; Since we set <b> visible</b> to true, the workbench will initially have the action set
checked in the action set list and the actions will be visible.</P>
<P >
The rest of the action set declaration is concerned with defining the menu in
which the actions appears and the actions themselves.</P>
<P >
We define a menu whose <b>label</b> appears in the workbench menus.&nbsp; The menu's <b>path</b>
tells the workbench to place the new menu in the <b>additions</b>
slot of the <b>window</b> menu.&nbsp; (For a discussion
of menu paths and slots, see <a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a>.)&nbsp;
We also define some slots in our new menu so that actions can be inserted at specific locations in our menu.</P>
<P >
This markup alone is enough to cause the menu to appear in the workbench <b>Window</b>
menu.</P>
<P >
<img src="images/readmeactionset.png" alt="Workbench Window menu with Readme File Editor entry" border="0" ></P>
<P >
Next, we define the actions themselves.&nbsp;&nbsp;</P>
<P >
The action definition (<b>id</b>,
<b>label</b>, <b>icon</b>, <b>class</b>) is
similar to the other actions we've seen in views, editors, and popups.&nbsp;
We'll focus here on what's different:&nbsp; where does the action go?&nbsp; We
use&nbsp; <b>menubarPath</b> and <b>toolbarPath</b>
to indicate its location.&nbsp; First, we define the <b>menubarPath</b> to add the
action to a slot in the menu
that we just defined (&nbsp;<b>&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;</b>).</P>
<P >
<img src="images/readmeactionsetmenu.png" alt="Readme File Editor menu with menu items" border="0" ></P>
<P >
Then, we define a new <b> toolbarPath</b> to insert our actions in the workbench tool
bar.&nbsp; Since we've defined a new tool path, <b>&quot;readme&quot;</b>, the workbench will decide where it goes
relative to other plug-in's toolbar contributions.</P>
<P >
<img src="images/readmeactionsettoolbar.png" alt="Workbench tool bar with readme action" border="0" ></P>
<P >
What happens when the action is selected by the user?&nbsp; The action is
implemented by the class specified in the <b>class</b>
attribute.&nbsp; The action <b> class</b> must implement
<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowActionDelegate.html"> IWorkbenchWindowActionDelegate</a></b>,
or
<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowPulldownDelegate.html"> IWorkbenchWindowPulldownDelegate</a></b> 
if the action will be shown as a pull-down tool item in the tool bar.&nbsp; Since we are not
creating a pull-down tool item, we provide <b>WindowActionDelegate</b>.&nbsp;
This class is similar to <b>ObjectActionDelegate</b>.&nbsp;
It launches the readme sections dialog when the user chooses the action.&nbsp; (We'll
discuss the sections dialog in <a href="dialogs_applications.htm">Application
dialogs</a>.)</P>


<P >
The action also supplies enabling conditions for its menu item and tool bar
item.&nbsp; The menu and tool bar items will only be enabled when a single (<b>enablesFor=&quot;1&quot;</b>)
readme file (<b>selectionClass =&quot;org.eclipse.core.resources.IFile&quot;
name=&quot;*.readme&quot;</b>) is selected.&nbsp; This action's menu and toolbar
item appear and are enabled by virtue of the markup
in the <b>plugin.xml</b> file.&nbsp; None of the
plug-in code will execute until the user chooses the action and the workbench
runs the action <b>class</b>.</P>

<p>The <b>definitionId</b> allows the action to be linked to a command created by the
<b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a></b>
extension, which can be used for keybindings.  All <b>actions</b> in an <b>actionSets</b>
should be linked to a command, either existing commands provided by the workbench or
commands created by the contributing plugin. 
See <a href="wrkAdv_keyBindings_actionDef.htm" class="XRef">Associating actions to commands</a>
and <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> for
defining commands.</p>

<P >
We'll look at the other two actions later in the context of <a href="wrkAdv_retarget_contribute.htm">retargetable
actions</a>.</P>





</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>org.eclipse.ui.editorActions</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H3>
org.eclipse.ui.editorActions</H3>

<P >
We've just seen how editors
can contribute their own actions to the workbench menus and tool bar when they
become active.&nbsp; The <b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">org.eclipse.ui.editorActions</a></b> extension
point allows a plug-in to add
to the workbench menus and tool bar when another plug-in's editor becomes active.</P>
<P >
In the readme example, the plug-in uses the <b>editorActions</b>
extension point to contribute additional actions to the menu contributed by the
readme editor. The definition in our
<b> plugin.xml</b> should look pretty familiar by now.</P>
<pre>
&lt;extension
    point = &quot;org.eclipse.ui.editorActions&quot;&gt;
      &lt;editorContribution 
         id=&quot;org.eclipse.ui.examples.readmetool.ec1&quot; 
         targetID=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditor&quot;&gt;        
	   &lt;action id=&quot;org.eclipse.ui.examples.readmetool.ea1&quot; 
              label=&quot;%Editors.Action.label&quot; 
              toolbarPath=&quot;ReadmeEditor&quot; 
              icon=&quot;icons/obj16/editor.png&quot; 
              tooltip=&quot;%Editors.Action.tooltip&quot; 
              class=&quot;org.eclipse.ui.examples.readmetool.EditorActionDelegate&quot;
              definitionId=&quot;org.eclipse.ui.examples.readmetool.ea1&quot;
              /&gt; 
      &lt;/editorContribution&gt;
 &lt;/extension&gt;</pre>
<P >Similar to a view action, the extension must specify the <b> targetID</b> of the
editor to which it is contributing actions.&nbsp; The action itself is very
similar to a view action (<b>id</b>, <b>label</b>, <b>icon</b>, <b>toolbarPath</b>,
...), except that the specified class
must implement <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>
and a <b>definitionId</b> can be specified to link this action to a Command specified 
by the <b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a></b>
extension, which is important for keybinding.  
See <a href="wrkAdv_keyBindings_actionDef.htm" class="XRef">Associating actions to commands</a>
and <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> for
defining commands.</P>
<P >Note that a menu bar path is not specified in this markup.&nbsp; Therefore,
the action will appear in the workbench tool bar when the editor is active,
but not in the workbench menu bar.&nbsp; (See <a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a> for a discussion of toolbar and menu paths.)</P>
<P >Sure enough, when the editor is active, we see our editor action on the tool
bar next to the actions that were contributed by the editor itself.</P>
<P ><img src="images/editorAction.png" alt="Editor action appears next to original editor contributions in workbench toolbar" border="0" ></P>
<P >
The readme tool supplies <b> EditorActionDelegate</b>
to implement the action.&nbsp; This class is very similar to the view action delegate
we saw earlier.</P>

<pre>
public void run(IAction action) {
	MessageDialog.openInformation(editor.getSite().getShell(),
		MessageUtil.getString(&quot;Readme_Editor&quot;),  
		MessageUtil.getString(&quot;Editor_Action_executed&quot;)); 
}</pre>



</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<HEAD>

<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. 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">

editor on the same file from a different workbench window or perspective).&nbsp;
Unlike views, however, the same editor type, such as a text editor, may be open
many times
within one workbench page for different inputs.  The editor input can also be a path
to an in memory model, as in the InfoEditor example.</P>
<P >
The workbench extension point <b><a href="../reference/extension-points/org_eclipse_ui_editors.html">org.eclipse.ui.editors</a></b>
is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor

for the editor. Some
of the editor information, such as the implementation <b> class</b> and the
<b> name</b> and the <b>icon</b>  to be used in the workbench menus and
labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands. 
Editors also use <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> and <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>
to contribute to the workbench menus and toolbars when that editor is active.</P>
<P >
The interface for editors is defined in <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>, but plug-ins
can choose to extend the

are implemented using
<b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>.</i></blockquote> 
<P >
The editor can contribute its own content outliner page to the
workbench outline view.&nbsp;&nbsp;</P>
<P >
 The configuration for the editor extension is defined as follows.</P>
<pre>
&lt;extension
    point = &quot;org.eclipse.ui.editors&quot;&gt;
      &lt;editor
            class="org.eclipse.ui.examples.contributions.editor.InfoEditor"
            icon="icons/editor.gif"
            id="org.eclipse.ui.examples.contributions.editor"
            name="%contributions.editor.name"&gt;
      &lt;/editor&gt;
           contributorClass=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor&quot;&gt;
	&lt;/editor&gt;
&lt;/extension&gt;</pre>
<P >
We see the familiar configuration markup for <b>id</b>,
<b>name</b>,
<b>icon</b> (which must be specified when specifying <b>class</b>),
and <b>class</b>.&nbsp;&nbsp; You could use the <b>extensions</b> attribute
describes the file types that the editor understands, like <b>extensions=&quot;person&quot;</b>,
although this example doesn't need it.
(You could also
specify <b>filenames</b> if you need to be more specific.)&nbsp; The <b>class</b>
implements the editor.</P>
providing editor-related actions.  The contributor is not normally used to
contribute commands or handlers to the workbench menu or toolbar, that's done
via <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
Let's look at the contributor that's used for actions in more
detail.</P>

<H4>
Editor action contributors</H4>
<P >
The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the
<b><a href="../reference/api/org/eclipse/ui/IEditorActionBarContributor.html"> IEditorActionBarContributor</a></b> interface. The contributor is
separate from the editor itself since any given workbench page can have multiple editors of the same type.
A single contributor is shared by all the editors of a specific type, rather than
having each instance of an editor create actions and images.&nbsp;</P>
<P >
In <b>ReadmeEditorActionBarContributor</b>, we contribute three actions,
&quot;Editor Action1,&quot; &quot;Editor Action2,&quot; and &quot;Editor Action3.&quot;&nbsp;&nbsp;
These are set up in the constructor.</P>
<pre>
   public ReadmeEditorActionBarContributor() {
      	...
	action1 = new EditorAction(MessageUtil.getString(&quot;Editor_Action1&quot;)); 
	action1.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action1&quot;)); 
	action1.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_DISABLE);
	action1.setImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_ENABLE);
	...	
	action2 = new RetargetAction(IReadmeConstants.RETARGET2, MessageUtil.getString(&quot;Editor_Action2&quot;)); 
	action2.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action2&quot;)); 
	action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
	action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
	...
	action3 = new LabelRetargetAction(IReadmeConstants.LABELRETARGET3, MessageUtil.getString(&quot;Editor_Action3&quot;));
	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
	...   
   }
</pre>
<P >
The names and icons for the actions are set up in the code rather than in the <b>plugin.xml</b>.&nbsp;
(We'll ignore the differences in the action classes for now until we look at <a href="wrkAdv_retarget_contribute.htm">retargetable
actions</a>.)&nbsp;&nbsp;</P>
<P >Note how similar the action information is to the
<b> viewActions</b> information we saw in the markup
for the view action.&nbsp; The actions are set up in code since we have to
manage the sharing of the actions among different instances of the same editor.&nbsp;
When the actions are created in the constructor, they are independent of any
particular instance of the editor.</P>
<P >
Editor menus and editor toolbars are placed in the main menu and main toolbar.  See 
<a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a> for how to use the
<b>locationURI</b> to place the commands correctly.</P>
<img src="images/contributions_global.png" alt="Showing a global menu additions" border="0" >
<P>
These menu and tool bar items can be shown only when the editor is active using core expressions.
To define a re-usable core expression for your editor, use
<b><a href="../reference/extension-points/org_eclipse_core_expressions_definitions.html">org.eclipse.core.expressions.definitions</a></b></P>
<pre>
&lt;extension
    point = &quot;org.eclipse.core.expressions.definitions&quot;&gt;
      &lt;definition id="org.eclipse.ui.examples.contributions.view.activeEditor"&gt;    
         &lt;with variable="activeEditorId"&gt;
            &lt;equals value="org.eclipse.ui.examples.contributions.editor"/&gt;
         &lt;/with&gt;
      &lt;/definition&gt;
&lt;/extension&gt;</pre>

<img src="images/editormenu.png" alt="Readme entry in workbench menu bar with three editor actions" border="0" >



<p><img src="images/editortoolbar.png" alt="Workbench toolbar with three readme actions" border="0" ></p>
<P >
These menu and tool bar items are only shown when the editor is active. The location for the menu and tool bar items can be specified as described in
<a HREF="workbench_menupaths.htm" CLASS="XRef">Menu and toolbar paths</a>.</P>



<H4>
Editors and content outliners
</h4>
<P >
Although the Info Editor does not, editors often have corresponding content outliners 
that provide a structured
to the outline view when a readme file is being edited. It does not change any behavior inside the text editor.</P>
<p><img src="images/readmeoutliner.png" alt="" border="0"></p>
<P >
Editors often have corresponding content outliners that provide a structured
view of the editor's contents and assist the user in navigating through the
contents of the editor.&nbsp; See <a href="editors_workbench_outliner.htm">Content
outliners</a> for more detail. </P>

editors and platform text</a>. </P>





</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>org.eclipse.ui.popupMenus</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H3>
org.eclipse.ui.popupMenus</H3>

<P >
The <b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html"> org.eclipse.ui.popupMenus</a></b> extension
point allows a plug-in to contribute to the popup menus of other
views and editors.</P>
<P >
You can contribute an action to a specific popup menu by its id (<b>viewerContribution</b>), or
by associating it with a particular object type (<b>objectContribution</b>).&nbsp;</P>
<ul>
  <li>An <b>objectContribution</b> will cause the menu
    item to appear in popup menus for views or editors where objects of
    the specified type are selected.</li>
  <li>A <b>viewerContribution</b> will cause the menu
    item to appear in the popup menu of a view or editor specified by id in the
    markup.&nbsp;&nbsp;</li>
</ul>
<p>
You can add commands to context menus for a similar result, see the 
<b>Contributing to popup menus</b> section in 
<a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
</p>
<P >
The readme tool defines both. Let's look at the object contribution
first.&nbsp;&nbsp;</P>
<pre>
&lt;extension point = &quot;org.eclipse.ui.popupMenus&quot;&gt;
     &lt;objectContribution
        id=&quot;org.eclipse.ui.examples.readmetool&quot;
        objectClass=&quot;org.eclipse.core.resources.IFile&quot;
	    nameFilter=&quot;*.readme&quot;&gt;
	    &lt;action id=&quot;org.eclipse.ui.examples.readmetool.action1&quot;
	       label=&quot;%PopupMenus.action&quot;
	       icon=&quot;icons/ctool16/openbrwsr.png&quot;
	       menubarPath=&quot;additions&quot;
	       helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
	       class=&quot;org.eclipse.ui.examples.readmetool.PopupMenuActionDelegate&quot;	
           definitionId=&quot;org.eclipse.ui.examples.readmetool.action1&quot;
	       enablesFor=&quot;1&quot;&gt;
	    &lt;/action&gt;
	 &lt;/objectContribution&gt;
 	 ...
</pre><h4>
   Object contribution
</h4>
<P >
The action &quot;Show Readme Action&quot; is contributed for the object class <a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>. This means that any view containing
<a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>
objects will show the contribution if <a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>
objects are selected. We see that the selection criteria is restricted further with a name filter
(<b>nameFilter=&quot;*.readme&quot;</b>) and for single selections (<b>enablesFor=&quot;1&quot;</b>). As we've discussed before, the registration of this menu does not run any code from our plug-in until the menu item is actually selected. </P>
<P >
When the menu item is selected, the workbench will run the specified class.&nbsp;
Since the popup is declared as an <b>objectContribution</b>,
the supplied class must implement <b><a href="../reference/api/org/eclipse/ui/IObjectActionDelegate.html">IObjectActionDelegate</a></b>.&nbsp;</P>
<P >
The action is implemented in <b>PopupMenuActionDelegate</b>.&nbsp;&nbsp;</P>
<pre>
   public void run(IAction action) {
      MessageDialog.openInformation(
         this.part.getSite().getShell(),
         &quot;Readme Example&quot;,
         &quot;Popup Menu Action executed&quot;);
   }
</pre>
<P >
We can see the popup menu contribution when we select a readme file from the resource navigator.</P>

<img src="images/readmepopupmenu.png" alt="" border="0">
<h4>Viewer contribution</h4>
<p>
A viewer contribution is used to contribute to a specific view or editor's popup menu
by using its id.
Here is the readme tool's viewer contribution:</p>
<pre>      ...
      &lt;viewerContribution
        id=&quot;org.eclipse.ui.examples.readmetool2&quot;
        targetID=&quot;org.eclipse.ui.examples.readmetool.outline&quot;&gt;
	    &lt;action id=&quot;org.eclipse.ui.examples.readmetool.action1&quot;
	       label=&quot;%PopupMenus.action&quot;
	       icon=&quot;icons/ctool16/openbrwsr.png&quot;
	       menubarPath=&quot;additions&quot;
	       helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
           definitionId=&quot;org.eclipse.ui.examples.readmetool.action1&quot;
	       class=&quot;org.eclipse.ui.examples.readmetool.ViewActionDelegate&quot;&gt;	
	    &lt;/action&gt;
       &lt;/viewerContribution&gt;
&lt;/extension&gt;</pre>
<blockquote><i>
Note:&nbsp; The name <b> viewerContribution</b> is somewhat misleading, as it does not relate to JFace viewers. A better name would
be <b>popupMenuContribution</b>.</i></blockquote>
<P >
When the extension is a <b>viewerContribution</b>, the
supplied class must implement the
<b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html"> IEditorActionDelegate</a></b> or
<b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html"> IViewActionDelegate</a></b> interface, depending on whether the
action is contributed to an editor's or view's popup menu.&nbsp;</P>


<P >
The <b>targetID</b> specifies the popup menu that will be altered.&nbsp; If not specified
in the call to <code>getSite().registerContextMenu(*)</code> the popup menu's ID will default to the view or editor ID.&nbsp; In this
case, we are adding an action to one of the readme tool views, the
outliner.&nbsp; The action itself is similar to others that we've seen.&nbsp; We specify the <b>id</b>,
<b>definitionId</b>, <b>label</b>, and <b>icon</b> of the action, and
the <b>path</b> within the popup for our contribution.&nbsp; The action will be
shown only in the readme outline view's popup menu.</P>


<P >
<img src="images/readmeoutlinerpopup.png" alt="" border="0"></P>


 The interfaces required to contribute a <b>viewerContribution</b>
to the <b> popupMenus</b> extension
point are the same as those required by the <b> viewActions</b> and <b> editorActions</b> extension points. If you want to contribute the same action to the popup menu and the local menu of a view or editor, you can use the same class for both extensions.





</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>org.eclipse.ui.viewActions</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<H3>
org.eclipse.ui.viewActions</H3>

<P >
It is common for plug-ins to contribute behavior to views that already exist in the workbench. This is done through the
<b><a href="../reference/extension-points/org_eclipse_ui_viewActions.html"> org.eclipse.ui.viewActions</a></b> 
extension point. This extension point allows plug-ins to contribute menu items, submenus and tool bar entries to an
existing view's local
pull-down menu and local tool bar. </P>
<p>
Contributing menu items to views is also done using the 
<b><a href="../reference/extension-points/org_eclipse_ui_menus.html">org.eclipse.ui.menus</a></b>
extension point.  This allows command targeted at a view to be contributed to
an existing view's local pull-down menu and local tool bar, as in the <b>Contribution location</b> section
covering the Info View of <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
</p>
<P >
You may have noticed an item in the project explorer's local tool bar that becomes
enabled whenever a readme file is selected. This item also appears in the
project explorer's local
pull-down menu. These actions appear because the readme tool plug-in contributes
them using the
<b> viewActions</b> extension.</P>

<img src="images/readmeviewaction.png" alt="" border="0">
<P >
The relevant <b> plugin.xml</b> contribution is below.</P>
<pre>
&lt;extension
    point = &quot;org.eclipse.ui.viewActions&quot;&gt;
      &lt;viewContribution 
         id=&quot;org.eclipse.ui.examples.readmetool.vc1&quot; 
         targetID=&quot;org.eclipse.ui.navigator.ProjectExplorer&quot;&gt;        
	   &lt;action id=&quot;org.eclipse.ui.examples.readmetool.va1&quot; 
              label=&quot;%PopupMenu.ResourceNav.label&quot; 
	      menubarPath=&quot;additions&quot;
              toolbarPath=&quot;additions&quot; 
              icon=&quot;icons/obj16/editor.png&quot; 
              tooltip=&quot;%PopupMenu.ResourceNav.tooltip&quot; 
   	      helpContextId=&quot;org.eclipse.ui.examples.readmetool.view_action_context&quot;
              class=&quot;org.eclipse.ui.examples.readmetool.ViewActionDelegate&quot; 
              enablesFor=&quot;1&quot;&gt; 
		&lt;selection class=&quot;org.eclipse.core.resources.IFile&quot; name=&quot;*.readme&quot;/&gt; 
	   &lt;/action&gt;
      &lt;/viewContribution&gt;
 &lt;/extension&gt;
</pre>
<P >
A view contribution with a unique id is specified. The view to which we are adding
the action is specified in the
<b> targetID</b>. We are contributing to the Project
Explorer's menu.&nbsp; We specify the label and the menu bar and
tool bar locations for the new action.&nbsp; (For a complete discussion of menu and toolbar locations, see
<a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a>). </P>
<P >
We also specify the conditions under which the action should be enabled. You can see that this action will be enabled when there is one selection
(<b>enablesFor=&quot;1&quot;</b>) of type
<b><a href="../reference/api/org/eclipse/core/resources/IFile.html">IFile</a>
(class=&quot;org.eclipse.core.resources.IFile&quot;)</b>, whose name has
&quot;<b>.readme</b>&quot; in the file extension (<b>name=&quot;*.readme&quot;</b>). Sure enough, that's exactly what happens when you click around in the Project Explorer.&nbsp;&nbsp;</P>
<P >
The information in the <b> plugin.xml</b> is all that's needed to add items to menus and tool
bars since plug-in code will only run when the action is actually selected from the menu or toolbar.
To provide the action behavior, the implementation class specified in the
<b> plugin.xml</b> must implement the <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html"> IViewActionDelegate</a></b> interface. </P>
<P >
In this example, the readme plug-in supplies <b> ViewActionDelegate</b> to implement the action. If you browse this class you will see that it includes methods for
remembering its view, handling selection changes, and invoking its action.&nbsp;
When invoked the action itself simply launches a dialog that announces it was executed.</P>
<pre>
public void run(org.eclipse.jface.action.IAction action) {
	MessageDialog.openInformation(view.getSite().getShell(),
		MessageUtil.getString(&quot;Readme_Editor&quot;),  
		MessageUtil.getString(&quot;View_Action_executed&quot;)); 
}</pre>
<P >
Although this action is simple, we can imagine how using selections and more
functional dialogs could make this action do something more interesting.</P>





</BODY>
</HTML>




<P >
The extension point <b><a href="../reference/extension-points/org_eclipse_ui_views.html">org.eclipse.ui.views</a></b>
allows plug-ins to add views to the workbench. Plug-ins that contribute a view must register the view in their
<b> plugin.xml </b> file and provide configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.</P>
<P >
The interface for views is defined in <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, but plug-ins
can choose to extend the

let's take a look at the declaration of the extension in the <b>plugin.xml</b>.</P>
<pre>&lt;extension 
   point=&quot;org.eclipse.ui.views&quot;&gt;
      &lt;category
            id="org.eclipse.ui.examples.contributions.viewCategory"
            name="%contributions.viewCategory.name"&gt;
      &lt;/category&gt;
      &lt;view
            category="org.eclipse.ui.examples.contributions.viewCategory"
            class="org.eclipse.ui.examples.contributions.view.InfoView"
            id="org.eclipse.ui.examples.contributions.view"
            name="%contributions.view.name"&gt;
      &lt;/view&gt;
	&lt;/view&gt;
&lt;/extension&gt;
</pre>
<P >
This should look pretty familiar. We see that a new view, <b>InfoView</b>, is contributed to the workbench. The
<b>view id</b>, <b>name</b>,
and
<b> category</b> are specified as we've seen before.</P>
for the view, using a path relative to the plug-in's installation directory. </P>
<P >
Let's look at the <b>InfoView</b>. You can show any view in the
workbench by choosing

<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView")'>


and selecting the view from the <b>Show View</b> list.</P>
<P >
When we show the <b>InfoView</b>, a view with a list in it pops up.
The list is pre-populated with some data.</P>
the list is populated with sections from the readme file.</P>

<img src="images/contributions_window.png" alt="Picture of the workbench, showing the contributions">
<P >
How does the plug-in recognize the readme file and how did it know about selection changes? If we can track down
the answers to these questions, we are well on our way to understanding how to build integrated workbench plug-ins.</P>
<P >
We'll start with the familiar <b>createPartControl</b>
method.&nbsp; As we saw in the Hello World example, this is where the widgets

<pre>
   public void createPartControl(Composite parent) {
      viewer = new ListViewer(parent);
      viewer.setContentProvider(new ContentProvider());
      viewer.setLabelProvider(new LabelProvider());
      viewer.addDoubleClickListener(new IDoubleClickListener() {
         public void doubleClick(DoubleClickEvent event) {
            editSelection();
         }
      });
      // A service will be providing our input
      IPersonService service = (IPersonService) getSite().getService(
         IPersonService.class);
      viewerInput = new ArrayList(service.getPeople());
      viewer.setInput(viewerInput);
      ...
      // register myself as a selection provider for this view
      getSite().setSelectionProvider(viewer);

      // prime the selection
      selectionChanged(null, getSite().getPage().getSelection());
   }
</pre>
<P >
The view creates and stores a ListViewer and sets the content and label provides.
It also registers itself as the selection
provider for this view.
(The concept of selection provider, label provider, and content provider come
 from JFace <a href="jface_viewers.htm">viewers</a>.)
It obtains the service from its
<b><a href="../reference/api/org/eclipse/ui/IViewSite.html">IViewSite</a></b>, which contains information about the view's context, such as its workbench window,
its containing page, its local services, and its plug-in.</P>
<p>
</p>
   public void selectionChanged(IWorkbenchPart part, ISelection sel) {
      //if the selection is a readme file, get its sections.
      AdaptableList input = ReadmeModelFactory.getInstance().getSections(sel);
      viewer.setInput(input);
   }
</pre>
<P >
It looks like the <b> ReadmeModelFactory</b> class is responsible for turning the selection into readme
sections and these sections are input for
the viewer that we created in the <b>createPartControl</b>
method.</P>
<P >
But how did the viewer populate its list widgets?&nbsp; For now, let's assume that once the viewer was told its input element, it knew how to populate
its list widget with the information - it is a ListViewer, after all.&nbsp; If you must know right now what this viewer is all about, go to <a HREF="jface_viewers.htm" CLASS="XRef">Viewers</a>.&nbsp;</P>
<P >
We still do not know how readme files are detected or where the file's section
information comes from.&nbsp; A quick look at the
<b> ReadmeModelFactory</b> sheds some light.</P>
<pre>
   public AdaptableList getSections(ISelection sel) {
      // If sel is not a structured selection just return.
      if (!(sel instanceof IStructuredSelection))
         return null;
      IStructuredSelection structured = (IStructuredSelection)sel;

      //if the selection is a readme file, get its sections.
      Object object = structured.getFirstElement();
      if (object instanceof IFile) {
         IFile file = (IFile) object;
         String extension = file.getFileExtension();
         if (extension != null &amp;&amp; extension.equals(IReadmeConstants.EXTENSION)) {
            return getSections(file);
         }
      }

      //the selected object is not a readme file
      return null;
   }
</pre>
<P >We check the selection to see if it is a structured (multiple)
selection.&nbsp; (The concept of a structured selection comes from JFace <a href="jface_viewers.htm">viewers</a>.)&nbsp;
For the first object in the selection, we check to see whether it is a file (<b><a href="../reference/api/org/eclipse/core/resources/IFile.html">IFile</a></b>)
resource.&nbsp; If it is, we check its extension to see if it matches the &quot;<b>.readme</b>&quot;
extension.&nbsp; Once we know we have a readme file, we can use other methods to
parse the sections.&nbsp;&nbsp; You can browse the rest of <b>ReadmeModelFactory</b>,&nbsp;
<b>MarkElement</b>, and <b> DefaultSectionsParser</b> for the
details about the file parsing. </P>
<P >
We've covered a lot of common workbench concepts by studying this extension. Now we'll move on to some other workbench extensions and examine how your plug-in can further contribute to the workbench UI. </P>





</BODY>
</HTML>




of the Command Framework became mature.  In 3.3 the menu contributions portion
of the Command Framework became available.
</p>
<p >
The workbench defines extension points that allow plug-ins to contribute
behaviors to existing views and editors or to provide implementations for
new views and editors. We'll use the Info example from the
contributions plugin.  It provides a view that lists people and an
editor for updating their names. </p>
<p>
We are going to take a look at how commands, handlers, menu contributions,
and keybindings can be used to contribute behaviour to the workbench,
to views, and to editors.  
contributions plugin.  It provides a view that lists people and an
editor for updating their names.  Much of the contribution of editors
and views has already been covered in the readme example in 
<a href="workbench_basicext.htm" 
   class="XRef">Basic workbench extension points using actions</a>.
</p>

<img src="images/contributions_window.png" alt="Picture of the workbench, showing the contributions">





<p>A <b>command</b> is the declaration of a behaviour by <b>id</b>.
Commands are used to declare semantic behaviour so that action implementations defined
elsewhere by handlers. The separation of the command from the behaviour
implementation allows multiple plug-ins to define implementations that implement the
   class="XRef">Basic workbench extension points using actions</a>)
can associate themselves with a particular semantic
command. The separation of the command from the action
implementation allows multiple plug-ins to define actions that implement the
same semantic command. The command is what gets associated with a
particular key binding.</p>


<p>The workbench defines many common commands in its <b>plugin.xml</b>
file, and plug-ins are encouraged to associate their own implementations with these
commands where it makes sense. In this way, semantically similar
behaviour implemented in different plug-ins may share the same key binding.</p>


<h4>Defining a command</h4>



<p>The command definition specifies a <b>name</b>, <b>description</b>, and <b>id</b> for
the behaviour. It also specifies the id of a category for the command, which is
used to group commands in the preferences dialog.&nbsp; The categories are also
defined in the <b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a>
</b>





<h4>Contribution location</h4>
<p>
The <b>org.eclipse.ui.menus</b>
<a href="workbench_menupaths.htm" class="XRef">menu and toolbar paths</a>
to place menu items and tool items.  The <b>org.eclipse.ui.menus</b>
extension point requires the id of a menu, toolbar, or trim area and an insertion
point.  This is the <b>locationURI</b> of a &lt;menuContribution/&gt; element.
Some examples of <b>locationURIs</b>:</p>


<p>
A word about popup: locationURIs.  In <code>popup:id</code>, the id refers to
the id that comes from registering the context menu when the <code>registerContextMenu(*)</code>
method is called.  If an no id is specified in the call, it defaults to the id of
the view or editor registering the context menu.
</p>

</p>

<p>
You can add menu contributions that work similar to <b>org.eclipse.ui.editorActions (Deprecated)</b>.
First you define your editor command and handler, like Reset.  Then you can
add them in an editor menu like &quot;Info&quot; to the main menu:</p>
<pre>

<h4>Contributing to popup menus</h4>

<p>
Commands can be contributed to a specific context menu by the context menu's id, or to any
commands can be contributed to a specific context menu by the context menu's id, or to any
context menu where it can satisfy its &lt;visibleWhen&gt; clause.  For example, we can add
our Refresh command to the Info View popup as a convenience.  Because we didn't call
<code>registerContextMenu(*)</code> with a specific id it defaults to the view id.</p>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Menu and toolbar paths
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">

<h2>
Menu and toolbar paths</h2>
<P >
We've seen many action contributions that specify the path for the location of their action. Let's take a close look at what these paths mean.&nbsp;&nbsp;</P>

<h3 >
Menu paths</h3>

<P >
We'll look at menu paths first by looking at the workbench <b>Help</b> menu.</P>

<H4>
Named groups in the workbench</H4>
<P >
The locations for inserting new menus and menu items are defined using named groups. You can think of
a named group as a slot or placeholder that allows you to insert your menu items
at certain points in a menu bar or pulldown menu.</P>
<P >
The workbench defines all of its group slot names in the classes <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>
and <b><a href="../reference/api/org/eclipse/ui/ide/IIDEActionConstants.html">IIDEActionConstants</a></b>. 
(Two different classes are used since resource-related menu items are factored out of the generic workbench).
For each workbench menu, named groups are placed in the menu at locations where it is expected that
plug-ins will insert new actions.</P>
<P >
The following description of the help menu is adapted from the <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
class definition.</P>
<pre>
   Standard Help menu actions
   Start group - HELP_START - &quot;start&quot;
   End group - HELP_END - &quot;end&quot;
</pre>
<P >
The standard workbench help menu defines a named group called &quot;<b>start</b>,&quot; followed by a named group called &quot;<b>end</b>,&quot;.
Defining two groups gives plug-ins a little more control over where their contributed
items will be positioned within the help menu.&nbsp; When you define a menu, you can define as many slots as you like. Adding more slots gives 
other plug-ins more control over where their contributions appear relative to existing contributions. </P>
<P >
Plug-ins that add a menu item to the help menu can use these group names to decide where their
menu item will go.  For example, the cheatsheet plug-in adds an action
set containing the &quot;Cheat Sheets...&quot; menu to the workbench.&nbsp; Here's
the markup from the <b>org.eclipse.ui.cheatsheets</b> plug-in's
<b>plugin.xml</b>. </P>
<pre>
&lt;extension
	point="org.eclipse.ui.actionSets"&gt;
	&lt;actionSet
		label="%CHEAT_SHEETS"
		visible="true"
		id="org.eclipse.ui.cheatsheets.actionSet"&gt;
		&lt;action
			label="%CHEAT_SHEETS_MENU"
			class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
			<b>menubarPath="help/helpStart"</b>
			id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction"&gt;
		&lt;/action&gt;
	&lt;/actionSet&gt;
&lt;/extension&gt;
</pre>
<P >
The new help action will be placed in the help menu, inside the <b>helpStart</b> group.</P>


<H4>
Fully qualified menu paths</H4>
<P >
 A complete menu path is simply &quot;menu name/group
 name.&quot;&nbsp; Most menu names for the workbench are defined in
<b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>. 
(Resource-related menu names are defined in <b><a href="../reference/api/org/eclipse/ui/ide/IIDEActionConstants.html">IIDEActionConstants</a></b>.)
If we look for the name of the help menu in this class, we'll find
that the fully qualified path name for our help action is
 &quot;<b>help/helpEnd</b>.&quot; </P>
<P >
Some menus have nested submenus. This is where longer paths come into play. If the help menu had defined a submenu 
called &quot;<b>submenu</b>&quot; with a named group called &quot;<b>submenuStart</b>,&quot; 
then the fully qualified menu path for an action in the new submenu would be 
&quot;<b>help/submenu/submenuStart</b>.&quot;</P>


<H4>
<a name="workbench_menus_nls">
Externalizing UI labels</a></H4>
<p>The example above demonstrates a technique for externalizing strings
that appear in the UI.&nbsp; Externalized strings are used to make translating the plug-in's UI to
other languages simpler.&nbsp; We can externalize the strings in our <b>plugin.xml
</b>files by replacing the string with a key (<b>%CHEAT_SHEETS_MENU</b>) and creating entries in the <b>plugin.properties</b>
file of the form:</p>
<pre>
	CHEAT_SHEETS_MENU = Cheat Sheets...
</pre>
<P >
The <b>plugin.properties</b> file can be
translated for different languages and the <b>plugin.xml</b>
will not need to be modified.</P>


<H4>
Adding new menus and groups</H4>
<P >
In many of the examples we've seen so far, the actions contributed by the sample plug-ins have been added to existing named groups within menus.</P>
<P >
The <b><a href="../reference/extension-points/org_eclipse_ui_menus.html">menus</a></b> extension point
allows you to contribute to your menus using an alternative placement syntax, menu ids.
The <b><a href="../reference/extension-points/org_eclipse_ui_actionSets.html">actionSets</a></b>,
<b><a href="../reference/extension-points/org_eclipse_ui_viewActions.html">viewActions</a></b>,
<b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">editorActions</a></b>, and
<b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html"> popupMenus</a></b> extension points also allow you to define new menus and groups within your contribution. This means that you can define new submenus or new
pull-down menus and contribute your actions to these new menus. In this case, the path for your new action will contain the name of your newly defined menu. </P>
<P>
We saw this technique when the readme tool defined a new menu for its action
set.&nbsp; Let's look at the markup one more time now that we've looked at menu
paths in more detail. </P>
<pre>
   &lt;extension point = &quot;org.eclipse.ui.actionSets&quot;&gt;
   &lt;actionSet id=&quot;org_eclipse_ui_examples_readmetool_actionSet&quot;
	   label=&quot;%ActionSet.name&quot;
	   visible=&quot;true&quot;&gt;
	   &lt;<b>menu id=&quot;org_eclipse_ui_examples_readmetool&quot;</b>
		   label=&quot;%ActionSet.menu&quot;
		   <b>path=&quot;window/additions&quot;</b>&gt; 
		   &lt;separator name=&quot;slot1&quot;/&gt;
		   &lt;separator name=&quot;slot2&quot;/&gt;
		   &lt;separator name=&quot;slot3&quot;/&gt;
	   &lt;/menu&gt;
	   &lt;action id=&quot;org_eclipse_ui_examples_readmetool_readmeAction&quot;
		   <b>menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;</b>
		   toolbarPath=&quot;readme&quot;
		   label=&quot;%ReadmeAction.label&quot;
		   tooltip=&quot;%ReadmeAction.tooltip&quot;
		   helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
		   icon=&quot;icons/ctool16/openbrwsr.png&quot;
		   class=&quot;org.eclipse.ui.examples.readmetool.WindowActionDelegate&quot;
		   enablesFor=&quot;1&quot;&gt;
		   &lt;selection class=&quot;org.eclipse.core.resources.IFile&quot;
				name=&quot;*.readme&quot;&gt;
		   &lt;/selection&gt;
	   &lt;/action&gt;
	   ...
</pre>
<P >We added a new menu called&nbsp; &quot;<b>org_eclipse_ui_examples_readmetool</b>&quot;
whose label is defined in by the key &quot;<b>%ActionSet.name</b>&quot; in the
properties file. Within this menu, we define three named
groups:&nbsp; &quot;<b>slot1</b>,&quot; &quot;<b>slot2</b>,&quot;
and &quot;<b>slot3</b>.&quot;&nbsp; We add this new
menu to the path &quot;<b>window/additions</b>.&quot;</P>
<P >If we go back to <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>,
we see this definition of the window menu in the javadoc:</P>
<pre>
    * &lt;h3&gt;Standard Window menu actions&lt;/h3&gt;
    * &lt;ul&gt;
    * &lt;li&gt;Extra Window-like action group (&lt;code&gt;WINDOW_EXT&lt;/code&gt;)&lt;/li&gt; 
</pre>
<P >
If we look further at the class definition, we will see these related
definitions: </P>


<pre>
   public static final String MENU_PREFIX = &quot;&quot;;
   ...
   public static final String M_WINDOW = MENU_PREFIX+&quot;window&quot;;
   ...
   public static final String MB_ADDITIONS = &quot;additions&quot;;  // Group.
   ...
   public static final String WINDOW_EXT = MB_ADDITIONS;   // Group.
</pre>


<P >
From this information, we can piece together the path for adding something to
the workbench &quot;Window&quot; menu.&nbsp; The menu itself is called &quot;<b>window</b>&quot;
and it defines one slot called &quot;<b>additions</b>.&quot;&nbsp;
We use the path &quot;<b>window/additions</b>&quot; to
add our new menu. </P>


<P >
In the action set declaration, we add an action to our newly defined menu, using
the path &quot;<b>window/org_eclipse_ui_examples_readmetool/slot1</b>.&quot; </P>


<P >
<img src="images/readmeactionsetmenu.png" alt="" border="0"> </P>


<P >Other plug-ins could add to our menu by using this same path (or perhaps one
of the other slots) to add one of their own menus.&nbsp;&nbsp; </P>


<P >In the readme tool example, we use the <b>separator</b> attribute to
identify the group names.&nbsp; This will cause a separator line to appear
between these groups when they contain items.&nbsp; We could instead use the <b>groupMarker</b>
attribute if we want to define a named group without showing any separators in
the menu to distinguish between the groups. </P>


<h3 >Tool bar paths </h3>


<p>Tool bar paths work similarly to menu paths.&nbsp;&nbsp;</p>


<h4>Named tool bars in the workbench</h4>


<p>The workbench tool bar is composed of
tool bars contributed by different plug-ins, including the workbench
itself.&nbsp; Within any particular tool bar, there are named groups or slots that can be used for inserting new tool bar items.
&nbsp;&nbsp;&nbsp;</p>
<P >
The following description of the workbench tool bars is adapted from the <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
class definition.</P>
<pre>// Workbench toolbar ids
public static final String TOOLBAR_FILE = &quot;org.eclipse.ui.workbench.file&quot;
public static final String TOOLBAR_NAVIGATE = &quot;org.eclipse.ui.workbench.navigate&quot;; 

// Workbench toolbar group ids.  To add an item at the beginning of the group, 
// use the GROUP id.  To add an item at the end of the group, use the EXT id.
public static final String PIN_GROUP = &quot;pin.group&quot;; 
public static final String HISTORY_GROUP = &quot;history.group&quot;; 
public static final String NEW_GROUP = &quot;new.group&quot;; 
public static final String SAVE_GROUP = &quot;save.group&quot;; 
public static final String BUILD_GROUP = &quot;build.group&quot;; </pre>
<p>In the simplest case, a plug-in can contribute a tool bar item in its own
tool bar.&nbsp; For example, the readme tool actions contributed to the menu are
also given a tool bar path:  </p>
<pre>
&lt;action id=&quot;org_eclipse_ui_examples_readmetool_readmeAction&quot;&nbsp;&nbsp;
   menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;
&nbsp;&nbsp; <b>toolbarPath=&quot;readme&quot;
</b>...</pre>
<p>Since there is no reference to the workbench tool bar paths or groups, the
readme actions appear in their own group on the tool bar.&nbsp; Specifying the
following path would instead place the item in the file tool bar in the save
group:</p>
<pre>...
&lt;action id=&quot;org_eclipse_ui_examples_readmetool_readmeAction&quot;&nbsp;&nbsp;
   menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;
&nbsp;&nbsp; <b>toolbarPath=&quot;org.eclipse.ui.workbench.file/save.group&quot;
</b>...</pre>
<p>The paths defined in <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
 may be referenced in the tool bar paths of other plug-ins.</p>
<h4>Adding to action sets of another plug-in</h4>
<p>Suppose a plug-in wants its tool bar items better integrated with actions
from a different plug-in?&nbsp; Let's look at how the external
tools plug-in (<b>org.eclipse.ui.externaltools</b>) integrates its action with the debugger tool bar.&nbsp; The
debugger (<b>org.eclipse.debug.ui</b>) defines its tool bar actions like this:</p>
<pre>&lt;extension
      point=&quot;org.eclipse.ui.actionSets&quot;&gt;
   &lt;actionSet
         label=&quot;%LaunchActionSet.label&quot;
         visible=&quot;false&quot;
         id=&quot;org.eclipse.debug.ui.launchActionSet&quot;&gt;
   ...
   &lt;action
         <b>toolbarPath=&quot;debug&quot;</b>
         id=&quot;org.eclipse.debug.internal.ui.actions.RunDropDownAction&quot;
         hoverIcon=&quot;icons/full/ctool16/run_exc.png&quot;
         class=&quot;org.eclipse.debug.internal.ui.actions.RunToolbarAction&quot;
         disabledIcon=&quot;icons/full/dtool16/run_exc.png&quot;
         icon=&quot;icons/full/etool16/run_exc.png&quot;
         helpContextId=&quot;run_action_context&quot;
         label=&quot;%RunDropDownAction.label&quot;
         pulldown=&quot;true&quot;&gt;
   &lt;/action&gt;
   ...</pre>
<p>Just like the readme tool, the debugger plug-in defines its own tool bar
path, which means its tool bar items will be inside their own tool bar on the
workbench.&nbsp; What does the external tools plug-in do?</p>
<pre>&lt;extension point=&quot;org.eclipse.ui.actionSets&quot;&gt;
	&lt;actionSet
		id=&quot;org.eclipse.ui.externaltools.ExternalToolsSet&quot;
		label=&quot;%ActionSet.externalTools&quot;
		visible=&quot;true&quot;&gt;
		...
		&lt;action
			id=&quot;org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar&quot;
			definitionId= &quot;org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar&quot;
			label=&quot;%Action.externalTools&quot;
			<b>toolbarPath=&quot;org.eclipse.debug.ui.launchActionSet/debug&quot;</b>
			disabledIcon=&quot;icons/full/dtool16/external_tools.png&quot;
			icon=&quot;icons/full/etool16/external_tools.png&quot;
			hoverIcon=&quot;icons/full/ctool16/external_tools.png&quot;
			tooltip=&quot;%Action.externalToolsTip&quot;
			pulldown=&quot;true&quot;
			class=&quot;org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate&quot;&gt;
		&lt;/action&gt;
	&lt;/actionSet&gt;
&lt;/extension&gt;</pre><p>Note the use of the action set ID of the
debugger in the tool bar path.&nbsp; Using an action set ID in the path denotes
that the tool bar item should be placed in the tool bar used by the referenced
action set.&nbsp;  Within a toolbar group, items are ordered by action set id, so
for our example, the external tools action will appear after the debugger actions.&nbsp;</p>
<p>When adding to an action set's tool bar, new groups can also be defined.&nbsp;
If the external tools plug-in defined its <b> toolbarpath</b> as 
<b>&quot;org.eclipse.debug.ui.launchActionSet/external&quot;</b> a new group would be created 
for the action on the tool bar.&nbsp;  As with menus, tool bar groups are delineated by separators.&nbsp;</p>
<h3 >Using paths from another plug-in </h3>


<P >In general, it's not good practice to contribute to another plug-in's menu
or tool bar by deriving the path name from the <b>plugin.xml</b> unless it has
been marked specifically as being available for clients.&nbsp; It's possible that a future version of the plug-in could change the names of the
paths.&nbsp; Two common ways to mark your plug-in's action set ids and paths as
fair game are: </P>


<ul>
  <li>annotate the XML with comments that explicitly mark the menu path or
    action set as usable by clients</li>
  <li>define a public interface (much like <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>)
which specifies exactly which menus, tool bar groups, and slots are considered
fair game for use by other plug-ins</li>
</ul>





</BODY>
</HTML>




<TD width="118">
<P CLASS="CellBody">
<b>
viewActions</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody">
Actions appear in a specific view's local toolbar and local pulldown menu.</P>
</TD>
<TD width="335">
<P CLASS="CellBody">
Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html">IViewActionDelegate</a></b>. Specify the id of the contribution and the id of the target view that should show the action. The label and image
dictate the appearance of the action in the UI. The path specifies the location relative to the view's menu and toolbar items.</P>
</TD>
</TR>
<TR>
<TD width="118">
<P CLASS="CellBody"><b>editorActions</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody">
Actions are associated with an editor and appear in the workbench menu and/or tool bar.</P>
</TD>
<TD width="335">
<P CLASS="CellBody">
Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>. Specify the id of the contribution and the id of the target editor that causes the action to be shown. The label and image specify the appearance of the action in the UI. Separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.</P>
</TD>
</TR>
<TR>
<TD width="118">
<P CLASS="CellBody">
<b>
popupMenus</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody">
Actions appear in the popup menu of an editor or view. Actions associated with an object type show up in all popups of views
and editors that show the object type. Actions associated with a specific popup menu appear only in that popup menu.</P>
</TD>
<TD width="335">
<P CLASS="CellBody">
<b>
Object contributions</b> specify the type of object for which the action should appear in a popup menu. The action will be shown in all view
and editor popups
that contain the object type.&nbsp; Provide an action class that implements <b><a href="../reference/api/org/eclipse/ui/IObjectActionDelegate.html">IObjectActionDelegate</a></b>.&nbsp;<BR>
<b>
Viewer contributions</b> specify the id of the target popup menu in which the menu item should appear.&nbsp;
Provide an action class that implements <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>
or <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html">IViewActionDelegate</a></b>.&nbsp;</P>
</TD>
</TR>
<TR>
<TD width="118">
<P CLASS="CellBody">
<b>
actionSets</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody">
Actions appear in the workbench main menus and toolbar. Actions are grouped into action sets. All actions in an action set will show up in the workbench menus and toolbars according to the user's selection of action sets
and the current perspective shown in the workbench.&nbsp; May be influenced by
actionSetPartAssociations (below).</P>
</TD>
<TD width="335">
<P CLASS="CellBody">
Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowActionDelegate.html"> IWorkbenchWindowActionDelegate</a></b> or
<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowPulldownDelegate.html">IWorkbenchWindowPulldownDelegate</a></b>. Specify the
<b> name</b> and <b> id</b> of the action set. Enumerate all of the actions that are defined for that action set. For each action, separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.</P>
</TD>
</TR>
<tr>
<TD width="118">
<P CLASS="CellBody">
<b>
actionSetPartAssociations</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody"> Actions sets are shown only when the specified views or
editors are active.&nbsp; This is ignored if the user has customized the current
perspective.</P>
</TD>
<TD width="335">
<P CLASS="CellBody">
Specify an action set by <b>id</b> and followed by one or more parts (by <b>id</b>)
that must be active in the current perspective in order to show the action set.</P>
</TD>
</tr>
<TR>
<TD width="118">
<P CLASS="CellBody">
<b>
menus</b></P>
</TD>
<TD width="359">
<P CLASS="CellBody">
Commands can be placed in the main menu and toolbar.  Command can be placed in
part context menus, as well as view menus and view toolbars.  The placement
is controlled by the <b>locationURI</b> and the visibility is controlled by
the <b>visibleWhen</b> core expression.
</P>
</TD>
<TD width="335">

</TABLE>


<p>This replaces the old action extension points, <b>actionSets</b>, <b>editorActions</b>,
<b>viewActions</b>, 
<b>popupMenus</b>,
and <b>actionSetPartAssociations</b>.
</p>


</BODY>




<H2>
The plug-in class</H2>
<P >
So far, we've been looking at the different extensions that are provided by the contributions plug-in. Let's look at the general 
definition of the contributions plug-in.</P>

<H3>
Plug-in definition</H3>

<pre>
Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: %contributions.Activator.name
Bundle-SymbolicName: org.eclipse.ui.examples.contributions; singleton:=true
Bundle-Version: 3.3.100.qualifier
Bundle-Activator: org.eclipse.ui.examples.contributions.Activator
Require-Bundle: org.eclipse.ui;bundle-version="[3.3.0,4.0.0)",
Bundle-Vendor: %Plugin.providerName
Bundle-Localization: plugin
Require-Bundle: org.eclipse.ui,
 org.eclipse.core.resources,
 org.eclipse.core.runtime,
 org.eclipse.core.expressions;bundle-version="[3.3.0,4.0.0)"
Bundle-Vendor: %contributions.Activator.providerName
Bundle-Localization: plugin
Bundle-RequiredExecutionEnvironment: J2SE-1.4
Bundle-ActivationPolicy: lazy
 org.eclipse.ui.editors
Eclipse-AutoStart: true
Eclipse-AutoStart-comment: Use Eclipse-AutoStart instead of Eclipse-LazyStart because the readme example should run against 3.1 as well as 3.2.
</pre>
<P >
The plug-in definition includes the <b>Bundle-Name</b>, <b>Bundle-SymbolicName</b> (plug-in id),
<b>Bundle-Version</b>, and <b>Bundle-Vendor</b> of the plug-in. We 
saw most of these parameters before in our hello world plug-in. The contribution plug-in
also defines a specialized plug-in class,
<b>org.eclipse.ui.examples.contributions.Activator</b>. </P>
The name of the jar file is also provided. File names specified in <b>Bundle-ClassPath</b> are relative to the
plug-in's directory, so the readme tool's jar file should be located directly in the plug-in's directory.</P>
<P >
The <b>Require-Bundle</b> element informs the platform of the contribution plug-in's dependencies. 
The workbench UI plug-ins are listed as required plug-ins, along with the various core and expression plug-ins.  </P>

<H3>
AbstractUIPlugin</H3>
<P >
The<b> Activator</b> class represents the contribution plug-in 
and manages the life cycle of the plug-in.&nbsp; As we saw in the
Hello World example, you don't have to specify a plug-in class.&nbsp; The
platform will provide one for you.&nbsp; In this case, our plug-in needs to
initialize UI related data when it starts up.&nbsp; 
The platform class <a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>
provides a structure for managing UI resources and is extended by <b>
Activator</b>.</P>
<P >
<a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>
 uses the generic startup and shutdown methods to manage images, dialog settings, and a preference store during the lifetime of the plug-in.&nbsp;
</P>




Lines 32-38 Link Here

(-)guide/wrkAdv.htm (-1 / +1 lines)
32	<li><a href="swt.htm">SWT</a></li>	32	<li><a href="swt.htm">SWT</a></li>
33	<li><a href="resInt.htm">Resources overview</a></li>	33	<li><a href="resInt.htm">Resources overview</a></li>
34	</ul>	34	</ul>
35	Since the readme tool does not contribute to all of these extension	35	Since the contributions plug-in does not contribute to all of these extension
36	points, we will look at example extensions that are implemented by the platform	36	points, we will look at example extensions that are implemented by the platform
37	workbench, the platform help system, and Java tooling (JDT).	37	workbench, the platform help system, and Java tooling (JDT).
38	<p>When using any of these workbench features, it is a good idea to	38	<p>When using any of these workbench features, it is a good idea to






<pre>...
      &lt;key <b>commandId="org.eclipse.ui.file.save"</b>
            contextId="org.eclipse.ui.contexts.window"
            schemeId="org.eclipse.ui.examples.contributions.scheme"
            <b>sequence="CTRL+S"</b>&gt;
      &lt;/key&gt;
...</pre>


<p>There is our friend <b>org.eclipse.ui.file.save</b>.  In Eclipse, the workbench registers
the <b>SaveAction</b> as a handler for this command id in every Workbench Window.</p>

<pre>&lt;extension point = &quot;org.eclipse.ui.actionSets&quot;&gt;
	   &lt;actionSet id=&quot;com.example.actions.actionSet&quot;
		   label=&quot;Example Actions&quot;
		   visible=&quot;true&quot;&gt;
		   &lt;action id=&quot;com.example.actions.action1&quot;
			   menubarPath=&quot;additions&quot;
			   label=&quot;Example Save Action&quot;
			   class=&quot;org.example.actions.ExampleActionDelegate&quot;
			   <b>definitionId=&quot;org.eclipse.ui.file.save&quot;</b>&gt;
		   &lt;/action&gt;
		   ...
	   &lt;/actionSet&gt;
&lt;/extension&gt;</pre>
<p>The <b>sequence</b> attribute for a key binding defines the key
combination that is used to invoke a command.&nbsp; When the
workbench <b>SaveAction</b> is active, the key combination <kbd>CTRL+S</kbd> will invoke it,
since the workbench uses the same command id for its <b>SaveAction</b>.</p>

<p> Likewise, when the
workbench <b>SaveAction</b> is active, the same key combination will invoke it
instead, since the workbench uses the same command id for its <b>SaveAction</b>.</p>


<p>To complete the example, we need to understand what the <b>configuration</b>
is all about.</p>



</BODY>




<h3>Commands</h3>

<p>See the <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a>
section for creating command definitions, hooking them up with keybindings, and placing
them in menus.
</p>

<h4>Associating a legacy action with a command</h4>


<p>When still using the old legacy action extension points, actions can be associated with a 
command in code or in the <b>plugin.xml
</b>for action sets.&nbsp;
Your choice depends on where the action is defined.</p>

<p>
Instead of using an <b>IAction</b> you should prefer activating an 
<a href="../reference/api/org/eclipse/core/commands/AbstractHandler.html"><b>AbstractHandler</b></a>.
</p>
<pre>
    // IWorkbench, IWorkbenchWindow, and IWorkbenchPartSite are all IServiceLocators
    IHandlerService handlerService = (IHandlerService) locator.getService(IHandlerService.class);
    handlerService.activateHandler(org.eclipse.ui.IWorkbenchCommandConstants.FILE_SAVE, new MySaveHandler());
</pre>



<p>But when working with actions, actions that are instantiated in code can also be associated with an action
definition using <a href="../reference/api/org/eclipse/jface/action/IAction.html"><b>IAction</b></a>
protocol.&nbsp; This is typically done when the action is created.&nbsp; The <b>SaveAction</b>
uses this technique when it initializes itself. </p>

the command id that was used in the command definition markup. It is good practice to define constants for your action definitions so that
they are easily referenced in code. </p>


<p> If you define an
action in an action set, then you typically do not need to
instantiate an action yourself.&nbsp; The workbench will do it for you when the user




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Retargetable actions
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h2>Retargetable actions</h2>
<p>It is common for a plug-in's views and editors to implement actions that are
semantically similar to existing workbench actions, such as clipboard
cut/copy/paste, view refresh, or properties.&nbsp; The popup menu for views and
editors can become quite cluttered if every view or editor has to define unique
actions for these operations and include them in their menus.&nbsp; </p>


<p>To solve this problem, the workbench defines <b>retargetable</b> (also called
<b>global</b>) actions that can be handled by any view or editor.&nbsp; When a
view or editor is active, its handler will be run when the user chooses the
action from the workbench menu or toolbar.&nbsp; This allows views and editors
to share workbench menu space for semantically similar actions. </p>


<p><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b>IWorkbenchActionConstants</b></a>
documents all of the workbench actions and denotes retargetable actions as
global.&nbsp; For example, here is the definition of the <b>Properties</b> action.</p>


<pre>public static final String PROPERTIES = &quot;properties&quot;; // Global action. </pre>


<p>The following table summarizes some of the more common retargetable actions
that are implemented by views and editors:</p>


<table border="1" cellpadding="0" cellspacing="0" width="64%">
  <tr>
    <td width="20%">&nbsp;</td>
    <td width="20%"><b>File menu</b></td>
    <td width="20%"><b>Edit menu</b></td>
    <td width="20%"><b>Navigate menu</b></td>
    <td width="20%"><b>Project menu</b></td>
  </tr>
  <tr>
    <td width="20%"><b>views</b></td>
    <td width="20%">move<br>
      rename<br>
      refresh<br>
      properties</td>
    <td width="20%">&nbsp;</td>
    <td width="20%">go into<br>
      go to resource<br>
      sync with editor<br>
      back<br>
      forward<br>
      up<br>
      next<br>
      previous</td>
    <td width="20%">open<br>
      close<br>
      build<br>
      rebuild</td>
  </tr>
  <tr>
    <td width="20%"><b>editors</b></td>
    <td width="20%">revert<br>
      print</td>
    <td width="20%">find</td>
    <td width="20%">&nbsp;</td>
    <td width="20%">&nbsp;</td>
  </tr>
  <tr>
    <td width="20%"><b>views and editors</b></td>
    <td width="20%">&nbsp;</td>
    <td width="20%">cut<br>
      copy<br>
      paste<br>
      delete<br>
      select all<br>
      undo<br>
      redo</td>
    <td width="20%">&nbsp;</td>
    <td width="20%">&nbsp;</td>
  </tr>
</table>
<p>Retargetable actions are created using <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>.&nbsp;
The following snippet is from <b>WorkbenchActionBuilder</b>.</p>


<pre> propertiesAction = createGlobalAction(IWorkbenchActionConstants.PROPERTIES, &quot;file&quot;, false); </pre>


<p>The <b> createGlobalAction</b> method shows us exactly how to make a <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>.</p>


<pre>private RetargetAction createGlobalAction(String id, String actionDefPrefix, boolean labelRetarget) {
	RetargetAction action;
	if (labelRetarget) {
		action = new LabelRetargetAction(id, WorkbenchMessages.getString(&quot;Workbench.&quot; + id)); 
	}
	else {
		action = new RetargetAction(id, WorkbenchMessages.getString(&quot;Workbench.&quot; + id)); 
	}
	...
	return action;
}</pre>

<p>When creating a retargetable action, the workbench assigns the id for the
action and the default label.&nbsp; Note that there are two styles of retarget actions.&nbsp; <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
</b>simply allows a view or editor to reimplement an action.&nbsp; <b><a href="../reference/api/org/eclipse/ui/actions/LabelRetargetAction.html">LabelRetargetAction</a>
</b>also allows views and editors to reset the label of the action.&nbsp;&nbsp;
This is useful for making the menu label more specific, such as relabeling an <b>Undo</b>
action as <b>Undo Typing</b>.&nbsp;&nbsp;</p>


<p>Now we know how the retarget actions are defined by the workbench.&nbsp; Let's look
next at how your view or editor can provide an implementation for a retargetable action.&nbsp;
This is done by <a href="wrkAdv_retarget_setting.htm">setting a global action
handler</a>.</p>



</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Contributing new retargetable actions
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h3>Contributing new retargetable actions</h3>
<p>The workbench is not the only plug-in that can create retargetable
actions.&nbsp; Your plug-in can define its own retargetable action, so that
views and editors within your plug-in can share the same menu actions.&nbsp;
There are two ways to contribute retargetable actions from your plug-in:</p>
<ul>
  <li>An <b>editor</b> can define a retargetable action for which the editor and
    related views can hook handlers.&nbsp; The action is only available in the
    menu bar when the editor is open.&nbsp;&nbsp;</li>
  <li>An <b>action set</b> can define a retargetable action for which editors
    and views can hook handlers.&nbsp; The action will be visible as long as the
    action set is visible, but it will only be enabled if the active part has
    hooked a handler for the action.</li>
</ul>
<p>This mechanism is useful for providing tight integration between editors and
related views.&nbsp; For example, a content outline view can implement a handler
for an action defined by its associated editor.&nbsp;&nbsp;</p>
<p>The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
tool</a> example demonstrates both of these techniques.</p>



</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Retargetable action set actions
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h4>Retargetable action set actions</h4>
<p>The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
tool</a> action set also defines retargetable actions.&nbsp; The action remains
visible as long as the readme action set is visible, but it is only enabled when
a view or editor that implements the action is active.&nbsp; When using action
sets to define retargetable actions, the actions are created in the action set
markup rather than in code.&nbsp; The following is from the readme tool's action
set definition:</p>
<pre>&lt;extension point = &quot;org.eclipse.ui.actionSets&quot;&gt;
	   &lt;actionSet id=&quot;org_eclipse_ui_examples_readmetool_actionSet&quot;
		   label=&quot;%ActionSet.name&quot;
		   visible=&quot;true&quot;&gt;
...
&lt;action id=&quot;org_eclipse_ui_examples_readmetool_readmeRetargetAction&quot;
   menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;
   toolbarPath=&quot;readme&quot;
   label=&quot;%ReadmeRetargetAction.label&quot;
   tooltip=&quot;%ReadmeRetargetAction.tooltip&quot;
   helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
   icon=&quot;icons/ctool16/openbrwsr.png&quot;
   <b>retarget=&quot;true&quot;</b>&gt;
&lt;/action&gt;
&lt;action id=&quot;org_eclipse_ui_examples_readmetool_readmeRelabelRetargetAction&quot;
   menubarPath=&quot;window/org_eclipse_ui_examples_readmetool/slot1&quot;
   toolbarPath=&quot;readme&quot;
   label=&quot;%ReadmeRelabelRetargetAction.label&quot;
   tooltip=&quot;%ReadmeRelabelRetargetAction.tooltip&quot;
   helpContextId=&quot;org.eclipse.ui.examples.readmetool.open_browser_action_context&quot;
   icon=&quot;icons/ctool16/openbrwsr.png&quot;
   <b>retarget=&quot;true&quot;	</b>
   <b>allowLabelUpdate=&quot;true&quot;</b>&gt;
&lt;/action&gt;
...</pre>
<p>Retargeted actions are specified by using the <b>retarget=&quot;true&quot;</b>
attribute.&nbsp; This will cause a <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>
to be created in the action set.&nbsp; Note that the retargetable actions do not specify an implementing
<b>class</b> since it is up to each view or editor in the plug-in to set up a
handler that implements each action.&nbsp; If the <b>allowLabelUpdate</b>  is
true, then a <b><a href="../reference/api/org/eclipse/ui/actions/LabelRetargetAction.html">LabelRetargetAction</a>
</b>will be created instead.</p>
<p>The retargeted actions will be visible in the window menu when the readme
action set is visible.&nbsp; However, they will not be enabled if the readme
tool's editor or outline view are not active.</p>
<p><img src="images/readmeactionsetmenu.png" alt="Readme File Editor menu with two grayed items and one enabled item" border="0"></p>
<p>&nbsp;</p>
<p>What do the editor and view have to do?&nbsp; Again, the client side is
similar to registering a handler for the workbench or an editor's retargetable
action.&nbsp; The action id specified in the markup must be used when
registering a global action handler.</p>
<p>The <b>ReadmeEditorActionBarContributor </b>takes care of this for the
editor.&nbsp; First, it defines the handlers for the actions.</p>
<pre>public ReadmeEditorActionBarContributor() {
	...
	handler4 = new EditorAction(MessageUtil.getString(&quot;Editor_Action4&quot;)); 
	handler5 = new EditorAction(MessageUtil.getString(&quot;Editor_Action5&quot;)); 
	handler5.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action5&quot;));
	...
}</pre>
<p>The handlers are registered at the same time that the handlers for the editor
retargetable actions were registered.</p>
<pre>public void init(IActionBars bars, IWorkbenchPage page) {
	...
	bars.setGlobalActionHandler(IReadmeConstants.ACTION_SET_RETARGET4, handler4);
	bars.setGlobalActionHandler(IReadmeConstants.ACTION_SET_LABELRETARGET5, handler5);
	...
}</pre>
<p>Recall that action bar contributors are shared among different instances of
the same editor.&nbsp; This means the handlers must be notified if the active
editor for the <b>ReadmeEditorActionBarContributor </b>changes.</p>
<pre>public void setActiveEditor(IEditorPart editor) {
	...
	handler4.setActiveEditor(editor);
	handler5.setActiveEditor(editor);
	...
}</pre>
<p>That's it for the editor.&nbsp; We should see these actions enable when the
editor is activated.</p>
<p><img src="images/actionseteditorretargets.png" alt="Readme File Editor menu with actions enabled" border="0">&nbsp;</p>
<p>Note that the label for the first retargetable action (&quot;Editor Action
4&quot;) was not used since the action set XML markup did not set <b>allowLabelUpdate</b>.</p>
<p>The <b>ReadmeContentOutlinePage</b>
 defines its handlers in the same place it defined handlers for the editor's
retargetable actions:</p>
<pre>public void createControl(Composite parent) {
	...
	action = new OutlineAction(MessageUtil.getString(&quot;Outline_Action4&quot;)); 
	getSite().getActionBars().setGlobalActionHandler(
		IReadmeConstants.ACTION_SET_RETARGET4, 
		action);  
	action = new OutlineAction(MessageUtil.getString(&quot;Outline_Action5&quot;)); 
	action.setToolTipText(MessageUtil.getString(&quot;Readme_Outline_Action5&quot;)); 
	getSite().getActionBars().setGlobalActionHandler(
		IReadmeConstants.ACTION_SET_LABELRETARGET5, 
		action);  
}</pre>
<p>We should see its relabeled action when the content outliner is active.</p>
<p><img src="images/actionsetoutlineretargets.png" alt="Readme File Editor menu with renamed action" border="0"></p>
<h4>&nbsp;</h4>



</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Retargetable editor actions
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h4>Retargetable editor actions</h4>
<p>Recall that the <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
tool</a> defines its own editor which contributes actions
to the workbench menu bar using its <b>ReadmeEditorActionBarContributor</b>.&nbsp;&nbsp;</p>
<pre>&lt;extension
    point = &quot;org.eclipse.ui.editors&quot;&gt;
	&lt;editor
  	   id = &quot;org.eclipse.ui.examples.readmetool.ReadmeEditor&quot;
  	   name=&quot;%Editors.ReadmeEditor&quot;
      	   icon=&quot;icons/obj16/editor.png&quot;
      	   class=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditor&quot;
	   extensions=&quot;readme&quot;
           <b>contributorClass=&quot;org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor</b>&quot;&gt;
	&lt;/editor&gt;
&lt;/extension&gt;</pre>
<p>Let's look closer at what happens in the contributor class.</p>
<pre>public ReadmeEditorActionBarContributor() {
	...
	action2 = new <b>RetargetAction</b>(<b>IReadmeConstants.RETARGET2</b>, MessageUtil.getString(&quot;Editor_Action2&quot;));
	action2.setToolTipText(MessageUtil.getString(&quot;Readme_Editor_Action2&quot;));
	action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
	action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
	...
	action3 = new <b>LabelRetargetAction</b>(<b>IReadmeConstants.LABELRETARGET3</b>, MessageUtil.getString(&quot;Editor_Action3&quot;));
	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
	...&nbsp;&nbsp;
	<b>handler2</b> = new EditorAction(MessageUtil.getString(&quot;Editor_Action2&quot;)); 
	...
	<b>handler3</b> = new EditorAction(MessageUtil.getString(&quot;Editor_Action3&quot;)); 
	...</pre>
<p>When the contributor is created, it creates two retargetable actions (one
that allows label update and one that does not).&nbsp; Creation of the actions
uses the same technique that the workbench uses.&nbsp; It also creates two
handlers that will be used for the actions when the editor is the active
part.&nbsp;&nbsp;</p>
<p>But where are the handlers for the actions registered?&nbsp; Setting the
global handlers is done a little differently when your editor defines the
retargeted actions.&nbsp; Why?&nbsp; Because your contributor is in charge of
tracking the active view and hooking different handlers as different views or
the editor itself becomes active.&nbsp; (The workbench does this for you when
you set a handler for one of its global actions).&nbsp; Here's how the <b>ReadmeEditorActionBarContributor</b>
sets things up:</p>
<pre>public void init(IActionBars bars, IWorkbenchPage page) {
	super.init(bars, page);
	bars.setGlobalActionHandler(IReadmeConstants.RETARGET2, handler2);
	bars.setGlobalActionHandler(IReadmeConstants.LABELRETARGET3, handler3);
	...</pre>
<p>First, the contributor registers its handlers for the retargeted
actions.&nbsp; This ensures that the contributor's actions will be run when the
editor itself is active.&nbsp; The next step is to register each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
</b>as a part listener on the page.</p>
<pre>	...
	// Hook retarget actions as page listeners
	page.addPartListener(action2);
	page.addPartListener(action3);
	IWorkbenchPart activePart = page.getActivePart();
	if (activePart != null) {
		action2.partActivated(activePart);
		action3.partActivated(activePart);
	}
}</pre>
<p>Adding each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
</b>as a part listener means that it will be notified when the active part
changes.&nbsp; The action can get the correct global handler from the newly
activated part.&nbsp; (See the implementation of <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
</b>for all the details.)&nbsp;&nbsp; Note that to start, the action is seeded
with the currently active part. </p>
<p>When the editor contributor is disposed, it should unhook the retargetable
actions as page listeners.</p>
<pre>public void dispose() {
	// Remove retarget actions as page listeners
	getPage().removePartListener(action2);
	getPage().removePartListener(action3);
}</pre>
<p>Finally, recall that action bar contributors are shared among instances of
the same editor class.&nbsp; For this reason, the handlers must be notified when
the active editor changes so that they can connect to the proper editor
instance.</p>
<pre>public void setActiveEditor(IEditorPart editor) {
	...
	handler2.setActiveEditor(editor);
	handler3.setActiveEditor(editor);
	...
}</pre>
<p>That completes the setup on the editor side.&nbsp; When the editor is open
and active, the handlers (and their labels) as defined by the <b>ReadmeEditorActionBarContributor
</b>will appear in the workbench menu bar.</p>
<p><img src="images/editorretargets.png" alt="Readme menu with three editor actions in workbench menu bar" border="0"></p>
<p>Now that the editor's contributions are in place, what does a view do to register a handler?&nbsp; The code on the client side
is similar to registering a handler for a workbench action, except that the
action id is the one defined by the plug-in's editor.&nbsp; The <b>ReadmeContentOutlinePage</b>
registers a handler for these actions.</p>
<pre>public void createControl(Composite parent) {
	super.createControl(parent);
	...
	getSite().getActionBars().<b>setGlobalActionHandler(
		IReadmeConstants.RETARGET2, </b>
		new OutlineAction(MessageUtil.getString(&quot;Outline_Action2&quot;)));  

	OutlineAction action = new OutlineAction(MessageUtil.getString(&quot;Outline_Action3&quot;)); 
	<b>action.setToolTipText(MessageUtil.getString(&quot;Readme_Outline_Action3&quot;)); </b>
	getSite().getActionBars().<b>setGlobalActionHandler(
		IReadmeConstants.LABELRETARGET3, </b>
		action);  
	...</pre>
<p>Note that the outliner sets tool tip text and a label on the second action,
since it allows relabeling.&nbsp; When the readme outliner view is made active,
its handlers (and their labels) will now appear in the workbench menu bar.</p>
<p><img src="images/editoroutlineretargets.png" alt="Readme menu with one renamed editor action" border="0"></p>
<p>Note that the relabeled action shows the new label.</p>



</BODY>
</HTML>




<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
<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">
<TITLE>
Setting a global action handler
</TITLE>

<link rel="stylesheet" type="text/css" HREF="../book.css">
</HEAD>
<BODY BGCOLOR="#ffffff">
<h3>Setting a global action handler</h3>
<p>A plug-in contributes a <a href="wrkAdv_retarget.htm">retargetable action</a>
for a view or editor part by implementing an <a href="../reference/api/org/eclipse/jface/action/IAction.html"><b>IAction</b></a>
and registering it as a global action handler with the part's action bars.&nbsp;
In views, this is usually done at the time that the part creates its actions and
controls. For editors see <a href="wrkAdv_retarget_contribute_editors.htm">Retargetable editor actions</a>.
The name of the retargeted action (as defined in <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b>IWorkbenchActionConstants</b></a>)
is used to specify which action the handler is intended for.&nbsp; The following
shows how the workbench task list view registers its handler for the <b>PROPERTIES</b>
action.</p>
<pre>public void createPartControl(Composite parent) {
	...
	<b>makeActions();</b>
	...

	// Add global action handlers.
	...	
	getViewSite().getActionBars().<b>setGlobalActionHandler(
		IWorkbenchActionConstants.PROPERTIES,
		propertiesAction);</b>
	...</pre>
<p>The properties action is created in the local method <b>makeActions</b>:</p>
<pre>void makeActions() {
	...
	// properties
	propertiesAction = new TaskPropertiesAction(this, &quot;properties&quot;); 
	propertiesAction.setText(TaskListMessages.getString(&quot;Properties.text&quot;)); 
	propertiesAction.setToolTipText(TaskListMessages.getString(&quot;Properties.tooltip&quot;)); 
	propertiesAction.setEnabled(false);
}</pre>
<p>That's all that is needed.&nbsp; Your action will be run when the user
chooses the action from the workbench menu bar or tool bar and your view or
editor is active.&nbsp; The workbench handles the details of ensuring that the
retargeted action is always associated with the currently active view.  The
same applies to editor actions supplied through the EditorActionBarContributor.
</p>



</BODY>
</HTML>




</HEAD>
<BODY BGCOLOR="#ffffff">
<h2>Undoable operations</h2>
<p>We've looked at many different ways to contribute commands to the workbench, but we
haven't focused on the implementation of a command's <tt>execute(ExecutionEvent)</tt> method.
The mechanics
of the method depend on the specific command in question, but structuring the code as an
<b>undoable operation</b> allows the command to participate in the platform undo and redo
support.</p>
<p>
The platform provides an <b>undoable operations framework</b> in the package
<b><a href="../reference/api/org/eclipse/core/commands/operations/package-summary.html">org.eclipse.core.commands.operations</a></b>.
By implementing the code inside a <tt>execute(ExecutionEvent)</tt> method to create an
<a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>,
the operation can be made available for undo and redo.  Converting an command or action to use operations is straightforward, 
apart from implementing the undo and redo behavior itself.</p>
<h3>Writing an undoable operation</h3>
<p>
We'll start by looking at a very simple example.  Recall the simple
example in <b>org.eclipse.ui.examples.contributions.editor.DeltaInfoHandler</b>.
It builds a string and then opens a dialog.</p>
<pre>
public Object execute(ExecutionEvent event) throws ExecutionException {
        // Build the string buffer "buf"
        MessageDialog.openInformation(editor.getSite().getShell(),
                        ContributionMessages.DeltaInfoHandler_shellTitle, buf
                                        .toString());
        return null;
}
</pre>

Using operations, the execute method is responsible for creating an operation that does
the work formerly done in the execute method, and requesting that an <b>operations history</b> 
execute the operation, so that it can be remembered for undo and redo.
<pre>
public Object execute(ExecutionEvent event) throws ExecutionException {
        IUndoableOperation operation = new DeltaInfoOperation(
                        editor.getSite().getShell());
        operationHistory.execute(operation, null, null);
        return null;
}
</pre>
The operation encapsulates the old behavior from the run method, as well as the undo
and redo for the operation.
<pre>
class DeltaInfoOperation extends AbstractOperation {
	Shell shell;
	public DeltaInfoOperation(Shell shell) {
		super(&quot;Delta Operation&quot;);
		this.shell = shell;
	}
	public IStatus execute(IProgressMonitor monitor, IAdaptable info) {
        // Build the string buffer &quot;buf&quot;
        MessageDialog.openInformation(shell,
                        ContributionMessages.DeltaInfoHandler_shellTitle, buf
                                        .toString());
		return Status.OK_STATUS;
	}
	public IStatus undo(IProgressMonitor monitor, IAdaptable info) {
        // Build the string buffer &quot;buf&quot;
        MessageDialog.openInformation(shell,
                        ContributionMessages.DeltaInfoHandler_shellTitle,
                        &quot;Undoing delta calculation&quot;);
		return Status.OK_STATUS;
	}
	public IStatus redo(IProgressMonitor monitor, IAdaptable info) {
        // Build the string buffer &quot;buf&quot;
        // simply re-calculate the delta
        MessageDialog.openInformation(shell,
                        ContributionMessages.DeltaInfoHandler_shellTitle, buf
                                        .toString());
		return Status.OK_STATUS;
	}
}
</pre>

<p>
For simple commands, it may be possible to move all of the nuts and bolt work into the operation class.
In this case, it may be appropriate to collapse the former handler classes into a single handler class
that is parameterized.  The handler would simply execute the supplied operation when it is time to execute.
This is largely an application design decision.  
</p>
<p>
When a command launches a wizard, then the operation is typically created as part of the wizard's 
<tt>performFinish()</tt> method or a wizard page's <tt>finish()</tt> method.  Converting the <tt>finish</tt> method
to use operations is similar to converting an <tt>execute</tt> method.  The method is responsible for creating
and executing an operation that does the work previously done inline.
</p>
<h3>Operation history</h3>

So far we've used an <b>operations history</b> without really explaining it.
Let's look again at the code that creates our example operation.</p>
<pre>
public Object execute(ExecutionEvent event) throws ExecutionException {
        IUndoableOperation operation = new DeltaInfoOperation(
                        editor.getSite().getShell());
        ...
        operationHistory.execute(operation, null, null);
        return null;
}
</pre>
What is the <b>operation history</b> all about?  

operation history and also provides protocol to access it.  The following snippet demonstrates how to
obtain the operation history from the workbench. </p>
<pre>
IWorkbench workbench = editor.getSite().getWorkbenchWindow().getWorkbench();
IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();
</pre>
Once an operation history is obtained, it can be used to query the undo or redo history, find out which operation

Undo contexts can be created by the plug-in that is creating the undoable operations, or accessed through API.  For
example, the workbench provides access to an undo context that can be used for workbench-wide operations.  However they
are obtained, undo contexts should be assigned when an operation is created.  The following snippet shows how the
<tt>execute</tt> method could assign a workbench-wide context to its operations.
</p>
<pre>
public Object execute(ExecutionEvent event) throws ExecutionException {
        IUndoableOperation operation = new DeltaInfoOperation(
                        editor.getSite().getShell());
        ...
        IWorkbench workbench = editor.getSite().getWorkbenchWindow().getWorkbench();
        IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();
        IUndoContext undoContext = workbench.getOperationSupport().getUndoContext();
        operation.addContext(undoContext);
        operationHistory.execute(operation, null, null);
        return null;
}
</pre>
<p>

Whenever an operation is executed, undone, or redone using operation history protocol, clients can
provide a progress monitor and any additional UI info that may be needed for performing the operation.
This information is passed to the operation itself.  In our original
example, the <tt>execute</tt> method constructed an operation with a shell parameter that could be used to open
the dialog.  Instead of storing the shell in the operation, a better approach is to pass parameters
to the execute, undo, and redo methods that provide any UI information needed to run the operation.  These
parameters will be passed on to the operation itself.</p>
<pre>public Object execute(ExecutionEvent event) throws ExecutionException {
        IUndoableOperation operation = new DeltaInfoOperation(
                        editor.getSite().getShell());
        ...
        <b>operationHistory.execute(operation, null, infoAdapter);</b>
        return null;
}
</pre> 
The <b>infoAdapter</b> is an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a>

	if (info != null) {
		Shell shell = (Shell)info.getAdapter(Shell.class);
		if (shell != null) {
			// Build the string buffer &quot;buf&quot;
			MessageDialog.openInformation(shell,
					ContributionMessages.DeltaInfoHandler_shellTitle, buf
							.toString());
			return Status.OK_STATUS;
		}
	}

}
</pre> 

<h3>Undo and redo action handlers (Deprecated)</h3>
<p>The platform provides standard undo and redo <b>retargetable action handlers</b> 
that can be configured by views and editors to provide undo and redo support for their particular context.  When the 
action handler is created, a context is assigned to it so that the operations history is filtered in a way appropriate for
that particular view.  The action handlers take care of updating the undo and redo labels to show the current




    content outliner for an editor?</a></li>
  <li><a href="../guide/preferences_prefs.htm">How do I add a page to the
    preferences dialog?</a></li>
  <li><a href="../guide/workbench_cmd.htm">Where should I start learning
    how to extend the workbench UI?</a></li>
  <li><a href="../reference/extension-points/index.html">What extension points
    are defined by the workbench UI?</a></li>
  <li><a href="../guide/workbench_menus.htm">How do I add a menu to the
    workbench?</a></li>
  <li><a href="../guide/workbench_cmd_menus.htm">How do I
    specify menu and toolbar paths?</a></li>
  <li><a href="../guide/workbench_cmd.htm">How do I implement common actions
    like cut/copy/paste?</a></li>
  <li><a href="../guide/jface_resources.htm">How should I manage the icons in my
    plug-in?</a></li>





	<topic label="Plugging into the workbench"  href="guide/workbench.htm">
		<topic label="Workbench under the covers" href="guide/workbench_structure.htm" />
		<topic label="Basic workbench extension points using commands" href="guide/workbench_cmd.htm" >
			<topic label="org.eclipse.ui.views" href="guide/workbench_basicext_views.htm" />
			<topic label="org.eclipse.ui.viewActions" href="guide/workbench_basicext_viewActions.htm" />
			<topic label="org.eclipse.ui.editors" href="guide/workbench_basicext_editors.htm" />
			<topic label="org.eclipse.ui.editorActions" href="guide/workbench_basicext_editorActions.htm" />
			<topic label="org.eclipse.ui.popupMenus" href="guide/workbench_basicext_popupMenus.htm" />
			<topic label="org.eclipse.ui.actionSets" href="guide/workbench_basicext_actionSets.htm" />
		</topic>
		<topic label="Basic workbench extension points using commands" href="guide/workbench_cmd.htm" >
			<topic label="org.eclipse.ui.commands" href="guide/workbench_cmd_commands.htm" />
			<topic label="org.eclipse.ui.menus" href="guide/workbench_cmd_menus.htm" />
			<topic label="org.eclipse.ui.handlers" href="guide/workbench_cmd_handlers.htm" />
			<topic label="org.eclipse.ui.bindings" href="guide/workbench_cmd_bindings.htm" />
			<topic href="guide/workbench_cmd_expressions.htm" label="Workbench Core Expressions">
   </topic>
		</topic>
		<topic label="The plug-in class" href="guide/workbench_plugin.htm" />

	
	<topic label="JFace UI framework" href="guide/jface.htm">
		<topic label="Viewers" href="guide/jface_viewers.htm" />
		<topic label="Actions and contributions (Deprecated)" href="guide/jface_actions.htm" />
		<topic label="User interface resources" href="guide/jface_resources.htm" />
		<topic label="Long-running operations" href="guide/jface_operations.htm" />
		<topic label="Field assist" href="guide/jface_fieldassist.htm" />


	<topic label="Advanced workbench concepts" href="guide/wrkAdv.htm">
		<topic label="Workbench menu contributions" href="guide/workbench_menus.htm" />
		<topic label="Menu and toolbar paths" href="guide/workbench_menupaths.htm" />
		<topic label="Action set part associations" href="guide/workbench_basicext_actionSetPartAssociations.htm" />
		<topic label="Boolean expressions and action filters" href="guide/workbench_actionfilters.htm" />
		<topic label="Retargetable actions" href="guide/wrkAdv_retarget.htm" >
			<topic label="Setting a global action handler" href="guide/wrkAdv_retarget_setting.htm" />
			<topic label="Contributing new retargetable actions" href="guide/wrkAdv_retarget_contribute.htm" >
				<topic label="Retargetable editor actions" href="guide/wrkAdv_retarget_contribute_editors.htm" />
				<topic label="Retargetable action set actions" href="guide/wrkAdv_retarget_contribute_actionsets.htm" />
			</topic>
		</topic>
		<topic label="Undoable operations" href="guide/wrkAdv_undo.htm" >
			<topic label="Undo and the IDE Workbench" href="guide/wrkAdv_undo_ide.htm" />
		</topic>

		</topic>
		<topic label="Decorators" href="guide/workbench_advext_decorators.htm" />
		<topic label="Workbench key bindings" href="guide/wrkAdv_keyBindings.htm" >
			<topic label="Associating actions to commands" href="guide/wrkAdv_keyBindings_actionDef.htm" />
			<topic label="Bindings" href="guide/wrkAdv_keyBindings_accelSet.htm" />
			<topic label="Schemes" href="guide/wrkAdv_keyBindings_accelConfig.htm" />
			<topic label="Contexts and key bindings" href="guide/wrkAdv_keyBindings_contexts.htm" />

		<topic label="Honoring single click support" href="guide/wrkAdv_singleclick.htm" />
		<topic label="Working sets" href="guide/wrkAdv_workingsets.htm" />
		<topic label="Filtering large user interfaces" href="guide/workbench_scalability.htm" >
			<topic label="Activities (Not currently in 4.1)" href="guide/workbench_advext_activities.htm" />
			<topic label="Contexts" href="guide/workbench_advext_contexts.htm" />
		</topic>
		<topic label="Workbench concurrency support" href="guide/workbench_jobs.htm" />

Return to bug 348821

Lines 87-93 Link Here

(-)guide/team_ui_actions.htm (-1 / +31 lines)
87	</ul>	87	</ul>
88	<p>The implementation of an action is largely dependent on your specific	88	<p>The implementation of an action is largely dependent on your specific
89	provider.</p>	89	provider.</p>
90	<p> </p>	90	<p>Commands can be contributed in a similar way:</p>
		91	<pre>
		92	<extension point="org.eclipse.core.expressions.definitions">
		93	<definition id="org.eclipse.ui.example.ccvs.ui.IFileContributions">
		94	<iterate ifEmpty="false">
		95	<adapt type="org.eclipse.core.resources.IFile">
		96	<test <b>property="org.eclipse.core.resources.projectPersistentProperty"</b>
		97	<b>value="org.eclipse.team.core.repository=org.eclipse.team.cvs.core.cvsnature"</b>/>
		98	</adapt>
		99	</iterate>
		100	</definition>
		101	</extension>
		102	<extension point="org.eclipse.ui.menus">
		103	<menuContribution locationURI="popup:<b>team.main?after=group3</b>">
		104	<command commandId="org.eclipse.team.ccvs.ui.ignore"
		105	id="org.eclipse.ui.example.ccvs.ui.ignore"
		106	style="push">
		107	<visibleWhen checkEnabled="false">
		108	<or>
		109	<with variable="activeMenuSelection">
		110	<reference definitionId="org.eclipse.ui.example.ccvs.ui.IFileContributions"/>
		111	</with>
		112	<with variable="activeMenuEditorInput">
		113	<reference definitionId="org.eclipse.ui.example.ccvs.ui.IFileContributions"/>
		114	</with>
		115	</or>
		116	</visibleWhen>
		117	</command>
		118	</menuContribution>
		119	</extension>
		120	</pre>
91	<p>	121	<p>
92		122
93	</p>	123	</p>

Removed Link Here

(-)guide/workbench_actionfilters.htm (-242 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Boolean expressions and action filters
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<H2>
18	Boolean expressions and action filters</H2>
19	<p>
20	When a plug-in contributes an action to the workbench UI using one of the menu
21	extension points, it can specify the conditions under which the menu item is
22	visible and/or enabled in the menu. In addition to supplying simple enabling
23	conditions, such as selection counts and selection classes, plug-ins can use <b>boolean
24	expressions</b> for more flexibility in determining when an action should be visible or enabled.</p>
25
26
27	<h3>Boolean enablement expressions</h3>
28	<p>Boolean expressions can contain the boolean operators (NOT, AND, OR) combined with a predefined syntax
29	for evaluating certain conditions. Many of these conditions test a particular object. The identity of the
30	"object in focus" (the object being tested) depends upon the specific context of the enablement expression:
31	</p>
32	<ul>
33	<li><b>instanceof</b> tests whether the type of the object in focus is a subtype of the specified type name.</li>
34	<li><b>test</b> tests whether the value of a named property of the object in focus matches the specified value.</li>
35	<li><b>systemTest</b> tests whether the value of a named system property matches the specified value. </li>
36	<li><b>equals</b> tests whether the object in focus is equal to the specified value.</li>
37	<li><b>count</b> tests the number of elements in a list.</li>
38	<li><b>with</b> changes the object in focus to the object referenced by a supplied variable.</li>
39	<li><b>resolve</b> changes the object in focus to the object referenced by a supplied variable, supplying additional
40	arguments with the variable.</li>
41	<li><b>adapt</b> adapts the object in focus to the type specified.</li>
42	<li><b>iterate</b> iterates over a variable that is a collection and combines the boolean value of each value using AND or OR.</li>
43	</ul>
44	<p>
45	When specifying a value to be tested against any of these expressions, the value is assumed to be a string except for when
46	the following conversions are successful:
47	</p>
48	<ul>
49	<li>the string "true" is converted into Boolean.TRUE</li>
50	<li>the string "false" is converted into Boolean.FALSE</li>
51	<li>if the string contains a dot, the interpreter tries to convert the value into a Float object</li>
52	<li>if the string only consists of numbers, the interpreter converts the value into an Integer object</li>
53	<li>the conversion into a Boolean, Float, or Integer can be suppressed by surrounding the string with single quotes.</li>
54	</ul>
55	<p>A complete definition of enablement XML syntax can be found in the extension point reference documentation for any
56	extension that defines an <b>enablement</b> element, such as
57	<b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html#e.enablement"> org.eclipse.ui.popupMenus</a></b>.
58	</p>
59	<p>Prior to R3.0, these generalized boolean expressions were not available. The following predefined expressions were used to
60	evaluate certain conditions without building a general expression. Note that any of these expressions could now be expressed with
61	the more generalized syntax. The predefined expressions can still be used as follows:</p>
62	<ul>
63	<li>
64	<p><b>objectClass</b> - true if each object in the
65	selection subclasses or implements the class.</p>
66	</li>
67	<li>
68	<p><b>objectState</b> - true if the named attribute equals the specified value.  <b><a href="../reference/api/org/eclipse/ui/IActionFilter.html">IActionFilter</a>
69	</b>assists in evaluating the expression.  An action filter dynamically computes the enablement
70	criteria for an action based on the target selection and the value of named
71	attributes.</p>
72	</li>
73	<li>
74	<p><b>systemProperty</b> - true if the named system
75	property equals the specified value.</p>
76	</li>
77	<li>
78	<p><b>pluginState</b> - specifies whether the specified
79	plug-in (by <b>id</b>) should be <b>installed</b> or <b>activated</b> </p>
80	</li>
81	</ul>
82	<p>For example, the following snippets represent enablement
83	expressions that could be used on a hypothetical action in an action set: </p>
84	<pre><action id="org.eclipse.examples.actionEnablement.class"
85	label="Red Element"
86	menubarPath="additions"
87	class="org.eclipse.examples.actionEnablement.ObjectTestAction">
88	<enablement>
89	<b> <and>
90	<objectClass name="org.eclipse.examples.actionEnablement.TestElement"/>
91	<objectState name="name" value="red"/>
92	</and>
93	</b> </enablement>
94	</action></pre>
95	<pre><action id="org.eclipse.examples.actionEnablement.property"
96	label="Property"
97	menubarPath="additions"
98	class="org.eclipse.examples.actionEnablement.PropertyTestAction">
99	<enablement>
100	<b> <systemProperty name="MyTestProperty" value="puppy"/>
101	</b> </enablement>
102	</action> </pre>
103	<pre><action id="org.eclipse.examples.actionEnablement.pluginState"
104	label="Installed"
105	menubarPath="additions"
106	class="org.eclipse.examples.actionEnablement.PluginTestAction">
107	<enablement>
108	<b><pluginState id="x.y.z.anotherPlugin" value="installed"/> </b>
109	</enablement>
110	</action> </pre>
111	<p>See the reference documentation of the extension points
112	for more elaborate samples of these expressions and a complete description of
113	the XML.</p>
114
115
116	<p>
117	The following table lists extension points that contribute actions and
118	summarizes how XML markup attributes and boolean expressions can be used to
119	affect enablement.</p>
120
121
122	<TABLE BORDER="1" width="671">
123	<TR>
124	<TH ROWSPAN="1" COLSPAN="1" width="118">
125	<P CLASS="CellHeading">
126	Extension point name</p>
127	</TH>
128	<TH ROWSPAN="1" COLSPAN="1" width="359">
129	<P CLASS="CellHeading">
130	Attributes affecting enablement</p>
131	</TH>
132	<TH ROWSPAN="1" COLSPAN="1" width="335">
133	<P CLASS="CellHeading">
134	Boolean expressions</p>
135	</TH>
136	</TR>
137	<TR>
138	<TD width="118">
139	<p>
140	<b>
141	<a href="../reference/extension-points/org_eclipse_ui_viewActions.html">
142	viewActions</a></b>,</p>
143	<p><b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">editorActions</a></b>,</p>
144	<p><b><a href="../reference/extension-points/org_eclipse_ui_actionSets.html">actionSets</a></b></p>
145	</TD>
146	<TD width="359">
147	<p>
148	<b>enablesFor</b> - specifies the selection count that must be met for the
149	action to be enabled</p>
150	<p>
151	<b>selection</b> <b>class</b> - the class that the selected objects must
152	subclass or implement in order for the action to be enabled</p>
153	<p>
154	<b>selection</b> <b>name</b> - a wild card filter that can be applied to the
155	objects in the selection.</p>
156	</TD>
157	<TD width="335">
158	<p>
159	<b>visibility</b> - a boolean expression.  Controls whether the menu item
160	is visible in the menu.</p>
161	<p>
162	<b>enablement</b> - a boolean expression.  Controls whether the menu item
163	is enabled in the menu.  The <b>enablesFor</b> attribute and the <b>selection</b> <b>class</b>
164	and <b>name</b>, and must be
165	satisfied before applying the enablement expression.</p>
166	</TD>
167	</TR>
168	<TR>
169	<TD width="118">
170	<p>
171	<b>
172	<a href="../reference/extension-points/org_eclipse_ui_popupMenus.html">
173	popupMenus</a></b></p>
174	</TD>
175	<TD width="359">
176	<p>
177	(For object contributions only.)</p>
178	<p>
179	<b>objectClass</b> - specifies the class that objects in the selection must
180	subclass or implement</p>
181	<p>
182	(For both object and viewer contributions)</p>
183	<p>
184	<b>enablesFor</b> - specifies the selection count that must be met for the
185	action to be enabled</p>
186	<p>
187	<b>selection</b> <b>class</b> - the class that the selected objects must
188	subclass or implement to enable the action</p>
189	<p>
190	<b>selection</b> <b>name</b> - a wild card filter that can be applied to the
191	objects in the selection.</p>
192	<p>
193	</p>
194	</TD>
195	<TD width="335">
196	<p>
197	(For both object and viewer contributions)</p>
198	<p>
199	<b>visibility</b> - a boolean expression.  Controls whether the menu item
200	is visible in the menu.</p>
201	<p><b>enablement</b> - a boolean expression.  Controls
202	whether the menu item is enabled in the menu.
203	The <b>enablesFor</b> attribute and the <b>selection</b> <b>class</b> and <b>name</b>, and must be
204	satisfied before applying the enablement expression.</p>
205	</TD>
206	</TR>
207	</TABLE>
208
209	<h3>Using objectState with content types</h3>
210	<p>The ability to define content types (see <a href="runtime_content.htm">Content types</a>) can be combined
211	with boolean expressions to define very specific enablement or visibility conditions based on
212	the content type of a resource. For example, the following snippet makes a popup menu item visible only if the
213	selected file's content matches the plug-in's specialized content types.
214	</p>
215	<pre>
216	<extension point="org.eclipse.ui.popupMenus">
217	<objectContribution
218	id="com.example.objectContributions"
219	objectClass="org.eclipse.core.resources.IFile"
220	nameFilter="*.xml">
221	<visibility>
222	<or>
223	<objectState
224	<b>name="contentTypeId"</b>
225	value="com.example.employeeRecordContentType"/>
226	<objectState
227	<b>name="contentTypeId"</b>
228	value="com.example.customerRecordContentType"/>
229	</or>
230	</visibility>
231	<action id="com.example.action1"
232	...
233	</pre>
234	The <b>contentTypeId</b> attribute can be used in an objectState expression to check the content type of
235	the selected xml file. This allows a plug-in to apply very specific content checking before enabling or showing
236	menu actions related to specific types of files. See <a href="runtime_content.htm">Content types</a> for more detail
237	about the content type extension.
238
239
240
241	</BODY>
242	</HTML>

Removed Link Here

(-)guide/workbench_basicext.htm (-55 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2007. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Basic workbench extension points
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<H2>
18	Basic workbench extension points using actions</H2>
19	<P >
20	The workbench defines extension points that allow plug-ins to contribute
21	behaviors to existing views and editors or to provide implementations for
22	new views and editors. Using commands is covered in the <a href="workbench_cmd.htm"
23	class="XRef">Basic workbench extension points using commands</a> section. Here we are
24	going to take a look at the
25	contributions to these extension points from one of the workbench sample applications, the readme tool. </P>
26	<P >
27	The readme tool is a plug-in that provides custom editing and navigation for a specific resource
28	, a
29	<b> .readme</b> file. The example shows many typical (but simplified) ways that extensions can be used to provide specialized tools.</P>
30	<P >
31	The readme tool contributes to the menus of the navigator view, adds editor related actions to the workbench menus and
32	tool bar, defines a custom view and content outliner, and defines markers
33	and marker resolutions. The figure below shows some of the
34	customized features added to the workbench by the readme tool.</P>
35	<P >
36	<img src="images/readmeoverview.png" alt="Workbench with readme tool contributing action sets, view and editor actions, custom editors and views, and outliner" border="0"></P>
37	<P >
38	The readme tool also contributes preference and properties pages to the workbench. Later we'll also look
39	at some wizard contributions in
40	<a HREF="dialogs.htm" CLASS="XRef"> Dialogs and wizards</a>.</P>
41	<P >
42	The readme tool is located in the <b>org.eclipse.ui.examples.readmetool</b> package. The
43	<b> readmetool.jar</b> and <b> plugin.xml</b> can be found in the
44	<b> org.eclipse.ui.examples.readmetool</b> directory underneath the
45	<b> plugins</b> directory. To follow along, you will need to make sure that
46	you have installed the platform examples.  (See the <a href="../samples/samples.html">Examples
47	Guide </a> for more information.)  </P>
48	<P >
49	The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
50	tool</a> implements many different workbench extensions.  We will start
51	with one of the simplest workbench extension points, a view.  We'll
52	continue by looking at additional readme tool extensions. </P>
53
54	</BODY>
55	</HTML>

Removed Link Here

(-)guide/workbench_basicext_actionSetPartAssociations.htm (-72 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"></script>
11	<TITLE>Action set part associations</TITLE>
12
13	<link rel="stylesheet" type="text/css" HREF="../book.css">
14	</HEAD>
15	<BODY BGCOLOR="#ffffff">
16	<H2>
17	Action set part associations</H2>
18
19	<P >
20	Once your plug-in defines an <a href="workbench_basicext_actionSets.htm">action
21	set</a>, it can use the
22	<a href="../reference/extension-points/org_eclipse_ui_actionSets.html"><b> org.eclipse.ui.actionSetPartAssociations</b></a>
23	extension point to specify that an action set should be made visible when a
24	particular view or editor is active.   </P>
25
26	<P >
27	Ultimately, the user controls the
28	appearance of action sets using
29
30	<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.customizePerspective")'>
31	<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png" alt="command link">
32	<b>Window > Customize Perspectives...</b></a>
33
34	in
35	the workbench menu. If the user marks an action set visible, it will always be visible when the
36	perspective is active, regardless of
37	the active view or editor.  Likewise, if the user marks the action set as hidden, it will always be hidden when the perspective is active.  If the user does not change the state of
38	an action set in this dialog, then the action set part associations are used to
39	determine the visibility of the action set.</P>
40
41
42	<P >
43	The markup for an action set part association is straightforward.  The
44	following example comes from the Java development tools (JDT) UI plug-in.</P>
45	<pre>
46	<extension point="org.eclipse.ui.actionSetPartAssociations">
47	<actionSetPartAssociation
48	<b>targetID</b>="org.eclipse.jdt.ui.CodingActionSet">
49	<part id="org.eclipse.jdt.ui.PackageExplorer"/>
50	<part id="org.eclipse.jdt.ui.TypeHierarchy" />
51	<part id="org.eclipse.jdt.ui.CompilationUnitEditor"/>
52	<part id="org.eclipse.jdt.ui.ClassFileEditor"/>
53	<part id="org.eclipse.jdt.ui.ProjectsView"/>
54	<part id="org.eclipse.jdt.ui.PackagesView"/>
55	<part id="org.eclipse.jdt.ui.TypesView"/>
56	<part id="org.eclipse.jdt.ui.MembersView"/>
57	</actionSetPartAssociation>
58	</extension>
59	</pre>
60	<P >The <b>targetID</b> specifies the action set.  (The <b> CodingActionSet</b> was
61	previously defined in the JDT plug-in manifest.)  One or more <b>part</b>
62	attributes can be specified to indicate which views and editors will cause the
63	action set to become visible in the menus and toolbar.  The effect of this extension
64	contribution is that the actions associated with writing Java code will only be
65	visible when one of the specified views is active.</P>
66
67
68
69
70
71	</BODY>
72	</HTML>

Removed Link Here

(-)guide/workbench_basicext_actionSets.htm (-158 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<script language="JavaScript" src="PLUGINS_ROOT/org.eclipse.help/livehelp.js" type="text/javascript"></script>
11	<TITLE>org.eclipse.ui.actionSets</TITLE>
12
13	<link rel="stylesheet" type="text/css" HREF="../book.css">
14	</HEAD>
15	<BODY BGCOLOR="#ffffff">
16	<H3>
17	org.eclipse.ui.actionSets</H3>
18
19	<P >
20	Your plug-in can contribute menus, menu items, and tool bar items to the workbench menus and toolbar
21	by using the
22	<a href="../reference/extension-points/org_eclipse_ui_actionSets.html"><b> org.eclipse.ui.actionSets</b></a>
23	extension point. In order to reduce the clutter that would be caused by having every plug-in's menu contributions shown at once, the contributions are grouped into action sets which can be made visible by user preference.</P>
24	<P >
25	You can see which action sets have been contributed to your workbench by choosing
26
27	<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.window.customizePerspective")'>
28	<img src="PLUGINS_ROOT/org.eclipse.help/command_link.png" alt="command link">
29	<b>Window > Customize Perspective...</b></a>
30
31	from the workbench menu. This option will show you a dialog that lists
32	action sets as groups of commands. A checkmark by a command group means that the menu and tool bar actions are visible in the workbench.
33	You can select the name of the command group to see the list of available menu and toolbar actions to the right. The figure below shows the
34	list of command groups available in our workbench.  (Your workbench may look different depending on which plug-ins you have
35	installed and which perspective is active.)</P>
36
37	<img src="images/actionsets.png" alt="Customize Perspective dialog with action set list" border="0">
38
39
40	<P >
41	The readme tool uses an action set to contribute several different "Open Readme
42	Browser" actions to the workbench menu.  (We contributed a similar
43	action to the popup menu of the resource navigator.)  The markup follows:</P>
44	<pre>
45	<extension point = "org.eclipse.ui.actionSets">
46	<actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
47	label="%ActionSet.name"
48	visible="true">
49	<menu id="org_eclipse_ui_examples_readmetool"
50	label="%ActionSet.menu"
51	path="window/additions">
52	<separator name="slot1"/>
53	<separator name="slot2"/>
54	<separator name="slot3"/>
55	</menu>
56	<action id="org.eclipse.ui.examples.readmetool.readmeAction"
57	menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
58	toolbarPath="readme"
59	label="%ReadmeAction.label"
60	tooltip="%ReadmeAction.tooltip"
61	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
62	icon="icons/ctool16/openbrwsr.png"
63	class="org.eclipse.ui.examples.readmetool.<b>WindowActionDelegate</b>"
64	definitionId="org.eclipse.ui.examples.readmetool.readmeAction"
65	enablesFor="1">
66	<selection class="org.eclipse.core.resources.IFile"
67	name="*.readme">
68	</selection>
69	</action>
70	...
71	</actionSet>
72	</extension></pre>
73	<P >
74	Wow, there's a lot going on here!  Let's take it a step at a time, looking
75	only at the first action for now.  </P>
76	<P >
77	First, the action set is declared and given a <b>label</b>.
78	The label "ReadMe Actions" (defined for <b> %ActionSet.name</b> key in the plug-in's
79	properties file) is used to display the action set in the
80	dialog shown above.  Since we set <b> visible</b> to true, the workbench will initially have the action set
81	checked in the action set list and the actions will be visible.</P>
82	<P >
83	The rest of the action set declaration is concerned with defining the menu in
84	which the actions appears and the actions themselves.</P>
85	<P >
86	We define a menu whose <b>label</b> appears in the workbench menus.  The menu's <b>path</b>
87	tells the workbench to place the new menu in the <b>additions</b>
88	slot of the <b>window</b> menu.  (For a discussion
89	of menu paths and slots, see <a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a>.)
90	We also define some slots in our new menu so that actions can be inserted at specific locations in our menu.</P>
91	<P >
92	This markup alone is enough to cause the menu to appear in the workbench <b>Window</b>
93	menu.</P>
94	<P >
95	<img src="images/readmeactionset.png" alt="Workbench Window menu with Readme File Editor entry" border="0" ></P>
96	<P >
97	Next, we define the actions themselves.  </P>
98	<P >
99	The action definition (<b>id</b>,
100	<b>label</b>, <b>icon</b>, <b>class</b>) is
101	similar to the other actions we've seen in views, editors, and popups.
102	We'll focus here on what's different:  where does the action go?  We
103	use  <b>menubarPath</b> and <b>toolbarPath</b>
104	to indicate its location.  First, we define the <b>menubarPath</b> to add the
105	action to a slot in the menu
106	that we just defined ( <b>"window/org_eclipse_ui_examples_readmetool/slot1"</b>).</P>
107	<P >
108	<img src="images/readmeactionsetmenu.png" alt="Readme File Editor menu with menu items" border="0" ></P>
109	<P >
110	Then, we define a new <b> toolbarPath</b> to insert our actions in the workbench tool
111	bar.  Since we've defined a new tool path, <b>"readme"</b>, the workbench will decide where it goes
112	relative to other plug-in's toolbar contributions.</P>
113	<P >
114	<img src="images/readmeactionsettoolbar.png" alt="Workbench tool bar with readme action" border="0" ></P>
115	<P >
116	What happens when the action is selected by the user?  The action is
117	implemented by the class specified in the <b>class</b>
118	attribute.  The action <b> class</b> must implement
119	<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowActionDelegate.html"> IWorkbenchWindowActionDelegate</a></b>,
120	or
121	<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowPulldownDelegate.html"> IWorkbenchWindowPulldownDelegate</a></b>
122	if the action will be shown as a pull-down tool item in the tool bar.  Since we are not
123	creating a pull-down tool item, we provide <b>WindowActionDelegate</b>.
124	This class is similar to <b>ObjectActionDelegate</b>.
125	It launches the readme sections dialog when the user chooses the action.  (We'll
126	discuss the sections dialog in <a href="dialogs_applications.htm">Application
127	dialogs</a>.)</P>
128
129
130	<P >
131	The action also supplies enabling conditions for its menu item and tool bar
132	item.  The menu and tool bar items will only be enabled when a single (<b>enablesFor="1"</b>)
133	readme file (<b>selectionClass ="org.eclipse.core.resources.IFile"
134	name="*.readme"</b>) is selected.  This action's menu and toolbar
135	item appear and are enabled by virtue of the markup
136	in the <b>plugin.xml</b> file.  None of the
137	plug-in code will execute until the user chooses the action and the workbench
138	runs the action <b>class</b>.</P>
139
140	<p>The <b>definitionId</b> allows the action to be linked to a command created by the
141	<b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a></b>
142	extension, which can be used for keybindings. All <b>actions</b> in an <b>actionSets</b>
143	should be linked to a command, either existing commands provided by the workbench or
144	commands created by the contributing plugin.
145	See <a href="wrkAdv_keyBindings_actionDef.htm" class="XRef">Associating actions to commands</a>
146	and <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> for
147	defining commands.</p>
148
149	<P >
150	We'll look at the other two actions later in the context of <a href="wrkAdv_retarget_contribute.htm">retargetable
151	actions</a>.</P>
152
153
154
155
156
157	</BODY>
158	</HTML>

Removed Link Here

(-)guide/workbench_basicext_editorActions.htm (-77 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>org.eclipse.ui.editorActions</TITLE>
11
12	<link rel="stylesheet" type="text/css" HREF="../book.css">
13	</HEAD>
14	<BODY BGCOLOR="#ffffff">
15	<H3>
16	org.eclipse.ui.editorActions</H3>
17
18	<P >
19	We've just seen how editors
20	can contribute their own actions to the workbench menus and tool bar when they
21	become active.  The <b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">org.eclipse.ui.editorActions</a></b> extension
22	point allows a plug-in to add
23	to the workbench menus and tool bar when another plug-in's editor becomes active.</P>
24	<P >
25	In the readme example, the plug-in uses the <b>editorActions</b>
26	extension point to contribute additional actions to the menu contributed by the
27	readme editor. The definition in our
28	<b> plugin.xml</b> should look pretty familiar by now.</P>
29	<pre>
30	<extension
31	point = "org.eclipse.ui.editorActions">
32	<editorContribution
33	id="org.eclipse.ui.examples.readmetool.ec1"
34	targetID="org.eclipse.ui.examples.readmetool.ReadmeEditor">
35	<action id="org.eclipse.ui.examples.readmetool.ea1"
36	label="%Editors.Action.label"
37	toolbarPath="ReadmeEditor"
38	icon="icons/obj16/editor.png"
39	tooltip="%Editors.Action.tooltip"
40	class="org.eclipse.ui.examples.readmetool.EditorActionDelegate"
41	definitionId="org.eclipse.ui.examples.readmetool.ea1"
42	/>
43	</editorContribution>
44	</extension></pre>
45	<P >Similar to a view action, the extension must specify the <b> targetID</b> of the
46	editor to which it is contributing actions.  The action itself is very
47	similar to a view action (<b>id</b>, <b>label</b>, <b>icon</b>, <b>toolbarPath</b>,
48	...), except that the specified class
49	must implement <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>
50	and a <b>definitionId</b> can be specified to link this action to a Command specified
51	by the <b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a></b>
52	extension, which is important for keybinding.
53	See <a href="wrkAdv_keyBindings_actionDef.htm" class="XRef">Associating actions to commands</a>
54	and <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> for
55	defining commands.</P>
56	<P >Note that a menu bar path is not specified in this markup.  Therefore,
57	the action will appear in the workbench tool bar when the editor is active,
58	but not in the workbench menu bar.  (See <a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a> for a discussion of toolbar and menu paths.)</P>
59	<P >Sure enough, when the editor is active, we see our editor action on the tool
60	bar next to the actions that were contributed by the editor itself.</P>
61	<P ><img src="images/editorAction.png" alt="Editor action appears next to original editor contributions in workbench toolbar" border="0" ></P>
62	<P >
63	The readme tool supplies <b> EditorActionDelegate</b>
64	to implement the action.  This class is very similar to the view action delegate
65	we saw earlier.</P>
66
67	<pre>
68	public void run(IAction action) {
69	MessageDialog.openInformation(editor.getSite().getShell(),
70	MessageUtil.getString("Readme_Editor"),
71	MessageUtil.getString("Editor_Action_executed"));
72	}</pre>
73
74
75
76	</BODY>
77	</HTML>

Lines 1-7 Link Here

(-)guide/workbench_basicext_editors.htm (-92 / +37 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">	1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>	2	<HEAD>
3		3
4	<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." >	4	<meta name="copyright" content="Copyright (c) IBM Corporation and others 2000, 2011. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page." >
5		5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">	6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">	7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
Lines 28-34 Link Here
28	editor on the same file from a different workbench window or perspective).	28	editor on the same file from a different workbench window or perspective).
29	Unlike views, however, the same editor type, such as a text editor, may be open	29	Unlike views, however, the same editor type, such as a text editor, may be open
30	many times	30	many times
31	within one workbench page for different inputs.</P>	31	within one workbench page for different inputs. The editor input can also be a path
		32	to an in memory model, as in the InfoEditor example.</P>
32	<P >	33	<P >
33	The workbench extension point <b><a href="../reference/extension-points/org_eclipse_ui_editors.html">org.eclipse.ui.editors</a></b>	34	The workbench extension point <b><a href="../reference/extension-points/org_eclipse_ui_editors.html">org.eclipse.ui.editors</a></b>
34	is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor	35	is used by plug-ins to add editors to the workbench. Plug-ins that contribute an editor must register the editor
Lines 36-43 Link Here
36	for the editor. Some	37	for the editor. Some
37	of the editor information, such as the implementation <b> class</b> and the	38	of the editor information, such as the implementation <b> class</b> and the
38	<b> name</b> and the <b>icon</b> to be used in the workbench menus and	39	<b> name</b> and the <b>icon</b> to be used in the workbench menus and
39	labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands. Editors can also define a	40	labels, is similar to the view information. In addition, editor extensions specify the file extensions or file name patterns of the file types that the editor understands.
40	<b> contributorClass</b>, which is a class that adds actions to workbench menus and tool bars when the editor is active.</P>	41	Editors also use <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a> and <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>
		42	to contribute to the workbench menus and toolbars when that editor is active.</P>
41	<P >	43	<P >
42	The interface for editors is defined in <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>, but plug-ins	44	The interface for editors is defined in <b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>, but plug-ins
43	can choose to extend the	45	can choose to extend the
Lines 50-159 Link Here
50	are implemented using	52	are implemented using
51	<b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>.</i></blockquote>	53	<b><a href="../reference/api/org/eclipse/ui/IEditorPart.html">IEditorPart</a></b>.</i></blockquote>
52	<P >	54	<P >
53	The readme tool provides a custom editor primarily for the purpose of contributing its own content outliner page to the	55	The editor can contribute its own content outliner page to the
54	workbench outline view.  </P>	56	workbench outline view.  </P>
55	<P >	57	<P >
56	The configuration for the editor extension is defined as follows.</P>	58	The configuration for the editor extension is defined as follows.</P>
57	<pre>	59	<pre>
58	<extension	60	<extension
59	point = "org.eclipse.ui.editors">	61	point = "org.eclipse.ui.editors">
60	<editor	62	<editor
61	id = "org.eclipse.ui.examples.readmetool.ReadmeEditor"	63	class="org.eclipse.ui.examples.contributions.editor.InfoEditor"
62	name="%Editors.ReadmeEditor"	64	icon="icons/editor.gif"
63	icon="icons/obj16/editor.png"	65	id="org.eclipse.ui.examples.contributions.editor"
64	class="org.eclipse.ui.examples.readmetool.ReadmeEditor"	66	name="%contributions.editor.name">
65	extensions="readme"	67	</editor>
66	contributorClass="org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor">
67	</editor>
68	</extension></pre>	68	</extension></pre>
69	<P >	69	<P >
70	We see the familiar configuration markup for <b>id</b>,	70	We see the familiar configuration markup for <b>id</b>,
71	<b>name</b>,	71	<b>name</b>,
72	<b>icon</b>, and <b>class</b>.   The <b>extensions</b> attribute	72	<b>icon</b> (which must be specified when specifying <b>class</b>),
73	describes the file types that the editor understands.  (You could also	73	and <b>class</b>.   You could use the <b>extensions</b> attribute
		74	describes the file types that the editor understands, like <b>extensions="person"</b>,
		75	although this example doesn't need it.
		76	(You could also
74	specify <b>filenames</b> if you need to be more specific.)  The <b>class</b>	77	specify <b>filenames</b> if you need to be more specific.)  The <b>class</b>
75	implements the editor, and the <b>contributorClass</b> is responsible for	78	implements the editor.</P>
76	providing editor-related actions. The contributor is not normally used to
77	contribute commands or handlers to the workbench menu or toolbar, that's done
78	via <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
79	Let's look at the contributor that's used for actions in more
80	detail.</P>
81		79
82	<H4>
83	Editor action contributors</H4>
84	<P >
85	The contributor class adds editor-related actions to the workbench menu and toolbar. It must implement the
86	<b><a href="../reference/api/org/eclipse/ui/IEditorActionBarContributor.html"> IEditorActionBarContributor</a></b> interface. The contributor is
87	separate from the editor itself since any given workbench page can have multiple editors of the same type.
88	A single contributor is shared by all the editors of a specific type, rather than
89	having each instance of an editor create actions and images. </P>
90	<P >
91	In <b>ReadmeEditorActionBarContributor</b>, we contribute three actions,
92	"Editor Action1," "Editor Action2," and "Editor Action3."
93	These are set up in the constructor.</P>
94	<pre>
95	public ReadmeEditorActionBarContributor() {
96	...
97	action1 = new EditorAction(MessageUtil.getString("Editor_Action1"));
98	action1.setToolTipText(MessageUtil.getString("Readme_Editor_Action1"));
99	action1.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_DISABLE);
100	action1.setImageDescriptor(ReadmeImages.EDITOR_ACTION1_IMAGE_ENABLE);
101	...
102	action2 = new RetargetAction(IReadmeConstants.RETARGET2, MessageUtil.getString("Editor_Action2"));
103	action2.setToolTipText(MessageUtil.getString("Readme_Editor_Action2"));
104	action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
105	action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
106	...
107	action3 = new LabelRetargetAction(IReadmeConstants.LABELRETARGET3, MessageUtil.getString("Editor_Action3"));
108	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
109	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
110	...
111	}
112	</pre>
113	<P >
114	The names and icons for the actions are set up in the code rather than in the <b>plugin.xml</b>.
115	(We'll ignore the differences in the action classes for now until we look at <a href="wrkAdv_retarget_contribute.htm">retargetable
116	actions</a>.)  </P>
117	<P >Note how similar the action information is to the
118	<b> viewActions</b> information we saw in the markup
119	for the view action.  The actions are set up in code since we have to
120	manage the sharing of the actions among different instances of the same editor.
121	When the actions are created in the constructor, they are independent of any
122	particular instance of the editor.</P>
123	<P >	80	<P >
124	When an editor becomes active and it has actions that need to be installed in the workbench menus and tool bar, the <b>setActiveEditor	81	Editor menus and editor toolbars are placed in the main menu and main toolbar. See
125	</b>message is sent to the contributor.  The contributor connects the editor actions to a specific editor.  </P>	82	<a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a> for how to use the
		83	<b>locationURI</b> to place the commands correctly.</P>
		84	<img src="images/contributions_global.png" alt="Showing a global menu additions" border="0" >
		85	<P>
		86	These menu and tool bar items can be shown only when the editor is active using core expressions.
		87	To define a re-usable core expression for your editor, use
		88	<b><a href="../reference/extension-points/org_eclipse_core_expressions_definitions.html">org.eclipse.core.expressions.definitions</a></b></P>
126	<pre>	89	<pre>
127	public void setActiveEditor(IEditorPart editor) {	90	<extension
128	...	91	point = "org.eclipse.core.expressions.definitions">
129	action1.setActiveEditor(editor);	92	<definition id="org.eclipse.ui.examples.contributions.view.activeEditor">
130	...	93	<with variable="activeEditorId">
131	}	94	<equals value="org.eclipse.ui.examples.contributions.editor"/>
132	</pre>	95	</with>
133	<P >	96	</definition>
134	As you can see, the actions show up in the workbench menu and tool bar when a readme editor is active. </P>	97	</extension></pre>
135
136	<img src="images/editormenu.png" alt="Readme entry in workbench menu bar with three editor actions" border="0" >
137
138
139
140	<p><img src="images/editortoolbar.png" alt="Workbench toolbar with three readme actions" border="0" ></p>
141	<P >
142	These menu and tool bar items are only shown when the editor is active. The location for the menu and tool bar items can be specified as described in
143	<a HREF="workbench_menupaths.htm" CLASS="XRef">Menu and toolbar paths</a>.</P>
144
145
146		98
147	<H4>	99	<H4>
148	Editors and content outliners	100	Editors and content outliners
149	</h4>	101	</h4>
150	<P >	102	<P >
151	The readme editor itself, <b>ReadmeEditor</b>, is not very complicated. It extends the	103	Although the Info Editor does not, editors often have corresponding content outliners
152	<b><a href="../reference/api/org/eclipse/ui/editors/text/TextEditor.html"> TextEditor</a></b> class so that it can contribute a customized content outliner page	104	that provide a structured
153	to the outline view when a readme file is being edited. It does not change any behavior inside the text editor.</P>
154	<p><img src="images/readmeoutliner.png" alt="" border="0"></p>
155	<P >
156	Editors often have corresponding content outliners that provide a structured
157	view of the editor's contents and assist the user in navigating through the	105	view of the editor's contents and assist the user in navigating through the
158	contents of the editor.  See <a href="editors_workbench_outliner.htm">Content	106	contents of the editor.  See <a href="editors_workbench_outliner.htm">Content
159	outliners</a> for more detail. </P>	107	outliners</a> for more detail. </P>
Lines 164-171 Link Here
164	editors and platform text</a>. </P>	112	editors and platform text</a>. </P>
165		113
166		114
167
168
169
170	</BODY>	115	</BODY>
171	</HTML>	116	</HTML>

Removed Link Here

(-)guide/workbench_basicext_popupMenus.htm (-138 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>org.eclipse.ui.popupMenus</TITLE>
11
12	<link rel="stylesheet" type="text/css" HREF="../book.css">
13	</HEAD>
14	<BODY BGCOLOR="#ffffff">
15	<H3>
16	org.eclipse.ui.popupMenus</H3>
17
18	<P >
19	The <b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html"> org.eclipse.ui.popupMenus</a></b> extension
20	point allows a plug-in to contribute to the popup menus of other
21	views and editors.</P>
22	<P >
23	You can contribute an action to a specific popup menu by its id (<b>viewerContribution</b>), or
24	by associating it with a particular object type (<b>objectContribution</b>). </P>
25	<ul>
26	<li>An <b>objectContribution</b> will cause the menu
27	item to appear in popup menus for views or editors where objects of
28	the specified type are selected.</li>
29	<li>A <b>viewerContribution</b> will cause the menu
30	item to appear in the popup menu of a view or editor specified by id in the
31	markup.  </li>
32	</ul>
33	<p>
34	You can add commands to context menus for a similar result, see the
35	<b>Contributing to popup menus</b> section in
36	<a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
37	</p>
38	<P >
39	The readme tool defines both. Let's look at the object contribution
40	first.  </P>
41	<pre>
42	<extension point = "org.eclipse.ui.popupMenus">
43	<objectContribution
44	id="org.eclipse.ui.examples.readmetool"
45	objectClass="org.eclipse.core.resources.IFile"
46	nameFilter="*.readme">
47	<action id="org.eclipse.ui.examples.readmetool.action1"
48	label="%PopupMenus.action"
49	icon="icons/ctool16/openbrwsr.png"
50	menubarPath="additions"
51	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
52	class="org.eclipse.ui.examples.readmetool.PopupMenuActionDelegate"
53	definitionId="org.eclipse.ui.examples.readmetool.action1"
54	enablesFor="1">
55	</action>
56	</objectContribution>
57	...
58	</pre><h4>
59	Object contribution
60	</h4>
61	<P >
62	The action "Show Readme Action" is contributed for the object class <a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>. This means that any view containing
63	<a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>
64	objects will show the contribution if <a href="../reference/api/org/eclipse/core/resources/IFile.html"><b>IFile</b></a>
65	objects are selected. We see that the selection criteria is restricted further with a name filter
66	(<b>nameFilter="*.readme"</b>) and for single selections (<b>enablesFor="1"</b>). As we've discussed before, the registration of this menu does not run any code from our plug-in until the menu item is actually selected. </P>
67	<P >
68	When the menu item is selected, the workbench will run the specified class.
69	Since the popup is declared as an <b>objectContribution</b>,
70	the supplied class must implement <b><a href="../reference/api/org/eclipse/ui/IObjectActionDelegate.html">IObjectActionDelegate</a></b>. </P>
71	<P >
72	The action is implemented in <b>PopupMenuActionDelegate</b>.  </P>
73	<pre>
74	public void run(IAction action) {
75	MessageDialog.openInformation(
76	this.part.getSite().getShell(),
77	"Readme Example",
78	"Popup Menu Action executed");
79	}
80	</pre>
81	<P >
82	We can see the popup menu contribution when we select a readme file from the resource navigator.</P>
83
84	<img src="images/readmepopupmenu.png" alt="" border="0">
85	<h4>Viewer contribution</h4>
86	<p>
87	A viewer contribution is used to contribute to a specific view or editor's popup menu
88	by using its id.
89	Here is the readme tool's viewer contribution:</p>
90	<pre> ...
91	<viewerContribution
92	id="org.eclipse.ui.examples.readmetool2"
93	targetID="org.eclipse.ui.examples.readmetool.outline">
94	<action id="org.eclipse.ui.examples.readmetool.action1"
95	label="%PopupMenus.action"
96	icon="icons/ctool16/openbrwsr.png"
97	menubarPath="additions"
98	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
99	definitionId="org.eclipse.ui.examples.readmetool.action1"
100	class="org.eclipse.ui.examples.readmetool.ViewActionDelegate">
101	</action>
102	</viewerContribution>
103	</extension></pre>
104	<blockquote><i>
105	Note:  The name <b> viewerContribution</b> is somewhat misleading, as it does not relate to JFace viewers. A better name would
106	be <b>popupMenuContribution</b>.</i></blockquote>
107	<P >
108	When the extension is a <b>viewerContribution</b>, the
109	supplied class must implement the
110	<b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html"> IEditorActionDelegate</a></b> or
111	<b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html"> IViewActionDelegate</a></b> interface, depending on whether the
112	action is contributed to an editor's or view's popup menu. </P>
113
114
115	<P >
116	The <b>targetID</b> specifies the popup menu that will be altered.  If not specified
117	in the call to <code>getSite().registerContextMenu(*)</code> the popup menu's ID will default to the view or editor ID.  In this
118	case, we are adding an action to one of the readme tool views, the
119	outliner.  The action itself is similar to others that we've seen.  We specify the <b>id</b>,
120	<b>definitionId</b>, <b>label</b>, and <b>icon</b> of the action, and
121	the <b>path</b> within the popup for our contribution.  The action will be
122	shown only in the readme outline view's popup menu.</P>
123
124
125	<P >
126	<img src="images/readmeoutlinerpopup.png" alt="" border="0"></P>
127
128
129	The interfaces required to contribute a <b>viewerContribution</b>
130	to the <b> popupMenus</b> extension
131	point are the same as those required by the <b> viewActions</b> and <b> editorActions</b> extension points. If you want to contribute the same action to the popup menu and the local menu of a view or editor, you can use the same class for both extensions.
132
133
134
135
136
137	</BODY>
138	</HTML>

Removed Link Here

(-)guide/workbench_basicext_viewActions.htm (-99 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>org.eclipse.ui.viewActions</TITLE>
11
12	<link rel="stylesheet" type="text/css" HREF="../book.css">
13	</HEAD>
14	<BODY BGCOLOR="#ffffff">
15	<H3>
16	org.eclipse.ui.viewActions</H3>
17
18	<P >
19	It is common for plug-ins to contribute behavior to views that already exist in the workbench. This is done through the
20	<b><a href="../reference/extension-points/org_eclipse_ui_viewActions.html"> org.eclipse.ui.viewActions</a></b>
21	extension point. This extension point allows plug-ins to contribute menu items, submenus and tool bar entries to an
22	existing view's local
23	pull-down menu and local tool bar. </P>
24	<p>
25	Contributing menu items to views is also done using the
26	<b><a href="../reference/extension-points/org_eclipse_ui_menus.html">org.eclipse.ui.menus</a></b>
27	extension point. This allows command targeted at a view to be contributed to
28	an existing view's local pull-down menu and local tool bar, as in the <b>Contribution location</b> section
29	covering the Info View of <a href="workbench_cmd_menus.htm" class="XRef">org.eclipse.ui.menus</a>.
30	</p>
31	<P >
32	You may have noticed an item in the project explorer's local tool bar that becomes
33	enabled whenever a readme file is selected. This item also appears in the
34	project explorer's local
35	pull-down menu. These actions appear because the readme tool plug-in contributes
36	them using the
37	<b> viewActions</b> extension.</P>
38
39	<img src="images/readmeviewaction.png" alt="" border="0">
40	<P >
41	The relevant <b> plugin.xml</b> contribution is below.</P>
42	<pre>
43	<extension
44	point = "org.eclipse.ui.viewActions">
45	<viewContribution
46	id="org.eclipse.ui.examples.readmetool.vc1"
47	targetID="org.eclipse.ui.navigator.ProjectExplorer">
48	<action id="org.eclipse.ui.examples.readmetool.va1"
49	label="%PopupMenu.ResourceNav.label"
50	menubarPath="additions"
51	toolbarPath="additions"
52	icon="icons/obj16/editor.png"
53	tooltip="%PopupMenu.ResourceNav.tooltip"
54	helpContextId="org.eclipse.ui.examples.readmetool.view_action_context"
55	class="org.eclipse.ui.examples.readmetool.ViewActionDelegate"
56	enablesFor="1">
57	<selection class="org.eclipse.core.resources.IFile" name="*.readme"/>
58	</action>
59	</viewContribution>
60	</extension>
61	</pre>
62	<P >
63	A view contribution with a unique id is specified. The view to which we are adding
64	the action is specified in the
65	<b> targetID</b>. We are contributing to the Project
66	Explorer's menu.  We specify the label and the menu bar and
67	tool bar locations for the new action.  (For a complete discussion of menu and toolbar locations, see
68	<a HREF="workbench_menupaths.htm" CLASS="XRef"> Menu and toolbar paths</a>). </P>
69	<P >
70	We also specify the conditions under which the action should be enabled. You can see that this action will be enabled when there is one selection
71	(<b>enablesFor="1"</b>) of type
72	<b><a href="../reference/api/org/eclipse/core/resources/IFile.html">IFile</a>
73	(class="org.eclipse.core.resources.IFile")</b>, whose name has
74	"<b>.readme</b>" in the file extension (<b>name="*.readme"</b>). Sure enough, that's exactly what happens when you click around in the Project Explorer.  </P>
75	<P >
76	The information in the <b> plugin.xml</b> is all that's needed to add items to menus and tool
77	bars since plug-in code will only run when the action is actually selected from the menu or toolbar.
78	To provide the action behavior, the implementation class specified in the
79	<b> plugin.xml</b> must implement the <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html"> IViewActionDelegate</a></b> interface. </P>
80	<P >
81	In this example, the readme plug-in supplies <b> ViewActionDelegate</b> to implement the action. If you browse this class you will see that it includes methods for
82	remembering its view, handling selection changes, and invoking its action.
83	When invoked the action itself simply launches a dialog that announces it was executed.</P>
84	<pre>
85	public void run(org.eclipse.jface.action.IAction action) {
86	MessageDialog.openInformation(view.getSite().getShell(),
87	MessageUtil.getString("Readme_Editor"),
88	MessageUtil.getString("View_Action_executed"));
89	}</pre>
90	<P >
91	Although this action is simple, we can imagine how using selections and more
92	functional dialogs could make this action do something more interesting.</P>
93
94
95
96
97
98	</BODY>
99	</HTML>

Lines 27-33 Link Here

(-)guide/workbench_basicext_views.htm (-83 / +40 lines)
27	<P >	27	<P >
28	The extension point <b><a href="../reference/extension-points/org_eclipse_ui_views.html">org.eclipse.ui.views</a></b>	28	The extension point <b><a href="../reference/extension-points/org_eclipse_ui_views.html">org.eclipse.ui.views</a></b>
29	allows plug-ins to add views to the workbench. Plug-ins that contribute a view must register the view in their	29	allows plug-ins to add views to the workbench. Plug-ins that contribute a view must register the view in their
30	<b> plugin.xml </b> file and provide  configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.</P>	30	<b> plugin.xml </b> file and provide configuration information about the view, such as its implementation class, the category (or group) of views to which it belongs, and the name and icon that should be used to describe the view in menus and labels.</P>
31	<P >	31	<P >
32	The interface for views is defined in <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, but plug-ins	32	The interface for views is defined in <b><a href="../reference/api/org/eclipse/ui/IViewPart.html">IViewPart</a></b>, but plug-ins
33	can choose to extend the	33	can choose to extend the
Lines 39-65 Link Here
39	let's take a look at the declaration of the extension in the <b>plugin.xml</b>.</P>	39	let's take a look at the declaration of the extension in the <b>plugin.xml</b>.</P>
40	<pre><extension	40	<pre><extension
41	point="org.eclipse.ui.views">	41	point="org.eclipse.ui.views">
42	<category	42	<category
43	id="org.eclipse.ui.examples.readmetool"	43	id="org.eclipse.ui.examples.contributions.viewCategory"
44	name="%Views.category">	44	name="%contributions.viewCategory.name">
45	</category>	45	</category>
46	<view	46	<view
47	id="org.eclipse.ui.examples.readmetool.views.SectionsView"	47	category="org.eclipse.ui.examples.contributions.viewCategory"
48	name="%Views.ReadmeSections"	48	class="org.eclipse.ui.examples.contributions.view.InfoView"
49	icon="icons/view16/sections.png"	49	id="org.eclipse.ui.examples.contributions.view"
50	category="org.eclipse.ui.examples.readmetool"	50	name="%contributions.view.name">
51	class="org.eclipse.ui.examples.readmetool.ReadmeSectionsView">	51	</view>
52	</view>
53	</extension>	52	</extension>
54	</pre>	53	</pre>
55	<P >	54	<P >
56	This should look pretty familiar. We see that a new view, <b>ReadmeSectionsView</b>, is contributed to the workbench. The	55	This should look pretty familiar. We see that a new view, <b>InfoView</b>, is contributed to the workbench. The
57	<b>view id</b>, <b>name</b>,	56	<b>view id</b>, <b>name</b>,
58	and	57	and
59	<b> category</b> are specified as we've seen before. An <b> icon</b> is also provided	58	<b> category</b> are specified as we've seen before.</P>
60	for the view, using a path relative to the plug-in's installation directory. </P>
61	<P >	59	<P >
62	Let's look at the <b>ReadmeSectionsView</b>. You can show any view in the	60	Let's look at the <b>InfoView</b>. You can show any view in the
63	workbench by choosing	61	workbench by choosing
64		62
65	<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView")'>	63	<a class="command-link" href='javascript:executeCommand("org.eclipse.ui.views.showView")'>
Lines 68-81 Link Here
68		66
69	and selecting the view from the <b>Show View</b> list.</P>	67	and selecting the view from the <b>Show View</b> list.</P>
70	<P >	68	<P >
71	When we show the <b>ReadmeSectionsView</b>, a view with a list in it pops up.	69	When we show the <b>InfoView</b>, a view with a list in it pops up.
72	The list is empty unless we click on a file with an extension of <b>.readme</b>, in which case	70	The list is pre-populated with some data.</P>
73	the list is populated with sections from the readme file.</P>
74		71
75	<img src="images/readmeview.png" alt="" border="0">	72	<img src="images/contributions_window.png" alt="Picture of the workbench, showing the contributions">
76	<P >
77	How does the plug-in recognize the readme file and how did it know about selection changes? If we can track down
78	the answers to these questions, we are well on our way to understanding how to build integrated workbench plug-ins.</P>
79	<P >	73	<P >
80	We'll start with the familiar <b>createPartControl</b>	74	We'll start with the familiar <b>createPartControl</b>
81	method.  As we saw in the Hello World example, this is where the widgets	75	method.  As we saw in the Hello World example, this is where the widgets
Lines 84-157 Link Here
84	<pre>	78	<pre>
85	public void createPartControl(Composite parent) {	79	public void createPartControl(Composite parent) {
86	viewer = new ListViewer(parent);	80	viewer = new ListViewer(parent);
		81	viewer.setContentProvider(new ContentProvider());
		82	viewer.setLabelProvider(new LabelProvider());
		83	viewer.addDoubleClickListener(new IDoubleClickListener() {
		84	public void doubleClick(DoubleClickEvent event) {
		85	editSelection();
		86	}
		87	});
		88	// A service will be providing our input
		89	IPersonService service = (IPersonService) getSite().getService(
		90	IPersonService.class);
		91	viewerInput = new ArrayList(service.getPeople());
		92	viewer.setInput(viewerInput);
87	...	93	...
88	// add myself as a global selection listener	94	// register myself as a selection provider for this view
89	getSite().getPage().addSelectionListener(this);	95	getSite().setSelectionProvider(viewer);
90
91	// prime the selection
92	selectionChanged(null, getSite().getPage().getSelection());
93	}	96	}
94	</pre>	97	</pre>
95	<P >	98	<P >
96	The view creates and stores a ListViewer and registers itself as a selection listener	99	The view creates and stores a ListViewer and sets the content and label provides.
97	on its page. It obtains the page from an	100	It also registers itself as the selection
		101	provider for this view.
		102	(The concept of selection provider, label provider, and content provider come
		103	from JFace <a href="jface_viewers.htm">viewers</a>.)
		104	It obtains the service from its
98	<b><a href="../reference/api/org/eclipse/ui/IViewSite.html">IViewSite</a></b>, which contains information about the view's context, such as its workbench window,	105	<b><a href="../reference/api/org/eclipse/ui/IViewSite.html">IViewSite</a></b>, which contains information about the view's context, such as its workbench window,
99	its containing page, its local services, and its plug-in. When we are notified of a selection change, what happens?	106	its containing page, its local services, and its plug-in.</P>
100	The following code is executed:</P>	107	<p>
101	<pre>	108	</p>
102	public void selectionChanged(IWorkbenchPart part, ISelection sel) {
103	//if the selection is a readme file, get its sections.
104	AdaptableList input = ReadmeModelFactory.getInstance().getSections(sel);
105	viewer.setInput(input);
106	}
107	</pre>
108	<P >
109	It looks like the <b> ReadmeModelFactory</b> class is responsible for turning the selection into readme
110	sections and these sections are input for
111	the viewer that we created in the <b>createPartControl</b>
112	method.</P>
113	<P >
114	But how did the viewer populate its list widgets?  For now, let's assume that once the viewer was told its input element, it knew how to populate
115	its list widget with the information - it is a ListViewer, after all.  If you must know right now what this viewer is all about, go to <a HREF="jface_viewers.htm" CLASS="XRef">Viewers</a>. </P>
116	<P >
117	We still do not know how readme files are detected or where the file's section
118	information comes from.  A quick look at the
119	<b> ReadmeModelFactory</b> sheds some light.</P>
120	<pre>
121	public AdaptableList getSections(ISelection sel) {
122	// If sel is not a structured selection just return.
123	if (!(sel instanceof IStructuredSelection))
124	return null;
125	IStructuredSelection structured = (IStructuredSelection)sel;
126
127	//if the selection is a readme file, get its sections.
128	Object object = structured.getFirstElement();
129	if (object instanceof IFile) {
130	IFile file = (IFile) object;
131	String extension = file.getFileExtension();
132	if (extension != null && extension.equals(IReadmeConstants.EXTENSION)) {
133	return getSections(file);
134	}
135	}
136
137	//the selected object is not a readme file
138	return null;
139	}
140	</pre>
141	<P >We check the selection to see if it is a structured (multiple)
142	selection.  (The concept of a structured selection comes from JFace <a href="jface_viewers.htm">viewers</a>.)
143	For the first object in the selection, we check to see whether it is a file (<b><a href="../reference/api/org/eclipse/core/resources/IFile.html">IFile</a></b>)
144	resource.  If it is, we check its extension to see if it matches the "<b>.readme</b>"
145	extension.  Once we know we have a readme file, we can use other methods to
146	parse the sections.   You can browse the rest of <b>ReadmeModelFactory</b>,
147	<b>MarkElement</b>, and <b> DefaultSectionsParser</b> for the
148	details about the file parsing. </P>
149	<P >	109	<P >
150	We've covered a lot of common workbench concepts by studying this extension. Now we'll move on to some other workbench extensions and examine how your plug-in can further contribute to the workbench UI. </P>	110	We've covered a lot of common workbench concepts by studying this extension. Now we'll move on to some other workbench extensions and examine how your plug-in can further contribute to the workbench UI. </P>
151		111
152		112
153
154
155
156	</BODY>	113	</BODY>
157	</HTML>	114	</HTML>

Lines 22-36 Link Here

(-)guide/workbench_cmd.htm (-6 / +7 lines)
22	of the Command Framework became mature. In 3.3 the menu contributions portion	22	of the Command Framework became mature. In 3.3 the menu contributions portion
23	of the Command Framework became available.	23	of the Command Framework became available.
24	</p>	24	</p>
		25	<p >
		26	The workbench defines extension points that allow plug-ins to contribute
		27	behaviors to existing views and editors or to provide implementations for
		28	new views and editors. We'll use the Info example from the
		29	contributions plugin. It provides a view that lists people and an
		30	editor for updating their names. </p>
25	<p>	31	<p>
26	We are going to take a look at how commands, handlers, menu contributions,	32	We are going to take a look at how commands, handlers, menu contributions,
27	and keybindings can be used to contribute behaviour to the workbench,	33	and keybindings can be used to contribute behaviour to the workbench,
28	to views, and to editors. We'll use the Info example from the	34	to views, and to editors.
29	contributions plugin. It provides a view that lists people and an
30	editor for updating their names. Much of the contribution of editors
31	and views has already been covered in the readme example in
32	<a href="workbench_basicext.htm"
33	class="XRef">Basic workbench extension points using actions</a>.
34	</p>	35	</p>
35		36
36	<img src="images/contributions_window.png" alt="Picture of the workbench, showing the contributions">	37	<img src="images/contributions_window.png" alt="Picture of the workbench, showing the contributions">

Lines 19-38 Link Here

(-)guide/workbench_cmd_commands.htm (-9 / +5 lines)
19		19
20	<p>A <b>command</b> is the declaration of a behaviour by <b>id</b>.	20	<p>A <b>command</b> is the declaration of a behaviour by <b>id</b>.
21	Commands are used to declare semantic behaviour so that action implementations defined	21	Commands are used to declare semantic behaviour so that action implementations defined
22	elsewhere by handlers, or linked to the action extension points (see	22	elsewhere by handlers. The separation of the command from the behaviour
23	<a href="workbench_basicext.htm"	23	implementation allows multiple plug-ins to define implementations that implement the
24	class="XRef">Basic workbench extension points using actions</a>)
25	can associate themselves with a particular semantic
26	command. The separation of the command from the action
27	implementation allows multiple plug-ins to define actions that implement the
28	same semantic command. The command is what gets associated with a	24	same semantic command. The command is what gets associated with a
29	particular key binding.</p>	25	particular key binding.</p>
30		26
31		27
32	<p>The workbench defines many common commands in its <b>plugin.xml</b>	28	<p>The workbench defines many common commands in its <b>plugin.xml</b>
33	file, and plug-ins are encouraged to associate their own actions with these	29	file, and plug-ins are encouraged to associate their own implementations with these
34	commands where it makes sense. In this way, semantically similar	30	commands where it makes sense. In this way, semantically similar
35	actions implemented in different plug-ins may share the same key binding.</p>	31	behaviour implemented in different plug-ins may share the same key binding.</p>
36		32
37		33
38	<h4>Defining a command</h4>	34	<h4>Defining a command</h4>
Lines 57-63 Link Here
57		53
58		54
59	<p>The command definition specifies a <b>name</b>, <b>description</b>, and <b>id</b> for	55	<p>The command definition specifies a <b>name</b>, <b>description</b>, and <b>id</b> for
60	the action. It also specifies the id of a category for the command, which is	56	the behaviour. It also specifies the id of a category for the command, which is
61	used to group commands in the preferences dialog.  The categories are also	57	used to group commands in the preferences dialog.  The categories are also
62	defined in the <b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a>	58	defined in the <b><a href="../reference/extension-points/org_eclipse_ui_commands.html">org.eclipse.ui.commands</a>
63	</b>	59	</b>

Lines 20-26 Link Here

(-)guide/workbench_cmd_expressions.htm (-2 / +3 lines)
20	<a href="../reference/extension-points/org_eclipse_core_expressions_definitions.html">org.eclipse.core.expressions.definitions</a>	20	<a href="../reference/extension-points/org_eclipse_core_expressions_definitions.html">org.eclipse.core.expressions.definitions</a>
21	for a description) for <code>enabledWhen</code> and <code>activeWhen</code> for handlers, programmatic	21	for a description) for <code>enabledWhen</code> and <code>activeWhen</code> for handlers, programmatic
22	activation of contexts, and for <code>visibleWhen</code> for menu contributions. Core expressions are also used	22	activation of contexts, and for <code>visibleWhen</code> for menu contributions. Core expressions are also used
23	as conditionals for certain property page contribution and object contribution expressions.	23	as conditionals for certain property page contribution and object contribution expressions, using the
		24	<code>enablement</code> element.
24	In most cases, the workbench provides the	25	In most cases, the workbench provides the
25	<a href="../reference/api/org/eclipse/core/expressions/IEvaluationContext.html">IEvaluationContext</a>	26	<a href="../reference/api/org/eclipse/core/expressions/IEvaluationContext.html">IEvaluationContext</a>
26	that command core expressions are evaluate against.	27	that command core expressions are evaluate against.
Lines 235-241 Link Here
235		236
236	<a name="ex5"></a><h4>ActionSets and Contexts</h4>	237	<a name="ex5"></a><h4>ActionSets and Contexts</h4>
237		238
238	<p>As of 3.3 all <a href="../reference/extension-points/org_eclipse_ui_actionSets.html">org.eclipse.ui.actionSets</a>	239	<p>As of 3.3 all <a href="../reference/extension-points/org_eclipse_ui_actionSets.html">org.eclipse.ui.actionSets</a> <b>(Deprecated)</b>
239	generate a context with a parent of <code>org.eclipse.ui.contexts.actionSet</code>. Contexts with	240	generate a context with a parent of <code>org.eclipse.ui.contexts.actionSet</code>. Contexts with
240	this parent are filtered from the <a class="command-link"	241	this parent are filtered from the <a class="command-link"
241	href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'>	242	href='javascript:executeCommand("org.eclipse.ui.window.preferences(preferencePageId=org.eclipse.ui.preferencePages.Keys)")'>

Lines 29-37 Link Here

(-)guide/workbench_cmd_menus.htm (-7 / +4 lines)
29		29
30	<h4>Contribution location</h4>	30	<h4>Contribution location</h4>
31	<p>	31	<p>
32	The older action contribution points use the concept of	32	The <b>org.eclipse.ui.menus</b>
33	<a href="workbench_menupaths.htm" class="XRef">menu and toolbar paths</a>
34	to place menu items and tool items. The <b>org.eclipse.ui.menus</b>
35	extension point requires the id of a menu, toolbar, or trim area and an insertion	33	extension point requires the id of a menu, toolbar, or trim area and an insertion
36	point. This is the <b>locationURI</b> of a <menuContribution/> element.	34	point. This is the <b>locationURI</b> of a <menuContribution/> element.
37	Some examples of <b>locationURIs</b>:</p>	35	Some examples of <b>locationURIs</b>:</p>
Lines 51-57 Link Here
51		49
52	<p>	50	<p>
53	A word about popup: locationURIs. In <code>popup:id</code>, the id refers to	51	A word about popup: locationURIs. In <code>popup:id</code>, the id refers to
54	the id that comes from registering the context menu when the registerContextMenu(*)	52	the id that comes from registering the context menu when the <code>registerContextMenu(*)</code>
55	method is called. If an no id is specified in the call, it defaults to the id of	53	method is called. If an no id is specified in the call, it defaults to the id of
56	the view or editor registering the context menu.	54	the view or editor registering the context menu.
57	</p>	55	</p>
Lines 253-259 Link Here
253	</p>	251	</p>
254		252
255	<p>	253	<p>
256	You can add menu contributions that work similar to <b>org.eclipse.ui.editorActions</b>.	254	You can add menu contributions that work similar to <b>org.eclipse.ui.editorActions (Deprecated)</b>.
257	First you define your editor command and handler, like Reset. Then you can	255	First you define your editor command and handler, like Reset. Then you can
258	add them in an editor menu like "Info" to the main menu:</p>	256	add them in an editor menu like "Info" to the main menu:</p>
259	<pre>	257	<pre>
Lines 308-315 Link Here
308	<h4>Contributing to popup menus</h4>	306	<h4>Contributing to popup menus</h4>
309		307
310	<p>	308	<p>
311	As in <a href="workbench_basicext_popupMenus.htm" class="XRef">org.eclipse.ui.popupMenus</a>,	309	Commands can be contributed to a specific context menu by the context menu's id, or to any
312	commands can be contributed to a specific context menu by the context menu's id, or to any
313	context menu where it can satisfy its <visibleWhen> clause. For example, we can add	310	context menu where it can satisfy its <visibleWhen> clause. For example, we can add
314	our Refresh command to the Info View popup as a convenience. Because we didn't call	311	our Refresh command to the Info View popup as a convenience. Because we didn't call
315	<code>registerContextMenu(*)</code> with a specific id it defaults to the view id.</p>	312	<code>registerContextMenu(*)</code> with a specific id it defaults to the view id.</p>

Removed Link Here

(-)guide/workbench_menupaths.htm (-338 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Menu and toolbar paths
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17
18	<h2>
19	Menu and toolbar paths</h2>
20	<P >
21	We've seen many action contributions that specify the path for the location of their action. Let's take a close look at what these paths mean.  </P>
22
23	<h3 >
24	Menu paths</h3>
25
26	<P >
27	We'll look at menu paths first by looking at the workbench <b>Help</b> menu.</P>
28
29	<H4>
30	Named groups in the workbench</H4>
31	<P >
32	The locations for inserting new menus and menu items are defined using named groups. You can think of
33	a named group as a slot or placeholder that allows you to insert your menu items
34	at certain points in a menu bar or pulldown menu.</P>
35	<P >
36	The workbench defines all of its group slot names in the classes <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>
37	and <b><a href="../reference/api/org/eclipse/ui/ide/IIDEActionConstants.html">IIDEActionConstants</a></b>.
38	(Two different classes are used since resource-related menu items are factored out of the generic workbench).
39	For each workbench menu, named groups are placed in the menu at locations where it is expected that
40	plug-ins will insert new actions.</P>
41	<P >
42	The following description of the help menu is adapted from the <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
43	class definition.</P>
44	<pre>
45	Standard Help menu actions
46	Start group - HELP_START - "start"
47	End group - HELP_END - "end"
48	</pre>
49	<P >
50	The standard workbench help menu defines a named group called "<b>start</b>," followed by a named group called "<b>end</b>,".
51	Defining two groups gives plug-ins a little more control over where their contributed
52	items will be positioned within the help menu.  When you define a menu, you can define as many slots as you like. Adding more slots gives
53	other plug-ins more control over where their contributions appear relative to existing contributions. </P>
54	<P >
55	Plug-ins that add a menu item to the help menu can use these group names to decide where their
56	menu item will go. For example, the cheatsheet plug-in adds an action
57	set containing the "Cheat Sheets..." menu to the workbench.  Here's
58	the markup from the <b>org.eclipse.ui.cheatsheets</b> plug-in's
59	<b>plugin.xml</b>. </P>
60	<pre>
61	<extension
62	point="org.eclipse.ui.actionSets">
63	<actionSet
64	label="%CHEAT_SHEETS"
65	visible="true"
66	id="org.eclipse.ui.cheatsheets.actionSet">
67	<action
68	label="%CHEAT_SHEETS_MENU"
69	class="org.eclipse.ui.internal.cheatsheets.actions.CheatSheetHelpMenuAction"
70	<b>menubarPath="help/helpStart"</b>
71	id="org.eclipse.ui.cheatsheets.actions.CheatSheetHelpMenuAction">
72	</action>
73	</actionSet>
74	</extension>
75	</pre>
76	<P >
77	The new help action will be placed in the help menu, inside the <b>helpStart</b> group.</P>
78
79
80	<H4>
81	Fully qualified menu paths</H4>
82	<P >
83	A complete menu path is simply "menu name/group
84	name."  Most menu names for the workbench are defined in
85	<b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>.
86	(Resource-related menu names are defined in <b><a href="../reference/api/org/eclipse/ui/ide/IIDEActionConstants.html">IIDEActionConstants</a></b>.)
87	If we look for the name of the help menu in this class, we'll find
88	that the fully qualified path name for our help action is
89	"<b>help/helpEnd</b>." </P>
90	<P >
91	Some menus have nested submenus. This is where longer paths come into play. If the help menu had defined a submenu
92	called "<b>submenu</b>" with a named group called "<b>submenuStart</b>,"
93	then the fully qualified menu path for an action in the new submenu would be
94	"<b>help/submenu/submenuStart</b>."</P>
95
96
97	<H4>
98	<a name="workbench_menus_nls">
99	Externalizing UI labels</a></H4>
100	<p>The example above demonstrates a technique for externalizing strings
101	that appear in the UI.  Externalized strings are used to make translating the plug-in's UI to
102	other languages simpler.  We can externalize the strings in our <b>plugin.xml
103	</b>files by replacing the string with a key (<b>%CHEAT_SHEETS_MENU</b>) and creating entries in the <b>plugin.properties</b>
104	file of the form:</p>
105	<pre>
106	CHEAT_SHEETS_MENU = Cheat Sheets...
107	</pre>
108	<P >
109	The <b>plugin.properties</b> file can be
110	translated for different languages and the <b>plugin.xml</b>
111	will not need to be modified.</P>
112
113
114	<H4>
115	Adding new menus and groups</H4>
116	<P >
117	In many of the examples we've seen so far, the actions contributed by the sample plug-ins have been added to existing named groups within menus.</P>
118	<P >
119	The <b><a href="../reference/extension-points/org_eclipse_ui_menus.html">menus</a></b> extension point
120	allows you to contribute to your menus using an alternative placement syntax, menu ids.
121	The <b><a href="../reference/extension-points/org_eclipse_ui_actionSets.html">actionSets</a></b>,
122	<b><a href="../reference/extension-points/org_eclipse_ui_viewActions.html">viewActions</a></b>,
123	<b><a href="../reference/extension-points/org_eclipse_ui_editorActions.html">editorActions</a></b>, and
124	<b><a href="../reference/extension-points/org_eclipse_ui_popupMenus.html"> popupMenus</a></b> extension points also allow you to define new menus and groups within your contribution. This means that you can define new submenus or new
125	pull-down menus and contribute your actions to these new menus. In this case, the path for your new action will contain the name of your newly defined menu. </P>
126	<P>
127	We saw this technique when the readme tool defined a new menu for its action
128	set.  Let's look at the markup one more time now that we've looked at menu
129	paths in more detail. </P>
130	<pre>
131	<extension point = "org.eclipse.ui.actionSets">
132	<actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
133	label="%ActionSet.name"
134	visible="true">
135	<<b>menu id="org_eclipse_ui_examples_readmetool"</b>
136	label="%ActionSet.menu"
137	<b>path="window/additions"</b>>
138	<separator name="slot1"/>
139	<separator name="slot2"/>
140	<separator name="slot3"/>
141	</menu>
142	<action id="org_eclipse_ui_examples_readmetool_readmeAction"
143	<b>menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"</b>
144	toolbarPath="readme"
145	label="%ReadmeAction.label"
146	tooltip="%ReadmeAction.tooltip"
147	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
148	icon="icons/ctool16/openbrwsr.png"
149	class="org.eclipse.ui.examples.readmetool.WindowActionDelegate"
150	enablesFor="1">
151	<selection class="org.eclipse.core.resources.IFile"
152	name="*.readme">
153	</selection>
154	</action>
155	...
156	</pre>
157	<P >We added a new menu called  "<b>org_eclipse_ui_examples_readmetool</b>"
158	whose label is defined in by the key "<b>%ActionSet.name</b>" in the
159	properties file. Within this menu, we define three named
160	groups:  "<b>slot1</b>," "<b>slot2</b>,"
161	and "<b>slot3</b>."  We add this new
162	menu to the path "<b>window/additions</b>."</P>
163	<P >If we go back to <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>,
164	we see this definition of the window menu in the javadoc:</P>
165	<pre>
166	* <h3>Standard Window menu actions</h3>
167	* <ul>
168	* <li>Extra Window-like action group (<code>WINDOW_EXT</code>)</li>
169	</pre>
170	<P >
171	If we look further at the class definition, we will see these related
172	definitions: </P>
173
174
175	<pre>
176	public static final String MENU_PREFIX = "";
177	...
178	public static final String M_WINDOW = MENU_PREFIX+"window";
179	...
180	public static final String MB_ADDITIONS = "additions"; // Group.
181	...
182	public static final String WINDOW_EXT = MB_ADDITIONS; // Group.
183	</pre>
184
185
186	<P >
187	From this information, we can piece together the path for adding something to
188	the workbench "Window" menu.  The menu itself is called "<b>window</b>"
189	and it defines one slot called "<b>additions</b>."
190	We use the path "<b>window/additions</b>" to
191	add our new menu. </P>
192
193
194	<P >
195	In the action set declaration, we add an action to our newly defined menu, using
196	the path "<b>window/org_eclipse_ui_examples_readmetool/slot1</b>." </P>
197
198
199	<P >
200	<img src="images/readmeactionsetmenu.png" alt="" border="0"> </P>
201
202
203	<P >Other plug-ins could add to our menu by using this same path (or perhaps one
204	of the other slots) to add one of their own menus.   </P>
205
206
207	<P >In the readme tool example, we use the <b>separator</b> attribute to
208	identify the group names.  This will cause a separator line to appear
209	between these groups when they contain items.  We could instead use the <b>groupMarker</b>
210	attribute if we want to define a named group without showing any separators in
211	the menu to distinguish between the groups. </P>
212
213
214	<h3 >Tool bar paths </h3>
215
216
217	<p>Tool bar paths work similarly to menu paths.  </p>
218
219
220	<h4>Named tool bars in the workbench</h4>
221
222
223	<p>The workbench tool bar is composed of
224	tool bars contributed by different plug-ins, including the workbench
225	itself.  Within any particular tool bar, there are named groups or slots that can be used for inserting new tool bar items.
226	</p>
227	<P >
228	The following description of the workbench tool bars is adapted from the <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
229	class definition.</P>
230	<pre>// Workbench toolbar ids
231	public static final String TOOLBAR_FILE = "org.eclipse.ui.workbench.file"
232	public static final String TOOLBAR_NAVIGATE = "org.eclipse.ui.workbench.navigate";
233
234	// Workbench toolbar group ids. To add an item at the beginning of the group,
235	// use the GROUP id. To add an item at the end of the group, use the EXT id.
236	public static final String PIN_GROUP = "pin.group";
237	public static final String HISTORY_GROUP = "history.group";
238	public static final String NEW_GROUP = "new.group";
239	public static final String SAVE_GROUP = "save.group";
240	public static final String BUILD_GROUP = "build.group"; </pre>
241	<p>In the simplest case, a plug-in can contribute a tool bar item in its own
242	tool bar.  For example, the readme tool actions contributed to the menu are
243	also given a tool bar path: </p>
244	<pre>
245	<action id="org_eclipse_ui_examples_readmetool_readmeAction"
246	menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
247	<b>toolbarPath="readme"
248	</b>...</pre>
249	<p>Since there is no reference to the workbench tool bar paths or groups, the
250	readme actions appear in their own group on the tool bar.  Specifying the
251	following path would instead place the item in the file tool bar in the save
252	group:</p>
253	<pre>...
254	<action id="org_eclipse_ui_examples_readmetool_readmeAction"
255	menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
256	<b>toolbarPath="org.eclipse.ui.workbench.file/save.group"
257	</b>...</pre>
258	<p>The paths defined in <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b> IWorkbenchActionConstants</b></a>
259	may be referenced in the tool bar paths of other plug-ins.</p>
260	<h4>Adding to action sets of another plug-in</h4>
261	<p>Suppose a plug-in wants its tool bar items better integrated with actions
262	from a different plug-in?  Let's look at how the external
263	tools plug-in (<b>org.eclipse.ui.externaltools</b>) integrates its action with the debugger tool bar.  The
264	debugger (<b>org.eclipse.debug.ui</b>) defines its tool bar actions like this:</p>
265	<pre><extension
266	point="org.eclipse.ui.actionSets">
267	<actionSet
268	label="%LaunchActionSet.label"
269	visible="false"
270	id="org.eclipse.debug.ui.launchActionSet">
271	...
272	<action
273	<b>toolbarPath="debug"</b>
274	id="org.eclipse.debug.internal.ui.actions.RunDropDownAction"
275	hoverIcon="icons/full/ctool16/run_exc.png"
276	class="org.eclipse.debug.internal.ui.actions.RunToolbarAction"
277	disabledIcon="icons/full/dtool16/run_exc.png"
278	icon="icons/full/etool16/run_exc.png"
279	helpContextId="run_action_context"
280	label="%RunDropDownAction.label"
281	pulldown="true">
282	</action>
283	...</pre>
284	<p>Just like the readme tool, the debugger plug-in defines its own tool bar
285	path, which means its tool bar items will be inside their own tool bar on the
286	workbench.  What does the external tools plug-in do?</p>
287	<pre><extension point="org.eclipse.ui.actionSets">
288	<actionSet
289	id="org.eclipse.ui.externaltools.ExternalToolsSet"
290	label="%ActionSet.externalTools"
291	visible="true">
292	...
293	<action
294	id="org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
295	definitionId= "org.eclipse.ui.externaltools.ExternalToolMenuDelegateToolbar"
296	label="%Action.externalTools"
297	<b>toolbarPath="org.eclipse.debug.ui.launchActionSet/debug"</b>
298	disabledIcon="icons/full/dtool16/external_tools.png"
299	icon="icons/full/etool16/external_tools.png"
300	hoverIcon="icons/full/ctool16/external_tools.png"
301	tooltip="%Action.externalToolsTip"
302	pulldown="true"
303	class="org.eclipse.ui.externaltools.internal.menu.ExternalToolMenuDelegate">
304	</action>
305	</actionSet>
306	</extension></pre><p>Note the use of the action set ID of the
307	debugger in the tool bar path.  Using an action set ID in the path denotes
308	that the tool bar item should be placed in the tool bar used by the referenced
309	action set.  Within a toolbar group, items are ordered by action set id, so
310	for our example, the external tools action will appear after the debugger actions. </p>
311	<p>When adding to an action set's tool bar, new groups can also be defined.
312	If the external tools plug-in defined its <b> toolbarpath</b> as
313	<b>"org.eclipse.debug.ui.launchActionSet/external"</b> a new group would be created
314	for the action on the tool bar.  As with menus, tool bar groups are delineated by separators. </p>
315	<h3 >Using paths from another plug-in </h3>
316
317
318	<P >In general, it's not good practice to contribute to another plug-in's menu
319	or tool bar by deriving the path name from the <b>plugin.xml</b> unless it has
320	been marked specifically as being available for clients.  It's possible that a future version of the plug-in could change the names of the
321	paths.  Two common ways to mark your plug-in's action set ids and paths as
322	fair game are: </P>
323
324
325	<ul>
326	<li>annotate the XML with comments that explicitly mark the menu path or
327	action set as usable by clients</li>
328	<li>define a public interface (much like <b><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html">IWorkbenchActionConstants</a></b>)
329	which specifies exactly which menus, tool bar groups, and slots are considered
330	fair game for use by other plug-ins</li>
331	</ul>
332
333
334
335
336
337	</BODY>
338	</HTML>

Lines 37-136 Link Here

(-)guide/workbench_menus.htm (-91 / +9 lines)
37	<TD width="118">	37	<TD width="118">
38	<P CLASS="CellBody">	38	<P CLASS="CellBody">
39	<b>	39	<b>
40	viewActions</b></P>
41	</TD>
42	<TD width="359">
43	<P CLASS="CellBody">
44	Actions appear in a specific view's local toolbar and local pulldown menu.</P>
45	</TD>
46	<TD width="335">
47	<P CLASS="CellBody">
48	Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html">IViewActionDelegate</a></b>. Specify the id of the contribution and the id of the target view that should show the action. The label and image
49	dictate the appearance of the action in the UI. The path specifies the location relative to the view's menu and toolbar items.</P>
50	</TD>
51	</TR>
52	<TR>
53	<TD width="118">
54	<P CLASS="CellBody"><b>editorActions</b></P>
55	</TD>
56	<TD width="359">
57	<P CLASS="CellBody">
58	Actions are associated with an editor and appear in the workbench menu and/or tool bar.</P>
59	</TD>
60	<TD width="335">
61	<P CLASS="CellBody">
62	Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>. Specify the id of the contribution and the id of the target editor that causes the action to be shown. The label and image specify the appearance of the action in the UI. Separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.</P>
63	</TD>
64	</TR>
65	<TR>
66	<TD width="118">
67	<P CLASS="CellBody">
68	<b>
69	popupMenus</b></P>
70	</TD>
71	<TD width="359">
72	<P CLASS="CellBody">
73	Actions appear in the popup menu of an editor or view. Actions associated with an object type show up in all popups of views
74	and editors that show the object type. Actions associated with a specific popup menu appear only in that popup menu.</P>
75	</TD>
76	<TD width="335">
77	<P CLASS="CellBody">
78	<b>
79	Object contributions</b> specify the type of object for which the action should appear in a popup menu. The action will be shown in all view
80	and editor popups
81	that contain the object type.  Provide an action class that implements <b><a href="../reference/api/org/eclipse/ui/IObjectActionDelegate.html">IObjectActionDelegate</a></b>. <BR>
82	<b>
83	Viewer contributions</b> specify the id of the target popup menu in which the menu item should appear.
84	Provide an action class that implements <b><a href="../reference/api/org/eclipse/ui/IEditorActionDelegate.html">IEditorActionDelegate</a></b>
85	or <b><a href="../reference/api/org/eclipse/ui/IViewActionDelegate.html">IViewActionDelegate</a></b>. </P>
86	</TD>
87	</TR>
88	<TR>
89	<TD width="118">
90	<P CLASS="CellBody">
91	<b>
92	actionSets</b></P>
93	</TD>
94	<TD width="359">
95	<P CLASS="CellBody">
96	Actions appear in the workbench main menus and toolbar. Actions are grouped into action sets. All actions in an action set will show up in the workbench menus and toolbars according to the user's selection of action sets
97	and the current perspective shown in the workbench.  May be influenced by
98	actionSetPartAssociations (below).</P>
99	</TD>
100	<TD width="335">
101	<P CLASS="CellBody">
102	Contribute an action class that implements <b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowActionDelegate.html"> IWorkbenchWindowActionDelegate</a></b> or
103	<b><a href="../reference/api/org/eclipse/ui/IWorkbenchWindowPulldownDelegate.html">IWorkbenchWindowPulldownDelegate</a></b>. Specify the
104	<b> name</b> and <b> id</b> of the action set. Enumerate all of the actions that are defined for that action set. For each action, separate menu and toolbar paths specify the existence and location of the contribution in the workbench menu and toolbar.</P>
105	</TD>
106	</TR>
107	<tr>
108	<TD width="118">
109	<P CLASS="CellBody">
110	<b>
111	actionSetPartAssociations</b></P>
112	</TD>
113	<TD width="359">
114	<P CLASS="CellBody"> Actions sets are shown only when the specified views or
115	editors are active.  This is ignored if the user has customized the current
116	perspective.</P>
117	</TD>
118	<TD width="335">
119	<P CLASS="CellBody">
120	Specify an action set by <b>id</b> and followed by one or more parts (by <b>id</b>)
121	that must be active in the current perspective in order to show the action set.</P>
122	</TD>
123	</tr>
124	<TR>
125	<TD width="118">
126	<P CLASS="CellBody">
127	<b>
128	menus</b></P>	40	menus</b></P>
129	</TD>	41	</TD>
130	<TD width="359">	42	<TD width="359">
131	<P CLASS="CellBody">	43	<P CLASS="CellBody">
132	Commands can be placed in all of the locations covered by the 4 main action	44	Commands can be placed in the main menu and toolbar. Command can be placed in
133	extension points, plus other trim areas.	45	part context menus, as well as view menus and view toolbars. The placement
		46	is controlled by the <b>locationURI</b> and the visibility is controlled by
		47	the <b>visibleWhen</b> core expression.
134	</P>	48	</P>
135	</TD>	49	</TD>
136	<TD width="335">	50	<TD width="335">
Lines 143-149 Link Here
143	</TABLE>	57	</TABLE>
144		58
145		59
146		60	<p>This replaces the old action extension points, <b>actionSets</b>, <b>editorActions</b>,
		61	<b>viewActions</b>,
		62	<b>popupMenus</b>,
		63	and <b>actionSetPartAssociations</b>.
		64	</p>
147		65
148		66
149	</BODY>	67	</BODY>

Lines 17-24 Link Here

(-)guide/workbench_plugin.htm (-31 / +23 lines)
17	<H2>	17	<H2>
18	The plug-in class</H2>	18	The plug-in class</H2>
19	<P >	19	<P >
20	So far, we've been looking at the different extensions that are provided by the readme tool. Let's look at the general	20	So far, we've been looking at the different extensions that are provided by the contributions plug-in. Let's look at the general
21	definition of the readme tool plug-in.</P>	21	definition of the contributions plug-in.</P>
22		22
23	<H3>	23	<H3>
24	Plug-in definition</H3>	24	Plug-in definition</H3>
Lines 27-77 Link Here
27	<pre>	27	<pre>
28	Manifest-Version: 1.0	28	Manifest-Version: 1.0
29	Bundle-ManifestVersion: 2	29	Bundle-ManifestVersion: 2
30	Bundle-Name: %Plugin.name	30	Bundle-Name: %contributions.Activator.name
31	Bundle-SymbolicName: org.eclipse.ui.examples.readmetool; singleton:=true	31	Bundle-SymbolicName: org.eclipse.ui.examples.contributions; singleton:=true
32	Bundle-Version: 3.3.0.qualifier	32	Bundle-Version: 3.3.100.qualifier
33	Bundle-ClassPath: readmetool.jar	33	Bundle-Activator: org.eclipse.ui.examples.contributions.Activator
34	Bundle-Activator: org.eclipse.ui.examples.readmetool.ReadmePlugin	34	Require-Bundle: org.eclipse.ui;bundle-version="[3.3.0,4.0.0)",
35	Bundle-Vendor: %Plugin.providerName
36	Bundle-Localization: plugin
37	Require-Bundle: org.eclipse.ui,
38	org.eclipse.core.resources,
39	org.eclipse.core.runtime,	35	org.eclipse.core.runtime,
40	org.eclipse.ui.views,	36	org.eclipse.core.expressions;bundle-version="[3.3.0,4.0.0)"
41	org.eclipse.ui.ide,	37	Bundle-Vendor: %contributions.Activator.providerName
42	org.eclipse.jface.text,	38	Bundle-Localization: plugin
43	org.eclipse.text,	39	Bundle-RequiredExecutionEnvironment: J2SE-1.4
44	org.eclipse.ui.workbench.texteditor,	40	Bundle-ActivationPolicy: lazy
45	org.eclipse.ui.editors
46	Eclipse-AutoStart: true
47	Eclipse-AutoStart-comment: Use Eclipse-AutoStart instead of Eclipse-LazyStart because the readme example should run against 3.1 as well as 3.2.
48	</pre>	41	</pre>
49	<P >	42	<P >
50	The plug-in definition includes the <b>Bundle-Name</b>, <b>Bundle-SymbolicName</b> (plug-in id),	43	The plug-in definition includes the <b>Bundle-Name</b>, <b>Bundle-SymbolicName</b> (plug-in id),
51	<b>Bundle-Version</b>, and <b>Bundle-Vendor</b> of the plug-in. We	44	<b>Bundle-Version</b>, and <b>Bundle-Vendor</b> of the plug-in. We
52	saw most of these parameters before in our hello world plug-in. The readme tool also defines a specialized plug-in class,	45	saw most of these parameters before in our hello world plug-in. The contribution plug-in
53	<b>ReadmePlugin</b>. </P>	46	also defines a specialized plug-in class,
54	<P >	47	<b>org.eclipse.ui.examples.contributions.Activator</b>. </P>
55	The name of the jar file is also provided. File names specified in <b>Bundle-ClassPath</b> are relative to the
56	plug-in's directory, so the readme tool's jar file should be located directly in the plug-in's directory.</P>
57	<P >	48	<P >
58	The <b>Require-Bundle</b> element informs the platform of the readme tool's dependencies.	49	The <b>Require-Bundle</b> element informs the platform of the contribution plug-in's dependencies.
59	The workbench UI plug-ins are listed as required plug-ins, along with the various core, jface, and text plug-ins. </P>	50	The workbench UI plug-ins are listed as required plug-ins, along with the various core and expression plug-ins. </P>
60		51
61	<H3>	52	<H3>
62	AbstractUIPlugin</H3>	53	AbstractUIPlugin</H3>
63	<P >	54	<P >
64	The<b> ReadmePlugin</b> class represents the readme	55	The<b> Activator</b> class represents the contribution plug-in
65	tool plug-in and manages the life cycle of the plug-in.  As we saw in the	56	and manages the life cycle of the plug-in.  As we saw in the
66	Hello World example, you don't have to specify a plug-in class.  The	57	Hello World example, you don't have to specify a plug-in class.  The
67	platform will provide one for you.  In this case, our plug-in needs to	58	platform will provide one for you.  In this case, our plug-in needs to
68	initialize UI related data when it starts up.  The platform class <a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>	59	initialize UI related data when it starts up.
		60	The platform class <a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>
69	provides a structure for managing UI resources and is extended by <b>	61	provides a structure for managing UI resources and is extended by <b>
70	ReadmePlugin</b>.</P>	62	Activator</b>.</P>
71	<P >	63	<P >
72	<a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>	64	<a href="../reference/api/org/eclipse/ui/plugin/AbstractUIPlugin.html"><b>AbstractUIPlugin</b></a>
73	uses the generic startup and shutdown methods to manage images, dialog settings, and a preference store during the lifetime of the plug-in.	65	uses the generic startup and shutdown methods to manage images, dialog settings, and a preference store during the lifetime of the plug-in.
74	We'll look at the specifics of the <b>ReadmePlugin</b> class when we work with dialogs and preferences.</P>	66	</P>
75		67
76		68
77		69

Lines 24-66 Link Here

(-)guide/wrkAdv_keyBindings_accelSet.htm (-32 / +10 lines)
24		24
25		25
26	<pre>...	26	<pre>...
27	<key	27	<key <b>commandId="org.eclipse.ui.file.save"</b>
28	<b>sequence="Ctrl+S"</b>	28	contextId="org.eclipse.ui.contexts.window"
29	<b>commandId="org.eclipse.ui.file.save"</b>	29	schemeId="org.eclipse.ui.examples.contributions.scheme"
30	schemeId="org.eclipse.ui.defaultAcceleratorConfiguration">	30	<b>sequence="CTRL+S"</b>>
31	</key>	31	</key>
32	...</pre>	32	...</pre>
33		33
34		34
35	<p>There is our friend <b>org.eclipse.ui.file.save</b>.  Recall our	35	<p>There is our friend <b>org.eclipse.ui.file.save</b>. In Eclipse, the workbench registers
36	hypothetical action definition:</p>	36	the <b>SaveAction</b> as a handler for this command id in every Workbench Window.</p>
37		37
38	<pre><extension point = "org.eclipse.ui.actionSets">
39	<actionSet id="com.example.actions.actionSet"
40	label="Example Actions"
41	visible="true">
42	<action id="com.example.actions.action1"
43	menubarPath="additions"
44	label="Example Save Action"
45	class="org.example.actions.ExampleActionDelegate"
46	<b>definitionId="org.eclipse.ui.file.save"</b>>
47	</action>
48	...
49	</actionSet>
50	</extension></pre>
51	<p>The <b>sequence</b> attribute for a key binding defines the key	38	<p>The <b>sequence</b> attribute for a key binding defines the key
52	combination that is used to invoke a command.  So, it follows that when our example action set is active, our save action will be invoked	39	combination that is used to invoke a command.  When the
53	when the user chooses <b>Ctrl+S</b>.</p>	40	workbench <b>SaveAction</b> is active, the key combination <kbd>CTRL+S</kbd> will invoke it,
54		41	since the workbench uses the same command id for its <b>SaveAction</b>.</p>
55
56	<p> Likewise, when the
57	workbench <b>SaveAction</b> is active, the same key combination will invoke it
58	instead, since the workbench uses the same command id for its <b>SaveAction</b>.</p>
59
60
61	<p>To complete the example, we need to understand what the <b>configuration</b>
62	is all about.</p>
63
64		42
65		43
66	</BODY>	44	</BODY>

Lines 17-34 Link Here

(-)guide/wrkAdv_keyBindings_actionDef.htm (-4 / +18 lines)
17	<h3>Commands</h3>	17	<h3>Commands</h3>
18		18
19	<p>See the <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a>	19	<p>See the <a href="workbench_cmd_commands.htm" class="XRef">org.eclipse.ui.commands</a>
20	section for defining command definitions.	20	section for creating command definitions, hooking them up with keybindings, and placing
		21	them in menus.
21	</p>	22	</p>
22		23
23	<h4>Associating an action with a command</h4>	24	<h4>Associating a legacy action with a command</h4>
24		25
25		26
26	<p>Actions can be associated with a command in code or in the <b>plugin.xml	27	<p>When still using the old legacy action extension points, actions can be associated with a
		28	command in code or in the <b>plugin.xml
27	</b>for action sets.	29	</b>for action sets.
28	Your choice depends on where the action is defined.</p>	30	Your choice depends on where the action is defined.</p>
29		31
		32	<p>
		33	Instead of using an <b>IAction</b> you should prefer activating an
		34	<a href="../reference/api/org/eclipse/core/commands/AbstractHandler.html"><b>AbstractHandler</b></a>.
		35	</p>
		36	<pre>
		37	// IWorkbench, IWorkbenchWindow, and IWorkbenchPartSite are all IServiceLocators
		38	IHandlerService handlerService = (IHandlerService) locator.getService(IHandlerService.class);
		39	handlerService.activateHandler(org.eclipse.ui.IWorkbenchCommandConstants.FILE_SAVE, new MySaveHandler());
		40	</pre>
30		41
31	<p>Actions that are instantiated in code can also be associated with an action	42
		43
		44	<p>But when working with actions, actions that are instantiated in code can also be associated with an action
32	definition using <a href="../reference/api/org/eclipse/jface/action/IAction.html"><b>IAction</b></a>	45	definition using <a href="../reference/api/org/eclipse/jface/action/IAction.html"><b>IAction</b></a>
33	protocol.  This is typically done when the action is created.  The <b>SaveAction</b>	46	protocol.  This is typically done when the action is created.  The <b>SaveAction</b>
34	uses this technique when it initializes itself. </p>	47	uses this technique when it initializes itself. </p>
Lines 53-58 Link Here
53	the command id that was used in the command definition markup. It is good practice to define constants for your action definitions so that	66	the command id that was used in the command definition markup. It is good practice to define constants for your action definitions so that
54	they are easily referenced in code. </p>	67	they are easily referenced in code. </p>
55		68
		69
56	<p> If you define an	70	<p> If you define an
57	action in an action set, then you typically do not need to	71	action in an action set, then you typically do not need to
58	instantiate an action yourself.  The workbench will do it for you when the user	72	instantiate an action yourself.  The workbench will do it for you when the user

Removed Link Here

(-)guide/wrkAdv_retarget.htm (-132 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Retargetable actions
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<h2>Retargetable actions</h2>
18	<p>It is common for a plug-in's views and editors to implement actions that are
19	semantically similar to existing workbench actions, such as clipboard
20	cut/copy/paste, view refresh, or properties.  The popup menu for views and
21	editors can become quite cluttered if every view or editor has to define unique
22	actions for these operations and include them in their menus.  </p>
23
24
25	<p>To solve this problem, the workbench defines <b>retargetable</b> (also called
26	<b>global</b>) actions that can be handled by any view or editor.  When a
27	view or editor is active, its handler will be run when the user chooses the
28	action from the workbench menu or toolbar.  This allows views and editors
29	to share workbench menu space for semantically similar actions. </p>
30
31
32	<p><a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b>IWorkbenchActionConstants</b></a>
33	documents all of the workbench actions and denotes retargetable actions as
34	global.  For example, here is the definition of the <b>Properties</b> action.</p>
35
36
37	<pre>public static final String PROPERTIES = "properties"; // Global action. </pre>
38
39
40	<p>The following table summarizes some of the more common retargetable actions
41	that are implemented by views and editors:</p>
42
43
44	<table border="1" cellpadding="0" cellspacing="0" width="64%">
45	<tr>
46	<td width="20%"> </td>
47	<td width="20%"><b>File menu</b></td>
48	<td width="20%"><b>Edit menu</b></td>
49	<td width="20%"><b>Navigate menu</b></td>
50	<td width="20%"><b>Project menu</b></td>
51	</tr>
52	<tr>
53	<td width="20%"><b>views</b></td>
54	<td width="20%">move<br>
55	rename<br>
56	refresh<br>
57	properties</td>
58	<td width="20%"> </td>
59	<td width="20%">go into<br>
60	go to resource<br>
61	sync with editor<br>
62	back<br>
63	forward<br>
64	up<br>
65	next<br>
66	previous</td>
67	<td width="20%">open<br>
68	close<br>
69	build<br>
70	rebuild</td>
71	</tr>
72	<tr>
73	<td width="20%"><b>editors</b></td>
74	<td width="20%">revert<br>
75	print</td>
76	<td width="20%">find</td>
77	<td width="20%"> </td>
78	<td width="20%"> </td>
79	</tr>
80	<tr>
81	<td width="20%"><b>views and editors</b></td>
82	<td width="20%"> </td>
83	<td width="20%">cut<br>
84	copy<br>
85	paste<br>
86	delete<br>
87	select all<br>
88	undo<br>
89	redo</td>
90	<td width="20%"> </td>
91	<td width="20%"> </td>
92	</tr>
93	</table>
94	<p>Retargetable actions are created using <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>.
95	The following snippet is from <b>WorkbenchActionBuilder</b>.</p>
96
97
98	<pre> propertiesAction = createGlobalAction(IWorkbenchActionConstants.PROPERTIES, "file", false); </pre>
99
100
101	<p>The <b> createGlobalAction</b> method shows us exactly how to make a <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>.</p>
102
103
104	<pre>private RetargetAction createGlobalAction(String id, String actionDefPrefix, boolean labelRetarget) {
105	RetargetAction action;
106	if (labelRetarget) {
107	action = new LabelRetargetAction(id, WorkbenchMessages.getString("Workbench." + id));
108	}
109	else {
110	action = new RetargetAction(id, WorkbenchMessages.getString("Workbench." + id));
111	}
112	...
113	return action;
114	}</pre>
115
116	<p>When creating a retargetable action, the workbench assigns the id for the
117	action and the default label.  Note that there are two styles of retarget actions.  <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
118	</b>simply allows a view or editor to reimplement an action.  <b><a href="../reference/api/org/eclipse/ui/actions/LabelRetargetAction.html">LabelRetargetAction</a>
119	</b>also allows views and editors to reset the label of the action.
120	This is useful for making the menu label more specific, such as relabeling an <b>Undo</b>
121	action as <b>Undo Typing</b>.  </p>
122
123
124	<p>Now we know how the retarget actions are defined by the workbench.  Let's look
125	next at how your view or editor can provide an implementation for a retargetable action.
126	This is done by <a href="wrkAdv_retarget_setting.htm">setting a global action
127	handler</a>.</p>
128
129
130
131	</BODY>
132	</HTML>

Removed Link Here

(-)guide/wrkAdv_retarget_contribute.htm (-40 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Contributing new retargetable actions
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<h3>Contributing new retargetable actions</h3>
18	<p>The workbench is not the only plug-in that can create retargetable
19	actions.  Your plug-in can define its own retargetable action, so that
20	views and editors within your plug-in can share the same menu actions.
21	There are two ways to contribute retargetable actions from your plug-in:</p>
22	<ul>
23	<li>An <b>editor</b> can define a retargetable action for which the editor and
24	related views can hook handlers.  The action is only available in the
25	menu bar when the editor is open.  </li>
26	<li>An <b>action set</b> can define a retargetable action for which editors
27	and views can hook handlers.  The action will be visible as long as the
28	action set is visible, but it will only be enabled if the active part has
29	hooked a handler for the action.</li>
30	</ul>
31	<p>This mechanism is useful for providing tight integration between editors and
32	related views.  For example, a content outline view can implement a handler
33	for an action defined by its associated editor.  </p>
34	<p>The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
35	tool</a> example demonstrates both of these techniques.</p>
36
37
38
39	</BODY>
40	</HTML>

Removed Link Here

(-)guide/wrkAdv_retarget_contribute_actionsets.htm (-119 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Retargetable action set actions
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<h4>Retargetable action set actions</h4>
18	<p>The <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
19	tool</a> action set also defines retargetable actions.  The action remains
20	visible as long as the readme action set is visible, but it is only enabled when
21	a view or editor that implements the action is active.  When using action
22	sets to define retargetable actions, the actions are created in the action set
23	markup rather than in code.  The following is from the readme tool's action
24	set definition:</p>
25	<pre><extension point = "org.eclipse.ui.actionSets">
26	<actionSet id="org_eclipse_ui_examples_readmetool_actionSet"
27	label="%ActionSet.name"
28	visible="true">
29	...
30	<action id="org_eclipse_ui_examples_readmetool_readmeRetargetAction"
31	menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
32	toolbarPath="readme"
33	label="%ReadmeRetargetAction.label"
34	tooltip="%ReadmeRetargetAction.tooltip"
35	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
36	icon="icons/ctool16/openbrwsr.png"
37	<b>retarget="true"</b>>
38	</action>
39	<action id="org_eclipse_ui_examples_readmetool_readmeRelabelRetargetAction"
40	menubarPath="window/org_eclipse_ui_examples_readmetool/slot1"
41	toolbarPath="readme"
42	label="%ReadmeRelabelRetargetAction.label"
43	tooltip="%ReadmeRelabelRetargetAction.tooltip"
44	helpContextId="org.eclipse.ui.examples.readmetool.open_browser_action_context"
45	icon="icons/ctool16/openbrwsr.png"
46	<b>retarget="true" </b>
47	<b>allowLabelUpdate="true"</b>>
48	</action>
49	...</pre>
50	<p>Retargeted actions are specified by using the <b>retarget="true"</b>
51	attribute.  This will cause a <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a></b>
52	to be created in the action set.  Note that the retargetable actions do not specify an implementing
53	<b>class</b> since it is up to each view or editor in the plug-in to set up a
54	handler that implements each action.  If the <b>allowLabelUpdate</b> is
55	true, then a <b><a href="../reference/api/org/eclipse/ui/actions/LabelRetargetAction.html">LabelRetargetAction</a>
56	</b>will be created instead.</p>
57	<p>The retargeted actions will be visible in the window menu when the readme
58	action set is visible.  However, they will not be enabled if the readme
59	tool's editor or outline view are not active.</p>
60	<p><img src="images/readmeactionsetmenu.png" alt="Readme File Editor menu with two grayed items and one enabled item" border="0"></p>
61	<p> </p>
62	<p>What do the editor and view have to do?  Again, the client side is
63	similar to registering a handler for the workbench or an editor's retargetable
64	action.  The action id specified in the markup must be used when
65	registering a global action handler.</p>
66	<p>The <b>ReadmeEditorActionBarContributor </b>takes care of this for the
67	editor.  First, it defines the handlers for the actions.</p>
68	<pre>public ReadmeEditorActionBarContributor() {
69	...
70	handler4 = new EditorAction(MessageUtil.getString("Editor_Action4"));
71	handler5 = new EditorAction(MessageUtil.getString("Editor_Action5"));
72	handler5.setToolTipText(MessageUtil.getString("Readme_Editor_Action5"));
73	...
74	}</pre>
75	<p>The handlers are registered at the same time that the handlers for the editor
76	retargetable actions were registered.</p>
77	<pre>public void init(IActionBars bars, IWorkbenchPage page) {
78	...
79	bars.setGlobalActionHandler(IReadmeConstants.ACTION_SET_RETARGET4, handler4);
80	bars.setGlobalActionHandler(IReadmeConstants.ACTION_SET_LABELRETARGET5, handler5);
81	...
82	}</pre>
83	<p>Recall that action bar contributors are shared among different instances of
84	the same editor.  This means the handlers must be notified if the active
85	editor for the <b>ReadmeEditorActionBarContributor </b>changes.</p>
86	<pre>public void setActiveEditor(IEditorPart editor) {
87	...
88	handler4.setActiveEditor(editor);
89	handler5.setActiveEditor(editor);
90	...
91	}</pre>
92	<p>That's it for the editor.  We should see these actions enable when the
93	editor is activated.</p>
94	<p><img src="images/actionseteditorretargets.png" alt="Readme File Editor menu with actions enabled" border="0"> </p>
95	<p>Note that the label for the first retargetable action ("Editor Action
96	4") was not used since the action set XML markup did not set <b>allowLabelUpdate</b>.</p>
97	<p>The <b>ReadmeContentOutlinePage</b>
98	defines its handlers in the same place it defined handlers for the editor's
99	retargetable actions:</p>
100	<pre>public void createControl(Composite parent) {
101	...
102	action = new OutlineAction(MessageUtil.getString("Outline_Action4"));
103	getSite().getActionBars().setGlobalActionHandler(
104	IReadmeConstants.ACTION_SET_RETARGET4,
105	action);
106	action = new OutlineAction(MessageUtil.getString("Outline_Action5"));
107	action.setToolTipText(MessageUtil.getString("Readme_Outline_Action5"));
108	getSite().getActionBars().setGlobalActionHandler(
109	IReadmeConstants.ACTION_SET_LABELRETARGET5,
110	action);
111	}</pre>
112	<p>We should see its relabeled action when the content outliner is active.</p>
113	<p><img src="images/actionsetoutlineretargets.png" alt="Readme File Editor menu with renamed action" border="0"></p>
114	<h4> </h4>
115
116
117
118	</BODY>
119	</HTML>

Removed Link Here

(-)guide/wrkAdv_retarget_contribute_editors.htm (-132 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Retargetable editor actions
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<h4>Retargetable editor actions</h4>
18	<p>Recall that the <a href="../samples/org.eclipse.ui.examples.readmetool/doc-html/ui_readmetool_ex.html">readme
19	tool</a> defines its own editor which contributes actions
20	to the workbench menu bar using its <b>ReadmeEditorActionBarContributor</b>.  </p>
21	<pre><extension
22	point = "org.eclipse.ui.editors">
23	<editor
24	id = "org.eclipse.ui.examples.readmetool.ReadmeEditor"
25	name="%Editors.ReadmeEditor"
26	icon="icons/obj16/editor.png"
27	class="org.eclipse.ui.examples.readmetool.ReadmeEditor"
28	extensions="readme"
29	<b>contributorClass="org.eclipse.ui.examples.readmetool.ReadmeEditorActionBarContributor</b>">
30	</editor>
31	</extension></pre>
32	<p>Let's look closer at what happens in the contributor class.</p>
33	<pre>public ReadmeEditorActionBarContributor() {
34	...
35	action2 = new <b>RetargetAction</b>(<b>IReadmeConstants.RETARGET2</b>, MessageUtil.getString("Editor_Action2"));
36	action2.setToolTipText(MessageUtil.getString("Readme_Editor_Action2"));
37	action2.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_DISABLE);
38	action2.setImageDescriptor(ReadmeImages.EDITOR_ACTION2_IMAGE_ENABLE);
39	...
40	action3 = new <b>LabelRetargetAction</b>(<b>IReadmeConstants.LABELRETARGET3</b>, MessageUtil.getString("Editor_Action3"));
41	action3.setDisabledImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_DISABLE);
42	action3.setImageDescriptor(ReadmeImages.EDITOR_ACTION3_IMAGE_ENABLE);
43	...
44	<b>handler2</b> = new EditorAction(MessageUtil.getString("Editor_Action2"));
45	...
46	<b>handler3</b> = new EditorAction(MessageUtil.getString("Editor_Action3"));
47	...</pre>
48	<p>When the contributor is created, it creates two retargetable actions (one
49	that allows label update and one that does not).  Creation of the actions
50	uses the same technique that the workbench uses.  It also creates two
51	handlers that will be used for the actions when the editor is the active
52	part.  </p>
53	<p>But where are the handlers for the actions registered?  Setting the
54	global handlers is done a little differently when your editor defines the
55	retargeted actions.  Why?  Because your contributor is in charge of
56	tracking the active view and hooking different handlers as different views or
57	the editor itself becomes active.  (The workbench does this for you when
58	you set a handler for one of its global actions).  Here's how the <b>ReadmeEditorActionBarContributor</b>
59	sets things up:</p>
60	<pre>public void init(IActionBars bars, IWorkbenchPage page) {
61	super.init(bars, page);
62	bars.setGlobalActionHandler(IReadmeConstants.RETARGET2, handler2);
63	bars.setGlobalActionHandler(IReadmeConstants.LABELRETARGET3, handler3);
64	...</pre>
65	<p>First, the contributor registers its handlers for the retargeted
66	actions.  This ensures that the contributor's actions will be run when the
67	editor itself is active.  The next step is to register each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
68	</b>as a part listener on the page.</p>
69	<pre> ...
70	// Hook retarget actions as page listeners
71	page.addPartListener(action2);
72	page.addPartListener(action3);
73	IWorkbenchPart activePart = page.getActivePart();
74	if (activePart != null) {
75	action2.partActivated(activePart);
76	action3.partActivated(activePart);
77	}
78	}</pre>
79	<p>Adding each <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
80	</b>as a part listener means that it will be notified when the active part
81	changes.  The action can get the correct global handler from the newly
82	activated part.  (See the implementation of <b><a href="../reference/api/org/eclipse/ui/actions/RetargetAction.html">RetargetAction</a>
83	</b>for all the details.)   Note that to start, the action is seeded
84	with the currently active part. </p>
85	<p>When the editor contributor is disposed, it should unhook the retargetable
86	actions as page listeners.</p>
87	<pre>public void dispose() {
88	// Remove retarget actions as page listeners
89	getPage().removePartListener(action2);
90	getPage().removePartListener(action3);
91	}</pre>
92	<p>Finally, recall that action bar contributors are shared among instances of
93	the same editor class.  For this reason, the handlers must be notified when
94	the active editor changes so that they can connect to the proper editor
95	instance.</p>
96	<pre>public void setActiveEditor(IEditorPart editor) {
97	...
98	handler2.setActiveEditor(editor);
99	handler3.setActiveEditor(editor);
100	...
101	}</pre>
102	<p>That completes the setup on the editor side.  When the editor is open
103	and active, the handlers (and their labels) as defined by the <b>ReadmeEditorActionBarContributor
104	</b>will appear in the workbench menu bar.</p>
105	<p><img src="images/editorretargets.png" alt="Readme menu with three editor actions in workbench menu bar" border="0"></p>
106	<p>Now that the editor's contributions are in place, what does a view do to register a handler?  The code on the client side
107	is similar to registering a handler for a workbench action, except that the
108	action id is the one defined by the plug-in's editor.  The <b>ReadmeContentOutlinePage</b>
109	registers a handler for these actions.</p>
110	<pre>public void createControl(Composite parent) {
111	super.createControl(parent);
112	...
113	getSite().getActionBars().<b>setGlobalActionHandler(
114	IReadmeConstants.RETARGET2, </b>
115	new OutlineAction(MessageUtil.getString("Outline_Action2")));
116
117	OutlineAction action = new OutlineAction(MessageUtil.getString("Outline_Action3"));
118	<b>action.setToolTipText(MessageUtil.getString("Readme_Outline_Action3")); </b>
119	getSite().getActionBars().<b>setGlobalActionHandler(
120	IReadmeConstants.LABELRETARGET3, </b>
121	action);
122	...</pre>
123	<p>Note that the outliner sets tool tip text and a label on the second action,
124	since it allows relabeling.  When the readme outliner view is made active,
125	its handlers (and their labels) will now appear in the workbench menu bar.</p>
126	<p><img src="images/editoroutlineretargets.png" alt="Readme menu with one renamed editor action" border="0"></p>
127	<p>Note that the relabeled action shows the new label.</p>
128
129
130
131	</BODY>
132	</HTML>

Removed Link Here

(-)guide/wrkAdv_retarget_setting.htm (-57 lines)
1	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"><html lang="en">
2	<HEAD>
3
4	<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." >
5
6	<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=ISO-8859-1">
7	<META HTTP-EQUIV="Content-Style-Type" CONTENT="text/css">
8
9	<LINK REL="STYLESHEET" HREF="../book.css" CHARSET="ISO-8859-1" TYPE="text/css">
10	<TITLE>
11	Setting a global action handler
12	</TITLE>
13
14	<link rel="stylesheet" type="text/css" HREF="../book.css">
15	</HEAD>
16	<BODY BGCOLOR="#ffffff">
17	<h3>Setting a global action handler</h3>
18	<p>A plug-in contributes a <a href="wrkAdv_retarget.htm">retargetable action</a>
19	for a view or editor part by implementing an <a href="../reference/api/org/eclipse/jface/action/IAction.html"><b>IAction</b></a>
20	and registering it as a global action handler with the part's action bars.
21	In views, this is usually done at the time that the part creates its actions and
22	controls. For editors see <a href="wrkAdv_retarget_contribute_editors.htm">Retargetable editor actions</a>.
23	The name of the retargeted action (as defined in <a href="../reference/api/org/eclipse/ui/IWorkbenchActionConstants.html"><b>IWorkbenchActionConstants</b></a>)
24	is used to specify which action the handler is intended for.  The following
25	shows how the workbench task list view registers its handler for the <b>PROPERTIES</b>
26	action.</p>
27	<pre>public void createPartControl(Composite parent) {
28	...
29	<b>makeActions();</b>
30	...
31
32	// Add global action handlers.
33	...
34	getViewSite().getActionBars().<b>setGlobalActionHandler(
35	IWorkbenchActionConstants.PROPERTIES,
36	propertiesAction);</b>
37	...</pre>
38	<p>The properties action is created in the local method <b>makeActions</b>:</p>
39	<pre>void makeActions() {
40	...
41	// properties
42	propertiesAction = new TaskPropertiesAction(this, "properties");
43	propertiesAction.setText(TaskListMessages.getString("Properties.text"));
44	propertiesAction.setToolTipText(TaskListMessages.getString("Properties.tooltip"));
45	propertiesAction.setEnabled(false);
46	}</pre>
47	<p>That's all that is needed.  Your action will be run when the user
48	chooses the action from the workbench menu bar or tool bar and your view or
49	editor is active.  The workbench handles the details of ensuring that the
50	retargeted action is always associated with the currently active view. The
51	same applies to editor actions supplied through the EditorActionBarContributor.
52	</p>
53
54
55
56	</BODY>
57	</HTML>

Lines 15-95 Link Here

(-)guide/wrkAdv_undo.htm (-62 / +76 lines)
15	</HEAD>	15	</HEAD>
16	<BODY BGCOLOR="#ffffff">	16	<BODY BGCOLOR="#ffffff">
17	<h2>Undoable operations</h2>	17	<h2>Undoable operations</h2>
18	<p>We've looked at many different ways to contribute actions to the workbench, but we	18	<p>We've looked at many different ways to contribute commands to the workbench, but we
19	haven't focused on the implementation of an action's <tt>run()</tt> method. The mechanics	19	haven't focused on the implementation of a command's <tt>execute(ExecutionEvent)</tt> method.
20	of the method depend on the specific action in question, but structuring the code as an	20	The mechanics
21	<b>undoable operation</b> allows the action to participate in the platform undo and redo	21	of the method depend on the specific command in question, but structuring the code as an
		22	<b>undoable operation</b> allows the command to participate in the platform undo and redo
22	support.</p>	23	support.</p>
23	<p>	24	<p>
24	The platform provides an <b>undoable operations framework</b> in the package	25	The platform provides an <b>undoable operations framework</b> in the package
25	<b><a href="../reference/api/org/eclipse/core/commands/operations/package-summary.html">org.eclipse.core.commands.operations</a></b>.	26	<b><a href="../reference/api/org/eclipse/core/commands/operations/package-summary.html">org.eclipse.core.commands.operations</a></b>.
26	By implementing the code inside a <tt>run()</tt> method to create an	27	By implementing the code inside a <tt>execute(ExecutionEvent)</tt> method to create an
27	<a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>,	28	<a href="../reference/api/org/eclipse/core/commands/operations/IUndoableOperation.html"><b>IUndoableOperation</b></a>,
28	the operation can be made available for undo and redo. Converting an action to use operations is straightforward,	29	the operation can be made available for undo and redo. Converting an command or action to use operations is straightforward,
29	apart from implementing the undo and redo behavior itself.</p>	30	apart from implementing the undo and redo behavior itself.</p>
30	<h3>Writing an undoable operation</h3>	31	<h3>Writing an undoable operation</h3>
31	<p>	32	<p>
32	We'll start by looking at a very simple example. Recall the simple	33	We'll start by looking at a very simple example. Recall the simple
33	<b>ViewActionDelegate</b> provided in the readme example plug-in. When	34	example in <b>org.eclipse.ui.examples.contributions.editor.DeltaInfoHandler</b>.
34	invoked, the action simply launches a dialog that announces it was executed.</p>	35	It builds a string and then opens a dialog.</p>
35	<pre>	36	<pre>
36	public void run(org.eclipse.jface.action.IAction action) {	37	public Object execute(ExecutionEvent event) throws ExecutionException {
37	MessageDialog.openInformation(view.getSite().getShell(),	38	// Build the string buffer "buf"
38	MessageUtil.getString("Readme_Editor"),	39	MessageDialog.openInformation(editor.getSite().getShell(),
39	MessageUtil.getString("View_Action_executed"));	40	ContributionMessages.DeltaInfoHandler_shellTitle, buf
40	}</pre>	41	.toString());
		42	return null;
		43	}
		44	</pre>
41		45
42	Using operations, the run method is responsible for creating an operation that does	46	Using operations, the execute method is responsible for creating an operation that does
43	the work formerly done in the run method, and requesting that an <b>operations history</b>	47	the work formerly done in the execute method, and requesting that an <b>operations history</b>
44	execute the operation, so that it can be remembered for undo and redo.	48	execute the operation, so that it can be remembered for undo and redo.
45	<pre>	49	<pre>
46	public void run(org.eclipse.jface.action.IAction action) {	50	public Object execute(ExecutionEvent event) throws ExecutionException {
47	IUndoableOperation operation = new ReadmeOperation(	51	IUndoableOperation operation = new DeltaInfoOperation(
48	view.getSite().getShell());	52	editor.getSite().getShell());
49	...	53	operationHistory.execute(operation, null, null);
50	operationHistory.execute(operation, null, null);	54	return null;
51	}	55	}
52	</pre>	56	</pre>
53	The operation encapsulates the old behavior from the run method, as well as the undo	57	The operation encapsulates the old behavior from the run method, as well as the undo
54	and redo for the operation.	58	and redo for the operation.
55	<pre>	59	<pre>
56	class ReadmeOperation extends AbstractOperation {	60	class DeltaInfoOperation extends AbstractOperation {
57	Shell shell;	61	Shell shell;
58	public ReadmeOperation(Shell shell) {	62	public DeltaInfoOperation(Shell shell) {
59	super("Readme Operation");	63	super("Delta Operation");
60	this.shell = shell;	64	this.shell = shell;
61	}	65	}
62	public IStatus execute(IProgressMonitor monitor, IAdaptable info) {	66	public IStatus execute(IProgressMonitor monitor, IAdaptable info) {
63	MessageDialog.openInformation(shell,	67	// Build the string buffer "buf"
64	MessageUtil.getString("Readme_Editor"),	68	MessageDialog.openInformation(shell,
65	MessageUtil.getString("View_Action_executed"));	69	ContributionMessages.DeltaInfoHandler_shellTitle, buf
		70	.toString());
66	return Status.OK_STATUS;	71	return Status.OK_STATUS;
67	}	72	}
68	public IStatus undo(IProgressMonitor monitor, IAdaptable info) {	73	public IStatus undo(IProgressMonitor monitor, IAdaptable info) {
69	MessageDialog.openInformation(shell,	74	// Build the string buffer "buf"
70	MessageUtil.getString("Readme_Editor"),	75	MessageDialog.openInformation(shell,
71	"Undoing view action");	76	ContributionMessages.DeltaInfoHandler_shellTitle,
		77	"Undoing delta calculation");
72	return Status.OK_STATUS;	78	return Status.OK_STATUS;
73	}	79	}
74	public IStatus redo(IProgressMonitor monitor, IAdaptable info) {	80	public IStatus redo(IProgressMonitor monitor, IAdaptable info) {
75	MessageDialog.openInformation(shell,	81	// Build the string buffer "buf"
76	MessageUtil.getString("Readme_Editor"),	82	// simply re-calculate the delta
77	"Redoing view action");	83	MessageDialog.openInformation(shell,
		84	ContributionMessages.DeltaInfoHandler_shellTitle, buf
		85	.toString());
78	return Status.OK_STATUS;	86	return Status.OK_STATUS;
79	}	87	}
80	}	88	}
81	</pre>	89	</pre>
82		90
83	<p>	91	<p>
84	For simple actions, it may be possible to move all of the nuts and bolt work into the operation class.	92	For simple commands, it may be possible to move all of the nuts and bolt work into the operation class.
85	In this case, it may be appropriate to collapse the former action classes into a single action class	93	In this case, it may be appropriate to collapse the former handler classes into a single handler class
86	that is parameterized. The action would simply execute the supplied operation when it is time to run.	94	that is parameterized. The handler would simply execute the supplied operation when it is time to execute.
87	This is largely an application design decision.	95	This is largely an application design decision.
88	</p>	96	</p>
89	<p>	97	<p>
90	When an action launches a wizard, then the operation is typically created as part of the wizard's	98	When a command launches a wizard, then the operation is typically created as part of the wizard's
91	<tt>performFinish()</tt> method or a wizard page's <tt>finish()</tt> method. Converting the <tt>finish</tt> method	99	<tt>performFinish()</tt> method or a wizard page's <tt>finish()</tt> method. Converting the <tt>finish</tt> method
92	to use operations is similar to converting a <tt>run</tt> method. The method is responsible for creating	100	to use operations is similar to converting an <tt>execute</tt> method. The method is responsible for creating
93	and executing an operation that does the work previously done inline.	101	and executing an operation that does the work previously done inline.
94	</p>	102	</p>
95	<h3>Operation history</h3>	103	<h3>Operation history</h3>
Lines 97-107 Link Here
97	So far we've used an <b>operations history</b> without really explaining it.	105	So far we've used an <b>operations history</b> without really explaining it.
98	Let's look again at the code that creates our example operation.</p>	106	Let's look again at the code that creates our example operation.</p>
99	<pre>	107	<pre>
100	public void run(org.eclipse.jface.action.IAction action) {	108	public Object execute(ExecutionEvent event) throws ExecutionException {
101	IUndoableOperation operation = new ReadmeOperation(	109	IUndoableOperation operation = new DeltaInfoOperation(
102	view.getSite().getShell());	110	editor.getSite().getShell());
103	...	111	...
104	<b>operationHistory.execute(operation, null, null);</b>	112	operationHistory.execute(operation, null, null);
		113	return null;
105	}	114	}
106	</pre>	115	</pre>
107	What is the <b>operation history</b> all about?	116	What is the <b>operation history</b> all about?
Lines 123-129 Link Here
123	operation history and also provides protocol to access it. The following snippet demonstrates how to	132	operation history and also provides protocol to access it. The following snippet demonstrates how to
124	obtain the operation history from the workbench. </p>	133	obtain the operation history from the workbench. </p>
125	<pre>	134	<pre>
126	IWorkbench workbench = view.getSite().getWorkbenchWindow().getWorkbench();	135	IWorkbench workbench = editor.getSite().getWorkbenchWindow().getWorkbench();
127	IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();	136	IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();
128	</pre>	137	</pre>
129	Once an operation history is obtained, it can be used to query the undo or redo history, find out which operation	138	Once an operation history is obtained, it can be used to query the undo or redo history, find out which operation
Lines 152-168 Link Here
152	Undo contexts can be created by the plug-in that is creating the undoable operations, or accessed through API. For	161	Undo contexts can be created by the plug-in that is creating the undoable operations, or accessed through API. For
153	example, the workbench provides access to an undo context that can be used for workbench-wide operations. However they	162	example, the workbench provides access to an undo context that can be used for workbench-wide operations. However they
154	are obtained, undo contexts should be assigned when an operation is created. The following snippet shows how the	163	are obtained, undo contexts should be assigned when an operation is created. The following snippet shows how the
155	readme plug-in's <b>ViewActionDelegate</b> could assign a workbench-wide context to its operations.	164	<tt>execute</tt> method could assign a workbench-wide context to its operations.
156	</p>	165	</p>
157	<pre>	166	<pre>
158	public void run(org.eclipse.jface.action.IAction action) {	167	public Object execute(ExecutionEvent event) throws ExecutionException {
159	IUndoableOperation operation = new ReadmeOperation(	168	IUndoableOperation operation = new DeltaInfoOperation(
160	view.getSite().getShell());	169	editor.getSite().getShell());
161	IWorkbench workbench = view.getSite().getWorkbenchWindow().getWorkbench();	170	...
162	IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();	171	IWorkbench workbench = editor.getSite().getWorkbenchWindow().getWorkbench();
163	IUndoContext undoContext = workbench.getOperationSupport().getUndoContext();	172	IOperationHistory operationHistory = workbench.getOperationSupport().getOperationHistory();
164	operation.addContext(undoContext);	173	IUndoContext undoContext = workbench.getOperationSupport().getUndoContext();
165	operationHistory.execute(operation, null, null);	174	operation.addContext(undoContext);
		175	operationHistory.execute(operation, null, null);
		176	return null;
166	}	177	}
167	</pre>	178	</pre>
168	<p>	179	<p>
Lines 214-227 Link Here
214	Whenever an operation is executed, undone, or redone using operation history protocol, clients can	225	Whenever an operation is executed, undone, or redone using operation history protocol, clients can
215	provide a progress monitor and any additional UI info that may be needed for performing the operation.	226	provide a progress monitor and any additional UI info that may be needed for performing the operation.
216	This information is passed to the operation itself. In our original	227	This information is passed to the operation itself. In our original
217	example, the readme action constructed an operation with a shell parameter that could be used to open	228	example, the <tt>execute</tt> method constructed an operation with a shell parameter that could be used to open
218	the dialog. Instead of storing the shell in the operation, a better approach is to pass parameters	229	the dialog. Instead of storing the shell in the operation, a better approach is to pass parameters
219	to the execute, undo, and redo methods that provide any UI information needed to run the operation. These	230	to the execute, undo, and redo methods that provide any UI information needed to run the operation. These
220	parameters will be passed on to the operation itself.</p>	231	parameters will be passed on to the operation itself.</p>
221	<pre>public void run(org.eclipse.jface.action.IAction action) {	232	<pre>public Object execute(ExecutionEvent event) throws ExecutionException {
222	IUndoableOperation operation = new ReadmeOperation();	233	IUndoableOperation operation = new DeltaInfoOperation(
223	...	234	editor.getSite().getShell());
224	<b>operationHistory.execute(operation, null, infoAdapter);</b>	235	...
		236	<b>operationHistory.execute(operation, null, infoAdapter);</b>
		237	return null;
225	}	238	}
226	</pre>	239	</pre>
227	The <b>infoAdapter</b> is an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a>	240	The <b>infoAdapter</b> is an <a href="../reference/api/org/eclipse/core/runtime/IAdaptable.html"><b>IAdaptable</b></a>
Lines 232-240 Link Here
232	if (info != null) {	245	if (info != null) {
233	Shell shell = (Shell)info.getAdapter(Shell.class);	246	Shell shell = (Shell)info.getAdapter(Shell.class);
234	if (shell != null) {	247	if (shell != null) {
		248	// Build the string buffer "buf"
235	MessageDialog.openInformation(shell,	249	MessageDialog.openInformation(shell,
236	MessageUtil.getString("Readme_Editor"),	250	ContributionMessages.DeltaInfoHandler_shellTitle, buf
237	MessageUtil.getString("View_Action_executed"));	251	.toString());
238	return Status.OK_STATUS;	252	return Status.OK_STATUS;
239	}	253	}
240	}	254	}
Lines 242-249 Link Here
242	}	256	}
243	</pre>	257	</pre>
244		258
245	<h3>Undo and redo action handlers</h3>	259	<h3>Undo and redo action handlers (Deprecated)</h3>
246	<p>The platform provides standard undo and redo <a href="wrkAdv_retarget.htm"><b>retargetable action handlers</b></a>	260	<p>The platform provides standard undo and redo <b>retargetable action handlers</b>
247	that can be configured by views and editors to provide undo and redo support for their particular context. When the	261	that can be configured by views and editors to provide undo and redo support for their particular context. When the
248	action handler is created, a context is assigned to it so that the operations history is filtered in a way appropriate for	262	action handler is created, a context is assigned to it so that the operations history is filtered in a way appropriate for
249	that particular view. The action handlers take care of updating the undo and redo labels to show the current	263	that particular view. The action handlers take care of updating the undo and redo labels to show the current

Lines 63-77 Link Here

(-)questions/index.html (-3 / +3 lines)
63	content outliner for an editor?</a></li>	63	content outliner for an editor?</a></li>
64	<li><a href="../guide/preferences_prefs.htm">How do I add a page to the	64	<li><a href="../guide/preferences_prefs.htm">How do I add a page to the
65	preferences dialog?</a></li>	65	preferences dialog?</a></li>
66	<li><a href="../guide/workbench_basicext.htm">Where should I start learning	66	<li><a href="../guide/workbench_cmd.htm">Where should I start learning
67	how to extend the workbench UI?</a></li>	67	how to extend the workbench UI?</a></li>
68	<li><a href="../reference/extension-points/index.html">What extension points	68	<li><a href="../reference/extension-points/index.html">What extension points
69	are defined by the workbench UI?</a></li>	69	are defined by the workbench UI?</a></li>
70	<li><a href="../guide/workbench_menus.htm">How do I add a menu to the	70	<li><a href="../guide/workbench_menus.htm">How do I add a menu to the
71	workbench?</a></li>	71	workbench?</a></li>
72	<li><a href="../guide/workbench_menupaths.htm">How do I	72	<li><a href="../guide/workbench_cmd_menus.htm">How do I
73	specify menu and toolbar paths?</a></li>	73	specify menu and toolbar paths?</a></li>
74	<li><a href="../guide/wrkAdv_retarget.htm">How do I implement common actions	74	<li><a href="../guide/workbench_cmd.htm">How do I implement common actions
75	like cut/copy/paste?</a></li>	75	like cut/copy/paste?</a></li>
76	<li><a href="../guide/jface_resources.htm">How should I manage the icons in my	76	<li><a href="../guide/jface_resources.htm">How should I manage the icons in my
77	plug-in?</a></li>	77	plug-in?</a></li>

Lines 62-81 Link Here

(-)topics_Guide.xml (-21 / +4 lines)
62		62
63	<topic label="Plugging into the workbench" href="guide/workbench.htm">	63	<topic label="Plugging into the workbench" href="guide/workbench.htm">
64	<topic label="Workbench under the covers" href="guide/workbench_structure.htm" />	64	<topic label="Workbench under the covers" href="guide/workbench_structure.htm" />
65	<topic label="Basic workbench extension points using actions" href="guide/workbench_basicext.htm" >	65	<topic label="Basic workbench extension points using commands" href="guide/workbench_cmd.htm" >
66	<topic label="org.eclipse.ui.views" href="guide/workbench_basicext_views.htm" />	66	<topic label="org.eclipse.ui.views" href="guide/workbench_basicext_views.htm" />
67	<topic label="org.eclipse.ui.viewActions" href="guide/workbench_basicext_viewActions.htm" />
68	<topic label="org.eclipse.ui.editors" href="guide/workbench_basicext_editors.htm" />	67	<topic label="org.eclipse.ui.editors" href="guide/workbench_basicext_editors.htm" />
69	<topic label="org.eclipse.ui.editorActions" href="guide/workbench_basicext_editorActions.htm" />
70	<topic label="org.eclipse.ui.popupMenus" href="guide/workbench_basicext_popupMenus.htm" />
71	<topic label="org.eclipse.ui.actionSets" href="guide/workbench_basicext_actionSets.htm" />
72	</topic>
73	<topic label="Basic workbench extension points using commands" href="guide/workbench_cmd.htm" >
74	<topic label="org.eclipse.ui.commands" href="guide/workbench_cmd_commands.htm" />	68	<topic label="org.eclipse.ui.commands" href="guide/workbench_cmd_commands.htm" />
75	<topic label="org.eclipse.ui.menus" href="guide/workbench_cmd_menus.htm" />	69	<topic label="org.eclipse.ui.menus" href="guide/workbench_cmd_menus.htm" />
76	<topic label="org.eclipse.ui.handlers" href="guide/workbench_cmd_handlers.htm" />	70	<topic label="org.eclipse.ui.handlers" href="guide/workbench_cmd_handlers.htm" />
77	<topic label="org.eclipse.ui.bindings" href="guide/workbench_cmd_bindings.htm" />	71	<topic label="org.eclipse.ui.bindings" href="guide/workbench_cmd_bindings.htm" />
78	<topic href="guide/workbench_cmd_expressions.htm" label="Workbench Core Expressions">	72	<topic href="guide/workbench_cmd_expressions.htm" label="Workbench Core Expressions">
79	</topic>	73	</topic>
80	</topic>	74	</topic>
81	<topic label="The plug-in class" href="guide/workbench_plugin.htm" />	75	<topic label="The plug-in class" href="guide/workbench_plugin.htm" />
Lines 106-112 Link Here
106		100
107	<topic label="JFace UI framework" href="guide/jface.htm">	101	<topic label="JFace UI framework" href="guide/jface.htm">
108	<topic label="Viewers" href="guide/jface_viewers.htm" />	102	<topic label="Viewers" href="guide/jface_viewers.htm" />
109	<topic label="Actions and contributions" href="guide/jface_actions.htm" />	103	<topic label="Actions and contributions (Deprecated)" href="guide/jface_actions.htm" />
110	<topic label="User interface resources" href="guide/jface_resources.htm" />	104	<topic label="User interface resources" href="guide/jface_resources.htm" />
111	<topic label="Long-running operations" href="guide/jface_operations.htm" />	105	<topic label="Long-running operations" href="guide/jface_operations.htm" />
112	<topic label="Field assist" href="guide/jface_fieldassist.htm" />	106	<topic label="Field assist" href="guide/jface_fieldassist.htm" />
Lines 201-216 Link Here
201		195
202	<topic label="Advanced workbench concepts" href="guide/wrkAdv.htm">	196	<topic label="Advanced workbench concepts" href="guide/wrkAdv.htm">
203	<topic label="Workbench menu contributions" href="guide/workbench_menus.htm" />	197	<topic label="Workbench menu contributions" href="guide/workbench_menus.htm" />
204	<topic label="Menu and toolbar paths" href="guide/workbench_menupaths.htm" />
205	<topic label="Action set part associations" href="guide/workbench_basicext_actionSetPartAssociations.htm" />
206	<topic label="Boolean expressions and action filters" href="guide/workbench_actionfilters.htm" />
207	<topic label="Retargetable actions" href="guide/wrkAdv_retarget.htm" >
208	<topic label="Setting a global action handler" href="guide/wrkAdv_retarget_setting.htm" />
209	<topic label="Contributing new retargetable actions" href="guide/wrkAdv_retarget_contribute.htm" >
210	<topic label="Retargetable editor actions" href="guide/wrkAdv_retarget_contribute_editors.htm" />
211	<topic label="Retargetable action set actions" href="guide/wrkAdv_retarget_contribute_actionsets.htm" />
212	</topic>
213	</topic>
214	<topic label="Undoable operations" href="guide/wrkAdv_undo.htm" >	198	<topic label="Undoable operations" href="guide/wrkAdv_undo.htm" >
215	<topic label="Undo and the IDE Workbench" href="guide/wrkAdv_undo_ide.htm" />	199	<topic label="Undo and the IDE Workbench" href="guide/wrkAdv_undo_ide.htm" />
216	</topic>	200	</topic>
Lines 220-226 Link Here
220	</topic>	204	</topic>
221	<topic label="Decorators" href="guide/workbench_advext_decorators.htm" />	205	<topic label="Decorators" href="guide/workbench_advext_decorators.htm" />
222	<topic label="Workbench key bindings" href="guide/wrkAdv_keyBindings.htm" >	206	<topic label="Workbench key bindings" href="guide/wrkAdv_keyBindings.htm" >
223	<topic label="Associating actions to commands" href="guide/wrkAdv_keyBindings_actionDef.htm" />
224	<topic label="Bindings" href="guide/wrkAdv_keyBindings_accelSet.htm" />	207	<topic label="Bindings" href="guide/wrkAdv_keyBindings_accelSet.htm" />
225	<topic label="Schemes" href="guide/wrkAdv_keyBindings_accelConfig.htm" />	208	<topic label="Schemes" href="guide/wrkAdv_keyBindings_accelConfig.htm" />
226	<topic label="Contexts and key bindings" href="guide/wrkAdv_keyBindings_contexts.htm" />	209	<topic label="Contexts and key bindings" href="guide/wrkAdv_keyBindings_contexts.htm" />
Lines 230-236 Link Here
230	<topic label="Honoring single click support" href="guide/wrkAdv_singleclick.htm" />	213	<topic label="Honoring single click support" href="guide/wrkAdv_singleclick.htm" />
231	<topic label="Working sets" href="guide/wrkAdv_workingsets.htm" />	214	<topic label="Working sets" href="guide/wrkAdv_workingsets.htm" />
232	<topic label="Filtering large user interfaces" href="guide/workbench_scalability.htm" >	215	<topic label="Filtering large user interfaces" href="guide/workbench_scalability.htm" >
233	<topic label="Activities" href="guide/workbench_advext_activities.htm" />	216	<topic label="Activities (Not currently in 4.1)" href="guide/workbench_advext_activities.htm" />
234	<topic label="Contexts" href="guide/workbench_advext_contexts.htm" />	217	<topic label="Contexts" href="guide/workbench_advext_contexts.htm" />
235	</topic>	218	</topic>
236	<topic label="Workbench concurrency support" href="guide/workbench_jobs.htm" />	219	<topic label="Workbench concurrency support" href="guide/workbench_jobs.htm" />