Content outliners

Editors often have corresponding content outliners that provide a structured view of the editor contents and assist the user in navigating through the contents of the editor.

The workbench provides a standard Outline view for this purpose.  The workbench user controls when this view is visible using the Window > Show View menu.

Since the generic TextEditor doesn't know anything about the structure of its text, it cannot provide behavior for an interesting outline view.  Therefore, the default Outline view, shown below, doesn't do much.

Default content outliner

Plug-ins can extend TextEditor for the sole purpose of adding a custom content outliner page to the outline view.   This approach is used in the workbench readme tool example.  The ReadmeEditor overrides a few methods in TextEditor to supply its own outliner.  

The outliner for an editor is specified when the workbench requests an adapter of type IContentOutlinePage.

   public Object getAdapter(Class key) {
      if (key.equals(IContentOutlinePage.class)) {
         IEditorInput input = getEditorInput();
         if (input instanceof IFileEditorInput) {
            page = new ReadmeContentOutlinePage(
               ((IFileEditorInput)input).getFile());
            return page;
         }
      }
      return super.getAdapter(key);
   }

When a ReadmeEditor is opened (on a .readme file), the corresponding readme outliner is displayed (if the workbench user is showing the Outline view.)

Readme content outliner

A content outliner page must implement IContentOutlinePage.  This interface combines the ability to notify selection change listeners (ISelectionProvider) with the behavior of being a page in a view (IPage).  Content outliners are typically implemented using JFace viewers.  The default implementation of a content outliner (ContentOutlinePage) uses a JFace tree viewer to display a hierarchical representation of the outline.  This representation is suitable for many structured outliners, including ReadmeContentOutlinePage.

The ReadmeContentOutlinePage is similar in appearance to the readme sections view, shown below,  that we saw when we implemented the readme views extension.

Readme sections dialog

In fact, the only real difference is that the outliner displays a hierarchical view of the sections, while the readme sections view displays a flat list of the sections.  It should be no great surprise that the implementation of the outliner is very similar to that of the view.  The only difference is that the outliner uses a tree viewer instead of a list viewer.

When the outline page was created by the editor, it was passed the editor's input element in the constructor.  This input can often be passed directly to the outline page's viewer, as is done below.

   public void createControl(Composite parent) {
      ...
      TreeViewer viewer = getTreeViewer();
      viewer.setContentProvider(new WorkbenchContentProvider());
      viewer.setLabelProvider(new WorkbenchLabelProvider());
      viewer.setInput(getContentOutline(input));
      ...
   }

The tree viewer creation is inherited from ContentOutlinePage.  The same content and label providers that were used in the readme sections view are used here, and the outline for the content is constructed using the same ReadmeModelFactory that constructed the sections for the view.

   private IAdaptable getContentOutline(IAdaptable input) {
      return ReadmeModelFactory.getInstance().getContentOutline(input);
   }

That's all there is to it!

Of course, the outliner itself doesn't provide any interesting behavior.  Selecting the sections does not navigate the text in the editor!  What good is this content outliner anyway?  You could argue that the content outliner doesn't provide any behavior (besides the hierarchical representation) that we didn't already see in the sections view.  Couldn't we have just used a tree viewer in the sections view instead of providing an outliner that doesn't do anything? 

It's just an example!  Actually, the ReadmeContentOutlinePage is provided to demonstrate how a content outliner can be customized for a text editor.  It is not a good example of a content outliner itself.  Users expect content outliners to assist them in the navigation of the editor content, so it would be a better decision to use the sections view if the only purpose is to display the structure of the content.

Where can you find more interesting content outliners?  Look at the subclasses of ContentOutlinePage and their corresponding editors.  The more typical pattern is that an editor supplies an outline page and registers selection events on it.  As items are selected in the content outline, the editor updates itself appropriately.

The Java source code editor (provided in the JDT) demonstrates an interesting content outliner.  The Java outliner presents a structured view of Java source code and allows the user to navigate through declarations, methods, and fields in the corresponding editor.  As the outliner reports selection events, the Java editor updates its vertical ruler to show where the elements in the outliner are located in the source code.

Java editor with content outliner

Copyright IBM Corp. and others 2000,2002.