uic.widgets.html
Class HTMLConfig

java.lang.Object
  uic.widgets.html.HTMLConfig

public class HTMLConfig
extends Object

A class used to control the default operation and rendering methods of a HTMLPane. The same Config object can be used with multiple panes. During construction all fields of the preferences object are set to default values. Individual fields can then be modified through the access methods listed.

Certain methods can only modify fields before the preferences object has been passed to a HTMLPane. Calling such methods after this point will not throw an exception - the calls are simply ignored.

See Also:

HTMLPane

Constructor Summary

HTMLConfig()
Creates a new Config object which will have all fields set to default values.

Method Summary

Font	getDefaultButtonFont(int displaySize) Returns a default font being used within THREEDEE and FLUSH Buttons and ComboBoxes.
Color	getDefaultColor(int attributeType) Returns a default color used by a HTMLPane to render documents.
Font	getDefaultFont(int displaySize) Returns a default font being used by a HTMLPane
Font	getDefaultFormTextFont(int displaySize) Returns a default font being used within THREEDEE and FLUSH Textfields, TextAreas and Lists.
int	getDefaultFrameSpacing() Returns the default spacing in pixels between frames within a FrameSet document.
int	getDefaultMarginheight() Returns the default vertical margin of a document.
int	getDefaultMarginwidth() Returns the default horizontal margin of a document.
int	getFormRenderingStyle() Returns the default rendering style of FORM components within a HTMLPane.
int	getFrameDisplayWidth(int displaySize) Returns the width for the specified displaySize at which point a HTMLPane will start scaling its display if optimizeDisplay is enabled.
int	getOptimizeDisplay() Returns whether a HTMLPane will adjust display parameters based on frame size.
Hashtable	getVisitedHash() Returns a Hashtable containing references to visited URLs.
boolean	isAutomaticallyFollowHyperlinksEnabled() Returns whether a HTMLPane will automatically navigate activated hyperlinks.
boolean	isDisplayErrorDialogsEnabled() Returns whether a HTMLPane will automatically display a dialog when errors such as failed hyperlinks occur.
boolean	isHandleFormSubmissionEnabled() Returns whether a HTMLPane will automatically handle GET and POST form submissions.
boolean	isHandleNewFramesEnabled() Returns whether a new HTMLPane will automatically be created if specified by an HTML tag.
boolean	isLoadImagesEnabled() Returns whether a HTMLPane will automatically load images within documents.
boolean	isRequestFocusOnMouseClickEnabled() Returns whether a HTMLPane will request keyboard focus if the mouse is clicked within it.
boolean	isShowHyperlinkOnMouseFocusEnabled() Returns whether a HTMLPane will only show a hyperlink when the link has mouse focus.
boolean	isShowTestNavBarEnabled() Returns whether a HTMLPane will display a diagnostic navigation bar on startup.
boolean	isShowWarningBeforePostEnabled() Returns whether a HTMLPane will show a warning to the user before a form POST submission is made.
boolean	isUnderlineLinksEnabled() Returns whether a HTMLPane will underline hyperlinks.
void	setAutomaticallyFollowHyperlinks(boolean b) Enables/disables the automatic navigation of activated hyperlinks in a HTMLPane.
void	setDefaultButtonFont(int displaySize, Font font) Sets a default font to be used within form Buttons and ComboBoxes.
void	setDefaultColor(int attributeType, Color c) Sets a default color.
void	setDefaultFont(int displaySize, Font font) Sets a default font to be used by a HTMLPane.
void	setDefaultFormTextFont(int displaySize, Font font) Sets a default font to be used within form TextFields, TextAreas and Lists.
void	setDefaultFrameSpacing(int n) Sets the default spacing in pixels between frames within a FrameSet document.
void	setDefaultMarginheight(int n) Sets the default vertical margin of a document.
void	setDefaultMarginwidth(int n) Sets the default horizontal margin of a document.
void	setDisplayErrorDialogs(boolean b) Enables/disables the automatic display of error dialogs within a HTMLPane.
void	setFormRenderingStyle(int style) Sets the rendering style of FORM components within a HTMLPane.
void	setFrameDisplayWidth(int displaySize, int width) Sets the width for the specified displaySize at which point a HTMLPane will start scaling its display if optimizeDisplay is enabled.
void	setHandleFormSubmission(boolean b) Enables/disables the automatic processing of GET and POST html forms within a HTMLPane.
void	setHandleNewFrames(boolean b) Enables/disables the automatic creation of a new HTMLPane if specified by an HTML tag.
void	setLoadImages(boolean b) Enables/disables the automatic loading of images within a HTMLPane.
void	setOptimizeDisplay(int optimizeLevel) Determines whether a HTMLPane will adjust display parameters based on frame width.
void	setRequestFocusOnMouseClick(boolean b) Determines whether a HTMLPane or one of its subframes will request keyboard focus if the mouse is clicked within it.
void	setShowHyperlinkOnMouseFocus(boolean b) Determines whether a hyperlink will only be marked as such when it has mouse focus.
void	setShowTestNavBar(boolean b) Enables/disables the display of a diagnostic navigation bar.
void	setShowWarningBeforePost(boolean b) Enables/disables the showing of a warning message before a form POST submission is made.
void	setUnderlineLinks(boolean b) Enables/disables the underlining of hyperlinks within a HTMLPane.
void	setVisitedHash(Hashtable table) Sets the Hashtable containing references to URLs which will be used by a HTMLPane to mark visited hyperlinks.

Methods inherited from class java.lang.Object

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

Constructor Detail

HTMLConfig

public HTMLConfig()

Creates a new Config object which will have all fields set to default values.

Method Detail

getVisitedHash

public Hashtable getVisitedHash()

Returns a Hashtable containing references to visited URLs. This hashtable can be passed into a new Config object at a later date so that a user's visited links are persistent. The method of storing the hashtable's contents outside of this class is left to the programmer.

The keys within the hashtable are all Integer objects, each representing a hashcode of a visited URL (note that this is not the hashcode returned from the URL.hashcode() method).
The values within the hashtable are all Long objects representing the System.currentTimeMillis() when the link was last visited. The programmer may therefore remove 'old' links if so desired.

Returns:

a Hashtable recording visited document URLs

See Also:

setVisitedHash(java.util.Hashtable)

setVisitedHash

public void setVisitedHash(Hashtable table)

Sets the Hashtable containing references to URLs which will be used by a HTMLPane to mark visited hyperlinks. Only pass in a hashtable which was previously obtained from a Config object via the getVisitedHash() method.

Parameters:

table - a Hashtable containing Integer/Long pairs representing visited document URLs

See Also:

getVisitedHash()

setOptimizeDisplay

public void setOptimizeDisplay(int optimizeLevel)

Determines whether a HTMLPane will adjust display parameters based on frame width. The arguments which can be sent to this method are:

• HTMLConstants.NO_OPTIMIZATION
  No adjustments will be made for frame width. This is the default value.
• HTMLConstants.OPTIMIZE_FONTS
  Font size may be scaled based on frame width.
• HTMLConstants.OPTIMIZE_ALL
  In addition to font scaling, other parameters such as table cellspacing and cellpadding may be adjusted in an attempt to fit the document into the current frame.

See the README.TXT file accompanying this document for more details on optimizeDisplay.

Parameters:

optimizeLevel - a value indicating the level (if any) of display optimization required

See Also:

setFrameDisplayWidth(int, int)

getOptimizeDisplay

public int getOptimizeDisplay()

Returns whether a HTMLPane will adjust display parameters based on frame size.

See the README.TXT file accompanying this document for more details on optimizeDisplay.

Returns:

a value indicating the current level of display optimization

setFrameDisplayWidth

public void setFrameDisplayWidth(int displaySize,
                                 int width)

Sets the width for the specified displaySize at which point a HTMLPane will start scaling its display if optimizeDisplay is enabled. The permitted displaySize arguments are:

• HTMLConstants.S_SMALL
• HTMLConstants.S_MEDIUM

There is no need to set a width for displaySize HTMLConstants.S_LARGE as a HTMLPane will treat any width greater than the HTMLConstants.S_MEDIUM width as a large display.

Default values are: S_SMALL: 250 pixels, S_MEDIUM: 400 pixels

See the README.TXT file accompanying this document for more details on optimizeDisplay.

getFrameDisplayWidth

public int getFrameDisplayWidth(int displaySize)

Returns the width for the specified displaySize at which point a HTMLPane will start scaling its display if optimizeDisplay is enabled. The permitted displaySize arguments are:

• HTMLConstants.S_SMALL
• HTMLConstants.S_MEDIUM

setDefaultFont

public void setDefaultFont(int displaySize,
                           Font font)

Sets a default font to be used by a HTMLPane. This method takes three different size arguments:

• HTMLConstants.S_SMALL
• HTMLConstants.S_MEDIUM
• HTMLConstants.S_LARGE

In most cases you will call this method with the HTMLConstants.S_LARGE argument. The S_SMALL and S_MEDIUM arguments are used in special cases relating to printing (which is not yet supported in the Java 2 version of HTMLPane) and the optimizeDisplay feature of HTMLPane.

The font point sizes supported in HTMLPane are: 10, 11, 12, 13, 14, 16, 18, 20, 22, 24, 28, 36, 48

If the size of the font sent to this method does not exactly match a supported size, then the closest supported value will be used.

See Also:

setOptimizeDisplay(int)

getDefaultFont

public Font getDefaultFont(int displaySize)

Returns a default font being used by a HTMLPane

See Also:

setDefaultFont(int, java.awt.Font)

setDefaultButtonFont

public void setDefaultButtonFont(int displaySize,
                                 Font font)

Sets a default font to be used within form Buttons and ComboBoxes. This method only applies to THREEDEE and FLUSH form components. LOOKANDFEEL components will not be affected. This method takes three different size arguments:

• HTMLConstants.S_SMALL
• HTMLConstants.S_MEDIUM
• HTMLConstants.S_LARGE

In most cases you will call this method with the HTMLConstants.S_LARGE argument. The S_SMALL and S_MEDIUM arguments are used in special cases relating to the optimizeDisplay feature of HTMLPane.

The font point sizes supported in HTMLPane are: 10, 11, 12, 13, 14, 16, 18, 20, 22, 24, 28, 36, 48

If the size of the font sent to this method does not exactly match a supported size, then the closest supported value will be used.

See Also:

setOptimizeDisplay(int)

getDefaultButtonFont

public Font getDefaultButtonFont(int displaySize)

Returns a default font being used within THREEDEE and FLUSH Buttons and ComboBoxes.

See Also:

setDefaultButtonFont(int, java.awt.Font)

setDefaultFormTextFont

public void setDefaultFormTextFont(int displaySize,
                                   Font font)

Sets a default font to be used within form TextFields, TextAreas and Lists. This method only applies to THREEDEE and FLUSH form components. LOOKANDFEEL components will not be affected. This method takes three different size arguments:

• HTMLConstants.S_SMALL
• HTMLConstants.S_MEDIUM
• HTMLConstants.S_LARGE

In most cases you will call this method with the HTMLConstants.S_LARGE argument. The S_SMALL and S_MEDIUM arguments are used in special cases relating to the optimizeDisplay feature of HTMLPane.

The font point sizes supported in HTMLPane are: 10, 11, 12, 13, 14, 16, 18, 20, 22, 24, 28, 36, 48

If the size of the font sent to this method does not exactly match a supported size, then the closest supported value will be used.

See Also:

setOptimizeDisplay(int)

getDefaultFormTextFont

public Font getDefaultFormTextFont(int displaySize)

Returns a default font being used within THREEDEE and FLUSH Textfields, TextAreas and Lists.

See Also:

setDefaultFormTextFont(int, java.awt.Font)

setDefaultColor

public void setDefaultColor(int attributeType,
                            Color c)

Sets a default color. Permitted values are:

attributeType	Default	Description
HTMLConstants.A_BGCOLOR	Color.white	Document background color
HTMLConstants.A_TEXT	Color.black	Document text color
HTMLConstants.A_LINK	Color(0xOOOOEA)	Normal link color
HTMLConstants.A_VLINK	Color(0x800080)	Visited link color
HTMLConstants.A_ALINK	Color.red	Active link color
HTMLConstants.FORM_CONTROL	UIControl	Control color of form components
HTMLConstants.FORM_HIGHLIGHT	UIHighlight	Highlight color of form components
HTMLConstants.FORM_SHADOW	UIShadow	Shadow color of form components
HTMLConstants.FORM_TEXT_BACKGROUND	Color.white	Background color within form components such as textfields
HTMLConstants.FORM_TEXT_COLOR	Color.black	Text color within form components such as textfields
HTMLConstants.TAB_FOCUS_BACKGROUND	Color(0x300060)	Background color of hyperlinks which have keyboard focus
HTMLConstants.TAB_FOCUS_FOREGROUND	Color(0xFFFFD0)	Foreground color of hyperlinks which have keyboard focus

This method should be called prior to passing the Config to a HTMLPane. Calls after this point will be ignored.

getDefaultColor

public Color getDefaultColor(int attributeType)

Returns a default color used by a HTMLPane to render documents. See setDefaultColor() for allowed attributeTypes

See Also:

setDefaultColor(int, java.awt.Color)

setFormRenderingStyle

public void setFormRenderingStyle(int style)

Sets the rendering style of FORM components within a HTMLPane. The permitted style values are:

• HTMLConstants.USE_LOOK_AND_FEEL
• HTMLConstants.USE_CALPA_THREEDEE
• HTMLConstants.USE_CALPA_FLUSH

The USE_LOOK_AND_FEEL argument will use standard Swing components based on the currently installed Look&Feel. Generally these will provide an acceptable display, but with certain document background colors these components lose style features due to a clash between the background color of the document and the control, shadow, and highlight color of the component.

The USE_CALPA_THREEDEE and USE_CALPA_FLUSH styles have been incorporated to help overcome such a situation. These components support author-specific color attributes which can be made to blend satisfactorily with the surrounding document color.

Note that setting the default style via this method does not prevent the document author from setting individual styles within the document itself. Styles can be freely mixed by specifying style attributes within the relevant document form tags.

Although this method can be called at any time during program execution, existing form components will remain in their original style.

The default rendering style of form components is USE_CALPA_THREEDEE

See the README.TXT file accompanying this document for more details on form rendering.

Parameters:

style - a value which determines the default rendering style of HTML form components

getFormRenderingStyle

public int getFormRenderingStyle()

Returns the default rendering style of FORM components within a HTMLPane.

Returns:

a value indicating the default rendering style of HTML form components

See Also:

setFormRenderingStyle(int)

setDefaultFrameSpacing

public void setDefaultFrameSpacing(int n)

Sets the default spacing in pixels between frames within a FrameSet document. The default setting is 4 pixels.

Parameters:

n - the default spacing in pixels between HTML frames in a FrameSet document

getDefaultFrameSpacing

public int getDefaultFrameSpacing()

Returns the default spacing in pixels between frames within a FrameSet document.

Returns:

the default spacing in pixels between HTML frames in a FrameSet document

setDefaultMarginwidth

public void setDefaultMarginwidth(int n)

Sets the default horizontal margin of a document. The default setting is 6 pixels.

Parameters:

n - the default horizontal margin in pixels between a document and the border of the frame it resides in.

getDefaultMarginwidth

public int getDefaultMarginwidth()

Returns the default horizontal margin of a document.

Returns:

the default horizontal margin in pixels between a document and the border of the frame it resides in.

setDefaultMarginheight

public void setDefaultMarginheight(int n)

Sets the default vertical margin of a document. The default setting is 6 pixels.

Parameters:

n - the default vertical margin in pixels between a document and the border of the frame it resides in.

getDefaultMarginheight

public int getDefaultMarginheight()

Returns the default vertical margin of a document.

Returns:

the default vertical margin in pixels between a document and the border of the frame it resides in.

setUnderlineLinks

public void setUnderlineLinks(boolean b)

Enables/disables the underlining of hyperlinks within a HTMLPane. The default value is true.

Parameters:

b - a flag indicating whether hyperlinks should be underlined

isUnderlineLinksEnabled

public boolean isUnderlineLinksEnabled()

Returns whether a HTMLPane will underline hyperlinks.

Returns:

true if hyperlinks will be underlined

setShowHyperlinkOnMouseFocus

public void setShowHyperlinkOnMouseFocus(boolean b)

Determines whether a hyperlink will only be marked as such when it has mouse focus. This is commonly used in help systems where it is obvious that all text is a hyperlink entry, and users only need to know which hyperlink is currently active. The default value is false.

Parameters:

b - a flag indicating whether hyperlinks will only be marked as such if they have mouse focus

isShowHyperlinkOnMouseFocusEnabled

public boolean isShowHyperlinkOnMouseFocusEnabled()

Returns whether a HTMLPane will only show a hyperlink when the link has mouse focus.

Returns:

true if a hyperlink will only be marked as such when it has mouse focus

setLoadImages

public void setLoadImages(boolean b)

Enables/disables the automatic loading of images within a HTMLPane. The default value is true.

Parameters:

b - a flag indicating whether images within documents should be loaded and displayed

isLoadImagesEnabled

public boolean isLoadImagesEnabled()

Returns whether a HTMLPane will automatically load images within documents.

Returns:

true if images within documents will be loaded and displayed

setDisplayErrorDialogs

public void setDisplayErrorDialogs(boolean b)

Enables/disables the automatic display of error dialogs within a HTMLPane. At present such errors will most commonly arise from a failure to navigate to a selected URL. The default value is true. If set to false, errors will not be displayed to the screen but will still be passed to the resident HTMLObserver

Parameters:

b - a flag indicating whether an dialog should be displayed if an error occurs within a Pane.

isDisplayErrorDialogsEnabled

public boolean isDisplayErrorDialogsEnabled()

Returns whether a HTMLPane will automatically display a dialog when errors such as failed hyperlinks occur.

Returns:

true if an error dialog will be displayed if an error occurs within a Pane.

setShowTestNavBar

public void setShowTestNavBar(boolean b)

Enables/disables the display of a diagnostic navigation bar. The default value is false.

The navigation bar is a legacy of testing the component and is very basic, but it has not been removed as it can be useful at times. It is expected that users will implement their own custom navigation controls if required.

The NavBar operates independently of the HTMLObserver monitoring the Pane, and will not interfere with updates to that object. Note also that the NavBar controls do not receive keyboard focus when tabbing.

This method should be called prior to passing the Config to a HTMLPane. Calls after this point will be ignored.

Parameters:

b - a flag indicating whether a HTMLPane's test navigation controls should be displayed.

isShowTestNavBarEnabled

public boolean isShowTestNavBarEnabled()

Returns whether a HTMLPane will display a diagnostic navigation bar on startup.

Returns:

true if a HTMLPane will display test navigation controls.

setAutomaticallyFollowHyperlinks

public void setAutomaticallyFollowHyperlinks(boolean b)

Enables/disables the automatic navigation of activated hyperlinks in a HTMLPane. The default value is true. If set to false, activated hyperlinks will not be followed but the event will still be passed to the resident HTMLObserver

Parameters:

b - a flag indicating whether hyperlinks should be followed if activated by mouse or keyboard.

isAutomaticallyFollowHyperlinksEnabled

public boolean isAutomaticallyFollowHyperlinksEnabled()

Returns whether a HTMLPane will automatically navigate activated hyperlinks.

Returns:

true if hyperlinks should be followed if activated by keyboard or mouse.

setHandleFormSubmission

public void setHandleFormSubmission(boolean b)

Enables/disables the automatic processing of GET and POST html forms within a HTMLPane. The default value is true. If set to false, form submissions will still be passed to the resident HTMLObserver

Parameters:

b - a flag indicating whether http GET and POST form submissions should be handled automatically by a HTMLPane

isHandleFormSubmissionEnabled

public boolean isHandleFormSubmissionEnabled()

Returns whether a HTMLPane will automatically handle GET and POST form submissions.

Returns:

true if http GET and POST form submissions will be handled automatically by a HTMLPane

setShowWarningBeforePost

public void setShowWarningBeforePost(boolean b)

Enables/disables the showing of a warning message before a form POST submission is made. The default value is true. This setting only has any meaning if the Pane is handling form submissions.

Parameters:

b - a flag indicating whether a warning message will displayed before an http form POST submission

isShowWarningBeforePostEnabled

public boolean isShowWarningBeforePostEnabled()

Returns whether a HTMLPane will show a warning to the user before a form POST submission is made.

Returns:

true if a warning message will displayed before an http form POST submission

setHandleNewFrames

public void setHandleNewFrames(boolean b)

Enables/disables the automatic creation of a new HTMLPane if specified by an HTML tag. The default value is true. If set to false, a request for a new frame will be sent to the resident HTMLObserver

Parameters:

b - a flag indicating whether a new HTMLPane should automatically be displayed if specified by an HTML tag.

isHandleNewFramesEnabled

public boolean isHandleNewFramesEnabled()

Returns whether a new HTMLPane will automatically be created if specified by an HTML tag.

Returns:

true if a new HTMLPane will automatically be displayed if specified by an HTML tag.

setRequestFocusOnMouseClick

public void setRequestFocusOnMouseClick(boolean b)

Determines whether a HTMLPane or one of its subframes will request keyboard focus if the mouse is clicked within it. The default value is false.

Parameters:

b - a flag indicating whether a HTMLPane frame should call requestFocus() if the mouse is clicked within it.

isRequestFocusOnMouseClickEnabled

public boolean isRequestFocusOnMouseClickEnabled()

Returns whether a HTMLPane will request keyboard focus if the mouse is clicked within it.

Returns:

true if a HTMLPane frame will call requestFocus() if the mouse is clicked within it.