Easy to Learn Java: Programming Articles, Examples and Tips

Start with Java in a few days with Java Lessons or Lectures

Home

Code Examples

Java Tools

More Java Tools!

Java Forum

All Java Tips

Books

Submit News
Search the site here...
Search...
 

Swing Chapter 25. (Special topics) JavaHelp. Easy for reading, Click here!

Custom Search
Swing Chapter 25. (Special topics) JavaHelp. Easy for reading, Click here!

[ Return to Swing (Book) ]

Page: 6/6 



Previous Page Previous Page (5/6)
Subpages: 1. JavaHelp introduction
2. JavaHelp API overview
3. Basic JavaHelp example
4. Adding dialog-style help
5. Customizing the JHelp viewer
5. Creating a custom help view

25.6  Creating a custom help view

As we mentioned earlier, JavaHelp allows developers to add a new navigator view by simply adding a new <view> tag to the HelpSet file. Unfortunately this navigator view cannot gain an access to the viewer component that displays it (it can only have access to a data file supplied as a parameter with the <data> tag, similar to TOC or index views). We can work around this limitation by using the same basic technique used in the previous section to access the JHelp toolbar. The following example adds a custom navigational view to the JHelp viewer tabbed pane to display a selectable, dynamically changeable help topic history.

Figure 25.5 Custom JavaHelp History view added to the JavaHelp viewer.

<<file figure25-5.gif>>

HelpSet file: FTP.hs

see \Chapter25\4\help\

   // Unchanged from section 25.4

   <view>

     <name>History</name>

     <label>History</label>

     <type>HistoryView</type>

   </view>

</helpset>

The Code: FTPApp.java

see \Chapter25\4

// Unchanged imports from section 25.5

public class FTPApp extends JFrame

{

  // Unchanged code from section 25.5

  public FTPApp() {

    super("FTP Client [Help History]");

    // Unchanged code from section 25.5

    WindowListener wndCloser = new WindowAdapter() {

      // Unchanged code from section 25.5

      public void windowDeactivated(WindowEvent e) {

        // Unchanged code from section 25.5

          Enumeration en = jh.getHelpNavigators();

          while (en.hasMoreElements()) {

            JHelpNavigator jhn = (JHelpNavigator)

              en.nextElement();

            NavigatorView view = jhn.getNavigatorView();

            if (view instanceof HistoryView)

              ((HistoryView)view).setNavigator(jhn);

          }

        }

      }

    };

    addWindowListener(wndCloser);

    // Unchanged code from section 25.5

  }

// Unchanged code from section 25.5

The Code: HistoryView.java

see \Chapter25\4

import java.awt.*;

import java.awt.event.*;

import java.util.*;

import java.net.*;

import javax.swing.*;

import javax.swing.event.*;

import javax.swing.tree.*;

import javax.help.*;

import javax.help.event.*;

public class HistoryView extends TOCView

 implements HelpModelListener

{

  protected DefaultMutableTreeNode m_topNode;

  protected JTree m_tree;

  protected DefaultTreeModel m_model;

  protected TreePath m_zeroPath;

  public HistoryView(HelpSet hs, String name, String label,

   Hashtable params) {

    super(hs, name, label, hs.getLocale(), params);

  }

  public HistoryView(HelpSet hs, String name, String label,

   Locale locale, Hashtable params) {

    super(hs, name, label, locale, params);

  }

  public Component createNavigator(HelpModel model) {

    JHelpNavigator navigator =

      new JHelpTOCNavigator(this, model);

    navigator.getUI().setIcon(new ImageIcon("History.gif"));

    return navigator;

  }

  public static MutableTreeNode parse(URL url, HelpSet hs,

    Locale locale, TreeItemFactory factory) {

      return new DefaultMutableTreeNode("History");

  }

  public void setNavigator(JHelpNavigator jhn) {

    jhn.getModel().addHelpModelListener(this);

    try {

      Container c = jhn;

      while (!(c instanceof JTree))

        c = (Container)(c.getComponent(0));

      m_tree = (JTree)c;

      TOCItem top = new TOCItem();

      top.setName("History");

      m_topNode = new DefaultMutableTreeNode(top);

      m_model = new DefaultTreeModel(m_topNode);

      m_tree.setModel(m_model);

      m_zeroPath = new TreePath(new Object[] { m_topNode });

    }

    catch (Exception ex) {

      ex.printStackTrace();

      System.err.println(ex.toString());

    }

  }

  public void idChanged(HelpModelEvent e) {

    // To avoid conflict with java.util.Map

    javax.help.Map.ID id = e.getID();

    if (m_topNode != null) {

      TOCItem item = new TOCItem(id, null, null);

      item.setName(id.id);

      for (int k=0; k<m_topNode.getChildCount(); k++) {

        DefaultMutableTreeNode child =

          (DefaultMutableTreeNode)m_topNode.getChildAt(k);

        TOCItem childItem = (TOCItem)child.getUserObject();

        if (childItem.getID().equals(id))

          m_topNode.remove(child);

      }

      DefaultMutableTreeNode node =

        new DefaultMutableTreeNode(item);

      m_topNode.insert(node, 0);

      m_model.reload(m_topNode);

      m_tree.expandPath(m_zeroPath);

    }

  }

}

Understanding the Code

FTP.hs

One more <view> tag is now added to our FTP.hs XML HelpSet file to request the creation of a HistoryView with a name and label of "History." This results in a new navigator in JHelp's navigational view tabbed pane. This navigator is connected to an instance of our custom HistoryView class.

Class FTPApp

To connect the history view to the viewer itself, some code has been added to our windowDeactivated() method in the WindowAdapter inner class. This code retrieves all help views using the getHelpNavigators() method, examines all of them in turn, and, if an instance of our custom HistoryView class is found, calls the setNavigator() method to pass a reference to JHelpNavigator to it.

Note: The fact that we have to add this code to our application in order to use a custom view should immediately stand out as bad design, even though it is only called once (see previous example). We are forced to do this because the parent class, NavigatorView, does not provide any means of retrieving the associated instance of JHelpNavigator used to display it. This severely limits the abilities of help customization and contradicts the flexible, JavaBeans design of Swing components. We hope to see this limitation accounted for in future JavaHelp releases, making this workaround unnecessary.

Class HistoryView

This class represents a custom implementation of NavigatorView to provide easy access to previously viewed help topics. HistoryView implements HelpModelListener and extends TOCView to inherit its functionality and avoid writing our own NavigatorView sub-class. Instance variables:

JTree m_tree: the tree component used to display historical help topics.

DefaultMutableTreeNode m_topNode: the root node in the tree parenting all historical help topics. This node is not visible because the rootVisible property is set to false by the parent TOCView class.

DefaultTreeModel m_model: the historical tree model.

TreePath m_zeroPath: path to the root node.

The two available constructors delegate their work the corresponding superclass constructors. The createNavigator() method creates an instance of JHelpTOCNavigator (a sub-class of JHelpNavigator) to represent our historical view graphically, and assigns it a custom icon (to be displayed in JHelp's navigational views tabbed pane).

Since we are not intending to parse any external data files in our historical view (all data is generated by the help viewer itself at run-time), the parse() method simply creates and returns an instance of DefaultMutableTreeNode with user object "History," and no child nodes.

Our custom setNavigator() method establishes a connection between this view and the JHelpNavigator component supplied as parameter representing our history information graphically. First, this view is added as a HelpModelListener to the JHelpNavigator's HelpModel to receive HelpModelEvents when a change in the current help topic occurs. Second, we search for the JHelpNavigator's tree component by iterating through its containment hierarchy. Then the m_topNode variable is assigned a DefaultMutableTreeNode instance with a default TOCItem user object assigned a name of "History." We also assign the m_model variable as a reference to this tree's model, and m_zeroPath is used to store the path from the tree's root to m_topNode (which simply consists of m_topNode itself). Both variables are needed in idChanged().

The idChanged() method will be called when the current help topic is changed. This method receives an instance of HelpModelEvent which encapsultes, among other things, the new help topic ID. It then creates a new TOCItem using that ID, and checks all child nodes of m_topNode to find out whether the corresponding topic already exists in the history view. If so, it is removed to avoid redundancy. Then the new topic is inserted at the top of the tree. Thus the previously viewed topics appear listed from most recent at the top, to least recent at the bottom. Finally we call reload() on the tree model and expandPath() on the tree, using m_zeroPath, to make sure that the tree updates its graphical representation correctly after it is reloaded.

Note: Since the root tree node is hidden and the path to it is collapsed by default, no nodes in the view will be visible after a reload() unless we expand m_zeroPath programmatically.

That's all we need to do to create a history view. As soon as the user clicks on the topic listed in the help view, it will be displayed in the viewer because we inherit this functionality from TOCView.

Running the Code

Figure 25.5 shows the customized help viewer for our FTP Client example with the custom history view. Select several help topics in a row using the TOC or index views and then select the history view. Note that all visited help topics are listed in the reverse order that they were visited in. Click on any of these topics and note that viewer jumps to that topic (at the same time the selected topic is displayed it moves to the top of the history view, as expected).



[ Return to Swing (Book) ]


Top 10 read Java Articles
 Get free "1000 Java Tips eBook"

 Java Calendar and Date: good to know facts and code examples

 Array vs ArrayList vs LinkedList vs Vector: an excellent overview and examples

 How can I convert any Java Object into byte array? And byte array to file object

 The Java Lesson 1: What is Java?

 How do I compare two dates and times, date between dates, time between times and

 Maven vs Ant or Ant vs Maven?

 How to open, read, write, close file(s) in Java? Examples on move, rename and de

 Java Array

 Java: JLabel font and color


[ More in News Section ]
Java Lessons

The Java Lesson 1:
What is Java?
The Java Lesson 2:
Anatomy of a simple Java program
The Java Lesson 3:
Identifiers and primitive data types
The Java Lesson 4:
Variables, constants, and literals
The Java Lesson 5:
Arithmetic operations, conversions, and casts
The Java Lesson 6:
Boolean expressions and operations
The Java Lesson 7:
Bitwise operations
The Java Lesson 8:
Flow control with if and else
The Java Lesson 9:
switch statements
The Java Lesson 10:
for, while, and do-while statements
The Java Lesson 11:
Using break and continue
The Java Lesson 12:
Class methods and how they are called
The Java Lesson 13:
Using the Math class
The Java Lesson 14:
Creating and calling custom class methods
The Java Lesson 15:
Overloading class methods
The Java Lesson 16:
An introduction to objects and object references
The Java Lesson 17:
The String class
The Java Lesson 18:
The StringBuffer class
The Java Lesson 19:
Initializing and processing arrays of primitives
The Java Lesson 20:
Initializing and processing arrays of objects
The Java Lesson 23:
Inheritance and overriding inherited methods
The Java Lesson 24:
abstract classes and polymorphism
The Java Lesson 25:
Interfaces, instanceof, and object conversion and casting
The Java Lesson 26:
Introduction to graphical programming and the java.awt packa
The Java Lesson 27:
The Component class
The Java Lesson 28:
Containers and simple layout managers
The Java Lesson 29:
The Color and Font classes
The Java Lesson 30:
Drawing geometric shapes
The Java Lesson 31:
Choice, List, and Checkbox controls
The Java Lesson 32:
Using the Scrollbar graphical control
The Java Lesson 33:
Menus and submenus
The Java Lesson 34:
An introduction to applets and the Applet class
The Java Lesson 35:
Essential HTML to launch an applet and pass it parameters
The Java Lesson 36:
Mouse event processing
Java Lesson 37:
Menus and submenus
Java Lesson 38:
The WindowListener interface and the WindowAdapter class
Java Lesson 39:
An introduction to GridBagLayout
Java Lesson 40:
An introduction to the Java Collections API
Java Lesson 41:
Exception handling with try, catch, and finally blocks
Java Lesson 42:
Claiming and throwing exceptions
Java Lesson 43:
Multithreading, the Thread class, and the Runnable interface
Java Lesson 44:
An introduction to I/O and the File and FileDialog classes
Java Lesson 45:
Low-level and high-level stream classes
Java Lesson 46:
Using the RandomAccessFile class
Java Lessons by
Joh Huhtala: Update

Latest articles
 Java Profiler JProbe to Resolve Performance Problems Faster

 SSL with GlassFish v2, page 5

 SSL with GlassFish v2, page 4

 SSL with GlassFish v2, page 3

 SSL with GlassFish v2, page 2

 The Java Lesson 2: Anatomy of a simple Java program, page 2

 New site about Java for robots and robotics: both software and hardware.

 Exceptions -III: What's an exception and why do I care?

 Exceptions -II: What's an exception and why do I care?

 Exceptions: What's an exception and why do I care?

 Double your Java code quality in 10 minutes, here is receipt

 Murach's Java Servlets and JSP

 How to get ascii code from a char in Java?

 Can we just try without catch? Yes!

 Make Tomcat page load faster

 Make your Tomcat More secure - limit network address for certain IP addresses

 New Java book online starts now here...

 Implementing RESTful Web Services in Java

 Firefox trimming from 1 GB to 40 Mb with many tabs opened

 SSL with GlassFish v2

 My request to replublish Tech Tips

 Search JavaFAQ.nu site here

 New Advanced Installer for Java 6.0 brings XML updates and imports 3rd party MSI

 EJB programming restrictions

 Maven vs Ant or Ant vs Maven?

 Why Java does not use default value which it should?

 How to unsign signed bytes in Java - your guide is here

 The Java Lesson 3: Identifiers and primitive data types. Page 2

 The Java Lesson 7: Bitwise operations with good examples, click here! Page 4

 The Java Lesson 7: Bitwise operations with good examples, click here! Page 3


[ More in News Section ]


Home Code Examples Java Forum All Java Tips Books Submit News, Code... Search... Offshore Software Tech Doodling

RSS feed Java FAQ RSS feed Java FAQ News     

    RSS feed Java Forums RSS feed Java Forums

All logos and trademarks in this site are property of their respective owner. The comments are property of their posters, all the rest 1999-2006 by Java FAQs Daily Tips.

Interactive software released under GNU GPL, Code Credits, Privacy Policy