Class Library: Other User-Interface Elements I (Public Classes)
WebPanel. The parent class to many other user-interface elements, this class is responsible for implementing EarthStones' AutoResTM features which transparently scale all user-interface components for the viewer's screen resolution. This is accomplished at the time the panel object is constructed by adapting the reshap() method for selectively scaling the panel's location and/or dimensions.
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; java.util.*; |
|
class declaration | public class WebPanel extends Panel implements Runnable | |
variables | protected Container webApp; | A reference to the object's main (host) Applet. |
protected int autoScale; | Takes values defined in Site: SCALE_NONE = 0 SCALE_SIZE = 1; SCALE_LOCATION = 2; SCALE_ALL = 3; |
|
protected boolean isLoaded = false; | Set in run() when panel's load() method has been called. | |
constructors | WebPanel(Container app) | |
WebPanel(Container app, int x, int y, int width, int height) | The typical constructor. Note that autoScale is set to SCALE_ALL in this case. | |
WebPanel(Container app, int x, int y, int width, int height,int auto) | Permits arbitrary choice of scaling. | |
methods | public void init() | Sets background color to white. |
The next three methods implement the class' Runnable interface. | ||
public void run() | 1) If isLoaded has not been set, calls
load() and sets isLoaded. 2) Calls update(). |
|
The next two methods must be overridden in subclasses. | ||
load() | Accomplishes the panel's initial loading. | |
update() | Updates any of the panel's elements to reflect the system's current state. | |
public void setAutoScale(int val) | Sets autoscale variable. | |
public int autoScale() | Returns autoscale variable. | |
protected int scale(int num, int scaleType) | This and the next two methods accomplish the scaling by calling the scaling methods of Web. | |
protected int scale(float num, int scaleType) | ||
protected int scale(int num) |
EventManagerPanel. This class manages all user-action events which occur in instances of DocumentPanel and FooterPanel (e.g., hyperlinks, hint message display upon mouse-over, form submission) which are not entirely handled locally (e.g., ImageButton and its subclasses manage its own events).
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; java.util.*; |
|
class declaration | public class EventManagerPanel extends WebPanel implements Runnable | |
variables | Variables used in managing Form events: | |
protected Form form = null; | A reference to the Form. | |
Variables used in managing hyperlink events: | ||
protected Vector links = new Vector(); | Stores a document's link objects which will be monitored for execution by this UI panel. | |
protected Link hotLink = null; | The link which fired. | |
Variables used in managing mouse-over hint events: | ||
protected Hint hotHint; | The activate hint's data. | |
protected TextPanel hintPanel; | The UI representation of the hint; will be reused for other "hot" hints. | |
protected Component hotComponent = null; | The component which fired the hint. | |
Private variables: | ||
private Thread waitThread; | Thread used to wait() before showing hint message. | |
private boolean mouseDown = false; | Set when mouseDown event occurs. | |
constructors | EventManagerPanel(Container app) | |
EventManagerPanel(Container app, int x, int y, int width, int height) | The typical constructor. Note that autoScale is set to SCALE_ALL in this case. | |
methods | public void init() | Calls setLayout(null). |
Messages for managing link events: Because the links are not real components they do not automatically receive mouse events on their own. Therefore this EventManagerPanel must use its own mouse methods (chiefly mouseMove()) to create pseudo mouseEnter and mouseExit events for the links. | ||
public synchronized boolean mouseMove(Event event, int x, int y) | Determine is mouse has entered or left a link. | |
public synchronized boolean mouseExit(Event event, int x, int y) | Mouse has left panel so we know it is now outside of hotLink. | |
public synchronized boolean mouseEnter(Event event, int x, int y) | Mouse has entered panel, but must determine if it is inside a link. | |
public boolean mouseDown(Event evt, int x, int y) | ||
public boolean mouseUp(Event evt, int x, int y) | ||
public Link hotLink(int x, int y) | Returns the active ("hot") link. | |
Methods for managing stat message display: | ||
protected void showStatMsg(String hint) | ||
protected void hideStatMsg() | ||
Methods for managing Form events. | ||
public synchronized boolean action(Event evt, Object arg) | Method listens for Button events and calls Form.execute() method. | |
public void setForm(Form frm) | Sets form instance variable. | |
Methods for managing hint events. | ||
public void run() | Called automatically when waitThread's start() method is called; starts thread which permits delay before showing hint. | |
public void showHint(Component component, int x, int y, Hint hint) | Shows hint panel. | |
public void updateHint(Component component, int x, int y, Hint hint) | Updates hint panel. | |
public void hideHint(Component component) | Hides hint panel. | |
private void setHintLocation(int x, int y) | This method resets the hint panel's position from coordinates (x, y) relative to the EventManagerPanel to a position relative to webApp. The position is then adjusted to stay within the webApp panel. | |
private Point locationRelApp() | This private helper method returns the location of this EventManagerPanel instance relative to webApp. | |
public void setForm(Form frm) | Sets form variable. |
CardPanel. This class implements Java's CardLayout class and allows one of a stack of alternative panels (i.e., "cards") to be displayed by name.
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; java.util.*; |
|
class declaration | public class CardPanel extends WebPanel | |
Variables used in managing mouse-over hint events: | ||
variables | Private variables: | |
private CardLayout layout; | The instance of Java's CardLayout object which presents the requested card to the viewer. | |
private Index cards; | An indexed list of cards currently defined for this CardPanel object stored as pairs (String name, Component comp). | |
private String currentState = null; | a string representing the CardPanel's current state; the getState() method extracts this information from the WebSite's current page. | |
private boolean sizeToChild = true; | if set, panel will automatically be scaled at run time to the size of its component | |
constructors | CardPanel(Container app) | |
CardPanel(Container app, int x, int y) | This form of the constructor is used when the panel's size will be set to that of its component at runtime. | |
CardPanel(Container app, int x, int y, int width, int height) |
This form preserves the specified panel dimenstions. | |
methods | public void init() | Creates instance of CardLayout and initializes index cards. This method is evoked by a call to super.init(). |
The next two methods must be overridden in classes: | ||
Component load(String name) | Method loads component object identified by name from disk. It is called by CardPanel's update() method if the panel needs updating. | |
String getState(); | Method extracts and returns string representing panel's current state from WebSite's current page. | |
The following 3 method returns values reflecting the CardPanel's current status. | ||
public String currentState() | Return panel's current state (i.e., the name of its current card). | |
public Index cards() | Returns the index of (String name, Component comp) cards. | |
public Component getComponent() | Returns the component of the current card. | |
public synchronized Component add(String name, Component comp) | Extends add() method of the CardLayout by adding an element to the index cards as well as adding a component to the stack. | |
public synchronized void update() | Responds to update message by: 1) Getting (new) state string 2) Comparing state to value of currentState 3) If currentState has not yet been set or if it is not the same as the new state, dispatches update() messages to its components section and chapter 4) Reseting currentState to state |
|
private synchronized void updateCard(String name) | Private helper method hides a card that is no longer needed and shows the desired card in its place. If the new card is not already in the cards index, it is first loaded from the disk. | |
public static void preload() | This method requires implementation only under the conditions of EarthStones' Version 2 website which required use of javascript calls and made it necessary to insure that certain objects were "preloaded". Not currently implemented. | |
public void preload(String name) | This method defined for convience in forcing the preloading of CardPanel components. It may be called by the preload() method. |
ImagePanel. Reads a .GIF or .JPG image file and displays it in the user interface.
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; |
|
class declaration | public class ImagePanel extends WebPanel | |
variables | protected String file; | The image source file. NOTE: the path to this file, if not fully specified, is assumed to be relative to HTML document in which this file reference is found. |
protected int width = 0; protected int height = 0; |
1) When set, these dimensions are used and
image is scaled accordingly, overriding its actual dimensions. 2) When default values (0)
are encountered instead, image dimensions depend upon the value of orient: 2a) When set to either prt (portrait) or lsc (landscape), default images sizes of 150 x 210 or 210 x 150 are used, respectively; 2b) otherwise (orient = null or ""), the images actual dimensions are used. Note: using the image's actual dimensions rather than supplying them or relying on defaults requires that the entire image be read before being rendered; for large images, supply dimensions when possible for faster rendering. |
|
protected String orient = null; | Image's specified orientation (must be supplied for progressive image rendering). | |
protected float scale = 1.00f; | Optional scale factor (in addition to resfactor). | |
protected int offset; | Set in ImageButton subclass to simulate movement upon mouse-click | |
protected Image image; | The image. | |
private int scWd, scHt; | Image's scaled dimensions | |
private URL url; | Image's URL. | |
private boolean waitForAll = false; | If set, waits for entire image before drawing. | |
constructors | ImagePanel(Container app) | Although ImagePanel inherits from WebPanel and makes internal use of its scaling routines, it does not utilize WebPanel's constructors which scale panel size at time of construction. Instead, it handles its own sizing within its paint method and implements a move method to handle panel location. |
ImagePanel(Container app, String fl) | This form of the constructor is used for small graphic images. Wait for entire image before drawing. | |
ImagePanel(Container app, String fl, String ort) | The following forms use the default setting waitForAll = false. Must either specify image dimensions or use defaults defined by the setDefaultSize() method. |
|
ImagePanel(Container app, String fl, int wid, int ht) | ||
ImagePanel(Container app, String fl, int wid, int ht, float sc) | ||
ImagePanel(Container app, String fl, String ort, int wid, int ht, float sc) | The following two syntaxes are used in Graphic. They are the most general in the sense that they use the values for wid, ht, and sc if specified or supply defaults when these are not given. | |
ImagePanel(Container app, String fl, String
ort, int wid, int ht, float sc, boolean insrt) |
The boolean insrt specifies whether or not the image is inserted into a text document; see setDefaultSize() for implications of setting this parameter. | |
methods | public void init() | Sets offset = 0. |
public void setDefaultSize(String ort, boolean isInsert) | Sets default image sizes are as follows: 1) If ort is specified: 1a) if isInsert = true: 150 x 210 (ort = "PTR" 210 x 150 (ort = "LSC") 1b) Otherwise 300 x 420 (ort = "PTR" 420 x 300 (ort = "LSC") 2) Otherwise, sets waitForAll which will use image's actual dimensions but requires that rendering wait until image is fully loaded. |
|
public void load(String fl, String ort) | Calls: setDefaultSize(ort, false); setFile(fl); |
|
public void setFile(String fl) | 1) Sets this.file = fl. 2) Sets private variable url to resource pointed to by file using documentBase (i.e., applet tag's HTML document file) as the base for setting relative path. If error ocurs in setting URL, prints message to Java console. 3) Calls setImage(url). |
|
public void setImage(URL aUrl) | Loads image (uses private method waitForImage()) and calls setSize(). | |
private void waitForImage(Image img) | If waitForAll is set, uses MediaTracker to notify that image has loaded. | |
public void setSize() | Sets scales dimensions scWd, scHt for image and resizes ImagePanel to these dimensions. | |
public void update(Graphics g) | Overrides default update() method to reduce image flicker. | |
public void paint(Graphics g) | Draws scaled image. | |
public void move(int x, int y) | Uses WebPanel's scaling methods to override panel's default move() method and automatically scale its location for the user's screen resolution. | |
public Image getImage() | Returns image variable. | |
public int scWd() | Returns scWd variable. | |
public int scHt() | Returns scHt variable. | |
public void setWaitForAll(boolean val) | Sets waitForAll variable. |
ImageButton. Turns an ImagePanel into a fully-functioning button which "depresses" when clicked and executes a user-defined action. The user is responsible for defining the appropriate action() method (typically done in the panel which creates the instance of ImageButton).
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; |
|
class declaration | public class ImageButton extends ImagePanel | |
variables | protected Hint hint = null; | These variables implement hint message upon mouse-over. |
protected String statMsg = ""; | The string displayed in browser's status panel upon mouse-over. | |
protected boolean autoStat = true; | when set, statMsg is automatically set to hint message. | |
private boolean mouseDown = false; | Set when mouse-down event occurs. | |
private int off = 0; | Initializes mouse-down offset to its "up" position. | |
constructors | ImageButton(Container app, String fl, String hnt) | Specifies an image file fl and a hint/stat message string. |
methods | public boolean mouseDown(Event evt, int x, int y) | Sets offset to simulate button movement and mouseDown, repaints panel, hides hint and statMsg, and posts an ACTION_EVENT message; this message must be handled in by an action() method in the panel which creates the ImageButton. |
public boolean mouseUp(Event evt, int x, int y) | Resets offset and mouseDown, repaints panel. | |
public synchronized boolean mouseMove(Event event, int x, int y) | Calls updateHint(). | |
public boolean mouseEnter(Event event, int x, int y) | If mouseDown is false, calls showHint() and showStatMsg() and sets HAND_CURSOR. | |
public boolean mouseExit(Event event, int x, int y) | Calls hideHint() and hideStatMsg() and resets cursor to DEFAULT_CURSOR. | |
protected void showHint(int x, int y) | Hides any hint that might be showing and calls the showHint() method of the EventManagerPanel pnl, passing as parameters the value returned by hotComponent() as well as the point (x, y) translated into pnl's coordinate frame. | |
protected void updateHint(int x, int y) | Calls the updateHint() method of the EventManagerPanel pnl, passing as parameters the value returned by hotComponent() as well as the point (x, y) translated into pnl's coordinate frame. | |
protected void hideHint() | Calls the hideHint() method of the EventManagerPanel pnl, passing as a parameters the value returned by hotComponent(). | |
protected void showStatMsg() | Uses method AppletContext.showStatus() to display appropriate status message. | |
protected void hideStatMsg() | Uses method AppletContext.showStatus() to display empty string in status panel. | |
public void paint(Graphics g) | Repaints screen using appropriate value of offset. | |
private Component hotComponent() | This method accounts for the fact that the ImageButton may be part of a CardPanel layout and insures that the "hotComponent" coordidnates passed to the EventManagerPanel are correct. | |
public void setAutoStat(boolean val) | Sets autoStat variable. | |
public Hint getHint() | Returns the hint object. | |
public void setStatMsg(String msg) | Sets the statMsg variable. |
WebChoice. Enhances Java's Choice (listbox) component by adding the transparent scaling features found in WebPanel as well as implementing a mouse-over hint message.
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; java.util.*; |
|
class declaration | class WebChoice extends Choice | |
constants | public static final int ht[] = {8, 10, 10,
12, 13, 13, 14, 16,19, 20, 20, 21, 23, 23, 25, 25, 27, 27, 28, 30, 31} |
Maps font sizes sz = 0,...,20 to the values ht[sz]. |
variables | protected Container webApp = null; | Reference to the main (host) applet. |
protected Hint hint = null; | These variables implement hints. | |
protected String statMsg = ""; | ||
protected boolean autoStat = true; | ||
private boolean mouseDown = false; | Set when mouseDown event occurs. | |
private String currentState = null; | String maintains the WebChoice's current selection. | |
constructors | WebChoice(Container app, String hnt) | Specifies a hint/stat message string. |
methods | public void init() | Sets WebChoice's font to Web's captionFontSize. |
public int getHeight() | If WebChoices' font size sz <=20, returns ht[sz]; otherwise returns sz + 10. | |
public void resize(int width, int height) | Resizes component height to getHeight()
calling super.resize(width, getHeight()). |
|
public String getState() | Extracts and returns string representing WebChoice's current state from WebSite's current page. | |
public void update() | Responds to update message by: 1) Getting (new) state string 2) Comparing state to value of currentState 3) If currentState has not yet been set or if it is not the same as the new state, attepmts to set WebChoice's state to currentState. 4) Reseting currentState to state |
|
public boolean mouseDown(Event evt, int x, int y) | Sets mouseDown and hides hint and statMsg. Note: does not post ACTION_EVENT here; handled in parent class. | |
public boolean mouseUp(Event evt, int x, int y) | Resets mouseDown. | |
public boolean mouseMove(Event event, int x, int y) | Calls updateHint(). | |
public boolean mouseEnter(Event event, int x, int y) | If mouseDown is false, calls showHint() and showStatMsg() and sets HAND_CURSOR. | |
public boolean mouseExit(Event event, int x, int y) | Calls hideHint(), hideStatMsg(), and resets cursor to DEFAULT_CURSOR. | |
protected void showHint(int x, int y) | Calls the showHint() method of the EventManagerPanel pnl, passing as parameters the value returned by hotComponent() as well as the point (x, y) translated into pnl's coordinate frame. | |
protected void updateHint(int x, int y) | Calls the updateHint() method of the EventManagerPanel pnl, passing as parameters the value returned by hotComponent() as well as the point (x, y) translated into pnl's coordinate frame. | |
protected void hideHint() | Calls the hideHint() method of the EventManagerPanel pnl, passing as a parameters the value returned by hotComponent(). | |
protected void showStatMsg() | Uses method AppletContext.showStatus() to display appropriate status message. | |
protected void hideStatMsg() | Uses method AppletContext.showStatus() to display empty string in status panel. | |
public Hint getHint() | Returns hint object. | |
private Component hotComponent() | This method accounts for the fact that the WebChoice may be part of a CardPanel layout and insures that the "hotComponent" coordidnates passed to the EventManagerPanel are correct. | |
public void setAutoStat(boolean val) | Sets autoStat variable. | |
public void setStatMsg(String msg) | Sets statMsg variable. |
TextPanel. Renders a Paragraph object as a panel in the user-interface.
package | earthstones | |
import | java.awt.*; java.applet.*; java.net.*; java.io.*; java.util.*; |
|
class declaration | public class TextPanel extends Panel | |
variables | protected Container webApp = null; | Reference to the main (host) applet. |
private Paragraph paragraph = null; | Paragraph object rendered by TextPanel. | |
private TextString orphan = null; | Contains that part of paragraph that does not fit on this TextPanel. | |
private int ruleHeight = 0; | Ruling line height above and below this TextPanel's paragraph. | |
private Color ruleColor = Color.black; | Ruling line color. | |
private Color bgColor = Color.white; | TextPanel's background color. | |
private boolean fillToLineMax = false; | If set, fill color extends only to maximum line width lineMax rather than to paragraph width. Set when rendering a hint panel. | |
private int lineMax = 0; | The maximum text line width in the paragraph. | |
boolean nullString = false; | Set in wrapText() under rare circumstances to prevent extra blank line after a paragraph. | |
private boolean fullLine; | This private variables saves the variable TextString.fullLine which, when set, specifies that the TextString will be rendered as full lines only and any remainder will be added to the paragraph's tail. Set in Paragraph.findBox() when an embedded box element is encountered. | |
private int thisString = 0; | Zero-based index of TextElement's position within Paragraph. | |
private boolean tooLong = false; | Signals that panel height has been exceeded. | |
private int maxascent = 0; | These variables are set by a call to setFontHeightMetrics() before any fontsare set in drawParagraph(). | |
private int maxdescent = 0; | ||
private int fontheight = 0; | ||
private int leading = 0; | ||
private int addabove = 0; | ||
private int addbelow = 0; | ||
private Point hot; | Used by drawParagraph() and wrapText() methods to save upper-left point of a hot-spot (hyperlink). | |
private int savindent = 0; | Saves indent after bullet. | |
constructors | TextPanel(Container app, int width) | Specifies the width of the TextPanel into which the paragraph is to be rendered. |
methods | public void init() | Sets panel's background color to bkcolor; |
These two forms of setParagraph() method provide the link between the data structure Paragraph and its user-interface representation TextPanel. | ||
public synchronized void setParagraph(Paragraph p) | Set's TextPanel's paragraph variable to p and calls setHeight(Document.INF). | |
public synchronized void setParagraph(Paragraph p, int ht) | Called in paragraph.resize(). Set's TextPanel's paragraph variable to p and calls setHeight(ht). | |
public synchronized Dimension setHeight(int ht) | 1) Resizes Textpanel to (paragraph.width(),
ht). 2) Calls drawParagraph() to render paragraph in offscreen graphic context; 3) Resizes TextPanel to dimensions of the offscreen context. |
|
private synchronized Point drawParagraph(Graphics g) | Renders paragraph in TextPanel and returns its end point. This is the main text-rendering method. | |
private void setFontHeightMetrics() | Called in drawParagraph() prior to setting fonts so that these parameters will be used subsequently in setting font parameters. Sets font parameters to the maximum value for fonts specified within paragraph (e.g., fontheight is set to the maximum value of fontheight for all fonts specified within paragraph.) | |
private void drawRules(Graphics g) | May be called by drawParagraph() to render ruling lines above and below paragraph. | |
public Point drawBitmap(Graphics g, String
map, int x, int y) |
May be called by drawParagraph() to render any inline bitmap images (i.e., bullet characters) in paragraph. Note: Other images are treated as Box objects around which text is wrapped rather than appear in-line. | |
private void drawUnderline(Graphics g, int x, int y, String udl) | This method implements EarthStones underline text style which is not supported in Java 1.02. The string parameter udl is passed here only to determine the line's length | |
public Point wrapText(Graphics g, String
text, int xoffset, int x, int y, int boundx, int boundy) |
This method does the work of wrapping the string text at offset xoffset within the specified bounding rectangle [(x, y) and (boundx, boundy)] and returns the point (boundx, boundy). It also sets multi-line hyperlinks. | |
public void paint(Graphics g) | Calls drawParagraph(). | |
These methods set and return (get) TextPanel's private variables. | ||
public int maxdescent() | ||
public int maxascent() | ||
public int fontheight() | ||
public int addabove() | ||
public int lineMax() | ||
public boolean fillToLineMax() | ||
public void setLineMax(int val) | ||
public void setFontheight(int val) | ||
public void setMaxascent(int val) | ||
public void setMaxdescent(int val) | ||
public void setLeading(int val) | ||
public void setAddabove(int val) | ||
public void setAddbelow(int val) | ||
public void setRuleHeight(int ht) | ||
public void setRuleColor(Color clr) | ||
public void setBgColor(Color clr) | ||
public void setFillToLineMax(boolean val) |
WebFont. Enhances Java's Font class by including a color attribute and adding underline to the font style list.
package | earthstones | |
import | java.awt.*; java.applet.*; java.util.*; |
|
class declaration | public class WebFont extends Font | |
class constants | public final static int UNDERLINE = 4; | Adds a constant for the underline style to those already defined by font: PLAIN, BOLD, and ITALIC. Note that this extension is consistent with the additive feature of these font attributes. For example, BOLD + UNDERLINE (i.e., 5) results in both bold and underline style attributes being rendered. |
public static final int htmlSizeToPoints[] = {9, 12, 15, 18, 21, 27, 36, 54}; | Translates HTML's font sizes 0,...,7 into comparable Java font sizes. Note. The conversion between HTML size and a font's point size suggested by Microsoft's FrontPage editor results in Java fonts that are too small, so the following are used instead. | |
variables | protected Color color = Color.black; | The font's color. This property is added to the name, style, and size properties defined by Font. |
constructors | WebFont() | |
WebFont(String aName, int aStyle, int aSize) | ||
WebFont(String aName, int aStyle, int aSize, Color aColor) | ||
static methods | public static int pointsToHtmlSize(int pts) | This static method inverts the htmlSizeToPoints[] array to convert a Java point size into the corresponding HTML size. |
public static int averageCharWidth(FontMetrics fm) | This method computes an average over the array of character widths returned by the FontMetrics method getWidths(). It is used by the Field class in sizing its user-interface elements. | |
methods | public boolean isUnderline() | Returns true if the WebFont's underline style is set in a manner with the methods defined by Font (e.g., is Bold()). |
public int notGreek(String face, int size) | Prevents returning a font size which is so
small that it will be rendered as "Greek" light gray text. For Courier and
TimesRoman fonts, a minimum size of 9 is returned; for Helvetica the value is 7. |
|
public WebFont setAttrib(Index fontAttrib) | Uses the Index attrib of name-value pairs from the link's <font> or <style> tag to set the font's variables. | |
These methods set or return WebFont's variables. | ||
public String name() | Returns name (font face) variable. | |
public int style() | Returns style variable. | |
public int size() | Returns size variable. | |
public Color color() | Returns color variable. | |
public WebFont setColor(Color clr) | Sets color variable. | |
public WebFont setStyle(int stl) | Increments current font style by stl (i.e., adds style attribute stl to current style). | |
public WebFont clearStyle(int stl) | Decrements current font style by stl (i.e., removes style attribute stl from current style). | |
public WebFont setSize(int sz) | Sets size variable. | |
public WebFont setFontFace(String face) | Sets name variable. | |
public Component setComponentFont(Component comp) | Sets the font of the Component object comp to the current font. This method is called by the Field class to set the fonts of its component elements. |