fedora.swing.jhelp
Class SimpleHelpBroker

java.lang.Object
  fedora.swing.jhelp.SimpleHelpBroker

All Implemented Interfaces:

java.awt.event.KeyListener, java.util.EventListener, javax.help.HelpBroker

public class SimpleHelpBroker
extends java.lang.Object
implements javax.help.HelpBroker, java.awt.event.KeyListener

Title: SimpleHelpBroker.java

Description: An impelmentation of the HelpBroker interface. This is based on DefaultHelpBroker v1.33 (01/25/99) that comes with JavaHelp, originally written by Roger Brinkley and Eduardo Pelegri-Llopart. JavaHelp comes with Java, and is written by Sun Microsystems. More information on JavaHelp can be found at http://java.sun.com/products/javahelp/faq.html I've added a new constructor, which takes an Image (the icon you want to use for the window), and also a little more intelligent size tracking. When you close the presentation, it remembers the old size, so subsequent opens look the same. There is a lot of extra stuff (like support for java 1.1) where I don't fully understand what they were doing and what variables they're passing around and whatnot, but it seems to work fine, and it does what I want for now, so I'm not gonna futz with it except for adding functionality as needed. Also, in createJHelp, this class configures the JHelp such that the content viewer UI (the panel where the html is displayed) is a SimpleContentViewerUI instead of a BasicContentViewerUI. See SimpleContentViewerUI javadoc for why it's better.

----------------------------------------------------------------------------- Portions created by Sun Microsystems are Copyright © Sun Microsystems, originally made available at java.sun.com

-----------------------------------------------------------------------------

Version:

$Id: SimpleHelpBroker.java 4141 2005-05-18 22:21:15Z eddie $

Author:

Sun Microsystems, cwilper@cs.cornell.edu

Field Summary

protected javax.swing.JDialog	dialog The container for modally activated help
protected java.awt.event.ActionListener	displayHelpFromFocus
protected java.awt.event.ActionListener	displayHelpFromSource
protected java.awt.Font	font
protected javax.swing.JFrame	frame
protected javax.help.HelpSet	helpset
protected javax.help.JHelp	jhelp
protected java.util.Locale	locale
protected boolean	modallyActivated The flag for modally activated help.
protected java.awt.Window	ownerWindow The modal Window that activated help

Constructor Summary

SimpleHelpBroker()
Zero-argument constructor.

SimpleHelpBroker(javax.help.HelpSet hs)
Constructor

SimpleHelpBroker(javax.help.HelpSet hs, java.awt.Image iconImage)

Method Summary

void	enableHelp(java.awt.Component comp, java.lang.String id, javax.help.HelpSet hs) Enables help for a Component.
void	enableHelp(java.awt.MenuItem comp, java.lang.String id, javax.help.HelpSet hs) Enables help for a MenuItem.
void	enableHelpKey(java.awt.Component comp, java.lang.String id, javax.help.HelpSet hs) Enables the Help key on a Component.
void	enableHelpKey(java.awt.Component arg0, java.lang.String arg1, javax.help.HelpSet arg2, java.lang.String arg3, java.lang.String arg4)
void	enableHelpOnButton(java.awt.Component comp, java.lang.String id, javax.help.HelpSet hs) Enables help for a Component.
void	enableHelpOnButton(java.awt.MenuItem comp, java.lang.String id, javax.help.HelpSet hs) Enables help for a MenuItem.
void	enableHelpOnButton(java.lang.Object arg0, java.lang.String arg1, javax.help.HelpSet arg2, java.lang.String arg3, java.lang.String arg4)
void	ensureContentPanelDrawn(javax.help.Map.ID id)
javax.help.Map.ID	getCurrentID() Determines which ID is displayed (if any).
java.net.URL	getCurrentURL() Determines which URL is displayed.
java.lang.String	getCurrentView() Determines the current navigator.
protected java.awt.event.ActionListener	getDisplayHelpFromFocus() Returns the default DisplayHelpFromFocus listener.
protected java.awt.event.ActionListener	getDisplayHelpFromSource() Returns the default DisplayHelpFromSource listener.
java.awt.Font	getFont() Gets the font for this HelpBroker.
javax.help.HelpSet	getHelpSet() Returns the default HelpSet
java.util.Locale	getLocale() Gets the locale of this component.
java.awt.Point	getLocation() Requests the location of the presentation.
java.awt.Dimension	getSize() Requests the size of the presentation.
void	initPresentation() Initializes the presentation.
boolean	isDisplayed() Determines if the presentation is displayed.
boolean	isViewDisplayed() Determines if the current view is visible.
void	keyPressed(java.awt.event.KeyEvent e) Invoked when a key is pressed.
void	keyReleased(java.awt.event.KeyEvent e) Invoked when a key is released.
void	keyTyped(java.awt.event.KeyEvent e) Invoked when a key is typed.
void	setActivationWindow(java.awt.Window window) Set the activation window.
void	setCurrentID(javax.help.Map.ID id) Displays this ID--HelpVisitListeners are notified.
void	setCurrentID(java.lang.String id) Shows this ID as content relative to the (top) HelpSet for the HelpBroker instance--HelpVisitListeners are notified.
void	setCurrentURL(java.net.URL url) Displays this URL.
void	setCurrentView(java.lang.String name) Set the currentView to the navigator with the same name as the name parameter.
void	setDisplayed(boolean b) Displays the presentation to the user.
void	setFont(java.awt.Font f) Sets the font for this this HelpBroker.
void	setHelpSet(javax.help.HelpSet hs) Changes the HelpSet for this broker.
void	setHelpSetPresentation(javax.help.HelpSet.Presentation arg0)
void	setLocale(java.util.Locale l) Sets the locale of this HelpBroker.
void	setLocation(java.awt.Point p) Requests the presentation be located at a given position.
void	setPosition(java.awt.Point p)
void	setSize(java.awt.Dimension d) Requests the presentation be set to a given size.
void	setViewDisplayed(boolean displayed) Hides/Shows view.
void	showID(javax.help.Map.ID arg0, java.lang.String arg1, java.lang.String arg2)
void	showID(java.lang.String arg0, java.lang.String arg1, java.lang.String arg2)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

helpset

protected javax.help.HelpSet helpset

frame

protected javax.swing.JFrame frame

jhelp

protected javax.help.JHelp jhelp

locale

protected java.util.Locale locale

font

protected java.awt.Font font

dialog

protected javax.swing.JDialog dialog

The container for modally activated help

Since:

1.1

ownerWindow

protected java.awt.Window ownerWindow

The modal Window that activated help

Since:

1.1

modallyActivated

protected boolean modallyActivated

The flag for modally activated help. If true, help was activated from a modal dialog. Can not be set to true for V1.1.

Since:

1.1

displayHelpFromFocus

protected java.awt.event.ActionListener displayHelpFromFocus

displayHelpFromSource

protected java.awt.event.ActionListener displayHelpFromSource

Constructor Detail

SimpleHelpBroker

public SimpleHelpBroker(javax.help.HelpSet hs)

Constructor

SimpleHelpBroker

public SimpleHelpBroker(javax.help.HelpSet hs,
                        java.awt.Image iconImage)

SimpleHelpBroker

public SimpleHelpBroker()

Zero-argument constructor. It should be followed by a setHelpSet() invocation.

Method Detail

getHelpSet

public javax.help.HelpSet getHelpSet()

Returns the default HelpSet

Specified by:

getHelpSet in interface javax.help.HelpBroker

setHelpSet

public void setHelpSet(javax.help.HelpSet hs)

Changes the HelpSet for this broker.

Specified by:

setHelpSet in interface javax.help.HelpBroker

Parameters:

hs - The HelpSet to set for this broker. A null hs is valid parameter.

getLocale

public java.util.Locale getLocale()

Gets the locale of this component.

Specified by:

getLocale in interface javax.help.HelpBroker

Returns:

This component's locale. If this component does not have a locale, the defaultLocale is returned.

See Also:

setLocale(java.util.Locale)

setLocale

public void setLocale(java.util.Locale l)

Sets the locale of this HelpBroker. The locale is propagated to the presentation.

Specified by:

setLocale in interface javax.help.HelpBroker

Parameters:

l - The locale to become this component's locale. A null locale is the same as the defaultLocale.

See Also:

getLocale()

getFont

public java.awt.Font getFont()

Gets the font for this HelpBroker.

Specified by:

getFont in interface javax.help.HelpBroker

setFont

public void setFont(java.awt.Font f)

Sets the font for this this HelpBroker.

Specified by:

setFont in interface javax.help.HelpBroker

Parameters:

f - The font.

setPosition

public void setPosition(java.awt.Point p)

setCurrentView

public void setCurrentView(java.lang.String name)

Set the currentView to the navigator with the same name as the name parameter.

Specified by:

setCurrentView in interface javax.help.HelpBroker

Parameters:

name - The name of the navigator to set as the current view. If nav is null or not a valid Navigator in this HelpBroker then an IllegalArgumentException is thrown.

Throws:

java.lang.IllegalArgumentException - if nav is null or not a valid Navigator.

getCurrentView

public java.lang.String getCurrentView()

Determines the current navigator.

Specified by:

getCurrentView in interface javax.help.HelpBroker

initPresentation

public void initPresentation()

Initializes the presentation. This method allows the presentation to be initialized but not displayed. Typically this would be done in a separate thread to reduce the intialization time.

Specified by:

initPresentation in interface javax.help.HelpBroker

setDisplayed

public void setDisplayed(boolean b)

Displays the presentation to the user.

Specified by:

setDisplayed in interface javax.help.HelpBroker

isDisplayed

public boolean isDisplayed()

Determines if the presentation is displayed.

Specified by:

isDisplayed in interface javax.help.HelpBroker

setLocation

public void setLocation(java.awt.Point p)

Requests the presentation be located at a given position. This operation may throw an UnsupportedOperationException if the underlying implementation does not allow this.

Specified by:

setLocation in interface javax.help.HelpBroker

getLocation

public java.awt.Point getLocation()

Requests the location of the presentation.

Specified by:

getLocation in interface javax.help.HelpBroker

Throws:

javax.help.UnsupportedOperationException - If the underlying implementation does not allow this.

IllegalComponentStateExcetpion - If the presentation is not displayed.

setSize

public void setSize(java.awt.Dimension d)

Requests the presentation be set to a given size. This operation may throw an UnsupportedOperationException if the underlying implementation does not allow this.

Specified by:

setSize in interface javax.help.HelpBroker

getSize

public java.awt.Dimension getSize()

Requests the size of the presentation.

Specified by:

getSize in interface javax.help.HelpBroker

Throws:

javax.help.UnsupportedOperationException - If the underlying implementation does not allow this.

IllegalComponentStateExcetpion - If the presentation is not displayed.

setViewDisplayed

public void setViewDisplayed(boolean displayed)

Hides/Shows view.

Specified by:

setViewDisplayed in interface javax.help.HelpBroker

isViewDisplayed

public boolean isViewDisplayed()

Determines if the current view is visible.

Specified by:

isViewDisplayed in interface javax.help.HelpBroker

setCurrentID

public void setCurrentID(java.lang.String id)
                  throws javax.help.BadIDException

Shows this ID as content relative to the (top) HelpSet for the HelpBroker instance--HelpVisitListeners are notified.

Specified by:

setCurrentID in interface javax.help.HelpBroker

Parameters:

id - A string that identifies the topic to show for the loaded (top) HelpSet

Throws:

javax.help.BadIDException - The ID is not valid for the HelpSet

setCurrentID

public void setCurrentID(javax.help.Map.ID id)
                  throws javax.help.InvalidHelpSetContextException

Displays this ID--HelpVisitListeners are notified.

Specified by:

setCurrentID in interface javax.help.HelpBroker

Parameters:

id - a Map.ID indicating the URL to display

Throws:

javax.help.InvalidHelpSetContextException - if the current helpset does not contain id.helpset

getCurrentID

public javax.help.Map.ID getCurrentID()

Determines which ID is displayed (if any).

Specified by:

getCurrentID in interface javax.help.HelpBroker

setCurrentURL

public void setCurrentURL(java.net.URL url)

Displays this URL. HelpVisitListeners are notified. The currentID changes if there is a mathing ID for this URL

Specified by:

setCurrentURL in interface javax.help.HelpBroker

Parameters:

url - The url to display. A null URL is a valid url.

getCurrentURL

public java.net.URL getCurrentURL()

Determines which URL is displayed.

Specified by:

getCurrentURL in interface javax.help.HelpBroker

enableHelpKey

public void enableHelpKey(java.awt.Component comp,
                          java.lang.String id,
                          javax.help.HelpSet hs)

Enables the Help key on a Component. This method works best when the component is the rootPane of a JFrame in Swing implementations, or a java.awt.Window (or subclass thereof) in AWT implementations. This method sets the default helpID and HelpSet for the Component and registers keyboard actions to trap the "Help" keypress. When the "Help" key is pressed, if the object with the current focus has a helpID, the helpID is displayed. otherwise the default helpID is displayed.

Specified by:

enableHelpKey in interface javax.help.HelpBroker

Parameters:

comp - the Component to enable the keyboard actions on.

id - the default HelpID to be displayed

hs - the default HelpSet to be displayed. If hs is null the default HelpSet will be assumed.

See Also:

getHelpKeyActionListener

keyTyped

public void keyTyped(java.awt.event.KeyEvent e)

Invoked when a key is typed. This event occurs when a key press is followed by a key release. Not intended to be overridden or extended.

Specified by:

keyTyped in interface java.awt.event.KeyListener

keyPressed

public void keyPressed(java.awt.event.KeyEvent e)

Invoked when a key is pressed. Not intended to be overridden or extended.

Specified by:

keyPressed in interface java.awt.event.KeyListener

keyReleased

public void keyReleased(java.awt.event.KeyEvent e)

Invoked when a key is released. Not intended to be overridden or extended.

Specified by:

keyReleased in interface java.awt.event.KeyListener

enableHelp

public void enableHelp(java.awt.Component comp,
                       java.lang.String id,
                       javax.help.HelpSet hs)

Enables help for a Component. This method sets a component's helpID and HelpSet.

Specified by:

enableHelp in interface javax.help.HelpBroker

Parameters:

comp - the Component to set the id and hs on.

id - the String value of an Map.ID.

hs - the HelpSet the id is in. If hs is null the default HelpSet will be assumed.

See Also:

CSH.setHelpID, CSH.setHelpSet

enableHelp

public void enableHelp(java.awt.MenuItem comp,
                       java.lang.String id,
                       javax.help.HelpSet hs)

Enables help for a MenuItem. This method sets a component's helpID and HelpSet.

Specified by:

enableHelp in interface javax.help.HelpBroker

Parameters:

comp - the MenuItem to set the id and hs on.

id - the String value of an Map.ID.

hs - the HelpSet the id is in. If hs is null the default HelpSet will be assumed.

See Also:

CSH.setHelpID, CSH.setHelpSet

enableHelpOnButton

public void enableHelpOnButton(java.awt.Component comp,
                               java.lang.String id,
                               javax.help.HelpSet hs)

Enables help for a Component. This method sets a Component's helpID and HelpSet and adds an ActionListener. When an action is performed it displays the Component's helpID and HelpSet in the default viewer.

Specified by:

enableHelpOnButton in interface javax.help.HelpBroker

Parameters:

comp - the Component to set the id and hs on. If the Component is not a javax.swing.AbstractButton or a java.awt.Button an IllegalArgumentException is thrown.

id - the String value of an Map.ID.

hs - the HelpSet the id is in. If hs is null the default HelpSet will be assumed.

Throws:

java.lang.IllegalArgumentException - if comp is null.

See Also:

CSH.setHelpID, CSH.setHelpSet, AbstractButton, Button

enableHelpOnButton

public void enableHelpOnButton(java.awt.MenuItem comp,
                               java.lang.String id,
                               javax.help.HelpSet hs)

Enables help for a MenuItem. This method sets a Component's helpID and HelpSet and adds an ActionListener. When an action is performed it displays the Component's helpID and HelpSet in the default viewer.

Specified by:

enableHelpOnButton in interface javax.help.HelpBroker

Parameters:

comp - the MenuItem to set the id and hs on. If comp is null an IllegalAgrumentException is thrown.

id - the String value of an Map.ID.

hs - the HelpSet the id is in. If hs is null the default HelpSet will be assumed.

Throws:

java.lang.IllegalArgumentException - if comp is null.

See Also:

CSH.setHelpID, CSH.setHelpSet, MenuItem

getDisplayHelpFromFocus

protected java.awt.event.ActionListener getDisplayHelpFromFocus()

Returns the default DisplayHelpFromFocus listener.

See Also:

enableHelpKey

getDisplayHelpFromSource

protected java.awt.event.ActionListener getDisplayHelpFromSource()

Returns the default DisplayHelpFromSource listener.

See Also:

enableHelp

setActivationWindow

public void setActivationWindow(java.awt.Window window)

Set the activation window. If the window is an instance of a Dialog and the is modal, modallyActivated help is set to true and ownerDialog is set to the window. In all other instances modallyActivated is set to false and ownerDialog is set to null.

Parameters:

window - the activating window

Since:

1.1

ensureContentPanelDrawn

public void ensureContentPanelDrawn(javax.help.Map.ID id)

setHelpSetPresentation

public void setHelpSetPresentation(javax.help.HelpSet.Presentation arg0)

Specified by:

setHelpSetPresentation in interface javax.help.HelpBroker

showID

public void showID(javax.help.Map.ID arg0,
                   java.lang.String arg1,
                   java.lang.String arg2)
            throws javax.help.InvalidHelpSetContextException

Specified by:

showID in interface javax.help.HelpBroker

Throws:

javax.help.InvalidHelpSetContextException

showID

public void showID(java.lang.String arg0,
                   java.lang.String arg1,
                   java.lang.String arg2)
            throws javax.help.BadIDException

Specified by:

showID in interface javax.help.HelpBroker

Throws:

javax.help.BadIDException

enableHelpKey

public void enableHelpKey(java.awt.Component arg0,
                          java.lang.String arg1,
                          javax.help.HelpSet arg2,
                          java.lang.String arg3,
                          java.lang.String arg4)

Specified by:

enableHelpKey in interface javax.help.HelpBroker

enableHelpOnButton

public void enableHelpOnButton(java.lang.Object arg0,
                               java.lang.String arg1,
                               javax.help.HelpSet arg2,
                               java.lang.String arg3,
                               java.lang.String arg4)
                        throws java.lang.IllegalArgumentException

Specified by:

enableHelpOnButton in interface javax.help.HelpBroker

Throws:

java.lang.IllegalArgumentException