org.havi.ui

Class HMultilineEntryLook

java.lang.Object

org.havi.ui.HSinglelineEntryLook

org.havi.ui.HMultilineEntryLook

All Implemented Interfaces:

Cloneable, HExtendedLook, HLook

public class HMultilineEntryLook
extends HSinglelineEntryLook

The HMultilineEntryLook class is used by the HMultilineEntry component to display the entering of text. This look will be provided by the platform and the exact way in which it is rendered will be platform dependent.

The HMultilineEntryLook class draws the content set on an HMultilineEntry. It uses the getTextContent(int state) method to determine the content to render. The interaction state of the HMultilineEntry is ignored.

This is the default look that is used by HMultilineEntry and its subclasses.

The parameters to the constructors are as follows, in cases where parameters are not used, then the constructor should use the default values.

Default parameter values exposed in the constructors

Parameter	Description	Default value	Set method	Get method
None.

Default parameter values not exposed in the constructors

Description	Default value	Set method	Get method
None.

See Also:

HMultilineEntry

Constructor Summary

Constructors

Constructor and Description
HMultilineEntryLook() Creates a HMultilineEntryLook object.

Method Summary

Methods

Modifier and Type	Method and Description
void	fillBackground(Graphics g, HVisible visible, int state) The HExtendedLook.fillBackground(java.awt.Graphics, org.havi.ui.HVisible, int) method paints the component with its current background Color according to the HVisible.setBackgroundMode(int) method of HVisible.
int	getCaretCharPositionForLine(HVisible visible, int line) Returns the character position of the caret within the content string if it were to be moved vertically to the given 'line'.
int	getCaretPositionNextLine(HVisible visible) Returns the character position of the caret within the content string if it were to be moved down one line.
int	getCaretPositionPreviousLine(HVisible visible) Returns the character position of the caret within the content string if it were to be moved up one line.
Insets	getInsets(HVisible hvisible) Determines the insets of this HLook, which indicate the size of the border.
Dimension	getMaximumSize(HVisible hvisible) Gets the maximum size of the HVisible component when drawn with this HLook.
Dimension	getMinimumSize(HVisible hvisible) Gets the minimum size of the HVisible component when drawn with this HLook.
Dimension	getPreferredSize(HVisible hvisible) Gets the preferred size of the HVisible component when drawn with this HLook.
int[]	getSoftLineBreakPositions(HVisible visible) Returns the positions within the content string of all those characters that start on a new 'line' (including those following \n), in order from the first line to the last, including the line starting at 0.
int[]	getVisibleSoftLineBreakPositions(HVisible visible) Returns the starting positions of lines currently shown within the HVisible.
boolean	isOpaque(HVisible hvisible) Returns true if the entire painted area of the HVisible when using this look is fully opaque, i.e.
void	renderBorders(Graphics g, HVisible visible, int state) The HExtendedLook.renderBorders(java.awt.Graphics, org.havi.ui.HVisible, int) method paints any implementation specific borders according to the HVisible.setBordersEnabled(boolean) method of HVisible.
void	renderVisible(Graphics g, HVisible visible, int state) The HExtendedLook.renderVisible(java.awt.Graphics, org.havi.ui.HVisible, int) method paints any content or other data associated with the look's HVisible.
void	showLook(Graphics g, HVisible visible, int state) The showLook method is the entry point for repainting the entire HVisible component.
void	widgetChanged(HVisible visible, HChangeData[] changes) Called by the HVisible whenever its content, state, or any other data changes.

Methods inherited from class java.lang.Object

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

Constructor Detail

HMultilineEntryLook

public HMultilineEntryLook()

Creates a HMultilineEntryLook object. See the class description for details of constructor parameters and default values.

Method Detail

fillBackground

public void fillBackground(Graphics g,
                  HVisible visible,
                  int state)

The HExtendedLook.fillBackground(java.awt.Graphics, org.havi.ui.HVisible, int) method paints the component with its current background Color according to the HVisible.setBackgroundMode(int) method of HVisible.

This method is only called from showLook within this HExtendedLook implementation. It's not the intention to call this method directly from outside of the HExtendedLook.

Regardless of the background mode, it is an implementation option for this method to render added decorations which may affect the look's transparency. This method shall not be used to render any HVisible related data or content associated with the HVisible. It is purely for background and decoration only.

The fillBackground method should not modify the clipRect (clipping rectangle) of the Graphics object that is passed to it in a way which includes any area not part of that original clipRect. If any modifications are made, the original clipRect shall be restored.

Specified by:

fillBackground in interface HExtendedLook

Overrides:

fillBackground in class HSinglelineEntryLook

Parameters:

g - the graphics context.

visible - the visible.

state - the state parameter indicates the state of the visible

Since:

MHP 1.0.3/1.1.1

See Also:

HLook.isOpaque(org.havi.ui.HVisible)

renderBorders

public void renderBorders(Graphics g,
                 HVisible visible,
                 int state)

The HExtendedLook.renderBorders(java.awt.Graphics, org.havi.ui.HVisible, int) method paints any implementation specific borders according to the HVisible.setBordersEnabled(boolean) method of HVisible. If borders are drawn, the border decoration shall be rendered within the border area as returned by getInsets. The behavior of this method, when a subclass overrides the method getInsets is undefined, except that it will never draw outside the border area as returned by getInsets.

This method is only called from showLook within this HExtendedLook implementation. It's not the intention to call this method directly from outside of the HExtendedLook.

The HExtendedLook.renderBorders(java.awt.Graphics, org.havi.ui.HVisible, int) method should not modify the clipRect (clipping rectangle) of the Graphics object that is passed to it in a way which includes any area not part of that original clipRect. If any modifications are made, the original clipRect shall be restored.

Specified by:

renderBorders in interface HExtendedLook

Overrides:

renderBorders in class HSinglelineEntryLook

Parameters:

g - the graphics context.

visible - the visible.

state - the state parameter indicates the state of the visible

Since:

MHP 1.0.3/1.1.1

renderVisible

public void renderVisible(Graphics g,
                 HVisible visible,
                 int state)

The HExtendedLook.renderVisible(java.awt.Graphics, org.havi.ui.HVisible, int) method paints any content or other data associated with the look's HVisible. This method shall not be used to render a background nor any other decoration. Its purpose is purely to render content or other value data stored on the HVisible. This may be set via HVisible methods such as setTextContent and setGraphicContent. Rendering shall take place within the bounds returned by the getInsets method.

This method is only called from showLook within this HExtendedLook implementation. It's not the intention to call this method directly from outside of the HExtendedLook.

For looks which draw content (e.g. HTextLook, HGraphicLook and HAnimateLook), if no content is associated with the component, this method does nothing.

The HExtendedLook.renderVisible(java.awt.Graphics, org.havi.ui.HVisible, int) method should not modify the clipRect (clipping rectangle) of the Graphics object that is passed to it in a way which includes any area not part of that original clipRect. If any modifications are made, the original clipRect shall be restored.

Specified by:

renderVisible in interface HExtendedLook

Overrides:

renderVisible in class HSinglelineEntryLook

Parameters:

g - the graphics context.

visible - the visible.

state - the state parameter indicates the state of the visible

Since:

MHP 1.0.3/1.1.1

showLook

public void showLook(Graphics g,
            HVisible visible,
            int state)

The showLook method is the entry point for repainting the entire HVisible component. This method delegates the responsibility of drawing the component background, borders and any HVisible related data or content to the fillBackground, renderVisible and renderBorders methods respectively, subject to the clipping rectangle of the Graphics object passed to it. This method shall call the methods fillBackground, renderVisible, and renderBorders in that order and shall not do any rendering itself.

The showLook method should not modify the clipRect (clipping rectangle) of the Graphics object that is passed to it in a way which includes any area not part of that original clipRect. If any modifications are made, the original clipRect shall be restored.

Any resources explicitly associated with an HExtendedLook should be loaded by the HExtendedLook during its creation, etc. Note that the "standard" looks don't load content by default.

This method is called from the HVisible.paint(java.awt.Graphics) method of HVisible and must never be called from elsewhere. Components wishing to redraw themselves should call their repaint method in the usual way.

Specified by:

showLook in interface HExtendedLook

Specified by:

showLook in interface HLook

Overrides:

showLook in class HSinglelineEntryLook

Parameters:

g - the graphics context.

visible - the visible.

state - the state parameter indicates the state of the visible, allowing the look to render the appropriate content for that state. Note that some components (e.g. HStaticRange, HRange, HRangeValue) do not use state-based content.

widgetChanged

public void widgetChanged(HVisible visible,
                 HChangeData[] changes)

Called by the HVisible whenever its content, state, or any other data changes. See the class description of HVisible for more information about the changes parameter.

The implementation of this method should work out which graphical areas of the HVisible have changed and make any relevant calls to trigger the repainting of those areas.

A minimum implementation of this method could simply call

 visible.repaint()
 

Specified by:

widgetChanged in interface HLook

Overrides:

widgetChanged in class HSinglelineEntryLook

Parameters:

visible - the HVisible which has changed

changes - an array containing hint data and associated hint objects. If this argument is null a full repaint will be triggered.

getMinimumSize

public Dimension getMinimumSize(HVisible hvisible)

Gets the minimum size of the HVisible component when drawn with this HLook.

This size may be determined in several ways depending on the information available to the look. These steps are performed in order and the first available result is returned. For the purposes of this algorithm HLook classes that do not use content (e.g. HRangeLook) are treated as if no content was present.

The extra space required for border decoration can be determined from the getInsets method.

1. If this look is an HTextLook and if HVisible.getTextLayoutManager() returns an HDefaultTextLayoutManager, then this method should delegate the call to its getMinimumSize() method plus any additional dimensions that the HLook requires for border decoration etc. If the HDefaultTextLayoutManager returns a zero size, then proceed with the following steps.
2. If the HLook supports the scaling of its content (e.g. an HGraphicLook) and scaling is requested and content is set, then the return value is a size containing the width of the narrowest content and the height of the shortest content plus any additional dimensions that the HLook requires for border decoration etc.
3. If the HLook does not support scaling of content or no scaling is requested, and content is set then the return value is a size sufficiently large to hold each piece of content plus any additional dimensions that the HLook requires for border decoration etc.
4. If no content is available but a default preferred size has been set using setDefaultSize has been called to set then the return value is this value (as obtained with getDefaultSize) plus any additional dimensions that the HLook requires for border decoration etc.
5. If there is no content or default size set then the return value is an implementation-specific minimum size plus any additional dimensions that the HLook requires for border decoration etc.

Specified by:

getMinimumSize in interface HLook

Overrides:

getMinimumSize in class HSinglelineEntryLook

Parameters:

hvisible - HVisible to which this HLook is attached.

Returns:

A dimension object indicating this HLook's minimum size.

See Also:

HVisible.getMinimumSize()

getPreferredSize

public Dimension getPreferredSize(HVisible hvisible)

Gets the preferred size of the HVisible component when drawn with this HLook.

This size may be determined in several ways depending on the information available to the look. These steps are performed in order and the first available result is returned. For the purposes of this algorithm HLook classes that do not use content (e.g. HRangeLook) are treated as if no content was present.

The extra space required for border decoration can be determined from the getInsets method.

1. If a default preferred size has been set for this HVisible (using setDefaultSize) then the return value is this size (obtained with getDefaultSize) plus any additional dimensions that the HLook requires for border decoration etc.
2. If this look is an HTextLook and if a default preferred size has not been set and HVisible.getTextLayoutManager() returns an HDefaultTextLayoutManager, then this method should delegate the call to its getPreferredSize() method plus any additional dimensions that the HLook requires for border decoration etc. If the HDefaultTextLayoutManager returns a zero size, then proceed with the following steps.
3. If this HLook does not support scaling of content or no scaling is requested, and content is present then the return value is a size that is sufficiently large to hold each piece of content plus any additional dimensions that the HLook requires for border decoration etc.
4. If this HLook supports the scaling of its content (e.g. an HGraphicLook) and content is set then the return value is the current size of the HVisible as returned by getSize).
5. If there is no content and no default size set then the return value is the current size of the HVisible as returned by getSize).

If a default preferred size has been set for this HVisible (using setDefaultSize()) and the default preferred size has a NO_DEFAULT_WIDTH then the return value is a Dimension with this height (obtained with getDefaultSize()) and the preferred width for the content plus any additional dimensions that the HLook requires for border decoration etc.

If a default preferred size has been set for this HVisible (using setDefaultSize()) and the default preferred size has a NO_DEFAULT_HEIGHT then the return value is a Dimension with this width (obtained with getDefaultSize()) and the preferred height for the content plus any additional dimensions that the HLook requires for border decoration etc.

Specified by:

getPreferredSize in interface HLook

Overrides:

getPreferredSize in class HSinglelineEntryLook

Parameters:

hvisible - HVisible to which this HLook is attached.

Returns:

A dimension object indicating the preferred size of the HVisible when drawn with this HLook.

See Also:

HVisible.getPreferredSize(), HVisible.setDefaultSize(java.awt.Dimension)

getMaximumSize

public Dimension getMaximumSize(HVisible hvisible)

Gets the maximum size of the HVisible component when drawn with this HLook.

This size may be determined in several ways depending on the information available to the look. These steps are performed in order and the first available result is returned. For the purposes of this algorithm HLook classes that do not use content (e.g. HRangeLook) are treated as if no content was present.

The extra space required for border decoration can be determined from the getInsets method.

1. If this look is an HTextLook and if HVisible.getTextLayoutManager() returns an HDefaultTextLayoutManager, then this method should delegate the call to its getMaximumSize() method plus any additional dimensions that the HLook requires for border decoration etc. If the HDefaultTextLayoutManager returns a zero size, then proceed with the following steps.
2. If the HLook supports the scaling of its content (e.g. an HGraphicLook) then the return value is the current size of the HVisible (as returned by HVisible#getSize).
3. If the HLook does not support scaling of content or no scaling is requested, and content is set then the return value is a size sufficiently large to hold each piece of content plus any additional dimensions that the HLook requires for border decoration etc.
4. If there is no content set then a maximum size of [Short.MAX_VALUE, Short.MAX_VALUE] is returned as a Dimension.

Specified by:

getMaximumSize in interface HLook

Overrides:

getMaximumSize in class HSinglelineEntryLook

Parameters:

hvisible - HVisible to which this HLook is attached.

Returns:

A dimension object indicating this HLook's maximum size.

See Also:

HVisible.getMaximumSize()

isOpaque

public boolean isOpaque(HVisible hvisible)

Returns true if the entire painted area of the HVisible when using this look is fully opaque, i.e. the showLook method guarantees that all pixels are painted in an opaque Color.

The default value is implementation specific and depends on the background painting mode of the given HVisible. The consequences of an invalid overridden value are implementation specific.

Specified by:

isOpaque in interface HLook

Overrides:

isOpaque in class HSinglelineEntryLook

Parameters:

hvisible - the visible to test

Returns:

true if all the pixels with the java.awt.Component#getBounds method of an HVisible using this look are fully opaque, i.e. the showLook method guarantees that all pixels are painted in an opaque Color, otherwise false.

getInsets

public Insets getInsets(HVisible hvisible)

Determines the insets of this HLook, which indicate the size of the border. This area is reserved for the HLook to use for drawing borders around the associated HVisible.

Specified by:

getInsets in interface HLook

Overrides:

getInsets in class HSinglelineEntryLook

Parameters:

hvisible - HVisible to which this HLook is attached.

Returns:

the insets of this HLook.

getCaretPositionNextLine

public int getCaretPositionNextLine(HVisible visible)

Returns the character position of the caret within the content string if it were to be moved down one line.

Parameters:

visible - a multiline text entry component.

Note that if this component is not actually using this HLook to display itself the return value of this method will probably be wrong. Application authors should take care to only call this method with components which are using this instance of the HMultilineEntryLook.

Returns:

the caret position (as defined in HSinglelineEntry#getCaretCharPosition) to move the caret to if it were moved down one line, or the nearest position if this is not possible.

getCaretPositionPreviousLine

public int getCaretPositionPreviousLine(HVisible visible)

Returns the character position of the caret within the content string if it were to be moved up one line.

Parameters:

visible - a multiline text entry component.

Note that if this component is not actually using this HLook to display itself the return value of this method will probably be wrong. Application authors should take care to only call this method with components which are using this instance of the HMultilineEntryLook.

Returns:

the caret position (as defined in HSinglelineEntry#getCaretCharPosition) to move the caret to if it were moved up one line, or the nearest position if this is not possible.

getCaretCharPositionForLine

public int getCaretCharPositionForLine(HVisible visible,
                              int line)

Returns the character position of the caret within the content string if it were to be moved vertically to the given 'line'. A line is identified by its first character as obtained from the getSoftLineBreakPositions() method. If an invalid line is specified an IllegalArgumentException is thrown. If the caret cannot be moved to the same column position on this line, the nearest position should be returned.

Parameters:

visible - a multiline text entry component.

Note that if this component is not actually using this HLook to display itself the return value of this method will probably be wrong. Application authors should take care to only call this method with components which are using this instance of the HMultilineEntryLook.

line - the line number for which the caret position is requested

Returns:

the caret position (as defined in HSinglelineEntry#getCaretCharPosition) to move the caret to if it were moved to this line.

See Also:

HSinglelineEntry.getCaretCharPosition(), getSoftLineBreakPositions(org.havi.ui.HVisible)

getVisibleSoftLineBreakPositions

public int[] getVisibleSoftLineBreakPositions(HVisible visible)

Returns the starting positions of lines currently shown within the HVisible. Lines are identified by the positions of those characters that start on a new 'line' (including those following \n), in order, from the first visible line to the last. This method can be used to calculate the number of visible lines currently shown in the look as well as the line shown at the top of the visible window.

Parameters:

visible - a multiline text entry component.

Returns:

the starting positions of the lines currently shown within the HVisible. If there is no text content within the HVisible, a zero length array shall be returned.

getSoftLineBreakPositions

public int[] getSoftLineBreakPositions(HVisible visible)

Returns the positions within the content string of all those characters that start on a new 'line' (including those following \n), in order from the first line to the last, including the line starting at 0.

Parameters:

visible - a multiline text entry component.

Note that if this component is not actually using this HLook to display itself the return value of this method will probably be wrong. Application authors should take care to only call this method with components which are using this instance of the HMultilineEntryLook.

Returns:

the positions of 'soft line breaks' introduced by the HLook. If there is no text content within the HVisible, a zero length array shall be returned.