HListGroupLook

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`HListGroupLook()` Creates a `HListGroupLook` object.

Method Summary
`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 hvisible)` 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
`equals, 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 `HListElement`s 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 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`
  Parameters:
    `hvisible` - `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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD