All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.sgi.sysadm.ui.richText.RichTextComponent

java.lang.Object
   |
   +----java.awt.Component
           |
           +----java.awt.Container
                   |
                   +----javax.swing.JComponent
                           |
                           +----com.sgi.sysadm.ui.richText.RichTextComponent

public class RichTextComponent
extends JComponent
implements DynamicSize, DynamicCursor
RichTextComponent is a view-only JComponent for displaying rich text. The format of the text displayed by RichText is a small subset of HTML. The following HTML tags are supported:

The text to display can be specified by passing it to a constructor, by calling the setText method, or via a ResourceStack.

If constructed by specifying a ResourceStack, RichTextComponent looks in the ResourceStack for many resources which customize its appearance. RichTextComponent looks up each resource using two names. The first is the name argument that is passed to the RichTextComponent constructor prepended to the resource name. The second is the string "RichText" prepended to the resource name. If the resource cannot be found using either name, RichTextComponent uses a default value.

To specify resources for all instances of RichTextComponent that use a given ResourceStack, prepend the string "RichText" to the names of the resource settings in the properties file. To specify resources for a specific RichTextComponent instance give that instance a name and prepend that name to the resource settings in the properties file. The settings for the named RichTextComponent instances will override settings for all RichTextComponent instances.

Here is an example of a properties file containing resource settings for RichTextComponents:

   # All RichText components are to have a width of 600 points.
   RichText.width: 600
 

# The text to be displayed in the RichText component named # "homeDirectory" homeDirectory.text: <B>home directory</B><P>\ A directory in which you create and store your work.

# Set the left margin of the userName component to 0. userName.marginLeft: 0

# The userID RichText component should have a width of 500 points. userID.width: 500

All resources which specify sizes on the screen (WIDTH, MARGIN_LEFT, MARGIN_RIGHT, MARGIN_TOP, MARGIN_BOTTOM, INDENT_WIDTH, LINE_SPACING, BULLET_LEFT_OFFSET, and BULLET_TOP_OFFSET) are specified in units of points. A point is 1/72 of an inch. RichTextComponent divides the pixel height of a test font by the font's point size to determine how many pixels correspond to a point. RichTextComponent does not use java.awt.Toolkit's notion of screen resolution because experience has shown that different Java implementations do not have predictable relationships between screen resolutions and the correspondence between a font's point and pixel sizes.

The full list of the resources which can be specified is described in the Variable Index below.


Variable Index

 o ACTIVE_LINK_COLOR
The resource RichText.activeLinkColor or <componentName>.activeLinkColor is an Integer specifying the color to be used in the text of a link when the user is holding the mouse button down over that link.
 o AUTO_WRAP
The resource RichText.autoWrap or <componentName>.autoWrap is a Boolean specifying whether RichText should wrap long lines in paragraphs.
 o BOLD_LINKS
The resource RichText.boldLinks or <componentName>.boldLinks is a Boolean specifying whether or not links should always be bold.
 o BULLET_LEFT_OFFSET
The resource RichText.bulletLeftOffset or <componentName>.bulletLeftOffset is an Integer specifying the left offset of a bullet in a list item relative to the paragraph it is in.
 o BULLET_TOP_OFFSET
The resource RichText.bulletTopOffset or <componentName>.bulletTopOffset is an Integer specifying padding at the top of a bullet.
 o CLASS_NAME
RichText is the name prepended to resource names when looking for resource settings that apply to all instances.
 o FONT
The resource RichText.font or <componentName>.font is a String specifying the Font to be used.
 o INDENT_WIDTH
The resource RichText.indentWidth or <componentName>.indentWidth is an Integer specifying how many points to ident each level of list item.
 o LINE_BREAK_SCALE
The resource RichText.lineBreakScale or <componentName>.lineBreakScale is the float by which the height of the current font is multiplied to determine the vertical separation between paragraphs.
 o LINE_SPACING
The resource RichText.lineSpacing or <componentName>.lineSpacing is an Integer specifying the number of points to insert between each line in a paragraph.
 o LINK_COLOR
The resource RichText.linkColor or <componentName>.linkColor is an Integer specifying the color to be used in the text of a link.
 o LINK_STATE_ACTIVE
State of a link while the mouse button is down.
 o LINK_STATE_INITIAL
State of a link before it has been clicked.
 o LINK_STATE_VISITED
State of a link after it has been pressed.
 o LIST_NUMBER_FORMAT
The resource RichText.listNumberFormat or <componentName>.listNumberFormat is a format string used to display the numbers in ordered lists.
 o MARGIN_BOTTOM
The resource RichText.marginBottom or <componentName>.marginBottom is an Integer specifying the bottom margin in points.
 o MARGIN_LEFT
The resource RichText.marginLeft or <componentName>.marginLeft is an Integer specifying the left margin in points.
 o MARGIN_RIGHT
The resource RichtText.marginRight or <componentName>.marginRight is an Integer specifying the right margin in points.
 o MARGIN_TOP
The resource RichText.marginTop or <componentName>.marginTop is an Integer specifying the top margin in points.
 o TEXT
The resource RichText.text or <componentName>.text is a String containing the HTML to be displayed.
 o TEXT_COLOR
The resource RichText.textColor or <componentName>.textColor is an Integer specifying the color to be used for normal text.
 o UNDERLINE_LINKS
The resource RichText.underlineLinks or <componentName>.underlineLinks is a Boolean specifying whether or not links should be underlined.
 o VISITED_LINK_COLOR
The resource RichText.visitedLinkColor or <componentName>.visitedLinkColor is an Integer specifying the color to be used in the text of a link after the user has clicked on it.
 o WIDTH
The resource RichText.width or <componentName>.width is an Integer specifying the preferred width of a RichTextComponent in points.

Constructor Index

 o RichTextComponent()
Construct a RichTextComponent component.
 o RichTextComponent(ResourceStack)
Construct a RichTextComponent with a ResourceStack.
 o RichTextComponent(String)
Construct a RichTextComponent with a text string.
 o RichTextComponent(String, ResourceStack)
Construct a RichTextComponent with a name and a ResourceStack.
 o RichTextComponent(String, ResourceStack, String)
Construct a RichTextComponent with a name, a ResourceStack, and a text string.

Method Index

 o addLinkListener(LinkListener)
Add a listener to be notified when the user clicks on a link.
 o getAutoWrap()
Get the value of the auto wrap flag.
 o getCursorAt(int, int)
Get the cursor to display when the mouse is over the point x, y.
 o getLinkState(int)
Returns the link state of a specified link.
 o getLinkTarget(int)
Returns the link target (URL) of a specified link.
 o getNumLinks()
Determine the number of links in a document.
 o getPreferredHeight(int)
Calculate our preferred height given a particular width.
 o getPreferredSize()
Calculate our preferred size.
 o getText()
Get the text being displayed.
 o isFocusTraversable()
Controls whether or not this RichTextComponent can get focus when the user presses the TAB key.
 o paintComponent(Graphics)
Called when it's time to paint ourselves.
 o quoteString(String)
Replace any characters in str that have special meaning to RichTextComponent with escape sequences, so that when the returned string is displayed in a RichTextComponent the special characters will be displayed.
 o removeLinkListener(LinkListener)
Remove a listener from our link listeners.
 o removeTags(String)
Utility method for removing all of the tags from a RichTextComponent's text string.
 o setAutoWrap(boolean)
Set RichText's wrapping behavior.
 o setBounds(int, int, int, int)
Called when our size changes.
 o setFocusTraversable(boolean)
Control whether or not this RichTextComponent is focus traversable.
 o setFont(String, int)
Set the font that RichText uses to display text.
 o setLinkState(int, int)
Set the state of a link in the document.
 o setMargins(Insets)
Set the margins in pixels.
 o setText(String)
Set the text to be displayed.

Variables

 o TEXT
 public static final String TEXT
The resource RichText.text or <componentName>.text is a String containing the HTML to be displayed.

 o WIDTH
 public static final String WIDTH
The resource RichText.width or <componentName>.width is an Integer specifying the preferred width of a RichTextComponent in points. The preferred height is determined dynamically depending on the text being displayed.

 o MARGIN_LEFT
 public static final String MARGIN_LEFT
The resource RichText.marginLeft or <componentName>.marginLeft is an Integer specifying the left margin in points.

 o MARGIN_RIGHT
 public static final String MARGIN_RIGHT
The resource RichtText.marginRight or <componentName>.marginRight is an Integer specifying the right margin in points.

 o MARGIN_TOP
 public static final String MARGIN_TOP
The resource RichText.marginTop or <componentName>.marginTop is an Integer specifying the top margin in points.

 o MARGIN_BOTTOM
 public static final String MARGIN_BOTTOM
The resource RichText.marginBottom or <componentName>.marginBottom is an Integer specifying the bottom margin in points.

 o INDENT_WIDTH
 public static final String INDENT_WIDTH
The resource RichText.indentWidth or <componentName>.indentWidth is an Integer specifying how many points to ident each level of list item.

 o LINE_SPACING
 public static final String LINE_SPACING
The resource RichText.lineSpacing or <componentName>.lineSpacing is an Integer specifying the number of points to insert between each line in a paragraph.

 o TEXT_COLOR
 public static final String TEXT_COLOR
The resource RichText.textColor or <componentName>.textColor is an Integer specifying the color to be used for normal text.

 o LINK_COLOR
 public static final String LINK_COLOR
The resource RichText.linkColor or <componentName>.linkColor is an Integer specifying the color to be used in the text of a link.

 o ACTIVE_LINK_COLOR
 public static final String ACTIVE_LINK_COLOR
The resource RichText.activeLinkColor or <componentName>.activeLinkColor is an Integer specifying the color to be used in the text of a link when the user is holding the mouse button down over that link.

 o VISITED_LINK_COLOR
 public static final String VISITED_LINK_COLOR
The resource RichText.visitedLinkColor or <componentName>.visitedLinkColor is an Integer specifying the color to be used in the text of a link after the user has clicked on it.

 o UNDERLINE_LINKS
 public static final String UNDERLINE_LINKS
The resource RichText.underlineLinks or <componentName>.underlineLinks is a Boolean specifying whether or not links should be underlined.

 o BOLD_LINKS
 public static final String BOLD_LINKS
The resource RichText.boldLinks or <componentName>.boldLinks is a Boolean specifying whether or not links should always be bold.

 o FONT
 public static final String FONT
The resource RichText.font or <componentName>.font is a String specifying the Font to be used. Only the name and point size should be specified; RichTextComponent inserts different styles to create different fonts for supporting the <b> and <i> tags.

For example, to specify that a 12 point sans-serif font should be used for all RichTextComponents, specify the following resource:

   RichText.font = SansSerif-12
 

See Also:
setFont
 o BULLET_LEFT_OFFSET
 public static final String BULLET_LEFT_OFFSET
The resource RichText.bulletLeftOffset or <componentName>.bulletLeftOffset is an Integer specifying the left offset of a bullet in a list item relative to the paragraph it is in. The list item itself will be indented INDENT_WIDTH points, so BULLET_LEFT_OFFSET should be smaller than INDENT_WIDTH.

 o BULLET_TOP_OFFSET
 public static final String BULLET_TOP_OFFSET
The resource RichText.bulletTopOffset or <componentName>.bulletTopOffset is an Integer specifying padding at the top of a bullet. RichTextComponent calculates the location of the top of a bullet by centering the bullet with respect to the ascent of the font being used and then adding in bulletTopOffset. This is necessary because the ascent includes extra space which makes the bullet look too high without the padding.

 o LIST_NUMBER_FORMAT
 public static final String LIST_NUMBER_FORMAT
The resource RichText.listNumberFormat or <componentName>.listNumberFormat is a format string used to display the numbers in ordered lists.

 o LINE_BREAK_SCALE
 public static final String LINE_BREAK_SCALE
The resource RichText.lineBreakScale or <componentName>.lineBreakScale is the float by which the height of the current font is multiplied to determine the vertical separation between paragraphs.

 o AUTO_WRAP
 public static final String AUTO_WRAP
The resource RichText.autoWrap or <componentName>.autoWrap is a Boolean specifying whether RichText should wrap long lines in paragraphs. This affects the behavior of the getPreferredSize method. If AUTO_WRAP is true, then getPreferredSize will return a width corresponding to the width of the longest line in the text.

See Also:
setAutoWrap, getAutoWrap
 o CLASS_NAME
 public static final String CLASS_NAME
RichText is the name prepended to resource names when looking for resource settings that apply to all instances. Such resources can be overridden by giving a specific instance a name and prepending that name to the resource names.

 o LINK_STATE_INITIAL
 public static final int LINK_STATE_INITIAL
State of a link before it has been clicked.

 o LINK_STATE_ACTIVE
 public static final int LINK_STATE_ACTIVE
State of a link while the mouse button is down.

 o LINK_STATE_VISITED
 public static final int LINK_STATE_VISITED
State of a link after it has been pressed.

Constructors

 o RichTextComponent
 public RichTextComponent(String name,
                          ResourceStack rs,
                          String text)
Construct a RichTextComponent with a name, a ResourceStack, and a text string.

Parameters:
name - if non-null, name to use for resource lookup.
rs - if non-null, stack for getting resources.
text - if non-null, initial text to display
 o RichTextComponent
 public RichTextComponent()
Construct a RichTextComponent component. All settings get their default values. Use setText to set the text that is to be displayed.

 o RichTextComponent
 public RichTextComponent(String text)
Construct a RichTextComponent with a text string. All settings get their default values. text is displayed.

Parameters:
text - The text to display.
 o RichTextComponent
 public RichTextComponent(String name,
                          ResourceStack rs)
Construct a RichTextComponent with a name and a ResourceStack. Settings, including the text to be displayed, are taken from rs.

Parameters:
name - Name of this instance. Used for retrieving resources from rs.
rs - Resource stack containing settings for this RichTextComponent instance.
 o RichTextComponent
 public RichTextComponent(ResourceStack rs)
Construct a RichTextComponent with a ResourceStack. Setting will be taken from the default values found in rs. The text to display comes from the resource TEXT.

Parameters:
rs - Resource stack containing settings for this RichTextComponent instance.

Methods

 o setText
 public void setText(String text)
Set the text to be displayed.

Parameters:
text - The text to be displayed.
 o getText
 public String getText()
Get the text being displayed.

Returns:
The text being displayed. This can be null.
 o setFont
 public void setFont(String family,
                     int size)
Set the font that RichText uses to display text. Font is specified using family and size rather than an actual Font because RichTextComponent uses several different styles of fonts with the same family and size.

Parameters:
family - family of font to use.
size - size of font to use.
See Also:
FONT
 o setAutoWrap
 public void setAutoWrap(boolean autoWrap)
Set RichText's wrapping behavior. If autoWrap is true, then long lines will be wrapped.

Parameters:
autoWrap - Whether to wrap long lines.
See Also:
AUTO_WRAP
 o getAutoWrap
 public boolean getAutoWrap()
Get the value of the auto wrap flag.

Returns:
true if long lines will be wrapped, false otherwise.
See Also:
AUTO_WRAP
 o setLinkState
 public void setLinkState(int linkNumber,
                          int state)
Set the state of a link in the document. linkNumber specifies the number of the link to set; the links in a document are numbered starting from 0.

Note that setting a link's state to LINK_STATE_ACTIVE will will prevent RichTextComponent from notifying LinkListeners when a link is clicked on.

Parameters:
linkNumber - Number of link to set.
state - State of link to set. Should be one of the constants LINK_STATE_INITIAL, LINK_STATE_ACTIVE, or LINK_STATE_VISITED.
 o getLinkState
 public int getLinkState(int linkNumber)
Returns the link state of a specified link. linkNumber specifies the number of the link to get; the links in a document are numbered starting from 0.

Parameters:
linkNumber - Number of link to get.
Returns:
State of link. Will be one of the constants LINK_STATE_INITIAL, LINK_STATE_ACTIVE, or LINK_STATE_VISITED.
 o getLinkTarget
 public String getLinkTarget(int linkNumber)
Returns the link target (URL) of a specified link. linkNumber specifies the number of the link to get; the links in a document are numbered starting from 0.

Parameters:
linkNumber - Number of link to get.
Returns:
Target of link.
 o getNumLinks
 public int getNumLinks()
Determine the number of links in a document.

Returns:
The number of links in our document.
 o setMargins
 public void setMargins(Insets margins)
Set the margins in pixels. Margins are separate from and in addition to insets.

Parameters:
margins - new margins.
 o removeTags
 public static String removeTags(String richTextString)
Utility method for removing all of the tags from a RichTextComponent's text string.

Parameters:
richTextString - String from which tags are to be removed. This could be the value returned by getText.
Returns:
richTextString with tags removed.
 o quoteString
 public static String quoteString(String str)
Replace any characters in str that have special meaning to RichTextComponent with escape sequences, so that when the returned string is displayed in a RichTextComponent the special characters will be displayed.

Parameters:
str - String whose special characters are to be replaced.
Returns:
A quoted version of str.
 o addLinkListener
 public void addLinkListener(LinkListener listener)
Add a listener to be notified when the user clicks on a link.

Parameters:
listener - The listener to add.
 o removeLinkListener
 public void removeLinkListener(LinkListener listener)
Remove a listener from our link listeners.

Parameters:
listener - The listener to remove.
 o paintComponent
 public void paintComponent(Graphics graphics)
Called when it's time to paint ourselves.

Parameters:
graphics - Graphics to be used for painting.
Overrides:
paintComponent in class JComponent
 o setBounds
 public void setBounds(int x,
                       int y,
                       int width,
                       int height)
Called when our size changes. Adjust text accordingly.

Parameters:
x - new horizontal position.
y - new vertical position.
width - new width.
height - new height.
Overrides:
setBounds in class Component
 o getPreferredSize
 public Dimension getPreferredSize()
Calculate our preferred size. Our width comes from the width resource setting, and the height is calculated based on the text which is being displayed.

If getAutoWrap returns true, the width returned is the width of the widest line + margins that fits within the value of the width resource setting. This means that the actual size may be less than the width resource setting.

If getAutoWrap returns false, the width returned is the width of the widest line + margins.

Returns:
Our preferred size.
Overrides:
getPreferredSize in class JComponent
 o getPreferredHeight
 public int getPreferredHeight(int width)
Calculate our preferred height given a particular width. Can be used by LayoutManagers that have special knowledge of the fact that RichTextComponent's height depends on its width.

Parameters:
width - A proposed width for this component.
Returns:
the height this component would like to be given a width of width.
 o setFocusTraversable
 public void setFocusTraversable(boolean focusTraversable)
Control whether or not this RichTextComponent is focus traversable. RichTextComponent does not give any visual indication when it has focus.

Parameters:
focusTraversable - whether or not this RichTextComponent should be focus traversable.
 o isFocusTraversable
 public boolean isFocusTraversable()
Controls whether or not this RichTextComponent can get focus when the user presses the TAB key. The return value of this method can be controlled by calling setFocusTraversable

Returns:
true if this RichTextComponent is focus traversable.
Overrides:
isFocusTraversable in class JComponent
 o getCursorAt
 public Cursor getCursorAt(int x,
                           int y)
Get the cursor to display when the mouse is over the point x, y.

Parameters:
x - horizontal coordinate within this RichTextComponent.
y - vertical coordinate within this RichTextComponent.
See Also:
DynamicCursor

All Packages  Class Hierarchy  This Package  Previous  Next  Index