org.havi.ui

Class HListGroupLook

java.lang.Object

org.havi.ui.HListGroupLook

All Implemented Interfaces:

Cloneable, HAdjustableLook, HExtendedLook, HLook

public class HListGroupLook
extends Object
implements HExtendedLook, HAdjustableLook

The HListGroupLook class is used by the HListGroup component to display both the HListGroup itself (potentially including a scrollbar component) and graphical or textual list content held on the HListGroup. This look will be provided by the platform and the exact way in which it is rendered will be platform dependent.

The HListGroupLook class draws the HListGroup and any look-specific borders around the component, and then renders the content set on the HListGroup. It uses the getListContent method to determine the content to render. The content of the HListGroup does not depend on the interaction state.

HListGroupLook should use the following properties of HListGroup to lay out and render the HListElement content:

Item	Method	Purpose
Orientation	getOrientation	direction to lay out elements
Content	getListContent	elements to display
Scroll position	getScrollPosition	first element to draw
Selection	isItemSelected	mark an element as selected
Current item	getCurrentItem	highlight an element

HListGroupLook should draw a scrollbar as necessary when there are more HListElements than can be displayed. It is an implementation option to leave border space between each element. The insets used for the element borders can be retrieved using getElementInsets

Implementations of HListGroupLook should use the appropriate methods on HListGroup to determine which scaling and alignment modes to use when rendering content. See the class description for HLook for more details.

HListGroupLook may support scalable graphical content. As a minimum, all implementations must support the RESIZE_NONE scaling mode for graphical content, and all alignment modes for text content. However, Note that HListGroupLook behaves slightly differently from other HAVi HLook classes, as follows.

• Where supported, scaling applies to the icon (graphical content) of each HListElement, based on the area allocated to that HListElement rather than the entire area of the HListGroup.
• Alignment mode applies to the content of the HListElement within the area allocated to that HListElement rather than the entire area of the HListGroup.

Note that the results of applying the VALIGN_JUSTIFY and HALIGN_JUSTIFY alignment modes to graphical content are defined to identical to VALIGN_CENTER and HALIGN_CENTER modes respectively, as justification is meaningless in this context.

This is the default look that is used by HListGroup.

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
Element insets	null	getElementInsets	---

See Also:

HListGroup, HListElement, HVisible, HLook, HDefaultTextLayoutManager

Field Summary

Fields inherited from interface org.havi.ui.HAdjustableLook

ADJUST_BUTTON_LESS, ADJUST_BUTTON_MORE, ADJUST_NONE, ADJUST_PAGE_LESS, ADJUST_PAGE_MORE, ADJUST_THUMB

Constructor Summary

Constructors

Constructor and Description
HListGroupLook() Creates a HListGroupLook 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.
Insets	getElementInsets() Retrieve the element insets for this instance of HListGroupLook.
Insets	getInsets(HVisible visible) Determines the insets of this HLook, which indicate the size of the border.
Dimension	getMaximumSize(HVisible visible) Returns the size to present all elements of the specified HVisible plus any additional dimensions that the HListGroupLook requires for border decoration etc.
Dimension	getMinimumSize(HVisible visible) Returns the size to present one element of the specified HVisible plus any additional dimensions that the HListGroupLook requires for border decoration etc.
int	getNumVisible(HVisible visible) Retrieve the number of visible elements for the specified component.
Dimension	getPreferredSize(HVisible visible) Gets the preferred size of the HVisible component when drawn with this HListGroupLook.
Integer	getValue(HOrientable component, Point pt) Returns the value of the component which corresponds to the pointer position specified by pt.
int	hitTest(HOrientable component, Point pt) Returns a value which indicates the pointer click position in the on-screen representation of the orientable component.
boolean	isOpaque(HVisible visible) 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

HListGroupLook

public HListGroupLook()

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

Method Detail

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

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.

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

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

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.

The labels of the associated HListElements shall be rendered by using the current text layout manager of the HListGroup. For each visible label is the render() method of HTextLayoutManager called. The position and size per label are specified as insets relatively to the bounds of HListGroup. Note that the bounds are independent of any borders of the HListGroup, but the insets have to include the borders per element, if any. The look shall use the method getLabelSize() of HListGroup to determine the size for each label. If the returned dimension object has DEFAULT_LABEL_WIDTH for the width and/or DEFAULT_LABEL_HEIGHT for the height as values, then this method shall use implementation specific value(s) as default(s) for the missing dimension(s) instead. If getTextLayoutManager() returns null, then labels shall not be rendered.

If supported, scaling of icons shall reflect the resize mode of the visible within the area of the respective list element. The look shall use the method getIconSize() of HListGroup to determine the size for each icon. If the returned dimension object has DEFAULT_ICON_WIDTH for the width and/or DEFAULT_ICON_HEIGHT for the height as values, then this method shall use implementation specific value(s) as default(s) for the missing dimension(s) instead.

Except for the alignment of labels and sizes of labels and icons, it is explicitly not defined, how this look arranges icons and labels within the elements' areas. Additionally, it is an implementation option to render labels and icons in other sizes than specified, if the available size per element is smaller or larger than label and icon size. It is also not defined, how the look presents the current item and selected items, or the current selection mode. The elements shall be layed out as specified by getOrientation() of the associated HListGroup.

When the associated HListGroup contains more elements than presentable, the look shall make the user aware of that condition, e.g. by displaying an additional scrollbar reflecting the current scroll position. Again, the visible means by which this information is conveyed is not defined and implementation dependent. It is an implementation option for HListGroupLook to draw elements before the scroll position, in order to fill the available space.

The behavior of this method, when a subclass overrides the methods getInsets() or getElementInsets(), is not defined. Application developers shall not assume that the corresponding borders will appear as specified.

The HExtendedLook.renderVisible(java.awt.Graphics, org.havi.ui.HVisible, int) method is responsible for painting any implementation specific borders for each HListElement as well as drawing of an additional scrollbar if required.

Specified by:

renderVisible in interface HExtendedLook

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

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

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 visible)

Returns the size to present one element of the specified HVisible plus any additional dimensions that the HListGroupLook requires for border decoration etc.

The extra space required for border decoration can be determined from the getInsets() and getElementInsets() methods. The behavior is not defined for the case, when a subclass overrides these methods. Application developers shall not assume any influence on the returned dimensions.

The size per element shall be determined by calls to getIconSize() and getLabelSize() of HListGroup. If any of the dimensions requests a default as specified by DEFAULT_ICON_WIDTH, DEFAULT_ICON_HEIGHT, DEFAULT_LABEL_WIDTH and DEFAULT_LABEL_HEIGHT, then an implementation specific default is used for the corresponding value(s).

Specified by:

getMinimumSize in interface HLook

Parameters:

visible - HVisible to which this HLook is attached.

Returns:

A dimension object indicating this HLook's minimum size.

See Also:

HListGroup.setIconSize(java.awt.Dimension), HListGroup.setLabelSize(java.awt.Dimension), HVisible.getMinimumSize()

getPreferredSize

public Dimension getPreferredSize(HVisible visible)

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

If a default size for width and height was set with HVisible.setDefaultSize(), then the dimensions are rounded down to the nearest element (minimum of one) according to the orientation of the associated HListGroup, and any dimensions for border decorations etc. are added.

If no default size was set or only for one dimension (i.e. height is NO_DEFAULT_HEIGHT or width is NO_DEFAULT_WIDTH), then the unset dimension(s) shall be sufficiently large to present five elements according to the HListGroup's orientation. Any dimensions for border decoration etc. are added.

The extra space required for border decoration can be determined from the getInsets() and getElementInsets() methods. The behavior is not defined for the case, when a subclass overrides these methods. Application developers shall not assume any influence on the returned dimensions.

The size per element shall be determined by calls to getIconSize() and getLabelSize() of HListGroup. If any of the values requests a default as specified by DEFAULT_ICON_WIDTH, DEFAULT_ICON_HEIGHT, DEFAULT_LABEL_WIDTH and DEFAULT_LABEL_HEIGHT, then an implementation specific default is used for the corresponding value(s).

Specified by:

getPreferredSize in interface HLook

Parameters:

visible - HVisible to which this HLook is attached.

Returns:

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

See Also:

HListGroup.setIconSize(java.awt.Dimension), HListGroup.setLabelSize(java.awt.Dimension), HVisible.getPreferredSize(), HVisible.setDefaultSize(java.awt.Dimension)

getMaximumSize

public Dimension getMaximumSize(HVisible visible)

Returns the size to present all elements of the specified HVisible plus any additional dimensions that the HListGroupLook requires for border decoration etc. If no elements are present, a dimension object is returned with width and height set to java.lang.Short.MAX_VALUE.

The extra space required for border decoration can be determined from the getInsets() and getElementInsets() methods. The behavior is not defined for the case, when a subclass overrides these methods. Application developers shall not assume any influence on the returned dimensions.

The size per element shall be determined by calls to getIconSize() and getLabelSize() of HListGroup. If any of the values requests a default as specified by DEFAULT_ICON_WIDTH, DEFAULT_ICON_HEIGHT, DEFAULT_LABEL_WIDTH and DEFAULT_LABEL_HEIGHT, then an implementation specific default is used for the corresponding value(s).

Specified by:

getMaximumSize in interface HLook

Parameters:

visible - HVisible to which this HLook is attached.

Returns:

A dimension object indicating this HListGroupLook's maximum size.

See Also:

HListGroup.setIconSize(java.awt.Dimension), HListGroup.setLabelSize(java.awt.Dimension), HVisible.getMaximumSize()

isOpaque

public boolean isOpaque(HVisible visible)

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

Parameters:

visible - 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 visible)

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

Parameters:

visible - HVisible to which this HLook is attached.

Returns:

the insets of this HLook.

hitTest

public int hitTest(HOrientable component,
          Point pt)

Returns a value which indicates the pointer click position in the on-screen representation of the orientable component.

The behavior of this method in HListGroupLook differs from the behavior of HAdjustableLook.hitTest() in that if the position belongs to an HListElement of the associated HListGroup, then this method will return the index of that element. The HListGroup shall interpret this index as current item. If the value is ADJUST_THUMB, then the caller shall use getValue() to retrieve the actual scroll position corresponding to the specified pointer position. The look will not change the appearance of that element (eg. by highlighting it). Such a change may only occur due to a call to widgetChanged(org.havi.ui.HVisible, org.havi.ui.HChangeData[]).

Note that it is a valid implementation option to always return ADJUST_NONE.

Specified by:

hitTest in interface HAdjustableLook

Parameters:

component - - the HOrientable component for which the hit position should be calculated

pt - - the pointer click point relative to the upper-left corner of the specified component.

Returns:

one of ADJUST_NONE, ADJUST_BUTTON_LESS, ADJUST_PAGE_LESS, ADJUST_THUMB, ADJUST_PAGE_MORE or ADJUST_BUTTON_MORE, or a non-negative element index.

getValue

public Integer getValue(HOrientable component,
               Point pt)

Returns the value of the component which corresponds to the pointer position specified by pt. If the position does not map to a value (eg. the mouse is outside the active area of the component), this method returns null. A non-null value represents the scroll position of the associated HListGroup. The value shall never be less than zero.

The look shall not reflect the value returned by this method visibly. If the component uses the returned value, it will inform the look by calling widgetChanged().

Specified by:

getValue in interface HAdjustableLook

Parameters:

component - an HOrientable implemented by an HVisible

pt - the position of the mouse-cursor relative to the upper-left corner of the associated component

Returns:

the non-negative scroll position associated with the specified pointer position or null

See Also:

hitTest(org.havi.ui.HOrientable, java.awt.Point)

getElementInsets

public Insets getElementInsets()

Retrieve the element insets for this instance of HListGroupLook. The element insets control the amount of empty space left between the elements and the border of the HListGroup component.

Returns:

the element insets, or null if insets are not used by this implementation of HListGroupLook.

getNumVisible

public int getNumVisible(HVisible visible)

Retrieve the number of visible elements for the specified component.

This method should determine the number of list elements that would be completely visible should the specified component be drawn using this look.

Parameters:

visible - the HVisible to obtain the number of visible elements for.

Returns:

the number of visible elements.