sub_arctic.lib
Class html_element

java.lang.Object
  |
  +--sub_arctic.lib.html_element

public class html_element

extends java.lang.Object

implements std_constraint_consts

This is a class for keeping around enough state process an HTML document. It is probably not of interest to anyone other than programmers implementing support for new HTML tags. If you want to use HTML in your sub_arctic interfaces, look at the text_flow class.

This class keeps track of various display characteristics and the current contextual information. It also uses methods to generate the various interactors that go on the display and these may be overridden to provide support for new (and more complex) HTML tags.

Basically this class keeps a static variable which is the current "state" of the HTML parse. It is ostensibly a stack but because it is searched it various orders, it is implemented with a vector. You can use "push_element" and pop_element to pop elements of this class onto and off this stack. Thus, when a <B> tag is seen a new html_element is pushed onto the stack to note the font change; when the matching </B> tag is reached, the element is popped off the stack.

The static methods calculate_font(), calculate_color(), and calculate_indent() are used to compute the current font, color and indentation level whenever the stack is manipulated. Thus the variable _current_font is always the up-to-date value to use for creating new screen text. If you put values in the public slots of the html_element for your specific subclass, these methods will pick those values up and add them to the current "context" for drawing operations.

The static method calculate_functions performs an important speed optimization that users of this code must understand. Since you want your new subclasses of html_element to work "in context" with other instances of other subclasses, you must "advertise" which functions of the API you implement. Once you have done so, calculate_functions will determine when to call your object and when to ignore it. This is a speed optimization which allows us to avoid walking the state stack every time we want to insert a word of text (or do any other parsing operation). For example, the subclass numbered_element advertises that it implements the method list_item_prefix because all it cares about doing is inserting the correct prefix when a new LI tag is seen. A more complex example might be if you wanted some "context dependent" tag handling (such as supporting new tags which are only valid inside other tags) you would advertise that you implement the handle_tag operation.

The way you advertise what functions you implement is by overriding the method functions_implemented and returning a set of constants (bitwise ored together) from the static constants below.

The biggest weakness of this object right now is that it really can't handle anything that spans rows. Once we finish putting up a row, we throw everything about it away. This is probably going to make it hard in the future to do "align=RIGHT" type of stuff in IMG tags since to make it look nice it should span multiple rows of text.

Field Summary

protected static int	_basic_font_size This is the basic font size that the layout algorithm is going to use
protected static html_element	_current_add_list_item This is a pointer to the html_element which is handling ADD_LIST_ITEM.
protected static html_element	_current_add_space This is a pointer to the html_element which is handling ADD_SPACE
protected static html_element	_current_add_word This is a pointer to the html_element which is handling ADD_WORD
protected static java.lang.StringBuffer	_current_buffer This is where we hold the string we are currently building.
protected static int	_current_buffer_width This is where we keep track of how wide the string is that we have buffered in _current_buffer.
protected static color_pair	_current_colors This is the current set of colors in use.
protected static column	_current_column This is the current column (which is really the current paragraph) we are building.
protected static html_element	_current_end_of_line This is a pointer to the html_element which is handling END_OF_LINE
protected static text_flow	_current_flow This the text flow we are actually working on.
protected static java.awt.Font	_current_font This is where we store the current font as we are doing a layout pass.
protected static html_element	_current_handle_amp This is a pointer to the html_element which is handling HANDLE_AMP.
protected static html_element	_current_handle_tag This is a pointer to the html_element which is handling HANDLE_TAG
protected static int	_current_indent This variable is the amount of indentation to use if a new line is called for.
protected static html_element	_current_list_item_prefix This is a pointer to the html_element which is handling LIST_ITEM_PREFIX.
protected static html_element	_current_paragraph_end This is a pointer to the html_element which is handling PARAGRAPH_END.
protected static html_element	_current_paragraph_start This is a pointer to the html_element which is handling PARAGRAPH_START
protected static row	_current_row This is the row that we are currently constructing.
protected static html_element	_current_string_end This is a pointer to the html_element which is handling STRING_END
protected static int	_inter_child_space This is the amount of space between children.
protected static java.util.StringTokenizer	_tokenizer This is the string tokenizer we are using.
static int	ADD_LIST_ITEM
static int	ADD_SPACE
static int	ADD_WORD
color_pair	colors This is the color_pair to use for drawing the text.
static int	END_OF_LINE
int	font_modifier this is a font modifier for things like bold and italic it gets ORed into the font modifier mask ...
java.lang.String	font_name use this for tags that actually change the base font
int	font_size use this for tags that SET the size of the font
static int	HANDLE_AMP
static int	HANDLE_TAG
int	indent_contribution this is the amount of indentation that is tag's contribution to future rows.
static int	LIST_ITEM_PREFIX
static int	PARAGRAPH_END
static int	PARAGRAPH_START
protected static java.util.Vector	state This is basically a data structure for keeping track of the current state of the HTML parse so we can image correctly.
static int	STRING_END

Constructor Summary

html_element()
Construct a html_element.

html_element(boolean b)
Construct an HTML element which is the root of the state stack by passing true here.

Method Summary

void	add_list_item() Insert a list item.
protected void	add_space() This function gets called to add whitespace to the display.
protected void	add_word(java.lang.String word) This function does a calculation to see if the new word will fit on this line.
static void	calculate_colors() This function calculates the current color to be drawing in.
protected static void	calculate_font() This function calculates the current font by walking the state vector.
static void	calculate_functions() This function calculates the current set of objects which are handling parsing operations.
protected static void	calculate_indent() This function computes the current indent level by walking down the state and adding up the current amount of indentation.
void	end_of_line(int shift, boolean hard) This function gets called to polish off the current line.
protected static void	finish() This function is called to handle the end of the HTML parse and general close down operations.
int	functions_implemented() Override this method to inform the system what parsing methods you handle.
protected void	handle_amp(java.lang.String tok) This function gets called to handle putting things it that are used with the ampersand notation.
protected void	handle_tag(java.lang.String tag) This function gets called to implement a tags behavior.
protected static void	init(text_flow tf, java.lang.String text) This function is called to initialize the parse and get the state stack set up for future things.
interactor	list_item_prefix() This function is called to generate a prefix interactor for list elements.
void	paragraph_end() Handle the end of the current paragraph.
void	paragraph_start() Handle the start of a new paragraph.
static void	parse() This is the main driver function for this parsing operation.
protected static html_element	pop_element() This function removes things from the state vector.
static html_element	previous_function(int fn, html_element elem) This function is useful for "backchaining" in the state stack to an "older" version of a function.
protected static void	push_element(html_element he) This function pushes things on the state vector.
static boolean	row_is_empty(row r) This function determines if a row is empty or not.
static void	set_basic_font_size(int s) We need this for people who want to have switches for setting the size.
void	string_end() This function is called to inform us that the current string needs to be inserted into the row.

Methods inherited from class java.lang.Object

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

Field Detail

LIST_ITEM_PREFIX

public static final int LIST_ITEM_PREFIX

HANDLE_TAG

public static final int HANDLE_TAG

ADD_SPACE

public static final int ADD_SPACE

ADD_WORD

public static final int ADD_WORD

END_OF_LINE

public static final int END_OF_LINE

ADD_LIST_ITEM

public static final int ADD_LIST_ITEM

HANDLE_AMP

public static final int HANDLE_AMP

STRING_END

public static final int STRING_END

PARAGRAPH_END

public static final int PARAGRAPH_END

PARAGRAPH_START

public static final int PARAGRAPH_START

state

protected static java.util.Vector state

This is basically a data structure for keeping track of the current state of the HTML parse so we can image correctly. We add html_elements to it and it gets walked to do things like generate the current font and the current indentation level.

_current_font

protected static java.awt.Font _current_font

This is where we store the current font as we are doing a layout pass.

_current_indent

protected static int _current_indent

This variable is the amount of indentation to use if a new line is called for.

_current_row

protected static row _current_row

This is the row that we are currently constructing.

_current_colors

protected static color_pair _current_colors

This is the current set of colors in use.

_current_flow

protected static text_flow _current_flow

This the text flow we are actually working on.

_current_column

protected static column _current_column

This is the current column (which is really the current paragraph) we are building.

_current_list_item_prefix

protected static html_element _current_list_item_prefix

This is a pointer to the html_element which is handling LIST_ITEM_PREFIX.

_current_handle_tag

protected static html_element _current_handle_tag

This is a pointer to the html_element which is handling HANDLE_TAG

_current_add_space

protected static html_element _current_add_space

This is a pointer to the html_element which is handling ADD_SPACE

_current_add_word

protected static html_element _current_add_word

This is a pointer to the html_element which is handling ADD_WORD

_current_end_of_line

protected static html_element _current_end_of_line

This is a pointer to the html_element which is handling END_OF_LINE

_current_add_list_item

protected static html_element _current_add_list_item

This is a pointer to the html_element which is handling ADD_LIST_ITEM.

_current_handle_amp

protected static html_element _current_handle_amp

This is a pointer to the html_element which is handling HANDLE_AMP.

_current_string_end

protected static html_element _current_string_end

This is a pointer to the html_element which is handling STRING_END

_current_paragraph_end

protected static html_element _current_paragraph_end

This is a pointer to the html_element which is handling PARAGRAPH_END.

_current_paragraph_start

protected static html_element _current_paragraph_start

This is a pointer to the html_element which is handling PARAGRAPH_START

_tokenizer

protected static java.util.StringTokenizer _tokenizer

This is the string tokenizer we are using.

_inter_child_space

protected static int _inter_child_space

This is the amount of space between children.

_current_buffer

protected static java.lang.StringBuffer _current_buffer

This is where we hold the string we are currently building. This is used for the performance optimization so we don't have so many labels.

_current_buffer_width

protected static int _current_buffer_width

This is where we keep track of how wide the string is that we have buffered in _current_buffer. This is to avoid having to consult the FontMetrics every time.

_basic_font_size

protected static int _basic_font_size

This is the basic font size that the layout algorithm is going to use

font_name

public java.lang.String font_name

use this for tags that actually change the base font

font_size

public int font_size

use this for tags that SET the size of the font

font_modifier

public int font_modifier

this is a font modifier for things like bold and italic it gets ORed into the font modifier mask ... since plain is zero you can just let plain be the value if you don't want anything snazzy

indent_contribution

public int indent_contribution

this is the amount of indentation that is tag's contribution to future rows. Its not an absolute amount but a contribution

colors

public color_pair colors

This is the color_pair to use for drawing the text. If you don't do anything, you'll get null and the system will use the default system colors.

Constructor Detail

html_element

public html_element()

Construct a html_element. This constructor makes all the fields have ignored values and this object is "dead" with respect to what functions it implements.

html_element

public html_element(boolean b)

Construct an HTML element which is the root of the state stack by passing true here. You should ONLY do this if you intend that all objects below this one in the state stack have their functions ignored (which is only likely to be useful if you are putting this at the bottom of the state stack. This still makes all the fields have their default (ignored) values.

Parameters:

boolean - b true if this object is a root object.

Method Detail

set_basic_font_size

public static void set_basic_font_size(int s)

We need this for people who want to have switches for setting the size. This will not take effect until the next parse of an HTML document.

Parameters:

int - s the new basic font size

init

protected static void init(text_flow tf,
                           java.lang.String text)

This function is called to initialize the parse and get the state stack set up for future things.

Parameters:

text_flow - tf the text_flow we are laying out

String - text the text to put in the text_flow

finish

protected static void finish()

This function is called to handle the end of the HTML parse and general close down operations.

push_element

protected static void push_element(html_element he)

This function pushes things on the state vector. It also forces a recalculation of the current indentation level and current font.

Parameters:

html_element - he the html element to push onto the state

pop_element

protected static html_element pop_element()

This function removes things from the state vector. It also forces a recalculation of the current indentation level.

Returns:

html_element although the element removed is returned, its not clear what use that is.

calculate_font

protected static void calculate_font()

This function calculates the current font by walking the state vector. It's policy is that it uses the most current font and the most current font size. It does a binary or of all font modifiers found. Note that the the state is walked from oldest element to newest element.

calculate_indent

protected static void calculate_indent()

This function computes the current indent level by walking down the state and adding up the current amount of indentation.

calculate_colors

public static void calculate_colors()

This function calculates the current color to be drawing in. If it doesn't find anything, it uses the default system colors.

calculate_functions

public static void calculate_functions()

This function calculates the current set of objects which are handling parsing operations. This basically walks backwards through the state stack looking at what functions each object is advertising that it implements. If one is found, it is put in the slot for whatever functions it implements. This process proceeds until the root is encountered or state stack is emptied.

previous_function

public static html_element previous_function(int fn,
                                             html_element elem)

This function is useful for "backchaining" in the state stack to an "older" version of a function. E.g. you are implementing some new context-dependent tags and you find a tag you are not interested in, just call this function with the HANDLE_TAG mask and yourself as the object to look behind and you'll get returned an object on which you can call the handle_tag method and hand it the tag it should process.

This function might also be useful for finding out who is "behind" you in the context. E.g. if you wanted to make the numbering tags do dots between subordinate lists. E.g. the second level list would 2.1, 2.2, 2.3, etc.

Parameters:

int - fn the function code to find (must be one of the static constants above.

html_element - elem the object to start looking "behind" (note that this function will return null if the element is the root).

Returns:

html_element element implementing the function in question.

parse

public static void parse()

This is the main driver function for this parsing operation.

row_is_empty

public static boolean row_is_empty(row r)

This function determines if a row is empty or not.

Parameters:

row - r the row to check

Returns:

boolean true if the row is empty

functions_implemented

public int functions_implemented()

Override this method to inform the system what parsing methods you handle.

list_item_prefix

public interactor list_item_prefix()

This function is called to generate a prefix interactor for list elements. It should return an interactor to put right in front of the actual item. Thus subclasses like the numbered_element return a label with the correct number in it for this function...

handle_tag

protected void handle_tag(java.lang.String tag)

This function gets called to implement a tags behavior. Since Java can't handle pointers to functions, you'll just have to check for each string and then add your code at the appropriate place.

add_space

protected void add_space()

This function gets called to add whitespace to the display.

add_word

protected void add_word(java.lang.String word)

This function does a calculation to see if the new word will fit on this line. If it does, it just adds it to the current row. If not, it creates a new line and adds the word to that line, without considering if it fits. (Note: This means that words that are wider than the width of the parent just get clipped.)

Parameters:

String - word the text of the word to add

string_end

public void string_end()

This function is called to inform us that the current string needs to be inserted into the row. This allows us (usually) to make one big label for the string, rather than having a string for each word (which really slows things down). If you are implementing tags which will insert things into the current row, you'll probably need to call this function to make sure all the text is there.

end_of_line

public void end_of_line(int shift,
                        boolean hard)

This function gets called to polish off the current line. It takes the current row and adds to the current column and then sets up a new row. If you supply an argument, that much is subtracted from the normal indentation for this row. This is highly useful for keeping things aligned in the presence of list items marking the paragraphs.

Parameters:

int - shift the amount you want subtracted from the indentation.

boolean - hard true if you are sure you want to force the end of a line, even if you are at the beginning of an empty row. Use false to indicate that you just want to start at the beginning of a line.

add_list_item

public void add_list_item()

Insert a list item. This ends up causing whatever the current object for this lists iteration to be inserted.

handle_amp

protected void handle_amp(java.lang.String tok)

This function gets called to handle putting things it that are used with the ampersand notation.

Parameters:

String - s the string that was between the ampersand and the semicolon

paragraph_end

public void paragraph_end()

Handle the end of the current paragraph. This function takes the current column and shoves it into the text flow. It is most commonly called as P is encountered.

paragraph_start

public void paragraph_start()

Handle the start of a new paragraph. This default of this just makes the current column be left justified. It is most commonly called when a P is encountered, but can be called by tags like CENTER.