Changeset 10647

Show
Ignore:
Timestamp:
26.09.2005 16:30:38 (14 years ago)
Author:
mdewsnip
Message:

A lot of tidy ups and bug fixes. The help now works again in an applet configuration, and clicking a link to another section now updates the contents tree selection correctly.

Files:
1 modified

Legend:

Unmodified
Added
Removed
  • trunk/gli/src/org/greenstone/gatherer/gui/HelpFrame.java

    r10602 r10647  
    5353import org.w3c.dom.*; 
    5454 
     55 
    5556/** 
    5657 * This class provides a nice help facility. It is a separate frame that can be positioned 
     
    5960 */ 
    6061public class HelpFrame  
    61     extends JFrame { 
    62  
    63     static private final String NULL_STRING = "<null>"; 
     62    extends JFrame 
     63{ 
    6464    /** The size of the frame */ 
    6565    static private final Dimension SIZE = new Dimension(760, 560); 
     
    6767    static private HelpFrame self = null; 
    6868 
    69     /** The HTML rendering pane */ 
    70     private JEditorPane view = null; 
    71     /** The contents tree model */ 
    72     private ContentsModel model = null; 
    73     /** A contents tree for the top of the frame */ 
    74     private JTree contents = null; 
    75  
    76     private JSplitPane split_pane = null; 
     69    /** The help view at the bottom of the frame. */ 
     70    static private JEditorPane help_pane = null; 
     71    /** The help contents tree at the top of the frame. */ 
     72    static private JTree help_contents_tree = null; 
     73    /** The help contents tree model. */ 
     74    static private HelpContentsTreeModel help_contents_tree_model = null; 
     75    /** The split between the contents tree and the page view. */ 
     76    static private JSplitPane split_pane = null; 
    7777 
    7878 
     
    8383    Dictionary.registerText(this, "Help.Title"); 
    8484 
    85     view = new JEditorPane(); 
    86     view.setEditable(false); 
    87     view.addHyperlinkListener(new ViewHyperlinkListener()); 
    88  
    89     HelpItem rootNode = new HelpItem(Dictionary.get("Help.Contents"), NULL_STRING); 
    90     model = new ContentsModel(rootNode); 
    91     contents = new JTree((DefaultTreeModel) model); 
    92     contents.addTreeSelectionListener(new ContentsListener()); 
    93     contents.setExpandsSelectedPaths(true); 
     85    help_pane = new JEditorPane(); 
     86    help_pane.setEditable(false); 
     87    help_pane.addHyperlinkListener(new HelpPaneHyperlinkListener()); 
     88 
     89    HelpContentsTreeNode help_tree_root_node = new HelpContentsTreeNode(null, Dictionary.get("Help.Contents")); 
     90    help_contents_tree_model = new HelpContentsTreeModel(help_tree_root_node); 
     91    help_contents_tree = new JTree((DefaultTreeModel) help_contents_tree_model); 
     92    help_contents_tree.addTreeSelectionListener(new HelpContentsTreeSelectionListener()); 
     93    help_contents_tree.setExpandsSelectedPaths(true); 
    9494 
    9595    // Creation 
    9696    JPanel content_pane = (JPanel) this.getContentPane(); 
    9797    split_pane = new JSplitPane(JSplitPane.VERTICAL_SPLIT); 
    98     JScrollPane index_scroll = new JScrollPane(contents); 
    99     JScrollPane view_scroll = new JScrollPane(view); 
     98    JScrollPane help_contents_tree_scroll = new JScrollPane(help_contents_tree); 
     99    JScrollPane help_pane_scroll = new JScrollPane(help_pane); 
    100100 
    101101    // Layout 
    102     split_pane.add(index_scroll, JSplitPane.LEFT); 
    103     split_pane.add(view_scroll, JSplitPane.RIGHT); 
     102    split_pane.add(help_contents_tree_scroll, JSplitPane.LEFT); 
     103    split_pane.add(help_pane_scroll, JSplitPane.RIGHT); 
    104104    content_pane.setLayout(new BorderLayout()); 
    105105    content_pane.add(split_pane, BorderLayout.CENTER); 
     
    118118    public void destroy() 
    119119    { 
    120     view = null; 
    121     contents = null; 
    122     } 
    123  
    124  
    125     /** Retrieve the full file path to the help index xml file. 
    126      * @return the full path as a String 
    127      */ 
     120    help_contents_tree = null; 
     121    help_pane = null; 
     122    } 
     123 
     124 
     125    /** Retrieve the relative file path to the language-specific help index xml file. */ 
    128126    private String getHelpFolder() 
    129127    { 
    130128    String help_folder = "help/" + Configuration.getLanguage() + "/"; 
    131129 
    132     // Try in the JAR/classes directory first 
    133     URL help_folder_url = JarTools.getResource("/" + help_folder); 
    134     if (help_folder_url != null) { 
     130    // Applet case: get help files out of JAR file 
     131    if (Gatherer.isApplet && JarTools.getResource("/" + help_folder) != null) { 
    135132        return help_folder; 
    136133    } 
    137134 
    138     // Look in the base directory next 
    139     File help_folder_file = new File(help_folder); 
    140     if (help_folder_file.exists()) { 
     135    // Normal case: get help files out of GLI "help" folder 
     136    if (new File(help_folder).exists()) { 
    141137        return help_folder; 
    142138    } 
     
    147143 
    148144 
     145    private URL getURLForSection(String section_name) 
     146    { 
     147    // Form the path to the help file from the section name 
     148    if (section_name != null) { 
     149        String help_file_path = getHelpFolder() + section_name + StaticStrings.HTM_FILE_EXTENSION; 
     150 
     151        try { 
     152        // Applet case: get help file out of JAR file 
     153        if (Gatherer.isApplet) { 
     154            return JarTools.getResource("/" + help_file_path); 
     155        } 
     156 
     157        // Normal case: get help file out of GLI "help" folder 
     158        return (new File(help_file_path)).toURL(); 
     159        } 
     160        catch (Exception exception) { 
     161        DebugStream.printStackTrace(exception); 
     162        } 
     163    } 
     164 
     165    return null; 
     166    } 
     167 
     168 
     169    static private void selectHelpContentsTreeNode(String section_name) 
     170    { 
     171    // Find the tree node with this section name, then select it 
     172    selectHelpContentsTreeNode(help_contents_tree_model.getHelpContentsTreeNodeNamed(section_name)); 
     173    } 
     174 
     175 
     176    static private void selectHelpContentsTreeNode(HelpContentsTreeNode help_tree_node) 
     177    { 
     178    // Ensure the node in the help contents tree is selected and visible 
     179    TreePath help_tree_node_path = new TreePath(help_tree_node.getPath()); 
     180    help_contents_tree.setSelectionPath(help_tree_node_path); 
     181    help_contents_tree.scrollPathToVisible(help_tree_node_path); 
     182    } 
     183 
     184 
    149185    static public void setView(String section_name) 
    150186    { 
    151     self.setViewInternal(section_name); 
    152     } 
    153  
    154  
    155     public void setViewInternal(String sectionName) 
    156     { 
    157     // Find the node in the tree with the specified sectionName 
    158     HelpItem node = model.getHelpItemNamed(sectionName); 
    159  
    160     // Ensure the node is selected and visible 
    161     TreePath path = new TreePath(node.getPath()); 
    162     contents.setSelectionPath(path); 
    163     contents.scrollPathToVisible(path); 
    164  
     187    // Select the appropriate node in the help contents tree 
     188    selectHelpContentsTreeNode(section_name); 
     189 
     190    // Show the help page with the specified section name 
     191    self.showHelpPage(section_name); 
     192    } 
     193 
     194 
     195    private void showHelpPage(String section_name) 
     196    { 
     197    // Find the tree node with this section name, then show the page for the node 
     198    showHelpPage(getURLForSection(section_name)); 
     199    } 
     200 
     201 
     202    private void showHelpPage(URL help_page_url) 
     203    { 
    165204    // Display the selected page 
    166     URL url = node.getURL(); 
    167     if (url != null) { 
     205    if (help_page_url != null) { 
    168206        try { 
    169         view.setPage(url); 
     207        help_pane.setPage(help_page_url); 
    170208        } 
    171209        catch (Exception exception) { 
     
    180218 
    181219 
    182     private class ContentsModel 
    183     extends DefaultTreeModel { 
    184  
    185     public ContentsModel(MutableTreeNode rootNode) { 
    186         super(rootNode); 
    187  
    188         // Load the XML help file and build the contents structure from it 
     220    private class HelpContentsTreeModel 
     221    extends DefaultTreeModel 
     222    { 
     223    public HelpContentsTreeModel(MutableTreeNode help_tree_root_node) 
     224    { 
     225        super(help_tree_root_node); 
     226 
     227        // Load the XML help index file and build the contents structure from it 
    189228        try { 
    190         String help_index = getHelpFolder() + StaticStrings.HELP_INDEX_FILENAME; 
    191         Document document = XMLTools.parseXMLFile(help_index, true); 
    192  
    193         // Traverse the document hierarchy, building a tree representing its structure 
    194         Node documentNode = document.getFirstChild(); 
    195  
    196         int sectionNum = 0; 
    197         NodeList children = documentNode.getChildNodes(); 
     229        String help_index_file_path = getHelpFolder() + "help_index.xml"; 
     230        Document document = XMLTools.parseXMLFile(help_index_file_path, true); 
     231 
     232        // Traverse the help hierarchy, building a tree representing its structure 
     233        Node document_node = document.getFirstChild(); 
     234 
     235        // Add a help contents tree node for each major section 
     236        int section_number = 0; 
     237        NodeList children = document_node.getChildNodes(); 
    198238        for (int i = 0; i < children.getLength(); i++) { 
    199239            Node child = children.item(i); 
    200240            if (child.getNodeName().equals(StaticStrings.SECTION_ELEMENT)) { 
    201             sectionNum++; 
    202             buildContentsHierarchy(rootNode, sectionNum + StaticStrings.EMPTY_STR, child); 
     241            section_number++; 
     242            buildHelpContentsTree(help_tree_root_node, section_number + StaticStrings.EMPTY_STR, child); 
    203243            } 
    204244        } 
    205245        } 
    206         catch (Exception ex) { 
    207         ex.printStackTrace(); 
    208         } 
    209     } 
    210  
    211  
    212     public void buildContentsHierarchy(MutableTreeNode parent, String pos, Node node) 
     246        catch (Exception exception) { 
     247        DebugStream.printStackTrace(exception); 
     248        } 
     249    } 
     250 
     251 
     252    private void buildHelpContentsTree(MutableTreeNode parent, String pos, Node node) 
    213253    { 
    214254        // Determine the section name 
    215         String sectionName = ((Element) node).getAttribute(StaticStrings.NAME_ATTRIBUTE); 
     255        String section_name = ((Element) node).getAttribute(StaticStrings.NAME_ATTRIBUTE); 
    216256 
    217257        // Determine the section title 
    218         String sectionTitle = ""; 
     258        String section_title = ""; 
    219259        NodeList children = node.getChildNodes(); 
    220260        for (int i = 0; i < children.getLength(); i++) { 
    221261        Node child = children.item(i); 
    222262        if (child.getNodeName().equals(StaticStrings.TITLE_ELEMENT)) { 
    223             sectionTitle = pos + ": "; 
     263            section_title = pos + ": "; 
    224264            if (child.getFirstChild() != null) { 
    225             sectionTitle = sectionTitle + child.getFirstChild().getNodeValue(); 
     265            section_title += child.getFirstChild().getNodeValue(); 
    226266            } 
    227267        } 
     
    229269 
    230270        // Add the node into the tree 
    231         HelpItem item = new HelpItem(sectionTitle, sectionName); 
    232         insertNodeInto(item, parent, parent.getChildCount()); 
     271        HelpContentsTreeNode help_tree_node = new HelpContentsTreeNode(section_name, section_title); 
     272        insertNodeInto(help_tree_node, parent, parent.getChildCount()); 
    233273 
    234274        // Apply recursively to the children of this node 
    235         int sectionNum = 0; 
     275        int section_number = 0; 
    236276        for (int i = 0; i < children.getLength(); i++) { 
    237277        Node child = children.item(i); 
    238278        if (child.getNodeName().equals(StaticStrings.SECTION_ELEMENT)) { 
    239             sectionNum++; 
    240             buildContentsHierarchy(item, pos + StaticStrings.STOP_CHARACTER + sectionNum, child); 
    241         } 
    242         } 
    243     } 
    244  
    245  
    246     public HelpItem getHelpItemNamed(String sectionName) 
    247     { 
    248         // Find the node with name matching sectionName, somewhere in the tree 
    249         Enumeration descendants = ((DefaultMutableTreeNode) root).preorderEnumeration(); 
    250         while (descendants.hasMoreElements()) { 
    251         HelpItem node = (HelpItem) descendants.nextElement(); 
    252         if (node.name.equals(sectionName)) { 
    253             return node; 
     279            section_number++; 
     280            buildHelpContentsTree(help_tree_node, pos + StaticStrings.STOP_CHARACTER + section_number, child); 
     281        } 
     282        } 
     283    } 
     284 
     285 
     286    private HelpContentsTreeNode getHelpContentsTreeNodeNamed(String section_name) 
     287    { 
     288        // Find the node with name matching section name, somewhere in the tree 
     289        if (section_name != null) { 
     290        Enumeration descendants = ((DefaultMutableTreeNode) root).preorderEnumeration(); 
     291        while (descendants.hasMoreElements()) { 
     292            HelpContentsTreeNode help_tree_node = (HelpContentsTreeNode) descendants.nextElement(); 
     293            if (section_name.equals(help_tree_node.section_name)) { 
     294            return help_tree_node; 
     295            } 
    254296        } 
    255297        } 
    256298 
    257299        // Couldn't be found, so just return the root (Contents) node 
    258         return (HelpItem) root; 
     300        return (HelpContentsTreeNode) root; 
    259301    } 
    260302    } 
     
    264306     * to show the appropriate page as required. 
    265307     */ 
    266     private class ContentsListener 
    267     implements TreeSelectionListener { 
    268  
     308    private class HelpContentsTreeSelectionListener 
     309    implements TreeSelectionListener 
     310    { 
    269311    /** Any implementation of <i>TreeSelectionListener</i> must include this method so we can be informed when the tree selection changes. 
    270312     * @param event A <strong>TreeSelectionEvent</strong> containing al the relevant information about the event itself. 
     
    272314    public void valueChanged(TreeSelectionEvent event) 
    273315    { 
    274         TreePath path = event.getPath(); 
    275         HelpItem node = (HelpItem) path.getLastPathComponent(); 
    276         URL url = node.getURL(); 
    277         if (url != null) { 
    278         try { 
    279             view.setPage(url); 
    280         } 
    281         catch (Exception exception) { 
    282             DebugStream.printStackTrace(exception); 
    283         } 
    284         } 
     316        HelpContentsTreeNode help_tree_node = (HelpContentsTreeNode) event.getPath().getLastPathComponent(); 
     317        selectHelpContentsTreeNode(help_tree_node); 
     318        showHelpPage(help_tree_node.section_name); 
    285319    } 
    286320    } 
     
    290324     * provides the ability to set an html page to be loaded when this node is selected. 
    291325     */ 
    292     private class HelpItem  
    293     extends DefaultMutableTreeNode { 
    294  
     326    private class HelpContentsTreeNode  
     327    extends DefaultMutableTreeNode 
     328    { 
    295329    /** The unique name of the section (matches the HTML filename) */ 
    296     public String name = null; 
     330    public String section_name = null; 
    297331    /** The title to be displayed for this tree node. */ 
    298     public String title = null; 
    299  
    300  
    301     /** Constructor. 
    302      * @param title The title to be shown for this node as a <strong>String</strong>. 
    303      * @param name The name of the section as a <strong>String</strong>. 
    304      */ 
    305     public HelpItem(String title, String name) 
    306     { 
    307         this.name = name; 
    308         this.title = title; 
    309     } 
    310  
    311  
    312     /** Method to create a url from the file name. 
    313      * @return A <strong>URL</strong> that points to the file's location. 
    314      */ 
    315     public URL getURL() 
    316     { 
    317         URL url = null; 
    318  
    319         if (name != null && !name.equals("") && !name.equals(NULL_STRING)) { 
    320         String help_file_path = getHelpFolder() + name + StaticStrings.HTM_FILE_EXTENSION; 
    321         File help_file = new File(Gatherer.getGLIDirectoryPath() + help_file_path); 
    322         if (Gatherer.isGsdlRemote) { 
    323             help_file = new File(Gatherer.getGLIUserDirectoryPath() + help_file_path); 
    324         } 
    325         try { 
    326             url = help_file.toURL(); 
    327         } 
    328         catch (Exception exception) { 
    329             DebugStream.printStackTrace(exception); 
    330         } 
    331         } 
    332  
    333         return url; 
    334     } 
    335  
     332    public String section_title = null; 
     333 
     334    public HelpContentsTreeNode(String section_name, String section_title) 
     335    { 
     336        this.section_name = section_name; 
     337        this.section_title = section_title; 
     338    } 
    336339 
    337340    public String toString() 
    338341    { 
    339         return title; 
    340     } 
    341     } 
    342  
    343  
    344     private class ViewHyperlinkListener 
    345     implements HyperlinkListener { 
    346     public void hyperlinkUpdate(HyperlinkEvent e) { 
    347         if(e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) { 
    348         try { 
    349             view.setPage(e.getURL()); 
    350         } 
    351         catch(Exception exception) { 
    352             DebugStream.printStackTrace(exception); 
    353         } 
     342        return section_title; 
     343    } 
     344    } 
     345 
     346 
     347    private class HelpPaneHyperlinkListener 
     348    implements HyperlinkListener 
     349    { 
     350    public void hyperlinkUpdate(HyperlinkEvent e) 
     351    { 
     352        if (e.getEventType() == HyperlinkEvent.EventType.ACTIVATED) { 
     353        // Determine which node in the help contents tree to select, then select it 
     354        String section_link = e.getURL().getFile(); 
     355        if (section_link.endsWith(".htm")) { 
     356            section_link = section_link.substring(section_link.lastIndexOf("/") + 1); 
     357            section_link = section_link.substring(0, section_link.length() - ".htm".length()); 
     358            selectHelpContentsTreeNode(section_link); 
     359        } 
     360 
     361        // Change to the page specified by the link 
     362        showHelpPage(e.getURL()); 
    354363        } 
    355364    }