javax.help.JHelp Maven / Gradle / Ivy
/*
* @(#) JHelp.java 1.77 - last change made 09/15/04
*
* Copyright (c) 1997 Sun Microsystems, Inc. All Rights Reserved.
*
* This software is the confidential and proprietary information of Sun
* Microsystems, Inc. ("Confidential Information"). You shall not
* disclose such Confidential Information and shall use it only in
* accordance with the terms of the license agreement you entered into
* with Sun.
*
* SUN MAKES NO REPRESENTATIONS OR WARRANTIES ABOUT THE SUITABILITY OF THE
* SOFTWARE, EITHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
* IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
* PURPOSE, OR NON-INFRINGEMENT. SUN SHALL NOT BE LIABLE FOR ANY DAMAGES
* SUFFERED BY LICENSEE AS A RESULT OF USING, MODIFYING OR DISTRIBUTING
* THIS SOFTWARE OR ITS DERIVATIVES.
*/
package javax.help;
import java.net.URL;
import javax.swing.JComponent;
import javax.swing.UIManager;
import javax.swing.LookAndFeel;
import javax.accessibility.*;
import java.util.Vector;
import java.util.Enumeration;
import java.util.EventListener;
import java.util.Locale;
import java.io.InputStream;
import java.beans.PropertyChangeEvent;
import java.beans.PropertyChangeListener;
import javax.help.plaf.HelpUI;
import javax.help.event.HelpSetListener;
import javax.help.event.HelpSetEvent;
import javax.help.Map.ID;
/**
* Displays HelpSet data with navigators and a content viewer.
*
* @author Roger D. Brinkley
* @author Eduardo Pelegri-Llopart
* @author Stepan Marek
* @author Richard Gregor
* @version 1.77 09/15/04
*/
public class JHelp extends JComponent implements HelpSetListener, Accessible {
protected TextHelpModel helpModel;
protected HelpHistoryModel historyModel;
protected Vector navigators;
protected boolean navDisplayed=true;
protected boolean toolbarDisplayed=true;
protected HelpSet.Presentation hsPres;
protected JHelpContentViewer contentViewer;
/**
* Create a JHelp with a JHelpContentViewer and all Navigators
* requested in the HelpSet.
*
* @param hs The HelpSet. If hs is null the JHelp is created with a
* TextHelpModel with no HelpSet.
*/
public JHelp(HelpSet hs) {
this(new DefaultHelpModel(hs),
null,
hs==null? null : hs.getDefaultPresentation());
}
/**
* Create a JHelp component without a TextHelpModel.
*/
public JHelp() {
this((TextHelpModel)null);
}
/**
* Create a JHelp using the TextHelpModel.
*
* @param model A model to use for the content and all the navigators. If model
* is null it is the same as creating without a TextHelpModel
*/
public JHelp(TextHelpModel model){
this(model, null, null);
}
/**
* Create a JHelp using the TextHelpModel and HelpHistoryModel
*
* @param model A model to use for the content and all the navigators. If model
* is null it is the same as creating without a TextHelpModel
* @param history A history model. If <history is null it is the same
* as creating without HelpHistoryModel
*/
public JHelp(TextHelpModel model, HelpHistoryModel history,
HelpSet.Presentation hsPres){
super();
if(history == null)
this.historyModel = new DefaultHelpHistoryModel(this);
else
this.historyModel = history;
this.hsPres = hsPres;
navigators = new Vector();
navDisplayed = true;
// HERE -- need to do something about doc title changes....
this.contentViewer = new JHelpContentViewer(model);
setModel(model);
if (model != null) {
setupNavigators();
}
updateUI();
}
protected void setupNavigators() {
HelpSet hs = helpModel.getHelpSet();
// Simply return if the hs is null
if (hs == null) {
return;
}
// Now add all the navigators
NavigatorView views[] = hs.getNavigatorViews();
debug("views: "+views);
for (int i=0; inewModel is null the internal model is set
* to null.
*/
public void setModel(TextHelpModel newModel) {
TextHelpModel oldModel = helpModel;
if (newModel != oldModel) {
if (oldModel != null) {
oldModel.getHelpSet().removeHelpSetListener(this);
}
helpModel = newModel;
if (newModel != null) {
HelpSet hs = newModel.getHelpSet();
if (hs != null) {
hs.addHelpSetListener(this);
}
}
firePropertyChange("helpModel", oldModel, helpModel);
// Now tell all the components we control
contentViewer.setModel((TextHelpModel) newModel);
getHistoryModel().setHelpModel((HelpModel) newModel);
// We'll have to destroy all of the navigators and
// reload them from the HelpSet
HelpUI help = getUI();
// Skip the navigators if the ui hasn't been setup yet.
if (help == null) {
return;
}
for (Enumeration e = getHelpNavigators();
e.hasMoreElements(); ) {
JHelpNavigator nav = (JHelpNavigator) e.nextElement();
help.removeNavigator(nav);
}
navigators.removeAllElements();
setupNavigators();
updateUI();
}
}
/**
* @return The HelpModel that is providing the data.
*/
public TextHelpModel getModel() {
return helpModel;
}
/**
* Returns The HelpHistoryModel
*
* @return The HelpHistoryModel which provides history data
*/
public HelpHistoryModel getHistoryModel(){
return historyModel;
}
/**
* Set the HelpSet.Presentation.
* @see HelpSet.Presentation
*/
public void setHelpSetPresentation(HelpSet.Presentation hsPres) {
this.hsPres = hsPres;
return;
}
/**
* @return The HelpSet.Presentation.
* @see HelpSet.Presentation
*/
public HelpSet.Presentation getHelpSetPresentation() {
return hsPres;
}
// HERE - need customizers, etc... -epll
// HERE - this is probably broken
/**
* Set the URL to the HelpSet. This forces the HelpSet to be reloaded.
*
* @param spec Where to locate the HelpSet. A null spec is valid
*/
public void setHelpSetSpec(String spec) {
URL url;
HelpSet hs;
ClassLoader loader = this.getClass().getClassLoader();
try {
url = new URL(spec);
hs = new HelpSet(loader, url);
} catch (Exception ex) {
System.err.println("Trouble setting HelpSetSpec to spec |"+spec+"|");
System.err.println(" ex: "+ex);
hs = null;
}
contentViewer.setModel(new DefaultHelpModel(hs));
setModel(contentViewer.getModel());
updateUI();
}
/**
* @return The URL to the HelpSet.
*/
public URL getHelpSetURL() {
HelpSet hs = contentViewer.getModel().getHelpSet();
if (hs == null) {
return null;
}
return hs.getHelpSetURL();
}
// === The JComponent methods
/**
* Sets the HelpUI that will provide the current look and feel.
* @param ui The HelpUI to set for this component. A null value for ui
* is valid.
*/
public void setUI(HelpUI ui) {
if ((HelpUI)this.ui != ui) {
super.setUI(ui);
}
}
/**
* Returns the HelpUI that is providing the current look and feel.
*/
public HelpUI getUI() {
return (HelpUI)ui;
}
/**
* Replaces the UI with the latest version from the default
* UIFactory.
*
* @overrides updateUI in class JComponent
*/
public void updateUI() {
SwingHelpUtilities.installUIDefaults();
setUI((HelpUI)UIManager.getUI(this));
invalidate();
}
/**
* @return "HelpUI"
*/
public String getUIClassID()
{
return "HelpUI";
}
/*
* Findd the navigator with a given name.
*/
private JHelpNavigator findNavigator(String name) {
debug("findNavigator("+name+")");
for (Enumeration e = getHelpNavigators();
e.hasMoreElements(); ) {
JHelpNavigator nav = (JHelpNavigator) e.nextElement();
debug(" nav: "+nav);
debug(" nav.getName: "+nav.getNavigatorName());
if (nav.getNavigatorName().equals(name)) {
return nav;
}
}
return null;
}
/**
* Adds a new HelpSet to "our" HelpSet.
*
* @param e HelpSetEvent
* @see javax.help.event.HelpSetEvent
* @see javax.help.event.HelpSetListener
*/
public void helpSetAdded(HelpSetEvent e) {
debug("helpSetAdded("+e+")");
HelpSet ehs = e.getHelpSet();
addHelpSet(ehs);
}
/*
* Adds a HelpSet.
*/
private void addHelpSet(HelpSet ehs) {
debug("helpset :"+ehs);
NavigatorView eviews[] = ehs.getNavigatorViews();
//if master help set is created using new HelpSet() -without arguments it hasn't got any navigators to merge
//we will create new navigators
int count = 0;
for (Enumeration e = getHelpNavigators() ; e.hasMoreElements() ;e.nextElement()) {
++count;
}
if(count == 0){
debug("master helpset without navigators");
HelpModel newModel= new DefaultHelpModel(ehs);
setModel((TextHelpModel)newModel);
setupNavigators();
return;
}
for (int i=0; i
* Each navigator listens to changes to the HelpModel.
* A navigator can also tell the model to change--the change
* is propagated to the other navigators, this component, and
* the content viewer if they all use the same
* HelpModel instance.
*
* @param navigator The Navigator to explicitly add to the JHelp.
*/
public void addHelpNavigator(JHelpNavigator navigator) {
debug("addHelpNavigator("+navigator+")");
navigators.addElement(navigator);
HelpUI help = getUI();
help.addNavigator(navigator);
// force a common model
navigator.setModel(getModel());
}
/**
* Removes a navigator.
*
* @param navigator The Navigator to explicitly add to the JHelp.
*/
public void removeHelpNavigator(JHelpNavigator navigator) {
debug("removeHelpNavigator("+navigator+")");
if (navigator == null) {
throw new NullPointerException("navigator");
}
navigators.removeElement(navigator);
HelpUI help = getUI();
help.removeNavigator(navigator);
}
/**
* @return An Enumeration of HelpNavigators in the HelpUI.
*/
public Enumeration getHelpNavigators() {
return navigators.elements();
}
/**
* Sets the current navigator in the HelpUI.
*
* @param navigator The navigator
* @exception throws InvalidNavigatorException if not a one of HELPUI
* navigators.
*/
public void setCurrentNavigator(JHelpNavigator navigator) {
HelpUI help = getUI();
help.setCurrentNavigator(navigator);
}
/**
* @return The current navigator in the HelpUI
*/
public JHelpNavigator getCurrentNavigator() {
HelpUI help = getUI();
return help.getCurrentNavigator();
}
/**
* Hidess/Displays the Navigators in the HelpUI.
*
* @displayed Whether to display or not
*/
public void setNavigatorDisplayed(boolean displayed) {
if (navDisplayed != displayed) {
navDisplayed = displayed;
firePropertyChange("navigatorDisplayed", !displayed, displayed);
}
}
/**
* Determines if the Navigators are hidden/displayed in the HelpUI.
*
* @return Are the navigators displayed?
* @since 2.0
*/
public boolean isNavigatorDisplayed() {
return navDisplayed;
}
/**
* Hidess/Displays the Toolbar in the HelpUI.
*
* @displayed Whether to display or not
* @since 2.0
*/
public void setToolbarDisplayed(boolean displayed) {
if (toolbarDisplayed != displayed) {
toolbarDisplayed = displayed;
firePropertyChange("toolbarDisplayed", !displayed, displayed);
}
}
/**
* Determines if the Navigators are hidden/displayed in the HelpUI.
*
* @return is the toolbar displayed?
* @since 2.0
*/
public boolean isToolbarDisplayed() {
return toolbarDisplayed;
}
/**
* Retrieves what is the current content viewer
* Read-Only property?
*/
public JHelpContentViewer getContentViewer() {
return contentViewer;
}
/**
* Debug code
*/
private boolean debug = false;
private void debug(String msg) {
if (debug) {
System.err.println("JHelp: "+msg);
}
}
/*
* Make sure the Look and Feel will be set for the Help Component
*/
static {
SwingHelpUtilities.installLookAndFeelDefaults();
}
/////////////////
// Accessibility support
////////////////
/**
* Get the AccessibleContext associated with this JComponent.
*
* @return The AccessibleContext of this JComponent
*/
public AccessibleContext getAccessibleContext() {
if (accessibleContext == null) {
accessibleContext = new AccessibleJHelp();
}
return accessibleContext;
}
/**
* The class used to obtain the accessible role for this object.
*
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is appropriate
* for short term storage or RMI between applications running the same
* version of Swing. A future release of Swing will provide support for
* long term persistence.
*/
protected class AccessibleJHelp extends AccessibleJComponent {
/**
* Get the role of this object.
*
* @return an instance of AccessibleRole describing the role of the
* object
*/
public AccessibleRole getAccessibleRole() {
return AccessibleRole.PANEL;
}
}
}