HImageEffectMatte

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 HImageEffectMatte

    java.lang.Object
      org.havi.ui.HImageEffectMatte

All Implemented Interfaces:
  HAnimateEffect, HMatte

    public class HImageEffectMatte

extends Object
implements HMatte, HAnimateEffect

The `HImageEffectMatte` class represents a matte that varies over both space and time, it is specified as a sequence of image masks.

The data for any HImageEffectMatte may be changed "on the fly" using the `setMatteData` method. However, some implementations may be asynchronously referencing their content (i.e. through a separate implementation-specific animation thread). Therefore the following restrictions apply to the `setMatteData` method:

- The method must be synchronized with any implementation-specific animation thread such that content cannot be changed while a different thread is using it.
- If the animation was running the method should stop the animation in a synchronized manner before changing content.
- The method should reset the animation to a starting position defined by the current play mode. The repeat count of the animation should be reset to 0.
- If the animation was running the method should start the animation.

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
--- | --- | --- | --- | ---
data | The transparency data for this image effect matte. | null (the matte should be treated as being spatially and temporally unvarying and opaque) | `setMatteData` | `getMatteData`

### Default parameter values not exposed in the constructors

Description | Default value | Set method | Get method
--- | --- | --- | ---
The initial piece of content to be presented, i.e. its position in the content array. | 0 | `setPosition` | `getPosition`
By default the animation should be stopped. Hence, to start the animation its start method must be explicitly invoked. This mechanism allows for animations that are programmatically controlled, e.g. via the setPosition method. | "stopped" | `start` / `stop` | `isAnimated`
The pixel offset for each image within the `HImageEffectMatte`, relative to the top, left corner of its associated component. | A java.awt.Point (0, 0) | `setOffset` | `getOffset`

Field Summary

Fields inherited from interface org.havi.ui.HAnimateEffect
`PLAY_ALTERNATING, PLAY_REPEATING, REPEAT_INFINITE`

Constructor Summary
`HImageEffectMatte()` Creates an `HImageEffectMatte` object.
`HImageEffectMatte(Image[] data)` Creates an `HImageEffectMatte` object.

Method Summary
`int` | `getDelay()` Gets the presentation delay for this `HImageEffectMatte`.
`Image[]` | `getMatteData()` Returns the data used for this matte.
`Point` | `getOffset(int index)` Get the offset of a specified frame of the matte relative to its component in pixels.
`int` | `getPlayMode()` Gets the playing mode for this `HImageEffectMatte`.
`int` | `getPosition()` Get the current index into the content array which this `HImageEffectMatte` is using to display content.
`int` | `getRepeatCount()` Gets the number of times that this `HImageEffectMatte` is to be played.
`boolean` | `isAnimated()` This method indicates the animation (running) state of the `HImageEffectMatte`.
`void` | `setDelay(int count)` Sets the delay between the presentation of successive pieces of content (frames).
`void` | `setMatteData(Image[] data)` Sets the data for this matte (an array of images).
`void` | `setOffset(Point p, int index)` Set the offset of a specified frame of the matte relative to its component in pixels.
`void` | `setPlayMode(int mode)` Sets the playing mode for this `HImageEffectMatte`.
`void` | `setPosition(int position)` Set this `HImageEffectMatte` to display the content at the specified position.
`void` | `setRepeatCount(int count)` Sets the number of times that this `HImageEffectMatte` should be played.
`void` | `start()` This method starts this `HImageEffectMatte` playing.
`void` | `stop()` This method indicates that the running `HImageEffectMatte` should be stopped.

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### HImageEffectMatte

    public HImageEffectMatte()

  Creates an `HImageEffectMatte` object. See the class description for details of constructor parameters and default values.

### HImageEffectMatte

    public HImageEffectMatte(Image[] data)

  Creates an `HImageEffectMatte` object. See the class description for details of constructor parameters and default values.

Method Detail

### setMatteData

    public void setMatteData(Image[] data)

  Sets the data for this matte (an array of images). Any previously set data is replaced. If this method is called when the animation is running the data is changed immediately and the current animation position is reset according to the active play mode. The changes affect the animation immediately.

  Note that if the size of an image is smaller than the size of the component to which the matte is applied, the empty space behaves as if it were an opaque flat matte of value 1.0. By default images are aligned at the top left corner of the component. This can be changed with the `setOffset` method

  Parameters:
    `data` - the data for this matte. Specify a null object to remove the associated data for this matte. If the length of the data array is zero, an IllegalArgumentException is thrown. If an element of the data array is null, or an image referred to is still being loaded, then that image will be skipped when the animation is playing.

### getMatteData

    public Image[] getMatteData()

  Returns the data used for this matte.

  Returns:
    the data used for this matte (an array of images) or null if no matte data has been set.

### setOffset

    public void setOffset(Point p,
                          int index)

  Set the offset of a specified frame of the matte relative to its component in pixels.

  Parameters:
    `p` - the offset of the specified frame of the matte relative to the top left corner of its component in pixels. If p is null a NullPointerException is thrown.
    `index` - the zero-index to the data for which the offset should be applied. If index is not valid for this matte an IndexOutOfBounds exception is thrown.

### getOffset

    public Point getOffset(int index)

  Get the offset of a specified frame of the matte relative to its component in pixels.

  Parameters:
    `index` - the zero-index to the data for which the offset should be recovered. If index is not valid for this matte an IndexOutOfBounds exception is thrown.
  Returns:
    the offset of the specified frame of the matte relative to its component in pixels (as a Point)

### start

    public void start()

  This method starts this `HImageEffectMatte` playing. If `start` is called when the animation is already running it resets the animation according to the current play mode, as returned by `getPlayMode`.

  Specified by:
    `start` in interface `HAnimateEffect`

### stop

    public void stop()

  This method indicates that the running `HImageEffectMatte` should be stopped. After calling this method, there is no guarantee that one or more frames will not be displayed before the animation actually stops playing. If the animation is already stopped further calls to `stop` have no effect.

  Specified by:
    `stop` in interface `HAnimateEffect`

### isAnimated

    public boolean isAnimated()

  This method indicates the animation (running) state of the `HImageEffectMatte`.

  Specified by:
    `isAnimated` in interface `HAnimateEffect`
  Returns:
    `true` if this `HImageEffectMatte` is running, i.e. the `start` method has been invoked - `false` otherwise.

### setPosition

    public void setPosition(int position)

  Set this `HImageEffectMatte` to display the content at the specified position. If the animation is already running a call to `setPosition` will change the current value and affect the animation immediately.

  Specified by:
    `setPosition` in interface `HAnimateEffect`
  Parameters:
    `position` - an index into the content array which specifies the next piece of content to be displayed. If `position` is less than 0, then the array element at index 0 is displayed, if `position` is greater than or equal to the length of the content array, then the array element at index [`length`-1] will be used.

### getPosition

    public int getPosition()

  Get the current index into the content array which this `HImageEffectMatte` is using to display content.

  Specified by:
    `getPosition` in interface `HAnimateEffect`
  Returns:
    the index of the content currently being displayed, in the range `0 <= index < length`

### setRepeatCount

    public void setRepeatCount(int count)

  Sets the number of times that this `HImageEffectMatte` should be played. If the animation is already running a call to `setRepeatCount` will change the current value and reset the current number of repeats to 0, affecting the animation immediately.

  Specified by:
    `setRepeatCount` in interface `HAnimateEffect`
  Parameters:
    `count` - the number of times that an `HImageEffectMatte` should be played. Valid values of the repeat count are one or more, and `REPEAT_INFINITE`.

### getRepeatCount

    public int getRepeatCount()

  Gets the number of times that this `HImageEffectMatte` is to be played. Note that this method does not return the number of repeats that are remaining to be played.

  Except for `HAnimateEffect` implementations that specify a different default, `getRepeatCount()` returns `REPEAT_INFINITE` if no call to `setRepeatCount()` has previously been made.

  Specified by:
    `getRepeatCount` in interface `HAnimateEffect`
  Returns:
    the total number of times that an `HImageEffectMatte` is to be played. The returned value shall be greater than zero, or `REPEAT_INFINITE`.

### setDelay

    public void setDelay(int count)

  Sets the delay between the presentation of successive pieces of content (frames).

  After calling `setDelay` on a currently playing `HImageEffectMatte`, there is no guarantee that one or more frames will not be displayed using the previous delay until the new delay value takes effect.

  Specified by:
    `setDelay` in interface `HAnimateEffect`
  Parameters:
    `count` - the content presentation delay in units of 0.1 seconds duration. If count is less than one "unit", then it shall be treated as if it were a delay of one "unit", i.e. 0.1 seconds.

### getDelay

    public int getDelay()

  Gets the presentation delay for this `HImageEffectMatte`.

  Specified by:
    `getDelay` in interface `HAnimateEffect`
  Returns:
    the presentation delay in units of 0.1 seconds.

### setPlayMode

    public void setPlayMode(int mode)

  Sets the playing mode for this `HImageEffectMatte`. If the animation is already running a call to `setPlayMode` will change the current value and affect the animation immediately. The position of the animation is unchanged.

  Specified by:
    `setPlayMode` in interface `HAnimateEffect`
  Parameters:
    `mode` - the play mode for this `HImageEffectMatte`, which must be either `HAnimateEffect.PLAY_ALTERNATING` or `HAnimateEffect.PLAY_REPEATING`.

### getPlayMode

    public int getPlayMode()

  Gets the playing mode for this `HImageEffectMatte`.

  Specified by:
    `getPlayMode` in interface `HAnimateEffect`
  Returns:
    the play mode for this `HImageEffectMatte`.

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

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