org.jhotdraw.contrib.html
Class HTMLTextAreaFigure

java.lang.Object
  extended by org.jhotdraw.standard.AbstractFigure
      extended by org.jhotdraw.figures.AttributeFigure
          extended by org.jhotdraw.contrib.TextAreaFigure
              extended by org.jhotdraw.contrib.html.HTMLTextAreaFigure
All Implemented Interfaces:
java.io.Serializable, java.lang.Cloneable, java.util.EventListener, AttributeContentProducerContext, ContentProducerContext, FigureContentProducerContext, HTMLContentProducerContext, Figure, FigureChangeListener, TextHolder, Storable

public class HTMLTextAreaFigure
extends TextAreaFigure
implements HTMLContentProducerContext, FigureChangeListener

An HTMLTextAreaFigure contains HTML formatted text.
Formatting is done internally by a JLabel component, so all display features and constrains that apply for a JLabel apply also for an HTMLTextAreaFigure, including text and images, as in any Web browser, even allowing for contents residing on external Web sources. But don't forget that this is NOT a Web browser, so HTML contents cannot be standard Web pages with headers, stylesheets, javascript and who knows what else, just plain down to earth HTML code.

In order to automatically integrate "external" attributes like FillColor, FontName, etc, HTMLTextAreaFigure encapsulates the text the user types in the editor within a table with a single cell occupying the whole area.
Here is what the HTML code passed to the JLabel looks like:
<html>
<table border='0' width='area.width' height='area.height' cellpadding='0' cellspacing='0' bgcolor='&FillColor;'>
<tr>
<td width='100%'>
<font face='&FontName;' color='&TextColor;' size='&FontSize;'>
<!-- add italic and bold attributes if required-->
<i>
<b>
============>> User's contents go here <============
<!-- close italic and bold attributes if required -->
</b>
</i>
</font>
</td>
</tr>
</table>
</html>

It is possible to write raw HTML code by calling setRawHTML(true). In that case no tags are issued.
The user is then responsible for applying the figure attributes and in general is responsible for the whole display. This setting can be dynamically toggled as needed.
Note that JLabel resets the font to its own default whenever it encounters an HTML structure, like a table or a header tag. I couldn't find a workaround for what can/should be called a bug. Normal browsers do not behave like this.

Internal attributes like FillColor or FontName are exposed as special SGML entities using the standard SGML entity notation, ex: &FillColor;.
Any attribute associated to the figure can be used and will be replaced with an appropriate value from a ContentsProducer (see below) or its toString() value if no specific ContentProducer is defined.

The HTML display and layouting can be time consuming, quite fast in most cases, unless the HTML structure is complicated. This can become a serious penalty when working with a large number of complicated figures.
To help in this issue HTMLTextAreaFigure offers two display modes, DirectDraw, where the HTML layout logic is executed every time the figure is displayed, and BufferedDraw, where HTMLTextAreaFigure creates an in-memory image of the resulting layout and uses the image for fast display until a change requires to regenerate the image.
The BufferedDraw mode is as fast as an image display can be, but it consumes more memory than the DirectDraw mode, which in turn is slower.
The setting is specific to each figure instance and it can be dynamically toggled at any time, so it is possible to fine tune when and which figures use either one of the drawing modes.

Remember the attributes based SGML entities?
If you set the figure to be read only, so not allowing the user to directly edit the HTML contens, then it is possible to use HTMLTextAreaFigures to produce very elaborate and complex information layout.
You create HTML templates for each figure layout you want to use and set them as the text of the figure. Within the template text you place field names wherever needed as you would for a Web page, then each figure using the template associates the field values as attributes of the figure. The attribute exposure feature will substitute the entity names with the current attribute's value.
Please refer to the accompanying sample program to see in detail the multiple ways this feature can enhance your drawings.

ContentProducers
As stated above, entities referenced in the HTML template code are replaced by their current value in the drawn figure. The values themselves are provided by ContentProducers.
For a detailed description of ContentProducers please refer to their own documentation, but to make it simple, a ContentProducer is an object that implements the method getContent and is registered to produce content for either specific entities, or entity classes.
An entity class is the class of the attribute containing its value, ie: an attribute containing a URL has class URL (attribute.getClass()), and an URLContentProducer can be associated to it so that when the layout needs the entity's value, the producer's getContent() method is called and the returned value (ex: contents from a Web page, FTP file or disk file) is used to replace the entity in the displayed figure.
The ContentProducer can return either a String, in which case it is used as is, or another Object. In the later case HTMLTextAreaFigure will continue calling registered ContentProviders depending on the class of the returned Object until it either gets a final String, or null. If null then the entity is considered as unknown and left as is in the displayed text. To make it dissapear alltogether the producer should return an empty String.

HTMLTextAreaFigure registers default ContentProducers: AttributeFigureContentProducer for the intrinsic attributes of the figure (height, width, font name, etc.), URLContentProducer for URL attributes, HTMLColorContentProducer for HTML color encoding and for embedded TextAreaFigure and HTMLTextAreaFigure classes. That's right, you can embed a TextAreaFigure or HTMLTextAreaFigure contents inside an HTMLTextAreaFigure recursively for as many levels as your CPU and memory will allow.
For instance, the main figure can consists of an HTML table where each cell's contents come from a different HTMLTextAreaFigure.

Version:
<$CURRENT_VERSION$>
Author:
Eduardo Francos - InContext
See Also:
Serialized Form

Field Summary
static char END_ENTITY_CHAR
          End marker for embedded attribute values
static char ESCAPE_CHAR
          Marker escape character
static char START_ENTITY_CHAR
          Start marker for embedded attribute values
 
Fields inherited from interface org.jhotdraw.framework.Figure
POPUP_MENU
 
Constructor Summary
HTMLTextAreaFigure()
          Constructor for the HTMLTextAreaFigure object
 
Method Summary
 void basicDisplayBox(java.awt.Point origin, java.awt.Point corner)
          Sets the display box for the figure
 java.lang.Object clone()
          Clones a figure and initializes it
 boolean containsPoint(int x, int y)
          True if the figure contains the point.
 void draw(java.awt.Graphics g)
          Draws the figure in the given graphics.
 void drawBackground(java.awt.Graphics g)
          Draws the background for the figure.
 void drawFrame(java.awt.Graphics g)
          Draws the frame around the text.
 void figureChanged(FigureChangeEvent e)
          handles frame figure's changed events.
 void figureInvalidated(FigureChangeEvent e)
          handles frame figure's invalidated events
 void figureRemoved(FigureChangeEvent e)
          handles frame figure's invalidatedremoved events.
 void figureRequestRemove(FigureChangeEvent e)
          handles frame figure's remove requests events.
 void figureRequestUpdate(FigureChangeEvent e)
          handles frame figure's update requests events.
 java.awt.Polygon getPolygon()
          Makes a polygon with the same shape and dimensions as the current figure
 Figure getRepresentingFigure()
          Usually, a TextHolders is implemented by a Figure subclass.
 HandleEnumeration handles()
          Returns an iterator of standard sizing handles to manipulate the figure
 boolean isRawHTML()
          Gets the rawHTML attribute of the HTMLTextAreaFigure object.
 void moveBy(int dx, int dy)
          Moves the figure by the specified displacement
 void read(StorableInput dr)
          Reads the figure from StorableInput
 ContentProducer registerContentProducer(java.lang.Class targetClass, ContentProducer producer)
          Registers a specific content producer for the target class
 void setAttribute(FigureAttributeConstant name, java.lang.Object value)
          A text area figure uses the "LeftMargin", "RightMargin", "TopMargin", "BottomMargin", "TabSize", "FontSize", "FontStyle", and "FontName" attributes
 void setFrameFigure(Figure newFrameFigure)
          Sets the frameFigure attribute of the HTMLTextAreaFigure object
 void setIntrinsicContentProducer(ContentProducer newIntrinsicContentProducer)
          Sets the IntrinsicContentProducer attribute of the HTMLTextAreaFigure object
 void setRawHTML(boolean newRawHTML)
          Sets the rawHTML attribute of the HTMLTextAreaFigure object
 void setUseBufferedDraw(boolean newUseBufferedDraw)
          Sets the useBufferedDraw attribute of the HTMLTextAreaFigure object
 void setUseDirectDraw(boolean newUseDirectDraw)
          Sets the useDirectDraw attribute of the HTMLTextAreaFigure object
 void unregisterContentProducer(java.lang.Class targetClass, ContentProducer producer)
          Unregisters a registered content producer.
 boolean usesBufferedDraw()
          Gets the usesBufferedDraw attribute of the HTMLTextAreaFigure object
 boolean usesDirectDraw()
          Gets the usesDirectDraw status of the HTMLTextAreaFigure object
 void write(StorableOutput dw)
          Writes the figure to StorableOutput
 
Methods inherited from class org.jhotdraw.contrib.TextAreaFigure
acceptsTyping, connect, createFont, disconnect, displayBox, getAttribute, getFont, getText, getTextColor, isEmpty, isFontDirty, isReadOnly, isSizeDirty, isTextDirty, overlayColumns, setAttribute, setFont, setFontDirty, setReadOnly, setSizeDirty, setText, textDisplayBox
 
Methods inherited from class org.jhotdraw.figures.AttributeFigure
getAttribute, getDefaultAttribute, getDefaultAttribute, getFillColor, getFrameColor, initDefaultAttribute, setDefaultAttribute
 
Methods inherited from class org.jhotdraw.standard.AbstractFigure
addDependendFigure, addFigureChangeListener, addToContainer, canConnect, center, changed, connectedTextLocator, connectionInsets, connectorAt, connectorVisibility, decompose, displayBox, displayBox, figures, findFigureInside, getDecoratedFigure, getDependendFigures, getTextHolder, getZValue, includes, invalidate, listener, release, removeDependendFigure, removeFigureChangeListener, removeFromContainer, setZValue, size, visit, willChange
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.jhotdraw.contrib.html.AttributeContentProducerContext
getAttribute
 
Methods inherited from interface org.jhotdraw.contrib.html.FigureContentProducerContext
displayBox, getFont
 

Field Detail

START_ENTITY_CHAR

public static final char START_ENTITY_CHAR
Start marker for embedded attribute values

See Also:
Constant Field Values

END_ENTITY_CHAR

public static final char END_ENTITY_CHAR
End marker for embedded attribute values

See Also:
Constant Field Values

ESCAPE_CHAR

public static final char ESCAPE_CHAR
Marker escape character

See Also:
Constant Field Values
Constructor Detail

HTMLTextAreaFigure

public HTMLTextAreaFigure()
Constructor for the HTMLTextAreaFigure object

Method Detail

clone

public java.lang.Object clone()
Clones a figure and initializes it

Specified by:
clone in interface Figure
Overrides:
clone in class AbstractFigure
Returns:
Description of the Return Value
See Also:
Figure.clone()

basicDisplayBox

public void basicDisplayBox(java.awt.Point origin,
                            java.awt.Point corner)
Sets the display box for the figure

Specified by:
basicDisplayBox in interface Figure
Overrides:
basicDisplayBox in class TextAreaFigure
Parameters:
origin - origin point
corner - corner point
See Also:
Figure

handles

public HandleEnumeration handles()
Returns an iterator of standard sizing handles to manipulate the figure

Specified by:
handles in interface Figure
Overrides:
handles in class TextAreaFigure
Returns:
Description of the Return Value
See Also:
Handle

containsPoint

public boolean containsPoint(int x,
                             int y)
True if the figure contains the point. The call is relayed to the frame figure

Specified by:
containsPoint in interface Figure
Overrides:
containsPoint in class AbstractFigure
Parameters:
x - Description of the Parameter
y - Description of the Parameter
Returns:
Description of the Return Value

moveBy

public void moveBy(int dx,
                   int dy)
Moves the figure by the specified displacement

Specified by:
moveBy in interface Figure
Overrides:
moveBy in class TextAreaFigure
Parameters:
dx - Description of the Parameter
dy - Description of the Parameter

draw

public void draw(java.awt.Graphics g)
Draws the figure in the given graphics. Draw is a template method calling drawBackground followed by drawText then drawFrame.
HTMLTextAreaFigure displays in a different order tahn most figures to avoid smearing of the border when enclosed in a weird frame figure.
Also, there is no such thing as a transparent background so we always draw it.

Specified by:
draw in interface Figure
Overrides:
draw in class TextAreaFigure
Parameters:
g - Description of the Parameter

drawFrame

public void drawFrame(java.awt.Graphics g)
Draws the frame around the text. It gets the shape of the frame from the enclosing figure

Overrides:
drawFrame in class TextAreaFigure
Parameters:
g - The graphics to use for the drawing
See Also:
AttributeFigure.draw(java.awt.Graphics)

drawBackground

public void drawBackground(java.awt.Graphics g)
Draws the background for the figure. It gets the shape of the frame from the enclosing figure

Overrides:
drawBackground in class TextAreaFigure
Parameters:
g - The graphics to use for the drawing
See Also:
AttributeFigure.draw(java.awt.Graphics)

usesDirectDraw

public boolean usesDirectDraw()
Gets the usesDirectDraw status of the HTMLTextAreaFigure object

Returns:
True if currently doing direct drawing, ie: not using a cached image

setUseDirectDraw

public void setUseDirectDraw(boolean newUseDirectDraw)
Sets the useDirectDraw attribute of the HTMLTextAreaFigure object

Parameters:
newUseDirectDraw - The new useDirectDraw value

setUseBufferedDraw

public void setUseBufferedDraw(boolean newUseBufferedDraw)
Sets the useBufferedDraw attribute of the HTMLTextAreaFigure object

Parameters:
newUseBufferedDraw - The new useBufferedDraw value

usesBufferedDraw

public boolean usesBufferedDraw()
Gets the usesBufferedDraw attribute of the HTMLTextAreaFigure object

Returns:
True if currently using buffered draw, ie: the cached image

read

public void read(StorableInput dr)
          throws java.io.IOException
Reads the figure from StorableInput

Specified by:
read in interface Storable
Overrides:
read in class TextAreaFigure
Parameters:
dr - Description of the Parameter
Throws:
java.io.IOException - the inout storable

write

public void write(StorableOutput dw)
Writes the figure to StorableOutput

Specified by:
write in interface Storable
Overrides:
write in class TextAreaFigure
Parameters:
dw - the output storable

setAttribute

public void setAttribute(FigureAttributeConstant name,
                         java.lang.Object value)
A text area figure uses the "LeftMargin", "RightMargin", "TopMargin", "BottomMargin", "TabSize", "FontSize", "FontStyle", and "FontName" attributes

Specified by:
setAttribute in interface Figure
Overrides:
setAttribute in class AttributeFigure
Parameters:
name - The new attribute name
value - The new attribute value

isRawHTML

public boolean isRawHTML()
Gets the rawHTML attribute of the HTMLTextAreaFigure object.
In RawHTML mode, the figure does not add any HTML formatting information so it's the user's responsibility to handle the whole displayed contents

Returns:
The rawHTML value

setRawHTML

public void setRawHTML(boolean newRawHTML)
Sets the rawHTML attribute of the HTMLTextAreaFigure object

Parameters:
newRawHTML - The new rawHTML value

setIntrinsicContentProducer

public void setIntrinsicContentProducer(ContentProducer newIntrinsicContentProducer)
Sets the IntrinsicContentProducer attribute of the HTMLTextAreaFigure object

Parameters:
newIntrinsicContentProducer - The new IntrinsicContentProducer value

registerContentProducer

public ContentProducer registerContentProducer(java.lang.Class targetClass,
                                               ContentProducer producer)
Registers a specific content producer for the target class

Parameters:
targetClass - the target class
producer - the producer
Returns:
the previously registered producer. May be null

unregisterContentProducer

public void unregisterContentProducer(java.lang.Class targetClass,
                                      ContentProducer producer)
Unregisters a registered content producer.

Parameters:
producer - Description of the Parameter
targetClass - Description of the Parameter

getPolygon

public java.awt.Polygon getPolygon()
Makes a polygon with the same shape and dimensions as the current figure

Returns:
Description of the Return Value

setFrameFigure

public void setFrameFigure(Figure newFrameFigure)
Sets the frameFigure attribute of the HTMLTextAreaFigure object

Parameters:
newFrameFigure - The new frameFigure value

figureInvalidated

public void figureInvalidated(FigureChangeEvent e)
handles frame figure's invalidated events

Specified by:
figureInvalidated in interface FigureChangeListener
Overrides:
figureInvalidated in class TextAreaFigure
Parameters:
e - Description of the Parameter

figureChanged

public void figureChanged(FigureChangeEvent e)
handles frame figure's changed events.
It updates the displayBox to match the frame figure's

Specified by:
figureChanged in interface FigureChangeListener
Overrides:
figureChanged in class TextAreaFigure
Parameters:
e - Description of the Parameter

figureRemoved

public void figureRemoved(FigureChangeEvent e)
handles frame figure's invalidatedremoved events.
Never happens because the frame figure is not part of the drawing

Specified by:
figureRemoved in interface FigureChangeListener
Overrides:
figureRemoved in class TextAreaFigure
Parameters:
e - Description of the Parameter

figureRequestRemove

public void figureRequestRemove(FigureChangeEvent e)
handles frame figure's remove requests events.
Never happens because the frame figure is not part of the drawing

Specified by:
figureRequestRemove in interface FigureChangeListener
Overrides:
figureRequestRemove in class TextAreaFigure
Parameters:
e - Description of the Parameter

figureRequestUpdate

public void figureRequestUpdate(FigureChangeEvent e)
handles frame figure's update requests events.
Never happens because the frame figure is not part of the drawing

Specified by:
figureRequestUpdate in interface FigureChangeListener
Overrides:
figureRequestUpdate in class TextAreaFigure
Parameters:
e - Description of the Parameter

getRepresentingFigure

public Figure getRepresentingFigure()
Usually, a TextHolders is implemented by a Figure subclass. To avoid casting a TextHolder to a Figure this method can be used for polymorphism (in this case, let the (same) object appear to be of another type). Note, that the figure returned is not the figure to which the TextHolder is (and its representing figure) connected.

Specified by:
getRepresentingFigure in interface TextHolder
Overrides:
getRepresentingFigure in class TextAreaFigure
Returns:
figure responsible for representing the content of this TextHolder