calpa.html
Class CalHTMLPreferences

java.lang.Object
  |
  +--calpa.html.CalHTMLPreferences

public class CalHTMLPreferences

extends java.lang.Object

implements calpa.html.CalCons

A class used to control the default operation and rendering methods of a CalHTMLPane. The same CalHTMLPreferences 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 CalHTMLPane. Calling such methods after this point will not throw an exception - the calls are simply ignored.

See Also:

CalHTMLPane

Constructor Summary

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

Method Summary

java.awt.Font	getDefaultButtonFont(int displaySize) Returns a default font being used within THREEDEE and FLUSH Buttons and ComboBoxes.
java.awt.Color	getDefaultColor(int attributeType) Returns a default color used by a CalHTMLPane to render documents.
java.awt.Font	getDefaultFont(int displaySize) Returns a default font being used by a CalHTMLPane
java.awt.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 CalHTMLPane.
int	getFrameDisplayWidth(int displaySize) Returns the width for the specified displaySize at which point a CalHTMLPane will start scaling its display if optimizeDisplay is enabled.
java.net.URL	getHomeURL() Returns the URL which will accessed if a CalHTMLPane's goHome() method is called
int	getOptimizeDisplay() Returns whether a CalHTMLPane will adjust display parameters based on frame size.
java.util.Hashtable	getVisitedHash() Returns a Hashtable containing references to visited URLs.
boolean	isAutomaticallyFollowHyperlinksEnabled() Returns whether a CalHTMLPane will automatically navigate activated hyperlinks.
boolean	isDisplayErrorDialogsEnabled() Returns whether a CalHTMLPane will automatically display a dialog when errors such as failed hyperlinks occur.
boolean	isHandleFormSubmissionEnabled() Returns whether a CalHTMLPane will automatically handle GET and POST form submissions.
boolean	isHandleNewFramesEnabled() Returns whether a new CalHTMLPane will automatically be created if specified by an HTML tag.
boolean	isLoadImagesEnabled() Returns whether a CalHTMLPane will automatically load images within documents.
boolean	isRequestFocusOnMouseClickEnabled() Returns whether a CalHTMLPane will request keyboard focus if the mouse is clicked within it.
boolean	isShowHyperlinkOnMouseFocusEnabled() Returns whether a CalHTMLPane will only show a hyperlink when the link has mouse focus.
boolean	isShowTestNavBarEnabled() Returns whether a CalHTMLPane will display a diagnostic navigation bar on startup.
boolean	isShowWarningBeforePostEnabled() Returns whether a CalHTMLPane will show a warning to the user before a form POST submission is made.
boolean	isUnderlineLinksEnabled() Returns whether a CalHTMLPane will underline hyperlinks.
void	setAutomaticallyFollowHyperlinks(boolean b) Enables/disables the automatic navigation of activated hyperlinks in a CalHTMLPane.
void	setDefaultButtonFont(int displaySize, java.awt.Font font) Sets a default font to be used within form Buttons and ComboBoxes.
void	setDefaultColor(int attributeType, java.awt.Color c) Sets a default color.
void	setDefaultFont(int displaySize, java.awt.Font font) Sets a default font to be used by a CalHTMLPane.
void	setDefaultFont(int displaySize, int fontFamily, int sizeIndex) Deprecated. Use setDefaultFont(int, Font) which allows the setting of system fonts.
void	setDefaultFormTextFont(int displaySize, java.awt.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 CalHTMLPane.
void	setFormFont(int displaySize, int fontFamily, int fontStyle, int sizeArrayIndex) Deprecated. Use either setDefaultButtonFont(int, Font) or setDefaultFormTextFont(int, Font).
void	setFormRenderingStyle(int style) Sets the rendering style of FORM components within a CalHTMLPane.
void	setFrameDisplayWidth(int displaySize, int width) Sets the width for the specified displaySize at which point a CalHTMLPane 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 CalHTMLPane.
void	setHandleNewFrames(boolean b) Enables/disables the automatic creation of a new CalHTMLPane if specified by an HTML tag.
void	setHomeURL(java.net.URL url) Sets the URL which will be accessed if a CalHTMLPane's goHome() method is called.
void	setLoadImages(boolean b) Enables/disables the automatic loading of images within a CalHTMLPane.
void	setOptimizeDisplay(int optimizeLevel) Determines whether a CalHTMLPane will adjust display parameters based on frame width.
void	setRequestFocusOnMouseClick(boolean b) Determines whether a CalHTMLPane 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 CalHTMLPane.
void	setVisitedHash(java.util.Hashtable table) Sets the Hashtable containing references to URLs which will be used by a CalHTMLPane to mark visited hyperlinks.

Methods inherited from class java.lang.Object

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

Constructor Detail

CalHTMLPreferences

public CalHTMLPreferences()

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

Method Detail

getVisitedHash

public java.util.Hashtable getVisitedHash()

Returns a Hashtable containing references to visited URLs. This hashtable can be passed into a new CalHTMLPreferences 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(java.util.Hashtable table)

Sets the Hashtable containing references to URLs which will be used by a CalHTMLPane to mark visited hyperlinks. Only pass in a hashtable which was previously obtained from a CalHTMLPreferences 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 CalHTMLPane will adjust display parameters based on frame width. The arguments which can be sent to this method are:

• CalCons.NO_OPTIMIZATION
  No adjustments will be made for frame width. This is the default value.
• CalCons.OPTIMIZE_FONTS
  Font size may be scaled based on frame width.
• CalCons.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), setDefaultFont(int, int, int)

getOptimizeDisplay

public int getOptimizeDisplay()

Returns whether a CalHTMLPane 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 CalHTMLPane will start scaling its display if optimizeDisplay is enabled. The permitted displaySize arguments are:

• CalCons.S_SMALL
• CalCons.S_MEDIUM

There is no need to set a width for displaySize CalCons.S_LARGE as a CalHTMLPane will treat any width greater than the CalCons.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 CalHTMLPane will start scaling its display if optimizeDisplay is enabled. The permitted displaySize arguments are:

• CalCons.S_SMALL
• CalCons.S_MEDIUM

setDefaultFont

public void setDefaultFont(int displaySize,
                           int fontFamily,
                           int sizeIndex)

Deprecated. Use setDefaultFont(int, Font) which allows the setting of system fonts.

setDefaultFont

public void setDefaultFont(int displaySize,
                           java.awt.Font font)

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

• CalCons.S_SMALL
• CalCons.S_MEDIUM
• CalCons.S_LARGE

In most cases you will call this method with the CalCons.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 CalPane) and the optimizeDisplay feature of CalHTMLPane.

This method replaces the now deprecated setDefaultFont(int displaySize, int fontFamily, int sizeIndex) method because Java 2 allows access to system fonts, rather than just Java's logical fonts.

The font point sizes supported in CalPane 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 java.awt.Font getDefaultFont(int displaySize)

Returns a default font being used by a CalHTMLPane

See Also:

setDefaultFont(int, java.awt.Font)

setFormFont

public void setFormFont(int displaySize,
                        int fontFamily,
                        int fontStyle,
                        int sizeArrayIndex)

Deprecated. Use either setDefaultButtonFont(int, Font) or setDefaultFormTextFont(int, Font).

setDefaultButtonFont

public void setDefaultButtonFont(int displaySize,
                                 java.awt.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:

• CalCons.S_SMALL
• CalCons.S_MEDIUM
• CalCons.S_LARGE

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

The font point sizes supported in CalPane 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 java.awt.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,
                                   java.awt.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:

• CalCons.S_SMALL
• CalCons.S_MEDIUM
• CalCons.S_LARGE

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

The font point sizes supported in CalPane 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 java.awt.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,
                            java.awt.Color c)

Sets a default color. Permitted values are:

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

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

getDefaultColor

public java.awt.Color getDefaultColor(int attributeType)

Returns a default color used by a CalHTMLPane 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 CalHTMLPane. The permitted style values are:

• CalCons.USE_LOOK_AND_FEEL
• CalCons.USE_CALPA_THREEDEE
• CalCons.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 CalHTMLPane.

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.

setHomeURL

public void setHomeURL(java.net.URL url)

Sets the URL which will be accessed if a CalHTMLPane's goHome() method is called. The default setting is http://www.w3.org

Parameters:

url - the default URL to be accessed.

getHomeURL

public java.net.URL getHomeURL()

Returns the URL which will accessed if a CalHTMLPane's goHome() method is called

Returns:

the default URL which will be accessed.

setUnderlineLinks

public void setUnderlineLinks(boolean b)

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

Parameters:

b - a flag indicating whether hyperlinks should be underlined

isUnderlineLinksEnabled

public boolean isUnderlineLinksEnabled()

Returns whether a CalHTMLPane 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 CalHTMLPane 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 CalHTMLPane. 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 CalHTMLPane 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 CalHTMLPane. 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 CalHTMLObserver

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 CalHTMLPane 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 CalHTMLObserver 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 CalHTMLPreferences to a CalHTMLPane. Calls after this point will be ignored.

Parameters:

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

isShowTestNavBarEnabled

public boolean isShowTestNavBarEnabled()

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

Returns:

true if a CalHTMLPane will display test navigation controls.

setAutomaticallyFollowHyperlinks

public void setAutomaticallyFollowHyperlinks(boolean b)

Enables/disables the automatic navigation of activated hyperlinks in a CalHTMLPane. 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 CalHTMLObserver

Parameters:

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

isAutomaticallyFollowHyperlinksEnabled

public boolean isAutomaticallyFollowHyperlinksEnabled()

Returns whether a CalHTMLPane 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 CalHTMLPane. The default value is true. If set to false, form submissions will still be passed to the resident CalHTMLObserver

Parameters:

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

isHandleFormSubmissionEnabled

public boolean isHandleFormSubmissionEnabled()

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

Returns:

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

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 CalHTMLPane 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 CalHTMLPane 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 CalHTMLObserver

Parameters:

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

isHandleNewFramesEnabled

public boolean isHandleNewFramesEnabled()

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

Returns:

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

setRequestFocusOnMouseClick

public void setRequestFocusOnMouseClick(boolean b)

Determines whether a CalHTMLPane 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 CalHTMLPane frame should call requestFocus() if the mouse is clicked within it.

isRequestFocusOnMouseClickEnabled

public boolean isRequestFocusOnMouseClickEnabled()

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

Returns:

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