/*
This file is part of the software framework JStatCom,
a library for building applications for data based analysis.
Copyright (C) 2000-2005 Markus Kraetzig
This library is free software; you can redistribute it and/or modify
it under the terms of the GNU Lesser General Public License as
published by the Free Software Foundation; either version 2.1 of the
License, or (at your option) any later version.
This library 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
Lesser General Public License for more details.
You should have received a copy of the GNU Lesser General Public
License along with this library; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307
USA
*/
package com.jstatcom.component;
import java.awt.Dimension;
import java.awt.Point;
import java.awt.event.ActionEvent;
import java.net.URL;
import java.util.List;
import javax.help.CSH;
import javax.help.HelpBroker;
import javax.help.HelpSet;
import javax.help.InvalidHelpSetContextException;
import javax.help.Map;
import javax.swing.AbstractAction;
import javax.swing.Icon;
import javax.swing.JLabel;
import javax.swing.KeyStroke;
import org.apache.log4j.Logger;
import EDU.oswego.cs.dl.util.concurrent.misc.SwingWorker;
/**
* Copyright (c) 2003 Markus Kratzig. All Rights Reserved.
*
* Markus Kratzig makes no representations or warranties about the fitness of
* this software for any particular purpose, including the implied warranty of
* merchantability.
*/
/**
* This class provides an AbstractAction that is geared towards
* supporting the creation and display of JavaHelp sets. It
* should be constructed via the get*Instance static factory
* methods that create instances of this class with slightly different
* behaviour.
*
* Usage note:
* Because usually there is only one helpset loaded in an application, the
* HelpBroker is static and needs to be
* constructed first. Therefore the startHelpWorker method must
* be invoked before any help action can be carried out. It takes the name of
* the helpset as an argument and constructs the HelpBroker in a
* worker thread. This should be done at program start.
*
*
* @author Markus Kraetzig
*/
public class JHelpAction extends AbstractAction {
private static final Logger log = Logger.getLogger(JHelpAction.class);
private static String helpSetName = null;
private static final ActionEvent cshAction = new ActionEvent(new JLabel(),
ActionEvent.ACTION_FIRST, null);
private static HelpBroker helpBroker = null;
private static WorkerHelpset worker = null;
private final static class WorkerHelpset extends SwingWorker {
private static Point loc = new Point(220, 0);
private static Dimension dimension = new Dimension(700, 600);
private final String helpSetName;
private HelpBroker mainHelpBroker = null;
private String[] mergeSets = null;
public WorkerHelpset(String helpSetName, String[] mergeSets) {
this.helpSetName = helpSetName;
this.mergeSets = mergeSets;
}
public synchronized Object construct() {
if (mainHelpBroker == null) {
try {
// : modified for Web Start
URL hsURL = HelpSet.findHelpSet(this.getClass()
.getClassLoader(), helpSetName);
HelpSet mainHelpSet = new HelpSet(null, hsURL);
if (mergeSets != null)
for (int i = 0; i < mergeSets.length; i++) {
try {
URL hsMergeURL = HelpSet.findHelpSet(this
.getClass().getClassLoader(),
mergeSets[i]);
HelpSet mergeHelpSet = new HelpSet(null,
hsMergeURL);
mainHelpSet.add(mergeHelpSet);
} catch (Throwable ex) {
log.error("Helpset \"" + mergeSets[i]
+ "\" could not be created.\n"
+ ex.getMessage());
}
}
mainHelpBroker = mainHelpSet.createHelpBroker();
} catch (Throwable ee) {
log.error("\nHelpSet " + helpSetName + " not created.\n"
+ ee.getMessage());
return null;
}
mainHelpBroker.setLocation(loc);
mainHelpBroker.setSize(dimension);
}
return mainHelpBroker;
}
public Object get() {
return construct();
}
}
/**
* JHelpViewerAction constructor not to be invoked.
*/
private JHelpAction() {
super();
}
/**
* JHelpViewerAction constructor, use static factories
* instead.
*
* @param name
* the name of the action
*/
protected JHelpAction(String name) {
super(name);
}
/**
* JHelpViewerAction constructor, use static factories
* instead.
*
* @param name
* the name of the action
* @param icon
* the icon to display in a component
*/
protected JHelpAction(String name, Icon icon) {
super(name, icon);
}
/**
* Action method that is invoked, when an action event is catched.
*
* @param evt
* the action event
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
public void actionPerformed(java.awt.event.ActionEvent evt) {
showHelp();
}
/**
* Gets an instance of this class that invokes
* showHelpFromFocus in its actionPerformed
* method. When this action is invoked, the helptopic for the component that
* currently has focus is displayed, given that it has a valid
* helpID.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getFocusInstance(String name) {
return new JHelpAction(name) {
public void actionPerformed(ActionEvent evt) {
showHelpFromFocus();
}
};
}
/**
* Same usage as {@link #getFocusInstance(String name)} but with an icon.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
* @param icon
* the icon to be displayed by components accepting this action
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getFocusInstance(String name, Icon icon) {
return new JHelpAction(name, icon) {
public void actionPerformed(ActionEvent evt) {
showHelpFromFocus();
}
};
}
/**
* Gets instance of broker object and ensures that it is initialized.
*
* @return help broker object or null if it could not be
* initialized
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
private static HelpBroker getHelpBroker() {
if (helpSetName == null)
throw new IllegalStateException(
"Name of helpset has not yet been set.");
if (helpBroker == null) {
Object o = worker.get();
if (o instanceof HelpBroker)
helpBroker = (HelpBroker) o;
}
// HelpBroker still null, creation failed.
if (helpBroker == null)
throw new IllegalStateException("HelpBroker has not been created.");
return helpBroker;
}
/**
* Gets an instance of this class that invokes showHelp in
* its actionPerformed method.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getShowHelpInstance(String name) {
JHelpAction action = new JHelpAction(name);
action.putValue(ACCELERATOR_KEY, KeyStroke.getKeyStroke("F1"));
return action;
}
/**
* Same usage as {@link #getShowHelpInstance(String name)} but with an icon.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
* @param icon
* the icon to be displayed by components accepting this action
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getShowHelpInstance(String name, Icon icon) {
JHelpAction action = new JHelpAction(name, icon);
action.putValue(ACCELERATOR_KEY, KeyStroke.getKeyStroke("F1"));
return action;
}
/**
* Gets an instance of this class that invokes showHelp(helpID)
* in its actionPerformed method. When this action is
* invoked, the helptopic associated with helpID is
* displayed.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
* @param helpID
* the identifier for the helptopic to display, must be a valid
* target, for example html.var_modeling
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getShowIDInstance(String name, final String helpID) {
return new JHelpAction(name) {
public void actionPerformed(ActionEvent evt) {
showHelp(helpID);
}
};
}
/**
* Same usage as {@link #getShowIDInstance(String name, String helpID)} but
* with an icon.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
* @param icon
* the icon to be displayed by components accepting this action
* @param helpID
* the identifier for the helptopic to display, must be a valid
* target, for example html.var_modeling
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getShowIDInstance(String name, Icon icon,
final String helpID) {
return new JHelpAction(name, icon) {
public void actionPerformed(ActionEvent evt) {
showHelp(helpID);
}
};
}
/**
* Gets an instance of this class that invokes trackFieldHelp
* in its actionPerformed method. When this action is
* invoked, the helptopic for the component that is clicked on next is
* displayed, given that it has a valid helpID. The mouse
* pointer changes during that operation. This is useful for displaying
* context sensitive help.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getTrackInstance(String name) {
JHelpAction action = new JHelpAction(name) {
public void actionPerformed(ActionEvent evt) {
trackFieldHelp();
}
};
action.putValue(ACCELERATOR_KEY, KeyStroke.getKeyStroke("control F1"));
return action;
}
/**
* Same usage as {@link #getTrackInstance(String name)} but with an icon.
*
* @param name
* the name of the action, usually displayed as text in
* components accepting AbstractAction objects
* @param icon
* the icon to be displayed by components accepting this action
*
* @return initialized action object that displays the helpset set by
* startHelpWorker
*/
public static JHelpAction getTrackInstance(String name, Icon icon) {
JHelpAction action = new JHelpAction(name, icon) {
public void actionPerformed(ActionEvent evt) {
trackFieldHelp();
}
};
action.putValue(ACCELERATOR_KEY, KeyStroke.getKeyStroke("control F1"));
return action;
}
/**
* Shows the helpset that has been initialized via
* startHelpWorker.
*
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
public static void showHelp() {
if (helpBroker == null) {
if (getHelpBroker() != null)
new CSH.DisplayHelpFromSource(helpBroker)
.actionPerformed(cshAction);
} else
helpBroker.setDisplayed(true);
return;
}
/**
* Shows the topic associated with target in the helpset that
* has been initialized via startHelpWorker.
*
* @param target
* the help ID to display
*
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
public static void showHelp(String target) {
showHelp();
if (target != null)
try {
if (getHelpBroker() != null)
getHelpBroker().setCurrentID(
Map.ID.create(target, helpBroker.getHelpSet()));
} catch (InvalidHelpSetContextException ee) {
log.error("Invalid helpset for target \"" + target + "\"", ee);
}
}
/**
* Shows the topic associated with the component that currently has focus in
* the helpset that has been initialized via startHelpWorker.
* If the component does not have a valid help ID, the default topic is
* displayed.
*
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
public static void showHelpFromFocus() {
if (getHelpBroker() != null)
new CSH.DisplayHelpFromFocus(helpBroker).actionPerformed(cshAction);
}
/**
* Creates a worker thread to initialize a HelpBroker object
* for a helpset specified by hSetName.
*
* This method should be called at program start to prepare the helpset for
* display. Usually it should only be called once. All other methods rely on
* the availability of the HelpBroker object created by this
* method.
*
* this method.
*
* @param hSetName
* the name of the helpset to statically initialize
* JHelpAction with, must be a valid filename that
* can be transformed to a URL, usually stated
* relative to the resource directory of this class
* @throws IllegalArgumentException
* if (hSetName == null)
*/
public static void startHelpWorker(String hSetName) {
if (hSetName == null)
throw new IllegalArgumentException("Helpset name was null.");
helpSetName = hSetName;
worker = new WorkerHelpset(helpSetName, null);
worker.start();
}
/**
* Creates a worker thread to initialize a HelpBroker object
* for a helpsets contained in helpSetList. All helpsets are
* merged dynamically.
*
* This method should be called at program start to prepare the helpset for
* display. Usually it should only be called once. All other methods rely on
* the availability of the HelpBroker object created by this
* method.
*
* @param helpSetList
* the list containing all helpsets to merge and load
* @throws IllegalArgumentException
* if (helpSetList == null)
*/
public static void startHelpWorker(List helpSetList) {
if (helpSetList == null)
throw new IllegalArgumentException("Helpset list was null.");
if (helpSetList.size() == 0)
return;
for (int i = 0; i < helpSetList.size(); i++)
if (helpSetList.get(i) == null)
throw new IllegalArgumentException(
"Helpset list contains null elements.");
helpSetName = helpSetList.get(0).toString();
if (helpSetList.size() == 1) {
startHelpWorker(helpSetList.get(0).toString());
return;
}
String[] hSetArray = new String[helpSetList.size() - 1];
for (int i = 1; i < helpSetList.size(); i++)
hSetArray[i - 1] = helpSetList.get(i).toString();
worker = new WorkerHelpset(helpSetName, hSetArray);
worker.start();
}
/**
* Shows the topic associated with the component that is clicked on with the
* mouse in the helpset that has been initialized via
* startHelpWorker. If the component does not have a valid
* help ID, the default topic is displayed. This operation is useful for
* implementing context sensitive help.
*
* @throws IllegalStateException
* if HelpBroker was not initialized via
* startHelpWorker before
*/
public static void trackFieldHelp() {
if (getHelpBroker() != null)
new CSH.DisplayHelpAfterTracking(helpBroker)
.actionPerformed(cshAction);
}
}
Ads help maintain this website.