HLook

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
Interface HLook

All Superinterfaces:
  Cloneable

All Known Subinterfaces:
  HAdjustableLook, HExtendedLook

All Known Implementing Classes:
  HAnimateLook, HGraphicLook, HListGroupLook, HMultilineEntryLook, HRangeLook, HSinglelineEntryLook, HTextLook

    public interface HLook

extends Cloneable

The `HLook` interface defines the "look" of a component and may be regarded as a mechanism to allow a "pluggable" paint method to be attached to the component. Instead of having to subclass the entire component to change its look, it is possible to simply implement an `HLook` that will render the component "look" and then associate this `HLook` implementation with the component.

### Borders

An implementation of `HLook` will also include code to draw implementation-specific borders. The application or component can query the reserved space for an `HLook` with the `getInsets` method.

Since the border area is included in the overall size of the component, the border effectively constrains the area available for rendering content to the rectangle which has an upper-left corner location of `(insets.left, insets.top)`, and has a size of `width - (insets.left + insets.right)` by `height - (insets.top + insets.bottom)`.

### Invocation Mechanism

The `showLook` method of the `HLook` interface will be called by the havi.ui framework in response to the paint method of the `HVisible` being called by the AWT lightweight component framework. Applications should simply invoke the component repaint method as in normal AWT, rather than calling the `showLook` method directly.

### Content Rendering

Some looks make use of content stored on an associated `HVisible`. These looks are:

- `HAnimateLook` - for animated graphical content
- `HGraphicLook` - for static graphical content
- `HTextLook` - for static textual content
- `HSinglelineEntryLook` - for single line text entry content
- `HMultilineEntryLook` - for multiline text entry content
- `HListGroupLook` - for list element content

Some of these looks may support the scaling and alignment of their content as an implementation option. The scaling and alignment modes supported are specified in the class description of `HVisible`. The table below details which features the content-based platform looks should support:

HLook | Scaling | Alignment
--- | --- | ---
HAnimateLook | Optional | Mandatory
HGraphicLook | Optional | Mandatory
HListGroupLook | Optional | Mandatory
HTextLook | Not used | Mandatory
HSinglelineEntryLook | Not used | Not used
HMultilineEntryLook | Not used | Not used

Where scaling support is optional all implementations must as a minimum support the `RESIZE_NONE` scaling mode. Platforms are not required to support scaling of textual content by default.

Looks should use the `getHorizontalAlignment` and `getVerticalAlignment` methods to retrieve the current alignment modes, and the `getResizeMode` method to determine the active scaling mode, where supported. However, note that HAVi platform looks which render text content using the `HDefaultTextLayoutManager` class shall delegate the alignment of text content to the layout manager.

### Rendering Hints

HLook provides a method, `widgetChanged` which can be called by an `HVisible` with one or more hints to inform the look that something has changed. This method provides information to the look about what has changed, which allows smarter repainting than having the HVisible simply call its `repaint` method. The hint constants are defined on `HVisible`. See the class definition for `HVisible` for more information.

### Private Data

Implementations of `HLook` may store private data on each instance of an `HVisible` to optimize the drawing of that component. However, this is an implementation option. Furthermore such data may be invalidated by another part of the system, for example if `setLook` is called on `HVisible`. Therefore if this mechanism is used by implementations of `HLook` those implementations must be capable of regenerating such data on the fly, according to the current state of the `HVisible`.

### Platform Looks

The HAVi UI provides a number of classes implementing the `HLook` interface. Applications wishing to provide their own `HLooks` may directly implement this interface or may subclass those provided by the platform.

### Default Behavior

Unless already specified in a particular `HLook`, implementations of `HLook` should use:

- the foreground color of each associated `HVisible` (using the java.awt.Component method getForeground) to determine the Color to render both the content and border (as necessary)
- the background color of each associated `HVisible` (using the java.awt.Component method getBackground) to determine the Color used to render a rectangular area to fill the component and erase any previous content, as specified by the current background drawing mode for that component - see `setBackgroundMode` on `HVisible`.
- the current alignment mode of each associated `HVisible` (using `getHorizontalAlignment` and `getVerticalAlignment`) to determine how to align content.
- the current scaling mode of each associated `HVisible` (using to `getResizeMode`) to determine how to scale content.

See Also:
  `HVisible.setLook(org.havi.ui.HLook)`, `HVisible.setLookData(java.lang.Object, java.lang.Object)`, `HVisible.paint(java.awt.Graphics)`, `HVisible.setBackgroundMode(int)`, `HVisible.setHorizontalAlignment(int)`, `HVisible.setVerticalAlignment(int)`, `HVisible.setResizeMode(int)`, `HTextLook`, `HGraphicLook`, `HAnimateLook`, `HRangeLook`, `HSinglelineEntryLook`, `HMultilineEntryLook`

Method Summary
`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`.
`boolean` | `isOpaque(HVisible visible)` Returns true if the entire painted area of the `HVisible` when using this look is fully opaque, i.e.
`void` | `showLook(Graphics g, HVisible visible, int state)` The `showLook` method is responsible for repainting the entire `HVisible` component, (including any content set on the component, and the component background), subject to the clipping rectangle of the Graphics object passed to it.
`void` | `widgetChanged(HVisible visible, HChangeData[] changes)` Called by the `HVisible` whenever its content, state, or any other data changes.

Method Detail

### showLook

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

  The `showLook` method is responsible for repainting the entire `HVisible` component, (including any content set on the component, and the component background), subject to the clipping rectangle of the Graphics object passed to it.

  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.

  For looks which draw content (e.g. `HTextLook`, `HGraphicLook` and `HAnimateLook`), if no content is associated with the component, the `showLook` method paints the component with its current background `Color` according to the `setBackgroundMode` method of `HVisible` and draws any (implementation-specific) borders. Note that by default the background mode is set so as to not paint a background. Furthermore on platforms which support transparent colors the background `Color` may be partially or completely transparent.

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

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

  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

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

  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

    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.

  Parameters:
    `hvisible` - `HVisible` to which this `HLook` is attached.
  Returns:
    A dimension object indicating this `HLook's` minimum size.
  See Also:
    `HVisible.getMinimumSize()`

### getPreferredSize

    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.

  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

    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.

  Parameters:
    `hvisible` - `HVisible` to which this `HLook` is attached.
  Returns:
    A dimension object indicating this `HLook's` maximum size.
  See Also:
    `HVisible.getMaximumSize()`

### isOpaque

    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.

  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

    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`.

  Parameters:
    `hvisible` - `HVisible` to which this `HLook` is attached.
  Returns:
    the insets of this `HLook`.

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

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