quicktime.app.anim
Class TwoDSprite

java.lang.Object
  |
  +--quicktime.app.anim.TwoDSprite
All Implemented Interfaces:
Compositable, ImageSettable, ImageSpec, Layerable, NotifyListener, Transformable
Direct Known Subclasses:
UIElement

public class TwoDSprite
extends java.lang.Object
implements NotifyListener, Transformable, Layerable, ImageSettable, Compositable

A TwoDSprite is a specialised presenter for image data within the context of a SpriteWorld. It contains information also about the layer within the SpriteWorld that the image presented by the Sprite is drawn. It also contains information about visibility and Matrix transformations and GraphicsMode drawing transformations that are applied to the image data when the Sprite is drawn in the SpriteWorld.

Typically an application will provide the image data and presentation characteristics and the SWCompositor assumes the responsibility of creating the actual TwoDSprite's Sprite that is used to present this data in the internal SpriteWorld that the SWCompositor uses to render and construct its image. The TwoDSprite uses the quicktime.std.anim.Sprite class to draw the image in a quicktime.std.anim.SpriteWorld.

See Also:
quicktime.app.display.Compositor, TwoDSpriteInfo

Field Summary
protected  java.lang.String label
          The actionCommand string that is presented to the QTActionListeners of the QTButton.
 
Fields inherited from interface quicktime.app.display.Layerable
kBackMostLayer
 
Constructor Summary
TwoDSprite()
          Create a sprite that will use a hidden image, visibility set to false and an Identity matrix.
TwoDSprite(ImageDataSequence images, int frame, Matrix matrix, boolean visibility, int layer)
          This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
TwoDSprite(ImageDataSequence images, int frame, Matrix matrix, boolean visibility, int layer, GraphicsMode graphicsMode)
          This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
TwoDSprite(ImageSpec image, Matrix matrix, boolean visibility, int layer)
          This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
TwoDSprite(ImageSpec image, Matrix matrix, boolean visibility, int layer, GraphicsMode graphicsMode)
          This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
TwoDSprite(Matrix matrix, int layer, GraphicsMode graphicsMode)
          Create a sprite that will use a hidden image and visibility set to false.
TwoDSprite(TwoDSpriteInfo spriteInfo)
          Create a sprite when the final destination of the sprite is not known.
 
Method Summary
 void createSprite(SpriteWorld sw)
          This will create a sprite object that presents the specified image and display options as specified in the contained info object.
 boolean equals(java.lang.Object obj)
          Returns true if the TwoDSprite represents the same Sprite object
 ImageDescription getDescription()
          This method gets the image description property of this sprite.
 GraphicsMode getGraphicsMode()
          This method gets the graphics mode property of this sprite.
 EncodedImage getImage()
          This method returns the actual image data.
 java.awt.Dimension getInitialSize()
          Deprecated. since QTJava 4.0
 java.lang.String getLabel()
           
 int getLayer()
          This method gets the layer property of this sprite.
 Matrix getMatrix()
          This method returns the current matrix of the Transformable object.
 QDDimension getOriginalSize()
          This method returns the original size before the transformations specified in the returned matrix are applied.
 SWCompositor getParent()
          Return the sprite world that this sprite belongs too.
 TwoDSpriteInfo getSpriteInfo()
          Returns all of the pertinent information about the current sprite's state to recreate a sprite.
 boolean getVisible()
          This method gets the visibility property of this sprite.
 boolean hitTest(int flags, QDPoint loc)
          This method tests if a point is inside a sprite.
 void invalidate()
          This method invalidates the portion of the sprite's sprite world which is occupied by the sprite.
 boolean isValid()
          Returns true if the Sprite being used by the TwoDSprite is valid and thus is constructed and present in a SpriteWorld.
 void notifyComplete()
          This method is called by the Notifier object when the image data that it is supplying to the TwoDSprite is valid.
 void remove()
          This will remove the sprite from the SpriteWorld it is contained in and destroy its internal structures.
protected  void removeNotify()
          This call should not be called by an application.
 void setDescription(ImageDescription idh)
          This method sets the image description property of this sprite.
 void setGraphicsMode(GraphicsMode gMode)
          This method sets the graphics mode property of this sprite.
 void setImage(EncodedImage image)
          This method should make the object's current image the specified image.
 void setImageData(EncodedImage im, ImageDescription id)
          This method can be used to change the image that is being presented by the Sprite and to ensure that the sprite is visible, if the specified image data is not null.
 void setLabel(java.lang.String label)
          You can set the label string for this TwoDSprite.
 void setLayer(int layer)
          This method sets the layer property of this sprite.
 void setMatrix(Matrix matrix)
          This method sets the current matrix of the Transformable object to the new matrix.
 boolean setNotifier(Notifier notifier)
          This registers the deferred listener.
 void setVisible(boolean visible)
          This method sets the visibility property of this sprite.
 java.lang.String toString()
          Returns a String representation of this class.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

label

protected java.lang.String label
The actionCommand string that is presented to the QTActionListeners of the QTButton.
Constructor Detail

TwoDSprite

public TwoDSprite(TwoDSpriteInfo spriteInfo)
           throws QTException
Create a sprite when the final destination of the sprite is not known. This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
Parameters:
spriteInfo - the image and layout information for the sprite when it is created.

TwoDSprite

public TwoDSprite()
           throws QTException
Create a sprite that will use a hidden image, visibility set to false and an Identity matrix.

TwoDSprite

public TwoDSprite(Matrix matrix,
                  int layer,
                  GraphicsMode graphicsMode)
           throws QTException
Create a sprite that will use a hidden image and visibility set to false. This constructor is used when the TwoDSprite is being used as a NotifyListener, expecting the image data from a Notifier to arrive at some indeterminate time in the future. The arguments supplied here will be used when the image data is supplied by the Notifier.
Parameters:
matrix - the display matrix of the sprite
layer - the layer of the SpriteWorld where the Sprite will be drawn
graphicsMode - the GraphicsMode that is applied to the rendering of the image data, this can be null

TwoDSprite

public TwoDSprite(ImageSpec image,
                  Matrix matrix,
                  boolean visibility,
                  int layer)
           throws QTException
This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
Parameters:
image - the image data and description that describes the image of the sprite
matrix - the display matrix of the sprite
visibility - whether the sprite will be visible (true) or not (false) when created
layer - the layer of the SpriteWorld where the Sprite will be drawn

TwoDSprite

public TwoDSprite(ImageSpec image,
                  Matrix matrix,
                  boolean visibility,
                  int layer,
                  GraphicsMode graphicsMode)
           throws QTException
This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
Parameters:
image - the image data and description that describes the image of the sprite
matrix - the display matrix of the sprite
visibility - whether the sprite will be visible (true) or not (false) when created
layer - the layer of the SpriteWorld where the Sprite will be drawn
graphicsMode - the GraphicsMode that is applied to the rendering of the image data, this can be null

TwoDSprite

public TwoDSprite(ImageDataSequence images,
                  int frame,
                  Matrix matrix,
                  boolean visibility,
                  int layer)
           throws QTException
This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
Parameters:
images - the image data and description that describes the images of the sprite
frame - the frame number within the images that will be used as the current image for the sprite when it is created
matrix - the display matrix of the sprite
visibility - whether the sprite will be visible (true) or not (false) when created
layer - the layer of the SpriteWorld where the Sprite will be drawn

TwoDSprite

public TwoDSprite(ImageDataSequence images,
                  int frame,
                  Matrix matrix,
                  boolean visibility,
                  int layer,
                  GraphicsMode graphicsMode)
           throws QTException
This constructor provides all of the state which will be used by the TwoDSprite object to create itself when it is attached to a SpriteWorld.
Parameters:
images - the image data and description that describes the images of the sprite
frame - the frame number within the images that will be used as the current image for the sprite when it is created
matrix - the display matrix of the sprite
visibility - whether the sprite will be visible (true) or not (false) when created
layer - the layer of the SpriteWorld where the Sprite will be drawn
graphicsMode - the GraphicsMode that is applied to the rendering of the image data, this can be null
Method Detail

setLabel

public void setLabel(java.lang.String label)
You can set the label string for this TwoDSprite.
Parameters:
label - a string that is associated with this sprite.

getLabel

public java.lang.String getLabel()
Returns:
the label that is associated with this TwoDSprite.

setNotifier

public boolean setNotifier(Notifier notifier)
This registers the deferred listener.
Specified by:
setNotifier in interface NotifyListener
Parameters:
dl - the listener that the DeferredListener notifies when its listen source becomes valid
Returns:
true if the Notifier is an instanceof ImageSpec and thus is a valid Notifier for the TwoDSprite. Returns false if the Notifier is not an instanceof ImageSpec.

notifyComplete

public void notifyComplete()
This method is called by the Notifier object when the image data that it is supplying to the TwoDSprite is valid.
Specified by:
notifyComplete in interface NotifyListener

setImageData

public void setImageData(EncodedImage im,
                         ImageDescription id)
                  throws QTException
This method can be used to change the image that is being presented by the Sprite and to ensure that the sprite is visible, if the specified image data is not null. This method is also called internally when the Notifier of this class notifies the Sprite that the image data is valid. If valid image data is provided this method also requires an ImageDescription that describes this image data.
Specified by:
setImageData in interface ImageSettable
Parameters:
im - the EncodedImage image data
id - the ImageDescription that describes the format of the EncodedImage data.

setImage

public void setImage(EncodedImage image)
              throws QTException
This method should make the object's current image the specified image.
Parameters:
imageData - the new image data that the object should make its current image.

getParent

public SWCompositor getParent()
Return the sprite world that this sprite belongs too. If the TwoDSprite is not currently attached to a SpriteWorld a SpriteInvalidException will be thrown.
Returns:
the current SpriteWorld of a valid TwoDSprite

isValid

public boolean isValid()
Returns true if the Sprite being used by the TwoDSprite is valid and thus is constructed and present in a SpriteWorld. Returns false if not.
Returns:
a boolean

remove

public void remove()
            throws QTException
This will remove the sprite from the SpriteWorld it is contained in and destroy its internal structures. The TwoDSprite must be reset after this call to recreate a Sprite object to attach it to a sprite world.
See Also:
createSprite

getSpriteInfo

public TwoDSpriteInfo getSpriteInfo()
                             throws QTException
Returns all of the pertinent information about the current sprite's state to recreate a sprite.
Returns:
the TwoDSprite info object that contains all of the information that the Sprite is presenting.

removeNotify

protected void removeNotify()
                     throws QTException
This call should not be called by an application. It is used by the Compositor to notify the Sprite that it is no longer valid - generally done when the Compositor is recreating its internal SpriteWorld.

createSprite

public void createSprite(SpriteWorld sw)
                  throws QTException
This will create a sprite object that presents the specified image and display options as specified in the contained info object.
Parameters:
sw - the Sprite world that the Sprite will appear in

getMatrix

public Matrix getMatrix()
                 throws QTException
This method returns the current matrix of the Transformable object.
Specified by:
getMatrix in interface Transformable

setMatrix

public void setMatrix(Matrix matrix)
               throws QTException
This method sets the current matrix of the Transformable object to the new matrix.
Specified by:
setMatrix in interface Transformable

getInitialSize

public java.awt.Dimension getInitialSize()
                                  throws QTException
Deprecated. since QTJava 4.0

This method returns the original size before the transformations specified in the returned matrix are applied.
Returns:
the runtime type is a java.awt.Dimension - the return value can be cast to this Class - however getOriginalSize should be used.
See Also:
()

getOriginalSize

public QDDimension getOriginalSize()
                            throws QTException
This method returns the original size before the transformations specified in the returned matrix are applied.
Specified by:
getOriginalSize in interface Transformable
Returns:
the original size

invalidate

public final void invalidate()
                      throws QTException
This method invalidates the portion of the sprite's sprite world which is occupied by the sprite.

hitTest

public boolean hitTest(int flags,
                       QDPoint loc)
                throws QTException
This method tests if a point is inside a sprite.
Parameters:
flags - Specifies the control flags.
loc - Specifies the test point.
Returns:
true if the point is inside the sprite, false if not.

getDescription

public ImageDescription getDescription()
                                throws QTException
This method gets the image description property of this sprite.
Specified by:
getDescription in interface ImageSpec
Returns:
the image description.

setDescription

public void setDescription(ImageDescription idh)
                    throws QTException
This method sets the image description property of this sprite.
Parameters:
idh - Specifies the image description.

getImage

public EncodedImage getImage()
                      throws QTException
This method returns the actual image data.
Specified by:
getImage in interface ImageSpec
Returns:
the image data

getVisible

public boolean getVisible()
                   throws QTException
This method gets the visibility property of this sprite.
Returns:
the visibility.

setVisible

public void setVisible(boolean visible)
                throws QTException
This method sets the visibility property of this sprite.
Parameters:
visible - Specifies the visibility.

getLayer

public int getLayer()
             throws QTException
This method gets the layer property of this sprite.
Specified by:
getLayer in interface Layerable
Returns:
the layer.

setLayer

public void setLayer(int layer)
              throws QTException
This method sets the layer property of this sprite.
Specified by:
setLayer in interface Layerable
Parameters:
layer - Specifies the layer.

getGraphicsMode

public GraphicsMode getGraphicsMode()
                             throws QTException
This method gets the graphics mode property of this sprite.
Specified by:
getGraphicsMode in interface Compositable
Returns:
the graphics mode.

setGraphicsMode

public void setGraphicsMode(GraphicsMode gMode)
                     throws QTException
This method sets the graphics mode property of this sprite.
Specified by:
setGraphicsMode in interface Compositable
Parameters:
gMode - Specifies the graphics mode.

equals

public boolean equals(java.lang.Object obj)
Returns true if the TwoDSprite represents the same Sprite object
Overrides:
equals in class java.lang.Object

toString

public java.lang.String toString()
Returns a String representation of this class.
Overrides:
toString in class java.lang.Object
Returns:
a String