Article-TreeViewer/TreeViewerArticle.htm

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2//EN">
<html>
  <head>
    <title>How to use the JFace Tree Viewer</title>
		<link rel="stylesheet" href="default_style.css">
  </head>
	<body LINK="#0000ff" VLINK="#800080">
<div align="right">&nbsp; <font face="Times New Roman, Times, serif" size="2">Copyright 
  &copy; 2002 Chris Grindstaff.</font> 
  <table border=0 cellspacing=0 cellpadding=2 width="100%">
    <tr> 
      <td align=LEFT valign=TOP colspan="2" bgcolor="#0080C0"><b><font face="Arial,Helvetica"><font color="#FFFFFF">&nbsp;Eclipse 
        Corner Article</font></font></b></td>
    </tr>
  </table>
</div>
<div align="left"> 
  <h1><img src="images/Idea.jpg" height=86 width=120></h1>
</div>
<p>&nbsp;</p>
      <h1 align="CENTER">How to use the JFace Tree Viewer</h1>
			<blockquote>
			<b>Summary</b>
			<br>
  The goal of this article is to teach you how to use TreeViewers in your Eclipse 
  plug-ins or stand-alone JFace/SWT applications. We&#8217;ll start with a simple 
  example and progressively add functionality. 
  <p><b> By Chris Grindstaff, Applied Reasoning</b> (<font face="arial,helvetica,geneva" size=-1>chrisg 
    at appliedReasoning.com)</font><br>
    <font size="-1">May 5, 2002</font> </p>
</blockquote>

<hr width="100%">
      <h2>Introduction</h2>
      <p>
        The TreeViewer is used throughout Eclipse. In fact, 
	trees are pervasive in most applications.
        This article will explain the following information about tree viewers:
      </p>
	<ul>
	  <li>how the tree viewer fits into the JFace UI toolkit</li>
	  <li>how to populate a tree viewer</li>
	  <li>how to listen for events generated by the tree viewer</li>
	  <li>how to select items in the tree viewer</li>
	  <li>how to filter out items</li>
	  <li>how to control the order of items in the tree viewer.</li>
	</ul>
      <p>
        The tree viewer can be used in Eclipse plug-ins or in a stand alone
        JFace/SWT application. We&#8217;ve chosen to implement a plug-in that 
	demonstrates the tree viewer functionality.
      </p>
      <p>
        <a name="mainView"></a>
        Here&#8217;s an example of what the plugin provides:
      </p>
      <p>
        <p align="center"><img alt="main.gif (4K)" src="images/main.gif" height="350" width="230" align="middle"></p>
      <p></p>
      <p>
        As you work through the article you may notice the
        occasional <img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">. These 
				icons indicate points where you should start up Eclipse and try the example. 
      </p>
      <h2>
        Source Code
      </h2>
      <p>
        To run the examples or view the source for this article,
        unzip <a href="cbg.article.treeviewer.zip">cbg.article.treeviewer.zip</a> 
				into your <i>eclipse_root</i> directory and restart Eclipse. In Windows
				the <i>eclipse_root</i> directory will look something like <i>d:\apps\eclipse\</i>.  
				Once Eclipse is restarted, select the Perspective | Show View |
        Other&#8230; menu option. In the &#8220;Other&#8221;
        category select &#8220;Moving Box.&#8221;
      </p>
      <p>
        <p align="center"><img alt="perspectiveMenu.jpg (21K)" src="images/perspectiveMenu.jpg" height="272" width="383"></p>
      <p></p>
      <p>
        <img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">
      </p>
      <p>
        This article will be most effective if you are able to run the plugin we&#8217;ve
	provided as you read it.
      </p>

      <h2>
        Big Picture
      </h2>
      <p>
        To understand how to use the TreeViewer, it is important
        to understand where the TreeViewer fits into JFace as a
        whole, and how JFace fits into Eclipse.
      </p>
      <p>
        JFace is a UI toolkit that helps solve 
        common UI programming tasks. JFace also acts as a bridge
        between low-level SWT widgets and your domain objects.
        SWT widgets interact with the host operating system and
        as such have no knowledge of your domain objects.
      </p>
      <p>
        One of the ways that JFace bridges the gap between SWT
        widgets and domain models is through viewers. JFace
        viewers consist of an SWT widget (e.g. Tree, Table, etc), plus
        your domain objects. You provide the viewers with the
        information they need in order to populate the underlying
        SWT widget. The viewer is able to sort and filter your domain objects,
				as well as update the widget when your domain objects change.
      </p>
      <p>
        More information about JFace and SWT can be found in the
        Javadoc for org.eclipse.jface.viewers,
        org.eclipse.swt.widgets, org.eclipse.swt.custom and 
        <a href="http://www.eclipse.org/documentation/html/plugins/org.eclipse.platform.doc.isv/doc/guide/jface_viewers.htm">JFace viewers</a>.
      </p>
      <h2>
        Setting the Stage
      </h2>
      <p>
        Because the TreeViewer uses domain objects to populate its Tree,
	we will create a simple model to be used throughout
        this article.
      </p>
      <p>
        Suppose you've bought a new house and it's time to pack up your
        stuff for the move. To keep all of your books and board
        games organized you decide to employ a TreeViewer to help
        you maintain order. (Yes, you're a geek.)
      </p>
      <p>
        Here are our domain objects:
      </p>
      <ul type="disc">
        <li>
          MovingBox
        </li>
      </ul>
      <p>
        A moving box can contain other moving boxes, books, and
        board games. A moving box may or may not have a name.
      </p>
      <ul type="disc">
        <li>Book</li>
        <li>Board game</li>
      </ul>
      <p>
        Each book and board game has both a title and an author.
      </p>
      <h2>
        Build a Simple TreeViewer
      </h2>
      <p>
        We&#8217;ll start with a simple TreeViewer example and
        build on it throughout the article.
      </p>
      <p>
        Here&#8217;s the code that creates this <a href="#mainView">view</a> depicted earlier.
      </p>
      <blockquote>
        <a name="sampleCode"></a><pre>treeViewer = new TreeViewer(parent);
treeViewer.setContentProvider(new MovingBoxContentProvider());
treeViewer.setLabelProvider(new MovingBoxLabelProvider());
treeViewer.setInput(getInitalInput());
treeViewer.expandAll();
</pre></blockquote>
      <h2>
        TreeViewer Domain Model Interactions
      </h2>
      <p>
        It is crucial to understand the model/view relationship as utilized by
        JFace viewers. Conceptually, all viewers perform two primary tasks:
      </p>
      <ul>
	  <li>they help adapt your domain objects into viewable entities</li>
	  <li>they provide notifications when the viewable entities are selected or
	   changed through the UI</li>
      </ul>
      <p>
        More specifically, when working with a tree viewer, you
        use your domain objects as arguments in the API methods.
        For example, you can 
        add a book to a moving box by calling the 
        TreeViewer.add(aMovingBox, aBook) method. You don&#8217;t
        need to translate your domain objects into UI elements;
        the tree viewer does that for you. You make your "root" domain object
	avaliable to the tree viewer by invoking the TreeViewer&#8217;s <b>setInput</b>
	method. Your domain object then becomes the tree viewer&#8217;s input.
      </p>
      <p>
        Likewise, when you ask the tree viewer for the selected
        objects, it will answer with the domain objects - not the underlying
        UI resources.
      </p>
      <h2>
        Content Provider
      </h2>
      <p>
        When working with a tree viewer, you need to provide the
        viewer with information on how to <i>transform</i> your
        domain object into an item in the UI tree. That is the
        purpose of an <code>ITreeContentProvider</code>. One of your domain
				classes could implement this interface. Instead of "polluting" your
				domain objects with user interface code, you may want to create
				another object to fulfill the tree content provider requirements.<br><br> 
        Let&#8217;s take a look at some of this interface&#8217;s
        methods.
      </p>
			<p>
			<ul type="disc">
        <li>
          <code>public Object[] getElements(Object inputElement)</code>
        </li>
      </ul>
			This is the method invoked by calling the <b>setInput</b> method on
			the tree viewer. In fact, the <b>getElements</b> method is called only in
			response to the tree viewer's <b>setInput</b> method and should answer with 
			the appropriate domain objects of the inputElement.
			
			The <b>getElements</b> and <b>getChildren</b> methods operate in a similar way.
			Depending on your domain objects, you may have the <b>getElements</b> simply 
			return the result of calling <b>getChildren</b>. The two methods are kept 
			distinct because it provides a clean way to differentiate between the root
			domain object and all other domain objects.			
			<p></p>
      <ul type="disc">
        <li>
          <code>public Object[] getChildren(Object parent)</code>
        </li>
      </ul>
      <p>
        The tree viewer calls its content provider&#8217;s
        getChildren method when it needs to create or display the
        child elements of the domain object, <b>parent</b>. This method
        should answer an array of domain objects that represent
        the unfiltered children of <b>parent</b> (more on filtering later).
      </p>
      <ul type="disc">
        <li>
          <code>public Object getParent(Object element)</code>
        </li>
      </ul>
      <p>
        The tree viewer calls its content provider&#8217;s
        getParent method when it needs to reveal collapsed domain objects programmatically 
	and to set the expanded state of domain objects. This method should answer the parent of the
        domain object element.
      </p>
      <p>
	<ul type="disc">
		 <li><code>public boolean hasChildren(Object element)</code></li>
	</ul>
      <p></p>
      <p>
        The tree viewer asks its content provider if the domain
        object represented by <b>element</b> has any children. This
        method is used by the tree viewer to determine whether or
        not a plus or minus should appear on the tree widget.
      </p>
      <ul type="disc">
        <li>
          <code>public void
          inputChanged</code><code>(Viewer viewer, Object
          oldInput, Object newInput)</code>
        </li>
      </ul>
      <p>
				This method really serves two slightly different purposes.
				This method is invoked when you set the tree viewer's input. In other
				words, anytime you change the tree viewer's input via the setInput
				method, the inputChanged method will be called. This will often be
				used to register the content provider as a recipient of domain changes
				and to de-register itself from the old domain object.<br><br>
				In big picture terms, input objects for the content provider are managed
				through the viewer.<br><br>

				The method is also called when the tree viewer wants
				to inform the content provider that it's no longer the tree viewer's 
				content provider. This happens when you set the tree viewer's content
				provider.
      </p>
      <p>
        For example, our moving box notifies its listeners
        whenever a book, board game or box is added to or removed
        from it. The content provider will register as a listener
        for these domain model changes so it can update its UI
        when the domain changes. Likewise, it will want to remove
        itself as a listener from domain objects that are no
        longer being viewed.
      </p>
      <p>
        Enough discussion about the abstract APIs. Let&#8217;s
        take a look at the actual code used in this example. In
        the code provided <a href="#sampleCode">above</a>
        the tree viewer&#8217;s content provider was set to an
        instance of <code>MovingBoxContentProvider</code>.
        Let&#8217;s take a look at that class in detail.
      </p>
      <p>
				<blockquote>
        <pre>
public Object[] getChildren(Object parentElement) {
    if(parentElement instanceof MovingBox) {
        MovingBox box = (MovingBox)parentElement;
        return concat(box.getBoxes().toArray(), 
            box.getBooks().toArray(), box.getGames().toArray());
    }
    return EMPTY_ARRAY;
}</pre></blockquote>
      <p></p>
      <p>
        Only MovingBox domain objects can have children, so an
        empty array is returned for any other object. A moving
        box&#8217;s children are a concatenation of its moving
        boxes, plus its books, plus its board games.
      </p>
      <p>
			<blockquote>
			<pre>
public Object[] getElements(Object inputElement) {
    return getChildren(inputElement);
}</pre></blockquote>
	<p></p>
      <p>
        The getElements method is used to obtain the root
        elements for the tree viewer. In our case,
				the tree viewer's root object is a moving box so we can simply call
				the getChildren method since it handles MovingBoxes. If the root
				domain object was <i>special</i> in some way, the getElement method
				would likely not delegate to the getChildren method.
      </p>
      <p>
			<blockquote>
			<pre>
public Object getParent(Object element) {
    if(element instanceof Model) {
        return ((Model)element).getParent();
    }
    return null;
}</pre></blockquote>      
	<p></p>
      <p>
        The getParent method is used to obtain the parent of the
        given element. In our example, the Model class is the common superclass
        of moving boxes, books and board games and defines a
        child/parent relationship.
      </p>
      <p>
			<blockquote>
			<pre>
public boolean hasChildren(Object element) {
    return getChildren(element).length > 0;
}</pre></blockquote>
      <p></p>
      <p>
        The hasChildren method is invoked by the tree viewer when
        it needs to know whether a given domain object has
        children.
      </p>
      <a name="inputChanged"></a>
      <p>
			<blockquote>
			<pre>
public void inputChanged(Viewer viewer, Object oldInput, Object newInput) {
    this.viewer = (TreeViewer)viewer;
    if(oldInput != null) {
        removeListenerFrom((MovingBox)oldInput);
    }
    if(newInput != null) {
       addListenerTo((MovingBox)newInput);
    }
}</pre></blockquote>
      <p></p>
			<p>
			     The <b>input changed</b> method caches the viewer argument for later 
					 use when responding to events. Recall that the <b>inputChanged</b> 
					 method will be called when the tree viewer's setInput method is
					 invoked. When the tree viewer's input is changed, we need to make
					 sure that we remove any listeners we have associated with the
					 old input so that we no longer receive updates from the stale input.
					 Likewise, we need to listen for changes in the new input. Typically 
					 the content provider adds itself as a listener to domain object 
					 changes. This way when the domain object changes the content provider
					 is notified and can in turn, notify the tree viewer.  
					 
					 Here is the addListenerTo method. (The removeListenerFrom method is 
					 almost exactly the same so we'll ignore it.)
			</p>
			<blockquote>
<pre>
/** Because the domain model does not have a richer
 * listener model, recursively add this listener
 * to each child box of the given box. */
protected void addListenerTo(MovingBox box) {
    box.addListener(this);
    for (Iterator iterator = box.getBoxes().iterator(); iterator.hasNext();) {
       MovingBox aBox = (MovingBox) iterator.next();
       addListenerTo(aBox);
    }
}		 
</pre></blockquote>
			<p>
			This method simply finds all the moving boxes and adds the content viewer
			as a listener; therefore, if any of the moving boxes change, the content
			viewer will be notified. Later in the article we'll show how the content
			viewer responds to these domain changes.
			</p>
      <h2>
        Label Provider
      </h2>
      <p>
        The label provider is responsible for providing an image
        and text for each item contained in the tree viewer. As
        with the content provider, the label provider accepts
        domain objects as its arguments. It is important that
        instances of label providers are not shared between tree viewers
        because the label provider will be disposed when the
        viewer is disposed.
      </p>
      <p>
        The tree viewer makes use of the ILabelProvider interface
        to provide these services. Let&#8217;s take a look
        at the interface&#8217;s two methods.
      </p>
      <p>
        <code>public Image getImage(Object element)</code>
      </p>
      <p>
        This method answers an SWT <code>Image</code> to be used
        when displaying the domain object, <b>element</b>. If the domain
        object does not have a corresponding image, you can
        answer null. Because images use OS resources you need to
        be careful to dispose of them when you are no longer using them.
	This is often accomplished by caching
        the images in the label provider or the plug-in class and
        disposing of them when the viewer is disposed.
      </p>
			
<p> Another important point to keep in mind is that the tree viewer will scale 
  your images if they are different sizes. The first image returned from this 
  method will be the "standard" tree viewer image size. All other images will 
  be scaled up or down to match the size of this first image. These plus and minus 
  images used in the tree viewer to show expanded and collapsed items are also 
  scaled to the "standard" size. <br>
  <br>
				 A safe size to use for your images is 16x16.
			</p>
      <p>
        <code>public String getText(Object element)</code>
      </p>
      <p>
        The getText method answers a string that represents the
        label for the domain object, element. If there is no
        label for the element, answer null.
      </p>
      <p>
        <code>public void dispose()</code>
      </p>
      <p>
        The dispose method is called when the tree viewer that
        contains the label provider is disposed. This method is often used
        to dispose of the cached images managed by the
        receiver.
      </p>
      <p>
        In
        the code listed <a href="#sampleCode">above</a>,
        the tree viewer&#8217;s label provider was set to an
        instance of <code>MovingBoxLabelProvider</code>.
        Let&#8217;s take a look at this class in detail.
      </p>
      <p>
<blockquote>
<pre>
public Image getImage(Object element) {
   ImageDescriptor descriptor = null;
   if (element instanceof MovingBox) {
       descriptor = TreeViewerPlugin.getImageDescriptor("movingBox.gif");
   } else if (element instanceof Book) {
       descriptor = TreeViewerPlugin.getImageDescriptor("book.gif");
   } else if (element instanceof BoardGame) {
       descriptor = TreeViewerPlugin.getImageDescriptor("gameboard.gif");
   } else {
       throw unknownElement(element);
   }

   //obtain the cached image corresponding to the descriptor
   Image image = (Image)imageCache.get(descriptor);
   if (image == null) {
       image = descriptor.createImage();
       imageCache.put(descriptor, image);
   }
   return image;
}
		</pre></blockquote>
	      <p></p>
      <p>
        This method answers the correct image for the given
        domain object, <b>element</b>. An ImageDescriptor is used to
        load the image for the corresponding domain
        object. If an image has not yet been
        loaded, the image descriptor is asked to create the image. The 
        <code>getImageDescriptor</code><code>(String)</code>
        method is shown below. This method will often be
        implemented as a static method on the plug-in class since
        it is a generic utility method and makes use of the
        plug-in&#8217;s installURL.
      </p>
      <p>
<blockquote>
<pre>
public static ImageDescriptor getImageDescriptor(String name) {
   String iconPath = "icons/";
   try {
       URL installURL = getDefault().getDescriptor().getInstallURL();
       URL url = new URL(installURL, iconPath + name);
       return ImageDescriptor.createFromURL(url);
   } catch (MalformedURLException e) {
       // should not happen
       return ImageDescriptor.getMissingImageDescriptor();
   }
}</pre></blockquote>
      <p></p>
      <p><blockquote>
<pre>
public void dispose() {
   for (Iterator i = imageCache.values().iterator(); i.hasNext();) {
       ((Image) i.next()).dispose();
   }
   imageCache.clear();
}</pre></blockquote>
      <p></p>
      <p>
        This dispose method makes sure the label provider correctly
        disposes of the images it has created. This is very
        important to insure that operating system resources are
        not &#8220;leaked.&#8221;
      </p>
      <h2>
        Setting the Initial Input
      </h2>
      <p>
        Now that we&#8217;ve discussed the content provider and the
        label provider, we are nearly finished with the code
        required to create the tree viewer. The one step missing from the example code
	is setting the initial input for the tree viewer. As it stands now, our
        tree viewer does not contain any domain objects.
        Here&#8217;s the code used to set the initial input of
        the tree viewer.
      </p>
      <p>
        <code>treeViewer.setInput(getInitalInput());</code>
      </p>
      <p>
        When you set the tree viewer&#8217;s input, the tree
        viewer works in conjunction with the content and label
        providers to display the tree. Also, remember our content
        provider&#8217;s <code><a href=
        "#inputChanged">inputChanged(&#8230;)</a></code> method
        will be invoked whenever the tree viewer&#8217;s setInput
        method is called.
      </p>
      <p>
        The getInitalInput() method simply creates our sample set
        of domain objects.
      </p>
      <p>
			<blockquote>
<pre>
public MovingBox getInitalInput() {
   MovingBox root = new MovingBox();
   MovingBox books = new MovingBox("Books");
   MovingBox games = new MovingBox("Games");
   MovingBox books2 = new MovingBox("More books");
   MovingBox games2 = new MovingBox("More games");
   
   root.addBox(books);
   root.addBox(games);
   root.addBox(new MovingBox());
   
   books.addBox(books2);
   games.addBox(games2);
   
   books.addBook(new Book("The Lord of the Rings", "J.R.R.", "Tolkien"));
   books.addBoardGame(new BoardGame("Taj Mahal", "Reiner", "Knizia"));
   books.addBook(new Book("Cryptonomicon", "Neal", "Stephenson"));
   books.addBook(new Book("Smalltalk, Objects, and Design", "Chamond", "Liu"));
   books.addBook(new Book("A Game of Thrones", "George R. R.", " Martin"));
   books.addBook(new Book("The Hacker Ethic", "Pekka", "Himanen"));
   //books.addBox(new MovingBox());
   
   books2.addBook(new Book("The Code Book", "Simon", "Singh"));
   books2.addBook(new Book("The Chronicles of Narnia", "C. S.", "Lewis"));
   books2.addBook(new Book("The Screwtape Letters", "C. S.", "Lewis"));
   books2.addBook(new Book("Mere Christianity ", "C. S.", "Lewis"));
   games.addBoardGame(new BoardGame("Tigris & Euphrates", "Reiner", "Knizia"));        
   games.addBoardGame(new BoardGame("La Citta", "Gerd", "Fenchel"));
   games.addBoardGame(new BoardGame("El Grande", "Wolfgang", "Kramer"));
   games.addBoardGame(new BoardGame("The Princes of Florence", "Richard", "Ulrich"));
   games.addBoardGame(new BoardGame("The Traders of Genoa", "Rudiger", "Dorn"));
   games2.addBoardGame(new BoardGame("Tikal", "M.", "Kiesling"));
   games2.addBoardGame(new BoardGame("Modern Art", "Reiner", "Knizia"));       
   return root;
}</pre></blockquote>

      <p></p>
      <h2>
        Selection
      </h2>
      <p>
        In most applications, the user selects an item from the tree viewer in
	order to perform some specific action. You can be notified of these 
	selections by adding a selection change listener
        to the tree viewer. When a selection occurs in the tree
        viewer, it will notify each of its selection change
        listeners, passing along a selection event describing
        what has been selected. Note that these events flow in the opposite
	direction of the model-generated events we discussed earlier.<br><br>
				
	Here&#8217;s an example of handling selection in the tree viewer.
      </p>
      
<p> <a name=
        "selectionChanged"></a> </p>
      <blockquote>
<pre>
treeViewer.addSelectionChangedListener(new ISelectionChangedListener() {
   public void selectionChanged(SelectionChangedEvent event) {
       // if the selection is empty clear the label
       if(event.getSelection().isEmpty()) {
           text.setText("");
           return;
       }
       if(event.getSelection() instanceof IStructuredSelection) {
           IStructuredSelection selection = (IStructuredSelection)event.getSelection();
           StringBuffer toShow = new StringBuffer();
           for (Iterator iterator = selection.iterator(); iterator.hasNext();) {
               Object domain = (Model) iterator.next();
               String value = labelProvider.getText(domain);
               toShow.append(value);
               toShow.append(", ");
           }
           // remove the trailing comma space pair
           if(toShow.length() > 0) {
               toShow.setLength(toShow.length() - 2);
           }
           text.setText(toShow.toString());
       }
   }
});
</pre>
</blockquote>
      <p></p>
      <p>
        Here an anonymous class selection changed listener is
        created. The selection changed method is implemented to
        display the currently selected items in a label or to
        clear the label if no items are selected. A few points to
        note:
      </p>
      <ul type="disc">
        <li>
          Because the selection changed listener method is
          defined in a very generic way, some casting is required.
          For example, a tree viewer&#8217;s selection will
          always be an <code>IStructuredSelection</code> even
          though the <code>SelectionChangedEvent</code>&#8217;s
          getSelection method will answer the more generic
          <code>ISelection</code>.
        </li>
        <li>
          We are using the label provider&#8217;s getText()
          method to assist us in converting the domain objects to
          a textual representation to display in the label.
        </li>
        <li>
          In most UI frameworks, the selection-changed listener
          will be called by the application&#8217;s UI thread.
          SWT is no exception; this means you should be careful
          to return from listener methods in a timely fashion.
        </li>
      </ul>
      <p>
        <img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">
      </p>
      <p>
        Open the &#8220;Moving Box&#8221; view and select one or
        more of the items in the tree. You should see the status
        label update with the names of the selected items like
        this:
      </p>
      <p>
        <p align="center"><img alt="selection.jpg (8K)" src="images/selection.jpg" height="120" width="214"></p>
      <p></p>
      <h2>
        Responding to Change
      </h2>
      <p>
        Applications aren&#8217;t very useful if they don&#8217;t
        handle change. Conceptually, change can be described in a couple
        of ways. When domain objects are changed, the UI
        usually reflects these changes. Likewise, user actions in the UI may
	require updates in the domain objects.
      </p>
      <h3>
        Responding to domain model changes
      </h3>
      <p>
        When a change occurs in the domain model, the UI needs 
	to reflect that change. For example, if a new
        book is added to one of our moving boxes
        programmatically, we want the UI to show the newly added book.
      </p>
      <p>
        While we want the domain to notify the UI through some
        means, we do not want to &#8220;pollute&#8221; the domain
        objects with knowledge about the UI. If the model and the 
        view are too strongly coupled, each becomes brittle and
        fragile to change. We employ an Observer or
        Event-Notification style pattern to break this strong
        coupling.
      </p>
      <p>
        In our example, we achieve this by creating a listener
        interface that our domain objects notify when an
        interesting change occurs. Now we need to provide
        an object to listen for the changes.
      </p>
      <p>
        Typically that object will be the tree viewer&#8217;s
        content provider. Remember the <a href=
        "#inputChanged">inputChanged</a>() method? Our
        inputChanged method will register itself as a listener to
        the domain object changes so it can notify the tree
        viewer of any changes.
      </p>
      <p>
        Typically the tree viewer will be notified of domain
        object changes by calling one of the update methods.
        These are important methods, so let&#8217;s take a look at each
        of them in more detail.
      </p>
      <h4>
        <a name="refeshAndUpdateDifference"></a>What&#8217;s the
        difference between refresh and update?
      </h4>
      <p>
        The tree viewer provides both a refresh and an update
        method. What is the difference between these two and when
        should you use one or the other?
      </p>
      <h5>
        Refresh method
      </h5>
      <p>
        The refresh method refreshes the domain object and all of
        the domain object&#8217;s children. The tree viewer
        updates the label for the object passed to the refresh
        method. The tree viewer also asks its content viewer for
        the children of the object passed to the refresh method
        and recursively updates each of them by collaborating
        with the label and content providers.
      </p>
      <p>
        In addition to this version of refresh, there is also a
        version that allows you to specify whether or not the
        labels of existing elements should be updated.
      </p>
      <h5>
        Update method<a name="update"></a>
      </h5>
      <p>
        The update method simply updates the given domain object&#8217;s
        label. In other words, if the domain object passed to
        the update method contained new children, those new
        children would not appear in the tree viewer by invoking
        the update method. Invoking update will only update the
        domain object&#8217;s label or image.
      </p>
      <h6>
        Update properties
      </h6>
      <p>
        In addition to this behavior, the update method also
        provides a means to specify which &#8220;parts&#8221; of
        the domain object changed. If you choose to specify these
        sub-parts, the tree viewer may be able to optimize the
        update. If no sub-properties are specified, a full update
        of the element is performed.
      </p>
      <p>
        In particular, when you call the update method the
        following decisions are made:
      </p>
      <ul type="disc">
        <li>
          Does the updated domain object need a new label and
          image?
        </li>
      </ul>
      <p>
        The tree viewer collaborates
        with your label provider in order to answer this question. 
				By default, all label providers
        answer that they should be updated when a given property
        of the domain object changes. You can override the
        <code>isLabelProperty(Object element, String
        property)</code> method to specify otherwise.
      </p>
      <ul type="disc">
        <li>
          If the tree viewer contains any filters, it asks each
          filter if the updated domain object needs to be filtered
          out of the tree.
        </li>
      </ul>
      <p>
        The same rules apply here. Each viewer filter can specify
        whether or not it is affected by a change in the given
        property. By default, viewer filters answer false but you
        can override the <code>isFilterProperty(Object element,
        String property)</code> method to specify otherwise.
      </p>
      <ul type="disc">
        <li>
          If the tree viewer contains a sorter, it asks the
          sorter if the updated domain object needs to be
          re-sorted.
        </li>
      </ul>
      <p>
        The same rules apply again. The sorter can specify whether or
        not it is affected by a change in the given property. By
        default, viewer sorters answer false but you can override
        the <code>isSorterProperty(Object element, String
        property)</code> method to specify otherwise.
      </p>
			<h4>Example of Responding to Domain Object Additions and Removals</h4>
			<p>
			  Let's take a look at how to respond to domain object changes. Let's
			  add a new book to one of the moving boxes. We will add this book in
			   response to a button push. It is
			  important to understand, however, that this domain change could come
			  from "anywhere" - a database trigger, a background thread or some other
			  program. We use a button press to keep it simple.   
			</p>
			<img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">
			<p>
			  When you press the "Add New Book" button on the view's toolbar, a 
				book will be added to the selected moving box. What happens when the
				button is pressed? When the SWT button is presed the OS generates an event 
				that is forwarded to the button's selection listener. The selection listener
				method adds a new book to the selected moving box. When a new book is
				added, the moving box will notify its listeners that a domain change has
				occurred. Since we added the content provider as a domain listener, it will
				be notified of the change. The content provider then updates the tree viewer.    
			</p>
				<img alt="addBook.jpg (5K)" src="images/addBook.jpg" height="55" width="415">
			<p> 
				If nothing is selected, the book will be added to the topmost moving 
				box.
			</p>
			<p>Let's take a look at the code.    
			</p>
			<blockquote>
<pre>
protected void addNewBook() {
   MovingBox receivingBox;
   if (treeViewer.getSelection().isEmpty()) {
       receivingBox = root;
   } else {
       IStructuredSelection selection = (IStructuredSelection) treeViewer.getSelection();
       Model selectedDomainObject = (Model) selection.getFirstElement();
       if (!(selectedDomainObject instanceof MovingBox)) {
           receivingBox = selectedDomainObject.getParent();
       } else {
          receivingBox = (MovingBox) selectedDomainObject;
       }
   }
   receivingBox.add(Book.newBook());
}
</pre></blockquote>
			<p>
			The addNewBook method is called when the "Add a New Book" toolbar button
			is pressed. Notice that if multiple items are selected, we ignore all of them
			except for the first one. Also notice that if the selected item is not a moving box,
			we ask the selected item for its parent, which will be a moving box. Once
			we have the moving box domain object, we tell it to add a new book. 
			</p>
			<p>
			The moving box's add method is not very interesting. It simply adds the
			book and notifies its listeners that a book has been added. When this
			notification occurs, the content viewer will be informed since it
			<a href="#inputChanged">registered</a> itself as a listener for these 
			domain changes. Let's take a look at how the content provider services
			the addition event notification. Here's the content provider's listener 
			method that is called on additions.
			</p>
			<blockquote>
<pre>
public void add(DeltaEvent event) {
    Object movingBox = ((Model)event.receiver()).getParent();
    viewer.refresh(movingBox, false);
}
</pre></blockquote>
			<p>
			Pretty simple, right? The content provider asks the event for the receiver,
			which is the newly added book. Next, the content provider asks the
			tree viewer to refresh the moving box that contains the newly added
			book. Remember that refresh will cause the tree viewer to consult with
			its content provider to supply a list of children for the refresh
			object. The false argument is passed along to the refresh method
			to let it know that we do not need the labels of the other objects in
			the tree refreshed.
			</p>
			<p>Removing something from the tree works in exactly the same way. We
			remove the domain object from the moving box and ask the tree viewer 
			to acquire its model objects from the content provider again.
			</p>
      <h3>
        Responding to UI changes
      </h3>
      <p>
        We also need to respond to changes made in the UI. Often
        these UI changes cause a domain object to change. For
        example, if we edit the author of one of the books in the
        tree viewer, we need to make sure this change is
        correctly propagated to the book domain object.
      </p>
      <p>
        Typically, you will create listeners and add them to the
        tree viewer. Your listener methods will retrieve the necessary
        domain objects from the tree viewer or passed event
        object.
      </p>
      <p>
        An example of this technique was shown in the
        selectionChanged method. Here's part of that method again.
      </p>
      <p>
<blockquote>
<pre>
public void selectionChanged(SelectionChangedEvent event) {
       // if the selection is empty clear the label
       if(event.getSelection().isEmpty()) {
           text.setText("");
           return;
       }
       if(event.getSelection() instanceof IStructuredSelection) {
           IStructuredSelection selection = (IStructuredSelection)event.getSelection();
           StringBuffer toShow = new StringBuffer();
           for (Iterator iterator = selection.iterator(); iterator.hasNext();) {
               <img SRC="images/tag_1.gif" BORDER=0 height=13 width=24>Object domain = (Model) iterator.next();
               String value = labelProvider.getText(domain);
               toShow.append(value);
               toShow.append(", ");
           }
           // remove the trailing comma space pair
           if(toShow.length() > 0) {
               toShow.setLength(toShow.length() - 2);
           }
           text.setText(toShow.toString());
}
</pre></blockquote>
      <p></p>
      <p>
      <img SRC="images/tag_1.gif" BORDER=0 height=13 width=24> In this example, we're retrieving the
      domain object from the event object's selection. We could have just as easily asked the tree viewer
      for the currently selected objects.
      </p>
      <p>
        Here is a list of listeners you can add to a tree viewer
        along with a description of each of them.
      </p>
      <table border="1" cellspacing="3" cellpadding="0" width="595">
        <tr>
          <td valign="top">
            <p align="center">
              <b>Listener Type</b>
            </p>
          </td>
          <td valign="top">
            <p align="center">
              <b>Description</b>
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addHelpListener(HelpListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Responds to help requests
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addSelectionChangedListener</code><code>(ISelectionChangedListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Responds to selection changes
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addDoubleClickListener</code><code>(IdoubleClickListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Responds to double clicks
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addDragSupport</code><code>(int, Transfer[],
              DragSourceListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Sets up a listener to support dragging items out of
              the tree viewer
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addDropSupport</code><code>(int, Transfer[],
              DropTargetListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Sets up a listener to support dropping objects in
              tree viewer
            </p>
          </td>
        </tr>
        <tr>
          <td valign="top">
            <p>
              <code>addTreeListener</code><code>(ItreeViewerListener)</code>
            </p>
          </td>
          <td valign="top">
            <p>
              Responds to expand and collapse events
            </p>
          </td>
        </tr>
      </table>
      <h2>
        <a name="viewFilters"></a><a name=
        "viewerFilters"></a>Viewer Filters
      </h2>
      <p>
        Viewer filters are used by a tree viewer to extract a
        subset of the domain objects provided by the content
        provider. You add and remove viewer filters from the tree
        viewer.
      </p>
      <p>
        Viewer filters are additive, which means that the output of
        one filter is passed in as the input of the next filter.
        The final result has been filtered through each view
        filter.
      </p>
      <p>
        ViewerFilter is an abstract class. In order to implement
        a viewer filter you subclass this class and override a
        single method, <code>select(Viewer, Object,
        Object)</code>. The method should answer true if
        the domain object makes it through the filter. The select
        method also passes the domain object&#8217;s
        parent.
      </p>
      <p>
        If you need more sophisticated filtering, you may override
        other methods in ViewFilter to refine how the filtering
        is accomplished. In particular the <code>isFilterProperty(Object
        domain, String property)</code> method can be used to
        answer whether or not the particular filter is interested in a
				<b>property</b> change to the <b>domain</b> object.
      </p>
      <p>
        The <code>isFilterProperty</code> method is used in
        conjunction with the tree viewer&#8217;s update method.
        More information about the update method can be found <a
        href="#update">here</a>.
      </p>
      <p>
        Let&#8217;s build a view filter that shows only the board
        games contained in our moving boxes.
      </p>
      <p>
        When building filters, it&#8217;s important to keep in
        mind the content providers and the input element for the viewer. For
        example, if we use the following filter, we&#8217;ll have
        problems.
      </p>
      <p>
			<blockquote>
<pre>
public boolean select(Viewer viewer, Object parentElement, Object element) {
    return element instanceof BoardGame;
}
</pre></blockquote>
      <p></p>
      <p>
        The problem with this example is that we will filter out our parent.
        In other words, this filter rejects moving boxes, but
        remember that moving boxes are what contain board games. So if
        we filter out moving boxes, the content provider will not
        have anything left to ask for content.
      </p>
      <p>
        We can solve this by changing our filter to
        this:
      </p>
      <p>
 <blockquote>
<pre>
public boolean select(Viewer viewer, Object parentElement, Object element) {
    return element instanceof BoardGame || element instanceof MovingBox;
}
</pre></blockquote>
     <p></p>
      <p>
        This filter works as intended, leaving only board games
        visible in the tree viewer.
      </p>
      <p>
        Let&#8217;s build another filter that both augments and
        works independently from the board game filter. The second
        filter will show only the contents of moving boxes that
        contain at least 3 items. Here&#8217;s the code for our
        ThreeItemFilter:
      </p>
      <p>
<blockquote>
<pre>
public boolean select(Viewer viewer, Object parentElement, Object element) {
    return parentElement instanceof MovingBox && ((MovingBox)parentElement).size() >= 3;
}
</pre></blockquote>
      <p></p>
      <p>
        Coupled with the first filter, this filter can be used
        to show all of the board games contained in moving boxes
        with three or more items in them.
      </p>
     <p>
        Another important point to remember with filters is that
        they also apply to the root of the tree viewer. In other words, if the
        root does not contain at least three
        items, then you will never get around to filtering the
        children.
      </p>
      <p>
        <img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">
      </p>
      <p>
        Open the &#8220;Moving Box&#8221; view and select the
        triangle near the edge of the window. Then choose the
        filters and verify that they are working.
      </p>
      <p>
        <p align="center"><img alt="filters.jpg (13K)" src="images/filters.jpg" height="117" width="482"></p>
      <p></p>
      <h2>
        <a name="viewerSorters"></a>Viewer Sorters
      </h2>
      <p>
        The tree viewer collaborates with a viewer sorter to order
        the domain objects provided by the content provider.
      </p>
      <p>
        In contrast to our discussion of viewer filters, a tree viewer may
				utilize only one viewer sorter at a given time. You can always set a different view
        sorter whenever you like, but at any specific moment, there is either
        exactly one viewer sorter or none at all.
      </p>
      <p>
        ViewerSorter is an abstract class that defines a default
        sorting behavior. Conceptually, the only method that needs
        to be implemented is the <code>public int compare(Viewer
        viewer, Object e1, Object e2)</code>method. The
        ViewerSorter class provides a default implementation of
        this method that defines a default sorting behavior.
      </p>
      <p>
        This default sorting behavior consists of grouping
	each domain object into categories [by
        invoking the public int category(Object
        element) method] and then sorting each domain
        object within a category by using the tree viewer&#8217;s
        label content provider&#8217;s getText method.
      </p>
      <p>
        By default the viewer sorter considers all domain
        objects to be in the same category.
      </p>
      <p>
        If this two-phase default sorting behavior makes
        sense for your application, then you likely only need to
        override the category method in order to place your domain objects
        into their respective categories. Otherwise you&#8217;re
        probably better off implementing the compare
        method to sort in the appropriate manner for your
        application. We&#8217;ll take a look at both
        approaches.
      </p>
      <p>
        As with the view filter, the view sorter contains an
        <code>isSorterProperty</code> method that can be used to
        answer whether or not the particular sorter would be
        affected by a change to the given property for the given
        domain object.
      </p>
      <p>
        The <code>isSorterProperty</code> method is used in
        conjunction with the tree viewer&#8217;s update method.
        More information about the update method can be found <a
        href="#update">here</a>.
      </p>
      <p>
        Our first sorter will rely on the default sorting
        behavior and implement a sorter that orders the items in
        such a way that books appear before moving boxes, which
        appear before board games. To achieve this we can simply
        override the category method like this:
      </p>
      <p>
<blockquote>
<pre>
/** Orders the items in such a way that books appear 
 * before moving boxes, which appear before board games. */
public int category(Object element) {
    if(element instanceof Book) return 1;
    if(element instanceof MovingBox) return 2;
return 3;
}
</pre></blockquote>

      <p></p>
      <p>
        The default sorting behavior uses the category method to
        place objects into bins, and the bins are arranged in
        ascending order.
      </p>
      <p>
        Our second sorter will use the text labels to order the items in an article
        independent fashion. This means that the literals (e.g. 
        &#8220;the&#8221;, &#8220;a&#8221;, &#8220;El&#8221; and
        &#8220;La&#8221; will be ignored in terms of sorting. For
        example &#8220;A Zoo&#8221; will sort after &#8220;The
        Car.&#8221; This was not true for the first sorter.
      </p>
      <p>
        The default sort method uses a simple case insensitive
        sort for items within the same category. We will
        override the compare method to implement an
        article-ignoring sort.
      </p>
      <p>
        Here&#8217;s our compare method (which is mostly a copy
        of ViewerSorter&#8217;s method).
      </p>
      <p><blockquote>
<pre>
public int compare(Viewer viewer, Object e1, Object e2) {
   int cat1 = category(e1);
   int cat2 = category(e2);
   if (cat1 != cat2) return cat1 - cat2;
   String name1, name2;
   if (viewer == null || !(viewer instanceof ContentViewer)) {
       name1 = e1.toString();
       name2 = e2.toString();
   } else {
       IBaseLabelProvider prov = ((ContentViewer)viewer).getLabelProvider();
       if (prov instanceof ILabelProvider) {
           ILabelProvider lprov = (ILabelProvider)prov;
           name1 = lprov.getText(e1);
           name2 = lprov.getText(e2);
       } else {
           name1 = e1.toString();
           name2 = e2.toString();
       }
   }
   if(name1 == null) name1 = "";
   if(name2 == null) name2 = "";
   name1 = stripArticles(name1);
   name2 = stripArticles(name2);
   return collator.compare(name1, name2);
}
</pre></blockquote>
      <p></p>
      <p>
        This is a verbatim copy of the superclass&#8217;s method,
        except for the addition of stripArticles near the bottom
        of the method. The stripArticles method looks like this:
      </p>
      <p>
<blockquote>
<pre>
protected String stripArticles(String name) {
   String test = name.toLowerCase();
   if(test.startsWith("the ") && test.length() > 3) {
       return name.substring(4);
   } else if(test.startsWith("a ") && test.length() > 1) {
       return name.substring(2);
   } else if(test.startsWith("el ") && test.length() > 2) {
       return name.substring(3);
   } else if(test.startsWith("la ") && test.length() > 2) {
       return name.substring(3);
   }
   return name;    
}
</pre></blockquote>
      <p></p>
      <p>
        This sorter does exactly what we want and shows an
        example of overriding the compare method to implement the search.
      </p>
      <p>
        <img alt="tryit.gif (1K)" src="images/tryit.gif" height="13" width="61">
      </p>
      <p>
        Open the &#8220;Moving Box&#8221; view and select the
        triangle near the edge of the window. Then choose the
        sorters and verify that they work as you expected.
      </p>
      <p>
         
      </p>
      <p>
       <p align="center"><img alt="sorters.jpg (15K)" src="images/sorters.jpg" height="144" width="501"></p>
      <p></p>
      <h2>
        Conclusion
      </h2>
      <p>
        This article has demonstrated the basic usage of tree
        viewers. Hopefully, you now understand how to use the tree
        viewer and understand where the tree viewer fits within
        the larger JFace framework.
      </p>
      <p>
        There are a number of topics planned for an
        &#8220;advanced&#8221; tree viewer article, including
 				drag and drop, auto expand nodes
        within the tree, in-place editing and making use of domain
        object properties.
      </p>
      <h2>
        Frequently Asked Questions
      </h2>
      <p>
        Here is a list of frequently asked questions about using
        the tree viewer.
      </p>
      <h3>
        How do I add or remove an item from the tree?
      </h3>
      <p>
        Addition and removal of items is essentially the same.
      </p>
      <p>
        To remove an item from the tree viewer you should remove
        the domain object from your model. Then ask
        the tree viewer to refresh the parent of the domain
        model. When the update method is called on the tree
        viewer, it will ask its content provider for
        the children of the parent of the domain model. However, since you
        removed it from the parent, it will not be there and
        subsequently will be removed from the view.
      </p>
      <p>
        If your domain objects trigger events, you will add
        the content provider as a listener so that whenever removals
        occur in your domain object, the content provider can be
        notified and perform the steps above.
      </p>
      <p>
        What about the tree viewer's remove methods?
	If you read the Javadoc for these
        methods, they will tell you the remove methods should be
        called by the <b>content provider</b>. This makes sense
        after all, because the content provider is responsible
        for supplying the content. If you removed the item from
        the tree viewer without &#8220;going through&#8221; the
        content provider, the item would likely reappear the next
        time the parent of the item is refreshed.
      </p>
      <h3>
        How do I programmatically select an item in the tree?
      </h3>
      <p>
        Call the tree viewer&#8217;s setSelection(new
        StructuredSelection(&lt;domain model&gt;), true).
      </p>
      <h3>
        What is the difference between the tree viewer&#8217;s
        update and refresh methods?
      </h3>
      <p>
        See this <a href=
        "#refeshAndUpdateDifference">discussion</a>.
      </p>
      <h3>
        How do I reveal a newly added model object that is hidden?
      </h3>
      <p>
        Let&#8217;s assume you&#8217;ve added the domain object
        book to your moving box. The moving box is
        already in the tree but isn&#8217;t expanded when you add
        the book to it. You want the book to be revealed when
        you add it to the moving box. You would do this:
      </p>
      <p>
        <blockquote><pre>
treeViewer.setExpandedState(movingBox, true);
treeViewer.refresh(movingBox, false);
	</pre></blockquote>	
      <p></p>
      <h3>
        My tree viewer hangs or isn&#8217;t very responsive
        because I&#8217;m hitting a database in my content
        provider. What can I do?
      </h3>
      <p>
        In most UI frameworks, the listeners are called by the
        application&#8217;s UI thread. SWT is no exception. This
        means you should be careful to return from listener or
        provider methods in a timely fashion. If you don&#8217;t,
        the GUI will not receive events, which makes for a
        sluggish and potentially useless UI.
      </p>
      <p>
        If you have a long running operation in your listener or
        provider methods, you should consider forking another
        thread to do the actual work. For example, if you are
        populating your tree from a database, you can&#8217;t have
        your content provider waiting for the database to return
        the domain objects. Instead you could have the content
        provider return a stub object that shows something like
        &#8220;Loading Data&#8230;&#8221; while the background
        thread loads the real data.
      </p>
      <p>
        Once the background thread has loaded the data, it would
        need to refresh the parent of the stub object so that the
        parent would request its domain objects again. Now
        when the parent requests the domain objects, they already
        exist since they&#8217;ve been loaded from the database.
      </p>
      <h3>
        How do I add a viewer filter to a tree viewer?
      </h3>
      <p>
        See this <a href="#viewerFilters">discussion</a>.
      </p>
      <h3>
        How do I change the order of the items in a tree viewer?
      </h3>
      <p>
        See this <a href="#viewerSorters">discussion</a>.
      </p>
      <h3>
        What does the setUseHashlookup() method do?
      </h3>
      <p>
        The setUseHashlookup(boolean) method informs the tree
        viewer that it should maintain a hash mapping of your
        domain object to the corresponding SWT TreeItem. Whenever
        the tree viewer needs to manipulate the SWT tree items,
        it uses the hash lookup or performs a recursive search
        starting at the root looking for the item.
      </p>
      <p>
        The tree viewer manipulates SWT tree items whenever you
        add, remove, collapse, expand, reveal, refresh or update
        a domain object. In other words, the tree viewer is
        manipulating tree items all the time.
      </p>
      <p>
        You should probably always setUseHashlookup to true.
        The only downside to doing so is that the tree viewer will
        require more memory since it&#8217;s maintaining the
        mapping, but it should perform much faster with a large
        set of domain objects.
      </p>
      <p>
        Another important point about tree viewers - in general, they don&#8217;t 
				handle domain objects that
        map to the same value. This is because the tree viewer
        uses the equals() method and potentially the hashCode()
        method if you use the setUseHashlookup method.
      </p>
  </body>
</html>