cdox.util.doc
Class Documentation

java.lang.Object
  extended bycdox.util.doc.Documentation

public class Documentation
extends java.lang.Object

This class grants easy access to an application's documentation. One has only to write the documentation once in XML format (using the Schema here) and can then use this class to display a help browser or a specific help text. This class is also a command line utility to generate HTML out of the documentation.

You can also use this class to display several documentations in one help browser. For ease of use, one can specify a class to be Documented (using the interface) and provide several of this classes instead of the appropriate Documentations.

Depending on the amount of documentation one can use either one Documentation for the application (and one class implements Documented) or several classes to be Documented. If you use the methods that require several Documented classes as argument, they are displayed as top-level documentation nodes.

Version:
May 22nd 2002
Author:
Rutger Bezema, Andreas Schmitz

Constructor Summary
Documentation(javax.swing.JFrame owner, java.io.File location)
          Constructs one using the given file.
Documentation(javax.swing.JFrame owner, java.io.InputStream in)
          Constructs one using the given stream.
Documentation(javax.swing.JFrame owner, java.lang.String location)
          Constructs one using the given file.
Documentation(javax.swing.JFrame owner, java.net.URL location)
          Constructs one using the given URL.
 
Method Summary
 void displayDocumentation(java.lang.String language)
          Displays all documentation in swing.
 void displayDocumentationFor(java.lang.String id, java.lang.String language)
          Displays the requested documentation in swing.
 java.util.HashMap[] getCategories(java.lang.String language)
          Returns category related information in this documentation in two HashMaps.
 java.lang.String getDefaultTopicName()
          Returns the default topic id of this documentation.
 org.w3c.dom.Document getDocument()
          Returns the DOM document for this documentation.
 java.lang.String getTitle(java.lang.String language)
          Returns the title of this documentation.
 java.lang.String getTopic(java.lang.String id, java.lang.String language)
          Returns the requested topic as HTML in the String.
 javax.swing.JEditorPane getTopics(java.lang.String language)
          Returns a JEditorPane with all the topics in the root of the documentation.
 java.lang.String getTopicsAsString(java.lang.String language, java.lang.String topic)
          Returns the requested topic's subtopics as HTML in a string.
 void setBackgroundURL(java.net.URL url)
          Sets a background image by URL.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Documentation

public Documentation(javax.swing.JFrame owner,
                     java.io.InputStream in)
              throws java.io.IOException
Constructs one using the given stream.

Parameters:
owner - a JFrame value indicating a parent frame.
in - the stream.
Throws:
java.io.IOException - if an error occurs.

Documentation

public Documentation(javax.swing.JFrame owner,
                     java.lang.String location)
              throws java.io.IOException
Constructs one using the given file.

Parameters:
owner - a JFrame value indicating a parent frame.
location - the path to the file.
Throws:
java.io.IOException - if an error occurs.

Documentation

public Documentation(javax.swing.JFrame owner,
                     java.net.URL location)
              throws java.io.IOException
Constructs one using the given URL.

Parameters:
owner - a JFrame value indicating a parent frame.
location - the URL.
Throws:
java.io.IOException - if an error occurs.

Documentation

public Documentation(javax.swing.JFrame owner,
                     java.io.File location)
              throws java.io.IOException
Constructs one using the given file.

Parameters:
owner - a JFrame value indicating a parent frame.
location - the file.
Throws:
java.io.IOException - if an error occurs.
Method Detail

getDocument

public org.w3c.dom.Document getDocument()
Returns the DOM document for this documentation. Modify on your own risk.

Returns:
the document.

displayDocumentationFor

public void displayDocumentationFor(java.lang.String id,
                                    java.lang.String language)
Displays the requested documentation in swing. This generates and displays a JFrame containing the documentation regarding the topic.

Parameters:
id - the topic to be displayed.
language - the desired language.

displayDocumentation

public void displayDocumentation(java.lang.String language)
Displays all documentation in swing.

Parameters:
language - the desired language.

getTitle

public java.lang.String getTitle(java.lang.String language)
Returns the title of this documentation.

Parameters:
language - the desired language.
Returns:
the title.

getTopicsAsString

public java.lang.String getTopicsAsString(java.lang.String language,
                                          java.lang.String topic)
Returns the requested topic's subtopics as HTML in a string. This will also return a HTML document, if there exist no subtopics.

Parameters:
language - the desired language.
topic - the topic.
Returns:
the HTML.

getTopics

public javax.swing.JEditorPane getTopics(java.lang.String language)
Returns a JEditorPane with all the topics in the root of the documentation.

Parameters:
language - the desired language.
Returns:
the pane.

getTopic

public java.lang.String getTopic(java.lang.String id,
                                 java.lang.String language)
Returns the requested topic as HTML in the String.

Parameters:
id - the topic.
language - the language.
Returns:
the String.

getDefaultTopicName

public java.lang.String getDefaultTopicName()
Returns the default topic id of this documentation.

Returns:
the topic id.

getCategories

public java.util.HashMap[] getCategories(java.lang.String language)
Returns category related information in this documentation in two HashMaps. The first map maps the topic ids to its direct ancestor, or the empty string, if none exists. The second map stores "true", if the topic is a category (has subtopics) and false, otherwise.

Parameters:
language - the language from which the topics are desired.
Returns:
the HashMaps with the mappings.

setBackgroundURL

public void setBackgroundURL(java.net.URL url)
Sets a background image by URL. This image will then be the background image in all displayed topics.

Parameters:
url - the url. Please note that you can also use jar URLs as defined in java.net.JarURLConnection.