The library.html Package

HtmlEdit

Synopsis

Class Name:                   library.html.HtmlEdit
Superclass:                   library.html.HtmlPage
Immediate Subclasses:         None
Interfaces Implemented:       None

Description

Class Summary

public class library.html.HtmlEdit extends library.html.HtmlPage {
     // Constructors
     public HtmlEdit();
     public HtmlEdit(char[] text);

     // Instance Methods
     public void addTextListener(TextListener l);
     protected Font getNormalFont();
     public boolean isPlainText();
     public void keyPressed(KeyEvent e);
     public void keyTyped(KeyEvent e);
     public void paint(Graphics g);
     public void processEvent(AWTEvent e);
     public void removeTextListener(TextListener l);
     public void setText(char[] text, boolean isPlain);
}

Constructors

 public HtmlEdit()
  Description  Constructs a HtmlEdit component with no initial text.

 public HtmlEdit(char[] text)
  Parameters   text           The initial text for the HtmlEdit component.
  Description  Constructs a HtmlEdit component initially containing the given text.

Instance Methods

 public void addTextListener(TextListener l)
  Parameters   l              An object which implements the TextListener interface.
  Description  Adds the specified TextListener to the internal list of objects interested
               in text-events occurring in this component.  The textValueChanged() method
               of the given object is called whenever the text in this component is changed.

 public boolean isPlainText()
  Returns      true if text is displayed in pre-formatted mode, otherwise false.
  Overrides    library.html.HtmlPage.isPlainText()
  Description  This method overrides HtmlPage to change the value returned to true, causing
               all text to be displayed in pre-formatted (plain-text) mode.

 protected Font getNormalFont()
  Returns      A Font to use as the normal font for text output on this component.
  Overrides    library.html.HtmlPage.getNormalFont()
  Description  This method overrides HtmlPage to change the settings for the normal font.

 public void keyPressed(KeyEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.html.HtmlPage.keyPressed(KeyEvent)
  Description  This method overrides HtmlPage to modify the way key-presses are interpreted.
               It provides the functionality for page navigation using an edit-cursor.

 public void keyTyped(KeyEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.html.HtmlPage.keyTyped(KeyEvent)
  Description  This method overrides HtmlPage to process printable key-presses.

 public void paint(Graphics g)
  Parameters   g              A Graphics context for drawing.
  Overrides    library.html.HtmlPage.paint(Graphics)
  Description  This method overrides HtmlPage to add the edit-cursor to the display.

 public void processEvent(AWTEvent e)
  Parameters   e              The event which has occurred.
  Overrides    java.awt.Component.processEvent(AWTEvent)
  Description  Overrides Component to add functionality for handling text-events.

 public void removeTextListener(TextListener l)
  Parameters   l              The TextListener object to be removed from this component.
  Description  Indicates that the specified TextListener object is no longer interested
               in text-events which occur in this component.

 public void setText(char[] text, boolean isPlain)
  Parameters   text           The new text for this HtmlEdit component.
               isPlain        true if the text is to be displayed in pre-formatted mode.
  Overrides    library.html.HtmlPage.setText(char[], boolean)
  Description  Overrides HtmlPage to ensure that the text for this HtmlEdit component is
               not null.  It also resets the current position to the top-left of the page.

HtmlEditor

Synopsis

Class Name:                   library.html.HtmlEditor
Superclass:                   library.html.HtmlWindow
Immediate Subclasses:         None
Interfaces Implemented:       java.awt.event.TextListener

Description

Class Summary

public class library.html.HtmlEditor extends library.html.HtmlWindow
  implements java.awt.event.TextListener {
     // Constructor
     public HtmlEditor(String title, char[] text, HtmlFile f);

     // Instance Methods
     public void actionPerformed(ActionEvent e);
     public void textValueChanged(TextEvent e);
     public void windowClosed(WindowEvent e);
}

Constructor

 public HtmlEditor(String title, char[] text, HtmlFile f)
  Parameters   title          The title for this window.
               text           The initial HTML text for this editor.
               f              The parent HtmlFile object for this editor.
  Description  Constructs a HtmlEditor window with the specified title to display the given
               text.  The parent HtmlFile object provides the additional functionality
               necessary to retrieve HTML files and to access other windows.  An HtmlEdit
               component is used to process HTML text.

Instance Methods

 public void actionPerformed(ActionEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.PolyMenuWindow.actionPerformed(ActionEvent)
  Description  Handles action events from the menu items and buttons on this window.

 public void textValueChanged(TextEvent e)
  Parameters   e              The event which has occurred.
  Description  A dummy handler for text-changed events.

 public void windowClosed(WindowEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.PolyMenuWindow.windowClosed(WindowEvent)
  Description  Intercepts window-closed events to update the parent HtmlFile object.

HtmlFile

Synopsis

Class Name:                   library.html.HtmlFile
Superclass:                   None
Immediate Subclasses:         None
Interfaces Implemented:       None

Description

Class Summary

public class library.html.HtmlFile {
     // Constructors
     public HtmlFile();
     public HtmlFile(String fname);
     public HtmlFile(String fname, char[] text);

     // Instance Methods
     public void emptyEditor();
     public void emptyViewer();
     public char[] getText();
     public void setText(char[] text);
     public void startEditor();
     public void startViewer();

     // Protected Instance Methods
     protected String msgFormatError();
     protected String msgModified();
     protected String msgReadError();
     protected String msgWriteError();
     protected void newEditor();
     protected void newViewer();
}

Constructors

 public HtmlFile()
  Description  Constructs a HtmlFile object with a default filename and containing no text.

 public HtmlFile(String fname)
  Parameters   fname          A name to use for the file associated with this object.
  Description  Constructs a HtmlFile object with the given filename and containing no text.

 public HtmlFile(String fname, char[] text)
  Parameters   fname          A name to use for the file associated with this object.
               text           The initial text associated with this object.
  Description  Constructs a HtmlFile object with the given filename and text.

Instance Methods

 public void emptyEditor()
  Description  Creates a new empty HtmlEditor window for this HtmlFile object.  If the
               current text has been modified, the user is given the option to save it.
               If the HtmlViewer window for this HtmlFile is active, it is destroyed.

 public void emptyViewer()
  Description  Creates a new empty HtmlViewer window for this HtmlFile object.  If the
               current text has been modified, the user is given the option to save it.
               If the HtmlEditor window for this HtmlFile is active, it is destroyed.

 public char[] getText()
  Returns      The HTML text for this HtmlFile object.
  Description  Returns a character array containing the current text for this HtmlFile.

 public void setText(char[] text)
  Parameters   text           The new text for this HtmlFile.
  Description  Changes the text contained by this HtmlFile object.

 public void startEditor()
  Description  Opens or reactivates the HtmlEditor window for the text contained by
               this HtmlFile.

 public void startViewer()
  Description  Opens or reactivates the HtmlViewer window for the text contained by
               this HtmlFile.

Protected Instance Methods

 protected String msgFormatError()
  Returns      A message string.
  Description  Returns a string to display when a file-format error occurs.

 protected String msgModified()
  Returns      A message string.
  Description  Returns a string to display when a file-format error occurs.

 protected String msgReadError()
  Returns      A message string.
  Description  Returns a string to display when a file-reading error occurs.

 protected String msgWriteError()
  Returns      A message string.
  Description  Returns a string to display when a file-writing error occurs.

 protected void newEditor()
  Description  Creates a new HtmlFile object containing a copy of the text in this one
               and activates the new object's HtmlEditor window to display the text.

 protected void newViewer()
  Description  Creates a new HtmlFile object containing a copy of the text in this one
               and activates the new object's HtmlViewer window to display the text.

HtmlPage

Synopsis

Class Name:                   library.html.HtmlPage
Superclass:                   java.awt.Canvas
Immediate Subclasses:         library.html.HtmlEdit
Interfaces Implemented:       java.awt.event.KeyListener

Description

An HtmlReader.Tag can register with a HtmlPage to receive mouse-click events that occur over blocks of text or images. This forms part of the system required for the implementation of hypertext links, that is, the <a href="..."> tag. An HtmlReader.Tag object for such a tag should implement the HtmlPage.ClickListener interface, which declares the method that is to receive mouse-click events. When the Tag object is activated during the drawing process, it should register its interest in mouse-clicks by calling the addClickArea() method. When the Tag object created for the closing </a> tag is activated, it should terminate the mouse-sensitive area of the display by calling the endClickArea() method. Any mouse-click events that then occur over the area of the page between the two tags will be passed to the event handler in the specified ClickListener object.

To properly handle a mouse-click event and complete the implementation of hypertext links, an HtmlReader.Tag object needs be able to replace the HTML text currently contained by the HtmlPage. The additional functionality required to retrieve HTML text from files is beyond the scope of an HtmlPage object, whose intended purpose is simply to display a given block of HTML text. An HtmlPage does, however, include default handlers for such methods which can be overridden to provide this ability, as is done for HtmlPage objects created by an HtmlFile object. These methods, getHref() which resolves file references and openUrl() which retrieves the contents of a file or a URL, can thus be called by HtmlReader.Tag objects to attempt to access HTML files.

Class Summary

public class library.html.HtmlPage extends java.awt.Canvas
  implements java.awt.event.KeyListener {
     // Constructors
     public HtmlPage(char[] text);
     public HtmlPage(char[] text, HtmlReader reader);
     public HtmlPage(char[] text, boolean isPlain, HtmlReader reader);

     // Instance Methods
     public void addIndent(int indent);
     public void addIndents(int indent);
     public void drawImage(Image i, Graphics g);
     public void drawImage(Image i, int align, Graphics g);
     public boolean drawText(String s, Graphics g);
     public Font getFont();
     public Object getHref(String name);
     public HtmlReader getHtmlReader();
     public char[] getText();
     public boolean isFocusTraversable();
     public boolean isPlainText();
     public void keyPressed(KeyEvent e);
     public void keyReleased(KeyEvent e);
     public void keyTyped(KeyEvent e);
     public boolean newline(Graphics g);
     public boolean newpara(Graphics g);
     public boolean nextline(Graphics g);
     public boolean openUrl(String addr);
     public void paint(Graphics g);
     public void setCentre(boolean state);
     public synchronized void setFont(Font f);
     public void setPreformat(boolean state);
     public void setText(char[] text, boolean isPlain);
     public void update(Graphics g);

     // Protected Instance Methods
     protected void addClickArea(ClickListener l);
     protected boolean endClickArea();
     protected Color getLinkColor();
     protected Color getNormalColor();
     protected Font getNormalFont();
     protected Font getTeleFont();
     protected void setBold(boolean state);
     protected void setFontName();
     protected void setFontName(String name);
     protected void setFontSize();
     protected void setFontSize(int size);
     protected void setItalic(boolean state);
     protected void setNormalFont();
     protected void setTeleFont();
     protected void setUnderline(boolean state);
     protected void updateText(char[] text, int pos, int offset);
}

Constructors

 public HtmlPage(char[] text)
  Parameters   text           The initial HTML text for this HtmlPage.
  Description  Constructs a HtmlPage component containing the given HTML text.

 public HtmlPage(char[] text, HtmlReader reader)
  Parameters   text           The initial HTML text for this HtmlPage.
               reader         A HtmlReader object to use for processing text.
  Description  Constructs a HtmlPage component containing the given HTML text.  The given
               HtmlReader is used to process the text instead of the default HtmlPageReader
               object.

 public HtmlPage(char[] text, boolean isPlain, HtmlReader reader)
  Parameters   text           The initial HTML text for this HtmlPage.
               isPlain        true if text is displayed as plain text, false if HTML text.
               reader         A HtmlReader object to use for processing text.
  Description  Constructs a HtmlPage component containing the given HTML text.  The given
               HtmlReader object is used to process the text instead of the default
               HtmlPageReader object.  If isPlain is true, the text is displayed as
               ordinary plain text.  If isPlain is false, the text is displayed using HTML
               formatting.

Instance Methods

 public void addIndent(int indent)
  Parameters   indent         A positive or negative value for indenting text.
  Description  This method adds the given value to the current left-indentation setting
               for text output on this HtmlPage.  The current output position is moved to
               the new start of the current line.

 public void addIndents(int indent)
  Parameters   indent         A positive or negative value for indenting text.
  Description  This method adds the given value to both the left and right indentation
               settings for text output on this HtmlPage.  The current output position is
               moved to the new start of the current line.

 public void drawImage(Image i, Graphics g)
  Parameters   image          An image to draw.
               g              A graphics context for drawing.
  Description  Begins drawing the specified image at the current output location on the
               given graphics context.  Text surrounding the image is aligned with the
               bottom of the image by default.

 public void drawImage(Image i, int align, Graphics g)
  Parameters   image          An image to draw.
               align          A value indicating the text-alignment method.
               g              A graphics context for drawing.
  Description  Begins drawing the specified image at the current output location on the
               given graphics context.  Text surrounding the image is aligned according
               to the value of the align parameter, as follows:

               Value      Alignment       Effect


                0          Bottom          Baseline of text aligns with bottom of image.
                1          Middle          Middle of text aligns with middle of image.
                2          Top             Top of text aligns with top of image.

 public boolean drawText(String s, Graphics g)
  Parameters   s              A string of text to draw.
               g              A graphics context for drawing.
  Returns true if the bottom of the visible area of the document has been reached.
  Description  This method draws the given string at the current output position on this
               HtmlPage component.  The text is displayed using the current HTML settings
               for this HtmlPage object on the given graphics context.  After drawing, the
               current output position is set to the end of the displayed text.

 public Font getFont()
  Returns      The current font of the HtmlPage.
  Overrides    java.awt.Component.getFont()
  Description  This method returns the font currently being used for output on this HtmlPage.

 public Object getHref(String name)
  Parameters   name           A partial filename specification.
  Returns      An absolute filename specification.
  Description  The default implementation of this method simply returns its name parameter.
               It should be overridden to provide a method which can be used to resolve a
               relative filename specification based upon the source location of the HTML
               text contained by this HtmlPage component.  If the source file resides on
               the local file-system, the value returned should be a String containing an
               absolute pathname.  Otherwise, the returned value should be a new URL object.

 public HtmlReader getHtmlReader()
  Returns      The HtmlReader object used by this HtmlPage.
  Description  This method returns a reference to the HtmlReader object that is being used
               to process HTML text for this HtmlPage.

 public char[] getText()
  Returns      The HTML text contained by this HtmlPage.
  Description  This method returns a reference to the HTML text contained by this HtmlPage.

 public boolean isFocusTraversable()
  Returns      true if this HtmlPage can receive the input-focus, otherwise false.
  Overrides    java.awt.Component.isFocusTraversable()
  Description  This method returns true to indicate that a HtmlPage can receive input-focus.
               It should be overridden to disable input-focus.

 public boolean isPlainText()
  Returns      true if text should be displayed without HTML formatting, otherwise false.
  Description  This method returns false to indicate that HTML formatting should be used.
               It should be overridden to disable HTML formatting.

 public void keyPressed(KeyEvent e)
  Parameters   e              The event which has occurred.
  Description  Processes key-press events occurring on this HtmlPage.

 public void keyReleased(KeyEvent e)
  Parameters   e              The event which has occurred.
  Description  This method does nothing.

 public void keyTyped(KeyEvent e)
  Parameters   e              The event which has occurred.
  Description  This method does nothing.

 public boolean newline(Graphics g)
  Parameters   g              A graphics context for drawing.
  Returns      true if the bottom of the visible area of the document has been reached.
  Description  If the current output position for this page is not at the start of a new
               line, this method moves it to the start of the next line.  Otherwise it
               does nothing.

 public boolean newpara(Graphics g)
  Parameters   g              A graphics context for drawing.
  Returns      true if the bottom of the visible area of the document has been reached.
  Description  If the current output position for this page is not at the start of a new
               paragraph, this method moves it to the start of the next paragraph.
               Otherwise it does nothing.

 public boolean nextline(Graphics g)
  Parameters   g              A graphics context for drawing.
  Returns      true if the bottom of the visible area of the document has been reached.
  Description  This method moves the current output position for this page to the start
               of the next line.

 public boolean openUrl(String addr)
  Parameters   addr           A String representing a location to retrieve HTML text from.
  Returns      true if HTML text was retrieved from the specified location, otherwise false.
  Description  The default implementation of this method simply returns the value false.
               It should be overridden to provide a method which can retrieve text from the
               specified location to replace the current text in this HtmlPage object.

 public void paint(Graphics g)
  Parameters   g              A graphics context for drawing.
  Overrides    java.awt.Canvas.paint(Graphics)
  Description  Draws the text contained by this HtmlPage using the current page settings
               and offsets on the given graphics context.

 public void setCentre(boolean state)
  Parameters   state          true to centre following text, otherwise false.
  Description  This method enables and disables the centre-text mode of a HtmlPage.

 public synchronized void setFont(Font f)
  Parameters   f              A Font containing the new font settings for this HtmlPage.
  Overrides    java.awt.Component.setFont(Font)
  Description  This method changes the current font settings for a HtmlPage.

 public void setPreformat(boolean state)
  Parameters   state          true to enable pre-formatted mode, otherwise false.
  Description  This method enables and disables pre-formatted mode for text output.  When
               pre-formatted mode is enabled, word-wrapping is disabled and all text is
               displayed without modification.  When pre-formatted mode is disabled, text
               is wrapped to fit within the current Component dimensions and sequences of
               spaces, tabs and newline characters are condensed into a single space.

 public void setText(char[] text, boolean isPlain)
  Parameters   text           The new text for this HtmlPage
               isPlain        true to display text as pre-formatted text, otherwise false.
  Description  Changes the text contained by this HtmlPage.  If isPlain is true, the entire
               text is displayed in pre-formatted mode (see the setPreformat() method).
               If isPlain is false, all HTML tags within the text are interpreted normally.

 public void update(Graphics g)
  Parameters   g              A graphics context for drawing.
  Overrides    java.awt.Component.update(Graphics)
  Description  Overrides Component to prevent the HtmlPage being cleared to its background
               colour before drawing.  Since graphics output is prepared in a double-buffer
               before being copied to the graphics context, clearing the HtmlPage first is
               not necessary.

Protected Instance Methods

 protected void addClickArea(ClickListener l)
  Parameters   l              An object which implements the ClickListener interface.
  Description  Adds the given ClickListener object to a list of objects interested in any
               mouse-clicks occurring over the text and images displayed by this HtmlPage.
               All mouse-clicks which occur over text or images after the current output
               position and up to the position at which the endClickArea() method is called
               (or the bottom of the display) are passed to the specified ClickListener.
               This allows tag-objects to process their own mouse-click events.

 protected boolean endClickArea()
  Returns      true if a click area was active, otherwise false.
  Description  Terminates the click area begun by a prior call to addClickArea() at the
               current output position.

 protected Color getLinkColor()
  Returns      The colour to use for hypertext links.
  Description  This method returns a colour to use for highlighting hypertext links.

 protected Color getNormalColor()
  Returns      The colour to use for normal text output.
  Description  This method returns a colour to use when displaying normal text.

 protected Font getNormalFont()
  Returns      A font to use for normal text output.
  Description  This method returns the font settings to use for displaying normal text.

 protected Font getTeleFont()
  Returns      A font to use for teletype text.
  Description  This method returns the font settings to use for displaying teletype text.

 protected void setBold(boolean state)
  Parameters   state          true to enable bold text, otherwise false.
  Description  Enables or disables bold-mode for text output on this HtmlPage.

 protected void setFontName()
  Description  Sets the current font name to that in the Font returned by getNormalFont().

 protected void setFontName(String name)
  Parameters   name           The name of a font to use for text output.
  Description  Changes the font used for text output on this HtmlPage.

 protected void setFontSize()
  Description  Changes the size of the font currently used for text output on this HtmlPage
               to that in the Font returned by getNormalFont().

 protected void setFontSize(int size)
  Parameters   size           The new font size for the current font.
  Description  Changes the size of the font currently used for text output on this HtmlPage.

 protected void setItalic(boolean state)
  Parameters   state          true to enable italic text, otherwise false.
  Description  Enables or disables italic-mode for text output on this HtmlPage.

 protected void setNormalFont()
  Description  Changes the settings for the font used for text output on this HtmlPage to
               the values returned by getNormalFont().

 protected void setTeleFont()
  Description  Changes the settings for the font used for text output on this HtmlPage to
               the values returned by getTeleFont().

 protected void setUnderline(boolean state)
  Parameters   state          true to enable underlined text, otherwise false.
  Description  Enables or disables underline-mode for text output on this HtmlPage.

 protected void updateText(char[] text, int pos, int offset)
  Parameters   text           The new text object for this HtmlPage.
               pos            The position at which a change was made in text.
               offset         The number of characters added (+ve) or removed (-ve) at pos.
  Description  This method updates the text contained by a HtmlPage to reflect the addition
               or removal of a given number of characters at a specific position in the text.

HtmlPage.ClickListener

Synopsis

Interface Name:               library.html.HtmlPage.ClickListener
Super-interface:              None
Immediate Sub-interfaces:     None
Implemented By:               library.html.aTag  (in HtmlPageReader.java)

Description

Interface Declaration

public interface library.html.HtmlPage.ClickListener {
     public void mouseClicked(HtmlPage p);
}

Method

 public void mouseClicked(HtmlPage p)
  Parameters   p              The HtmlPage component from which the event originated.
  Description  This method is called when a mouse-click event occurs over an area of the
               display which is registered to a ClickListener object.

HtmlPageReader

Synopsis

Class Name:                   library.html.HtmlPageReader
Superclass:                   library.html.HtmlReader
Immediate Subclasses:         None
Interfaces Implemented:       None

Description

     HTML Tag       TagType Class       Description
     a              aTag                Anchor (href)
     b              bTag                Bold text
     blockquote     blockquoteTag       Block-quote
     body           bodyTag             Document body
     br             brTag               Line-break
     center         centerTag           Centre text
     dd             ddTag               Definition-list definition
     dl             dlTag               Definition-list
     dt             dtTag               Definition-list term
     em             emTag               Emphasise text
     head           headTag             Document head
     html           htmlTag             Document boundary
     h1..6          hTag                Headings
     i              iTag                Italic text
     img            imgTag              Image
     li             liTag               List item
     ol             olTag               Ordered list
     p              pTag                Paragraph-break
     pre            preTag              Pre-formatted text
     strong         strongTag           Strong text
     title          titleTag            Document title
     u              uTag                Underline text
     ul             ulTag               Un-ordered list

All Tag classes are required to implement the HtmlReader.Tag interface so that the parent HtmlReader is able to access them. The aTag class also implements the HtmlPage.ClickListener interface, which is used by an HtmlPage to implement the mouse-sensitive area of a hypertext link. Some of the Tag classes for container-tags implement the HtmlReader.Context interface so that they can be added to the page-context list maintained by an HtmlReader. For example, an liTag object is used for list-item tags in both ordered and un-ordered lists. When an olTag or ulTag object is activated to start a list during the document-drawing process, it adds itself to the page-context list. Then, when an liTag object is activated, it accesses the page-context list to determine which style of list-item should be drawn (numbers or bullets) by identifying the most recent olTag or ulTag entry in the list. Entries are removed from the page-context list by the closing olTag or ulTag objects at the end of each list.

Class Summary

public class library.html.HtmlPageReader extends library.html.HtmlReader {
     // Protected Instance Methods
     protected Class getDefaultTagClass();
     protected Class[] getTagClasses();
}

Protected Instance Methods

 protected Class getDefaultTagClass()
  Returns      A Class object representing a default HtmlReader.Tag object.
  Description  This method is called by an HtmlReader to obtain a Class object representing
               the HtmlReader.Tag class to use for blocks of plain text or for tags which
               have not been recognized by any other HtmlReader.Tag object.  Plain text is
               interpreted as any text not enclosed within '<' and '>' characters.

               The action method of the class returned by this method in an HtmlPageReader
               writes the text that it refers to onto an HtmlPage component using its current
               settings.

 protected Class[] getTagClasses()
  Returns      An array of Class objects representing HtmlReader.Tag objects.
  Description  This method is called by a HtmlReader to obtain an array of Class objects.
               These objects represent the HtmlReader.Tag objects that implement the
               functionality of the various HTML tags.  An HTML tag is interpreted as a
               series of characters that begins with a '<' character and ends with a '>'
               character.

               The action methods of the classes returned by this method in a HtmlPageReader
               implement the proscribed behaviour of HTML tags using an HtmlPage component.

HtmlReader

Synopsis

Class Name:                   library.html.HtmlReader
Superclass:                   None
Immediate Subclasses:         library.html.HtmlPageReader
Interfaces Implemented:       None

Description

To use an HtmlReader, first create a set of classes which implement the HtmlReader.Tag interface. These are the classes that actually perform the functions of the various HTML tags using a given HtmlPage object. Then create a subclass of HtmlReader and implement the abstract methods to return the names of these classes as Class objects. There are two such methods; getDefaultTagClass(), which should return an object for handling text or unrecognized tags; and getTagClasses(), which should return an array of objects which implement the supported HTML tags.

An HtmlReader parses a block of HTML text by slicing it into sequences of characters. An HtmlReader.Tag object is created to interpret each character-sequence, thereby creating a list of Tag objects which represents and interprets the text. To draw a document, an HtmlReader passes sequentially through its list calling each Tag object to perform its specific function using a HtmlPage object.

Character-sequences are interpreted as being either HTML tags or blocks of text. An HTML tag is assumed to start with a '<' character and end with a '>' character. The characters immediately following the initial '<' are used to identify the tag and determine which HtmlReader.Tag object to create from the array returned by the getTagClasses() method. If the tag is not recognized by any of the Tag objects in that array, the default Tag object returned by the getDefaultTagClass() method is created instead. A defaut Tag object is also created if the character sequence is a block of text; that is, if it does not start with '<' and end with '>'.

The method used to process HTML text to construct the HtmlReader.Tag object list is as follows:

Start at the first character in the text
Loop while any more characters remain -
  If sequence is '<' followed by zero or more characters and then '>'
    If the characters after '<' match a Tag from getTagClasses()
      Create the matching Tag object for text from '<' to '>'
    Otherwise  (unrecognized HTML tag)
      Create the Tag from getDefaultTagClass() for text from '<' to '>'
  Otherwise  (not a HTML tag - text)
    Create the Tag from getDefaultTagClass() for text up to next '<'
  Move to the next character after the current sequence
End Loop

Some HTML tags create a 'page-context' which affects the way that other tags are interpreted. For example, after an <ol> (ordered list) tag, all following <li> (list item) tags begin a new item in an ordered list, whereas after an <ul> (unordered list) tag, all <li> tags begin a new item in an unordered list. An HtmlReader enables Tag objects to obtain context-dependent information from each other by providing a list of references to Tag objects that implement the HtmlReader.Context interface. This can be used, for example, to determine the current list-depth when deciding on the style of bullet to use for a list item.

Class Summary

public abstract class HtmlReader {
     // Variables
     protected boolean body;
     protected boolean head;
     protected boolean html;
     protected boolean title;

     // Constructors
     protected HtmlReader();
     protected HtmlReader(char[] text);

     // Instance Methods
     public void addContext(Context t);
     public void drawText(HtmlPage p, Graphics g);
     public Context getContext(String id);
     public void removeContext(String id);
     public synchronized void setPlainText(char[] text);
     public synchronized void setText(char[] text);
     public synchronized void updateText(char[] text, int pos, int off);

     // Protected Instance Methods
     protected abstract Class getDefaultTagClass();
     protected abstract Class[] getTagClasses();
}

Variables

 protected boolean body
  Description  This flag is available for use by implementations of the HtmlReader.Tag
               interface.  It is set to true to indicate that HTML text is being interpreted
               as part of the document body (ie. before <head> and after </head>), otherwise
               it is set to false.

 protected boolean head
  Description  This flag is available for use by implementations of the HtmlReader.Tag
               interface.  It is set to true to indicate that HTML text is being interpreted
               as part of the document head (ie. after <head> and before </head>), otherwise
               it is set to false.

 protected boolean html
  Description  This flag is available for use by implementations of the HtmlReader.Tag
               interface.  It is set to true to indicate that HTML text is being interpreted
               as part of the HTML document (ie. after <html> and before </html>), otherwise
               it is set to false.

 protected boolean title
  Description  This flag is available for use by implementations of the HtmlReader.Tag
               interface.  It is set to true to indicate that HTML text is being interpreted
               as part of the document title (ie. after <title> and before </title>),
               otherwise it is set to false.

Constructors

 protected HtmlReader()
  Description  Constructs a HtmlReader object containing no text.

 protected HtmlReader(char[] text)
  Parameters   text           The initial text for this HtmlReader.
  Description  Constructs a HtmlReader object containing the given text.

Instance Methods

 public void addContext(Context t)
  Parameters   t              An object which implements the HtmlReader.Context interface.
  Description  Appends a Context object to the internal page-context list.

 public void drawText(HtmlPage p, Graphics g)
  Parameters   p              A HtmlPage for use by HtmlReader.Tag objects.
               g              A graphics context for output.
  Description  Displays the output represented by the current HTML text by calling an
               action method for each HtmlReader.Tag object in an internal list.  This
               list is created by passing a block of text to a HtmlReader constructor or
               to either the setText() or setPlainText() methods.

 public Context getContext(String id)
  Parameters   id             A string used to identify a Context object.
  Returns      A Context object with the specified context identification string.
  Description  Returns a reference to the last Context object added to the internal
               page-context list which has the specified identification string.

 public void removeContext(String id)
  Parameters   id             A string used to identify a Context object.
  Description  Removes the last Context object with the specified identification string
               from the internal page-context list.

 public synchronized void setPlainText(char[] text)
  Parameters   text           The new text for the HtmlReader.
  Description  Changes the text for this HtmlReader.  The new text is interpreted as a
               block of pre-formatted plain text and not as a series of tag-objects.
               This is achieved by creating a single HtmlReader.Tag object to represent
               the entire block of text.  This object can then be activated to produce the
               display by calling the drawText() method.

 public synchronized void setText(char[] text)
  Parameters   text           The new text for the HtmlReader.
  Description  Changes the text for this HtmlReader.  The new text is interpreted as a
               series of tag-objects, each represented by an instance of a class which
               implements the HtmlReader.Tag interface.  This method processes the given
               text to create an internal list of these HtmlReader.Tag objects.  These
               are then activated in sequence to produce the HTML display by calling the
               drawText() method.

 public synchronized void updateText(char[] text, int pos, int offset)
  Parameters   text           The new text for the HtmlReader.
               pos            The position at which a change was made in the current text.
               offset         The number of characters added (+ve) or removed (-ve) at pos.
  Description  Updates the text for this HtmlReader.  This method can be used in place of
               setText() when a small modification has been made at a specific location in
               the text currently represented by the HtmlReader.  Only the HtmlReader.Tag
               objects in the internal list which are affected by the change are updated.

Protected Instance Methods

 protected abstract Class getDefaultTagClass()
  Returns      A Class object representing a default HtmlReader.Tag object.
  Description  This method is called by a HtmlReader to obtain a Class object representing
               the HtmlReader.Tag class to use for blocks of plain text or for tags which
               have not been recognized by any other HtmlReader.Tag object.  Plain text is
               interpreted as any text not enclosed within '<' and '>' characters.

 protected abstract Class[] getTagClasses()
  Returns      An array of Class objects representing HtmlReader.Tag objects.
  Description  This method is called by a HtmlReader to obtain an array of Class objects.
               These objects represent the HtmlReader.Tag objects that implement the
               functionality of the various HTML tags.  An HTML tag is interpreted as a
               series of characters beginning with a '<' character and ending with a '>'
               character.

HtmlReader.Context

Synopsis

Interface Name:               library.html.HtmlReader.Context
Super-interface:              None
Immediate Sub-interfaces:     None
Implemented By:               library.html.lTagType, library.html.dlTag (HtmlPageReader.java)

Description

Interface Declaration

public abstract interface library.html.HtmlReader.Context {
     public abstract String getContextId();
}

Method

 public abstract String getContextId()
  Returns      A context identification string.
  Description  This method is called by an HtmlReader to identify a Context object.

HtmlReader.Tag

Synopsis

Interface Name:               library.html.HtmlReader.Tag
Super-interface:              None
Immediate Sub-interfaces:     None
Implemented By:               library.html.TagType (in HtmlPageReader.java)

Description

Interface Declaration

public abstract interface library.html.HtmlReader.Tag {
     public abstract boolean action(HtmlPage p, Graphics g);
     public abstract boolean drawTag(HtmlPage p, Graphics g);
     public abstract int getLength();
     public abstract int getPos();
     public abstract String getTagId();
     public abstract Tag init(char[] text, int pos, int length);
     public abstract boolean isTextTag();
     public abstract void setPos(int pos);
     public abstract void setText(char[] text);
}

Methods

 public abstract boolean action(HtmlPage p, Graphics g)
  Parameters   p              A HtmlPage object for producing output.
               g              A graphics context for drawing.
  Returns true if the bottom of the visible area of the document has been reached.
  Description  When its HTML mode is enabled, a HtmlReader calls the action() method of
               each Tag object in its internal list during the execution of its drawText()
               method.  It causes a Tag to perform its function using the given HtmlPage
               object.  If the method returns true, indicating that the bottom of the
               visible page area has been reached, the HtmlReader terminates the output
               process.

 public abstract boolean drawTag(HtmlPage p, Graphics g)
  Parameters   p              A HtmlPage object for producing output.
               g              A graphics context for drawing.
  Returns true if the bottom of the visible area of the document has been reached.
  Description  When its HTML mode is disabled, a HtmlReader calls the drawTag() method
               of each Tag object in its internal list during the execution of its
               drawText() method.  This causes a Tag to draw itself (ie. the text it
               contains) using the given HtmlPage object.  If the method returns true,
               indicating that the bottom of the visible page area has been reached,
               the HtmlReader terminates the output process.

 public abstract int getLength()
  Returns      The length of the tag text.
  Description  A HtmlReader calls this method to obtain the number of characters
               contained by a Tag.

 public abstract int getPos()
  Returns      The starting position of the tag.
  Description  This method is called by a HtmlReader to obtain the starting position
               of a Tag object in the HTML text.

 public abstract String getTagId()
  Returns      A tag identification string.
  Description  This method is called when a HtmlReader needs to identify a Tag object
               by type (eg. "head", "body", etc).

 public abstract Tag init(char[] text, int pos, int length)
  Parameters   text           A block of HTML text.
               pos            The starting position of the tag in text.
               length         The number of characters in the tag.
  Returns      A reference to this Tag object.
  Description  This method is called to initialize a Tag object after it has been created.
               Tag objects cannot be initialized by a constructor method since they are
               represented within a HtmlReader by an array of generic Class objects.  An
               actual Tag object is created by a call to the Class.newInstance() method,
               which does not take any parameters.

 public abstract boolean isTextTag()
  Returns      true if this is a text-tag, otherwise false.
  Description  This method is called to determine whether a Tag object represents plain
               text (true) or a HTML tag (false).

 public abstract void setPos(int pos)
  Parameters   pos            The new starting position of the tag.
  Description  This method is called to change the starting position of the tag in the
               HTML text.  It is used when the HTML text has been modified but the tag
               itself has not been changed.

 public abstract void setText(char[] text)
  Parameters   text           The new HTML text which contains this tag.
  Description  This method changes the HTML text referred to by the tag.  It is called
               to update all Tag objects when the text has been changed.

HtmlViewer

Synopsis

Class Name:                   library.html.HtmlViewer
Superclass:                   library.html.HtmlWindow
Immediate Subclasses:         None
Interfaces Implemented:       None

Description

Class Summary

public class library.html.HtmlViewer extends library.html.HtmlWindow {
     // Constructor
     public HtmlViewer(String title, char[] text, HtmlFile f);

     // Instance Methods
     public void actionPerformed(ActionEvent e);
     public void windowActivated(WindowEvent e);
     public void windowClosed(WindowEvent e);
}

Constructor

 public HtmlViewer(String title, char[] text, HtmlFile f)
  Parameters   title          The title for this window.
               text           The initial HTML text for this viewer.
               f              The parent HtmlFile object for this viewer.
  Description  Constructs a HtmlViewer window with the specified title to display the given
               text.  The parent HtmlFile object provides the additional functionality
               necessary to retrieve HTML files and to create and access other windows.
               The HtmlViewer window contains a HtmlPage component for processing HTML text.

Instance Methods

 public void actionPerformed(ActionEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.PolyMenuWindow.actionPerformed(ActionEvent)
  Description  Handles action events from the menu items and buttons on this window.

 public void windowActivated(WindowEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.html.HtmlWindow.windowActivated(WindowEvent)
  Description  Intercepts window-activated events to update the HTML display.

 public void windowClosed(WindowEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.PolyMenuWindow.windowClosed(WindowEvent)
  Description  Intercepts window-closed events to update the parent HtmlFile object.

HtmlWindow

Synopsis

Class Name:                   library.html.HtmlWindow
Superclass:                   library.PolyMenuWindow
Immediate Subclasses:         library.html.HtmlEditor, library.html.HtmlViewer
Interfaces Implemented:       java.awt.event.ActionListener

Description

Class Summary

public abstract class library.html.HtmlWindow extends library.PolyMenuWindow
  implements java.awt.ActionListener {
     // Variables
     protected HtmlFile htmlFile;
     protected HtmlPage reader;

     // Constructor
     protected HtmlWindow(String title, HtmlFile htmlFile);

     // Instance Methods
     public char[] getText();
     public void setFilename(String fname);
     public void setMessage(String text);
     public void setText(char[] text);
     public void setTitle(String title);
     public void windowActivated(WindowEvent e);
     public void windowClosing(WindowEvent e);
}

Variables

 protected HtmlFile htmlFile
  Description  This variable holds a reference to the parent HtmlFile object for this window.

 protected HtmlPage reader
  Description  This variables holds a reference to the HTML text reader component for this
               window.

Constructor

 protected HtmlWindow(String title, HtmlFile htmlFile)
  Parameters   title          The title for this window.
               htmlFile       The parent HtmlFile object for this window.
  Description  Creates a HtmlWindow object with the specified title.  The parent HtmlFile
               object provides the functionality to retrieve HTML files and to access other
               windows.

Instance Methods

 public char[] getText()
  Returns      The HTML text contained by this window.
  Description  This method returns the HTML text currently displayed by this HtmlWindow.

 public void setFilename(String fname)
  Parameters   fname          The filename associated with this window.
  Description  This method changes the string which is displayed in the filename area of
               this HtmlWindow.

 public void setMessage(String text)
  Parameters   text           A message to display in this window.
  Description  This method changes the string displayed in the message area of this
               HtmlWindow.

 public void setText(char[] text)
  Parameters   text           The new HTML text for this window.
  Description  This method changes the HTML text displayed by this HtmlWindow.

 public void setTitle(String title)
  Parameters   title          The new title for this window.
  Overrides    library.PolyMenuWindow.setTitle(String)
  Description  Changes the title for this HtmlWindow.

 public void windowActivated(WindowEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.PolyMenuWindow.windowActivated(WindowEvent)
  Description  Intercepts window-activated events to update the HtmlFile and refresh
               the display.

 public void windowClosing(WindowEvent e)
  Parameters   e              The event which has occurred.
  Overrides    library.DefaultWindow.windowClosing(WindowEvent)
  Description  This method intercepts window-closing events to give the user the
               opportunity to save any changes made to the HTML text before closing the
               HtmlWindow.