rich client platform part3.mht

Rich Client Tutorial

      especially ids.=20
  <TR vAlign=3Dtop>
    <TD><IMG height=3D13 alt=3D#2=20
      src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_2.gif" =
width=3D24=20
      align=3Dcenter>=20
    <TD>The Platform supports editors but we're not using one for this=20
      example. Therefore you need to turn off the editor area so you =
won't have=20
      a big blank space in the middle of your Workbench Window.=20
  <TR vAlign=3Dtop>
    <TD><IMG height=3D13 alt=3D#3=20
      src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_3.gif" =
width=3D24=20
      align=3Dcenter>=20
    <TD>This is the most important part of the class. It adds the view =
to the=20
      perspective so it will be visible by default. The positioning =
parameters=20
      say to place this view above the editor area and let it take 100% =
of the=20
      Workbench Window. This might be a little strange since we don't =
have an=20
      editor area but it's lurking around somewhere even if it's =
invisible. As=20
      you add more than one view to your application you can define the =
default=20
      stacking and layout of your views here.=20
  <TR vAlign=3Dtop>
    <TD><IMG height=3D13 alt=3D#4=20
      src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_4.gif" =
width=3D24=20
      align=3Dcenter>=20
    <TD>This method causes the perspective to be on the short list if =
you=20
      implement the <CODE>PERSPECTIVES_SHORTLIST</CODE> menu item (see =
the=20
      sample code for an example). Without it, the perspective will only =
be on=20
      the long list seen when the user selects Window &gt; Open =
Perspective &gt;=20
      Other (or whatever the equivalent menu path is in your =
application).=20
  <TR vAlign=3Dtop>
    <TD><IMG height=3D13 alt=3D#5=20
      src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_5.gif" =
width=3D24=20
      align=3Dcenter>=20
    <TD>Same thing, only for views. </TR></TBODY></TABLE>
<P><IMG height=3D13 alt=3D"Tip: "=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tip.gif" =
width=3D62> To=20
remember the user's layout and window sizes for the next time they start =
your=20
application, add <CODE>configurer.setSaveAndRestore(true);</CODE> to the =

<CODE>initialize</CODE> method of <CODE>WorkbenchAdvisor</CODE>. An =
example of=20
this can be found in the sample project. </P>
<H3>Fixed views</H3>
<P>By default, views will be moveable, resizeable, and closable. Often =
you don't=20
want that flexibility. For example, if you're writing an order entry =
application=20
for unsophisticated users, you don't want to have to answer help desk =
questions=20
about what to do if somebody accidentally closes the form view. For this =
reason=20
Eclipse 3.0 introduces the notion of fixed perspectives and fixed views. =
</P>
<P>A fixed view is a view that cannot be closed. The title bar of the =
view=20
doesn't even have a close button. To create one of these you can use the =

<CODE>setFixed()</CODE> method on <CODE>IPageLayout</CODE>. </P>
<P>A better way might be to use a fixed perspective. A fixed perspective =
makes=20
all of the views it contains fixed, plus it prevents any of them from =
being=20
moved or resized. To make a perspective fixed, simply add the=20
<CODE>fixed=3D"true"</CODE> attribute to its definition, for example: =
</P><PRE>    &lt;extension
        point=3D"org.eclipse.ui.perspectives"&gt;
        &lt;perspective
            name=3D"%perspectiveName"
            icon=3D"icons/sample.gif"
            <B>fixed=3D"true"</B>
            class=3D"org.eclipse.ui.tutorials.rcp.part3.RcpPerspective"
            id=3D"org.eclipse.ui.tutorials.rcp.part3.RcpPerspective"&gt;
        &lt;/perspective&gt;
    &lt;/extension&gt;
</PRE>
<P>By using a fixed perspective and turning off the shortcut bar, you =
can lock=20
the user into one perspective and hide the concept of perspectives from =
them=20
altogether. </P>
<H2>Menus</H2>
<P>Letting you configure all the menus was one of the first requirements =
of the=20
RCP. There are two ways to add menus in an RCP application: </P>
<UL>
  <LI><CODE>WorkbenchAdvisor.fillActionBars</CODE>=20
  <LI><CODE>org.eclipse.ui.actionSets</CODE> in the plug-in manifest =
</LI></UL>
<P><CODE>fillActionBars</CODE> is the only way to reference built-in =
Workbench=20
actions, so we'll use it for that purpose. Everything else can be =
contributed by=20
the <CODE>actionSets</CODE> extension point. Both methods will be =
demonstrated=20
here. Although the example application does not use toolbars, they are =
very=20
similar to menus. </P>
<P>First let's take a look at <CODE>fillActionBars</CODE>: </P><PRE>	=
public void fillActionBars(
	    IWorkbenchWindow window,
	    IActionBarConfigurer configurer,
	    int flags) {
	    super.fillActionBars(window, configurer, flags);
<IMG height=3D13 alt=3D#1 =
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_1.gif" =
width=3D24 align=3Dcenter>         if ((flags &amp; FILL_MENU_BAR) !=3D =
0) {
	        fillMenuBar(window, configurer);
	    }
	}
</PRE>
<P><CODE>fillActionBars</CODE> is takes a flags parameter (<IMG =
height=3D13 alt=3D#1=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_1.gif" =
width=3D24=20
align=3Dcenter>) that indicates what the code should really do. There =
are flag=20
bits for filling in the menu bar, the tool bar, the status line, and =
even a bit=20
for whether or not this is a fake request for preference dialogs=20
(<CODE>FILL_PROXY</CODE>). The author has had some bad experiences with =
flags=20
like this, so the example code just calls a helper function called=20
<CODE>fillMenuBar</CODE> to do the actual filling. Here's the code for=20
<CODE>fillMenuBar</CODE>: </P><PRE>	private void fillMenuBar(
	    IWorkbenchWindow window,
	    IActionBarConfigurer configurer) {
	    IMenuManager menuBar =3D configurer.getMenuManager();
	    menuBar.add(createFileMenu(window));
	    menuBar.add(createEditMenu(window));
	    menuBar.add(createWindowMenu(window));
	    menuBar.add(createHelpMenu(window));
	}
</PRE>
<P>For this example we want to create four top-level menus: File, Edit, =
Window,=20
and Help. These correspond to the menus of the same name in the Eclipse =
IDE. For=20
a real application you may not want all these, or you might want to call =
them=20
something different. See figure 1 for an example. </P><IMG=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/complete.png">=20
<P><B>Figure 1. The Workbench menu bar is defined in the=20
<CODE>fillActionBars</CODE> method of <CODE>WorkbenchAdvisor</CODE>, and =
then=20
added to by the manifests of all plug-ins that extend=20
<CODE>org.eclipse.ui.actionSets</CODE>. </B></P>
<P>The code for all these methods can be found in the example project. =
Let's=20
just take a closer look at one of of them, the File menu: </P><PRE>	=
private MenuManager createFileMenu(IWorkbenchWindow window) {
<IMG height=3D13 alt=3D#1 =
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_1.gif" =
width=3D24 align=3Dcenter>	    MenuManager menu =3D new =
MenuManager(Messages.getString("File"), //$NON-NLS-1$
	        IWorkbenchActionConstants.M_FILE);
<IMG height=3D13 alt=3D#2 =
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_2.gif" =
width=3D24 align=3Dcenter>	    menu.add(new =
GroupMarker(IWorkbenchActionConstants.FILE_START));
	    menu.add(new GroupMarker(IWorkbenchActionConstants.MB_ADDITIONS));
<IMG height=3D13 alt=3D#3 =
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_3.gif" =
width=3D24 align=3Dcenter>	    =
menu.add(ActionFactory.QUIT.create(window));
	    menu.add(new GroupMarker(IWorkbenchActionConstants.FILE_END));
	    return menu;
	}
</PRE>
<P>All these menus work the same way. First you create a MenuManager for =
the=20
menu (<IMG height=3D13 alt=3D#1=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_1.gif" =
width=3D24=20
align=3Dcenter>) using the message file to lookup the actual =
human-readable title.=20
Then you add all the menu items and return the manager. See the =
references=20
section for more information about defining views and menus. Next, you =
create=20
some placeholders (<IMG height=3D13 alt=3D#2=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_2.gif" =
width=3D24=20
align=3Dcenter>) where additional menu items can be added by plug-ins, =
and one=20
real action supplied by the Workbench: the Quit action (<IMG height=3D13 =
alt=3D#3=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/tag_3.gif" =
width=3D24=20
align=3Dcenter>). A list of supported Workbench actions can be found by =
looking at=20
the Javadoc for <CODE>ActionFactory</CODE> and=20
<CODE>ContributionItemFactory</CODE>. </P>
<P><IMG height=3D13 alt=3D"Note: "=20
src=3D"http://eclipse.org/articles/Article-RCP-3/images/note.gif" =
width=3D62> There=20
are a number of standard placeholder names for menus and toolbars that =
you=20
should use when trying to make yours work just like the ones in the IDE. =
By=20
using these predefined groups, plug-ins that contribute menu and toolbar =
items=20
to the Eclipse IDE can also contribute them to your RCP application. =
These=20
aren't documented anywhere other than in the Javadoc for=20
<CODE>IWorkbenchActionConstants</CODE>, and even there you won't find =
any=20
guidance for their intended order. The sample code that accompanies this =

tutorial was created by looking at the <CODE>IDEWorkbenchAdvisor</CODE> =
class=20
used by the Eclipse IDE. </P>
<H2>Help</H2>
<P>One of the coolest features of the RCP is its help system. Simply by=20
providing the table of contents in XML format and the documents in HTML, =