manualviewer.java

The ElectricTM VLSI Design System is an open-source Electronic Design Automation (EDA) system that c

/* -*- tab-width: 4 -*-
 *
 * Electric(tm) VLSI Design System
 *
 * File: ManualViewer.java
 *
 * Copyright (c) 2004 Sun Microsystems and Static Free Software
 *
 * Electric(tm) is free software; you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation; either version 3 of the License, or
 * (at your option) any later version.
 *
 * Electric(tm) is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with Electric(tm); see the file COPYING.  If not, write to
 * the Free Software Foundation, Inc., 59 Temple Place, Suite 330,
 * Boston, Mass 02111-1307, USA.
 */
package com.sun.electric.tool.user.help;

import com.sun.electric.Main;
import com.sun.electric.database.hierarchy.Cell;
import com.sun.electric.database.hierarchy.Library;
import com.sun.electric.database.text.TextUtils;
import com.sun.electric.database.topology.NodeInst;
import com.sun.electric.tool.Job;
import com.sun.electric.tool.io.FileType;
import com.sun.electric.tool.user.ActivityLogger;
import com.sun.electric.tool.user.Resources;
import com.sun.electric.tool.user.dialogs.EDialog;
import com.sun.electric.tool.user.dialogs.EModelessDialog;
import com.sun.electric.tool.user.dialogs.OpenFile;
import com.sun.electric.tool.user.menus.EMenu;
import com.sun.electric.tool.user.menus.EMenuBar;
import com.sun.electric.tool.user.menus.EMenuItem;
import com.sun.electric.tool.user.menus.FileMenu;
import com.sun.electric.tool.user.ui.TopLevel;
import com.sun.electric.tool.user.ui.WindowFrame;

import java.awt.Dimension;
import java.awt.Frame;
import java.awt.GridBagConstraints;
import java.awt.GridBagLayout;
import java.awt.Insets;
import java.awt.Toolkit;
import java.awt.event.ActionEvent;
import java.awt.event.ActionListener;
import java.awt.event.MouseEvent;
import java.awt.event.MouseListener;
import java.awt.event.WindowAdapter;
import java.awt.event.WindowEvent;
import java.io.BufferedWriter;
import java.io.FileWriter;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.io.LineNumberReader;
import java.io.PrintWriter;
import java.io.UnsupportedEncodingException;
import java.lang.reflect.Method;
import java.net.URL;
import java.net.URLConnection;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.HashSet;
import java.util.Iterator;
import java.util.List;
import java.util.Set;
import java.util.regex.Matcher;
import java.util.regex.Pattern;

import javax.swing.JButton;
import javax.swing.JEditorPane;
import javax.swing.JFrame;
import javax.swing.JMenu;
import javax.swing.JMenuBar;
import javax.swing.JMenuItem;
import javax.swing.JPanel;
import javax.swing.JScrollPane;
import javax.swing.JSeparator;
import javax.swing.JSplitPane;
import javax.swing.JTextArea;
import javax.swing.JTextField;
import javax.swing.JTree;
import javax.swing.event.HyperlinkEvent;
import javax.swing.event.HyperlinkListener;
import javax.swing.text.DefaultEditorKit;
import javax.swing.text.html.HTMLDocument;
import javax.swing.text.html.HTMLEditorKit;
import javax.swing.text.html.HTMLFrameHyperlinkEvent;
import javax.swing.tree.DefaultMutableTreeNode;
import javax.swing.tree.DefaultTreeModel;
import javax.swing.tree.TreePath;
import javax.swing.tree.TreeSelectionModel;

/**
 * A Dialog for displaying the Electric users manual.
 *
 * The html files in the user's manual have special lines that control them:
 * <!-- HEADER 1-2: Chapter Title -->
 * <!-- COMMAND Menu/Command -->
 * <!-- PREFERENCE Section/Panel -->
 * <!-- PROJECTSETTING Panel -->
 * <!-- NEED 2in -->
 * <!-- TRAILER -->
 */
public class ManualViewer extends EModelessDialog
{
	private static final String RUSSIANMANUALPATH = "plugins/manualRussian";

	/** the menus that are not checked */
	public static Set<String> excludeMenu = new HashSet<String>();
	static
	{
		excludeMenu.add("Sun");
		excludeMenu.add("Test");
		excludeMenu.add("Steve");
		excludeMenu.add("Russell");
		excludeMenu.add("JonG");
		excludeMenu.add("Gilda");
		excludeMenu.add("Dima");
		excludeMenu.add("Kon");
		excludeMenu.add("Frankie");
		excludeMenu.add("Dinesh");
	}

	private static class PageInfo
	{
		String title;
		String fileName;
		String chapterName;
		String fullChapterNumber;
		int chapterNumber;
		int sectionNumber;
		URL url;
		int level;
		boolean newAtLevel;
	};

	private Class htmlBaseClass;
	private String htmlDirectory;
	private JScrollPane rightHalf;
	private JEditorPane editorPane;
	private JSplitPane splitPane;
	private JTextField searchField;
	private JTree manualTree;
	private DefaultMutableTreeNode rootNode;
	private List<PageInfo> pageSequence;
	private List<DefaultMutableTreeNode> pageNodeSequence;
	private int currentIndex;
	private boolean menubarShown = false;
	private static int lastPageVisited = 0;
	private static HashMap<String,String> menuMap = null;
	private static HashMap<String,String> keywordMap = null;
	private List<Object> history = new ArrayList<Object>();
	private static ManualViewer theManual = null;

    private static void setManualViewer(String preference, Class baseClass, String htmlDir, boolean setVisible)
    {
        if (theManual == null)
        {
            JFrame jf = null;
            if (TopLevel.isMDIMode()) jf = TopLevel.getCurrentJFrame();
            try{
                theManual = new ManualViewer(jf, preference, baseClass, htmlDir);
            }
            catch (Exception e)
            {
                System.out.println("Error creating the ManualViewer");
                theManual = null;
            }
        }
        if (theManual != null && setVisible)
            theManual.setVisible(true);
    }
    
    /**
	 * Method to display the user's manual.
	 */
	public static void userManualCommand()
	{
        setManualViewer(null, ManualViewer.class, "helphtml", true);
	}

	/**
	 * Method to tell whether there is a Russian user's manual installed.
	 * @return true if the Russian user's manual is available.
	 */
	public static boolean hasRussianManual()
	{
		URL url = Main.class.getResource(RUSSIANMANUALPATH + "/toc.txt");
		return url != null;
	}

	/**
	 * Method to display the Russian user's manual.
	 */
	public static void userManualRussianCommand()
	{
        setManualViewer(null, Main.class, RUSSIANMANUALPATH, true);
	}

	/**
	 * Method to show the help page for a particular panel in the "Preferences" dialog.
	 * @param preference the panel name, of the form "section/panel".
	 * For example, the "CIF" panel in the "I/O" section will be named "I/O/CIF".
	 */
	public static void showPreferenceHelp(String preference)
	{
		showSettingHelp("PREF", preference);
	}

	/**
	 * Method to show the help page for a particular panel in the "Project Settings" dialog.
	 * @param preference the panel name, of the form "section/panel".
	 * For example, the "CIF" panel in the "I/O" section will be named "I/O/CIF".
	 */
	public static void showProjectSettingHelp(String preference)
	{
		showSettingHelp("PROJ", preference);
	}

	/**
	 * Internal method to show Preferences or Project Settings help.
	 * @param str the help page requested.
	 */
	private static void showSettingHelp(String dialog, String str)
	{
        setManualViewer(dialog+str, ManualViewer.class, "helphtml", false);
        if (theManual == null)
            return; // error
        if (str != null)
        {
            String prefFileName = keywordMap.get(dialog+str);
            if (prefFileName == null)
            {
                Job.getUserInterface().showErrorMessage("No help for " + str + " settings", "Missing documentation");
            } else
            {
                for(int i=0; i<theManual.pageSequence.size(); i++)
                {
                    PageInfo pi = theManual.pageSequence.get(i);
                    if (pi.fileName.equals(prefFileName))
                    {
                        theManual.loadPage(i);
                        break;
                    }
                }
            }
        }
		theManual.setVisible(true);
	}

	/**
	 * Method to open the 2D view of a given layout cell
	 * @param fileName name of the library where the cell is stored
	 * @param cellName cell name
	 * @param menuName name of the menu executing this command
	 */
	public static Cell open2DSample(String fileName, String cellName, String menuName)
	{
		Library library = Library.findLibrary(fileName);
		if (library == null)
		{
			System.out.println("Load first the library '" + fileName +
				"' (Help -> " + menuName + " -> Load Library)");
			return null;
		}
		Cell cell = library.findNodeProto(cellName);
		if (cell == null)
		{
			System.out.println("Cell '" + cellName + "' not found");
			return null;
		}

		// Open the window frame if not available
		if (cell != WindowFrame.getCurrentCell())
			WindowFrame.createEditWindow(cell);
		return cell;
	}

	/**
	 * Method to open the 3D view of a given layout cell
	 * @param fileName name of the library where the cell is stored
	 * @param cellName cell name
	 */
	public static void open3DSample(String fileName, String cellName, String menuName)
	{
		Cell cell = open2DSample(fileName, cellName, menuName);

		if (cell == null) return; // error opening the 2D view

		// Making sure all cell instances are expanded
		for (Iterator<NodeInst> it = cell.getNodes(); it.hasNext();)
		{
			NodeInst ni = it.next();
			ni.setExpanded();
		}

		// to guarantee the redisplay with extended
		Class<?> plugin3D = Resources.get3DClass("ui.J3DMenu");
		if (plugin3D != null)
		{
			// Adding 3D/Demo menu
			try {
				Method createMethod = plugin3D.getDeclaredMethod("create3DViewCommand", new Class[] {Boolean.class});
				createMethod.invoke(plugin3D, new Object[] {Boolean.FALSE});
			} catch (Exception e)
			{
				System.out.println("Can't open 3D view: " + e.getMessage());
				ActivityLogger.logException(e);
			}
		}
	}

	/**
	 * Method to animate the 3D view of current layout cell
	 * @param demoName name of j3d file containing the demo
	 */
	public static void animate3DSample(String demoName)
	{
		String fileName = "helphtml/" + demoName;
		URL url = ManualViewer.class.getResource(fileName);
		if (url == null)
		{
			System.out.println("Can't open 3D demo file '" + fileName + "'");
			return;
		}
		Class<?> plugin3D = Resources.get3DClass("ui.J3DDemoDialog");
		if (plugin3D != null)
		{
			// Adding 3D/Demo menu
			try {
				Method createMethod = plugin3D.getDeclaredMethod("create3DDemoDialog",
					new Class[] {java.awt.Frame.class, URL.class});
				createMethod.invoke(plugin3D, new Object[] {TopLevel.getCurrentJFrame(), url});
			} catch (Exception e)
			{
				System.out.println("Can't open 3D demo dialog: " + e.getMessage());
				ActivityLogger.logException(e);
			}
		}
	}

	/**
	 * Method to load a sample library from the lib area.
	 * @param fileName library name
	 */
	public static void loadSamplesLibrary(String fileName, String cellName)
	{
		Library lib = Library.findLibrary(fileName);
		if (lib != null)
		{
			System.out.println(lib + " already loaded");
			Cell cell = lib.findNodeProto(cellName);
			if (cell == null)
				System.out.println("Cell '" + cellName + "' does not exist in " + lib);
			return;
		}
		URL url = ManualViewer.class.getResource("helphtml/"+fileName+".jelib");
		new FileMenu.ReadLibrary(url, FileType.JELIB, cellName);
	}

	/**
	 * Create a new user's manual dialog.
	 * @param parent
	 */
	private ManualViewer(Frame parent, String preference, Class baseClass, String htmlDir) throws Exception
	{
		super(parent, false);
		htmlBaseClass = baseClass;
		htmlDirectory = htmlDir;
		pageSequence = new ArrayList<PageInfo>();
		pageNodeSequence = new ArrayList<DefaultMutableTreeNode>();
		setTitle("User's Manual");
		init();

		// load indices
		loadPointers();
		String prefFileName = null;
		if (preference != null)
		{
			prefFileName = keywordMap.get(preference);
			if (prefFileName == null)
				Job.getUserInterface().showErrorMessage("No help for " + preference + " settings", "Missing documentation");
		}

		// load the table of contents
		String indexName = htmlDirectory + "/toc.txt";
		URL url = htmlBaseClass.getResource(indexName);
		InputStream stream = TextUtils.getURLStream(url, null);
		if (stream == null)
		{
            String msg = "Can't open " + indexName + " in " + htmlBaseClass.getPackage();
            Job.getUserInterface().showErrorMessage(msg, "Missing documentation");
            System.out.println(msg);
			return;
		}
		InputStreamReader is = new InputStreamReader(stream);
		DefaultMutableTreeNode [] stack = new DefaultMutableTreeNode[20];
		stack[0] = rootNode;
		boolean newAtLevel = false;
		String chapterName = null;
		int chapterNumber = 0;
		int [] sectionNumbers = new int[5];
		sectionNumbers[0] = -1;
		currentIndex = lastPageVisited;
		DefaultMutableTreeNode thisNode = null;
		for(;;)
		{
			String line = getLine(is);
			if (line == null) break;
			if (line.length() == 0) continue;
			int indent = 0;
			for(;;)
			{
				if (indent >= line.length() || line.charAt(indent) != ' ') break;