sprite.java

j2me is based on j2mepolish, client & server for mobile application. menu sample

	 * of the source image must be an integer multiple of the frame height.
	 * The  values returned by <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getWidth()"><CODE>Layer.getWidth()</CODE></A> and
	 * <A HREF="../../../../javax/microedition/lcdui/game/Layer.html#getHeight()"><CODE>Layer.getHeight()</CODE></A> will reflect the frame width and frame height
	 * subject to the Sprite's current transform.
	 * <p>
	 * Sprites have a default frame sequence corresponding to the raw frame
	 * numbers, starting with frame 0.  The frame sequence may be modified
	 * with <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#setFrameSequence(int[])"><CODE>setFrameSequence(int[])</CODE></A>.
	 * <p>
	 * By default, the Sprite is visible and its upper-left corner is
	 * positioned at (0,0) in the painter's coordinate system.
	 * <p>
	 * 
	 * @param image the Image to use for Sprite
	 * @param frameWidth the width, in pixels, of the individual raw frames
	 * @param frameHeight the height, in pixels, of the individual raw frames
	 * @throws NullPointerException if img is null
	 * @throws IllegalArgumentException if frameHeight or frameWidth is less than 1
	 *									or if the image width is not an integer multiple of the frameWidth
	 *									or if the image height is not an integer multiple of the frameHeight
	 */
	public Sprite( Image image, int frameWidth, int frameHeight)
	{
		//#ifdef polish.api.siemens-color-game-api
			//# super( image, frameWidth, frameHeight );
		//#else
			setImage(image, frameWidth, frameHeight);
		//#endif
	}

	/**
	 * Creates a new Sprite from another Sprite. 
	 * 
	 * All instance attributes (raw frames, position, frame sequence, current
	 * frame, reference point, collision rectangle, transform, and visibility)
	 * of the source Sprite are duplicated in the new Sprite.
	 * 
	 * @param s  the Sprite to create a copy of
	 * @throws NullPointerException if s is null
	 */
	public Sprite( Sprite s)
	{
		//#ifdef polish.api.siemens-color-game-api
			//# super( s );
			//# this.refPixelX = s.refPixelX;
			//# this.refPixelY = s.refPixelY;
			//# this.transformedRefX = s.transformedRefX;
			//# this.transformedRefY = s.transformedRefY;
			//# this.transform = s.transform;
			//# this.transformedCollisionX = s.transformedCollisionX;
			//# this.transformedCollisionY = s.transformedCollisionY;
			//# this.transformedCollisionWidth = s.transformedCollisionWidth;
			//# this.transformedCollisionHeight = s.transformedCollisionHeight;
		//#else
			this.image = s.image;
			this.frameWidth = s.frameWidth;
			this.frameHeight = s.frameHeight;
			this.numberOfColumns = s.numberOfColumns;
			this.width = s.width;
			this.height = s.height;
			this.xPosition = s.xPosition;
			this.yPosition = s.yPosition;
			this.frameSequenceIndex = s.frameSequenceIndex;
			if (s.frameSequence != null) {
				this.frameSequence = new int[s.frameSequence.length];
				System.arraycopy(s.frameSequence, 0, this.frameSequence, 0, this.frameSequence.length);
			}
			this.refPixelX = s.refPixelX;
			this.refPixelY = s.refPixelY;
			this.transformedRefX = s.transformedRefX;
			this.transformedRefY = s.transformedRefY;
			this.transform = s.transform;
			//#ifdef polish.api.nokia-ui
				//# this.nokiaTransform = s.nokiaTransform;
				//# this.nokiaFrame = s.nokiaFrame;
				//# this.nokiaFrames = s.nokiaFrames;
			//#endif
			this.collisionX = s.collisionX;
			this.collisionY = s.collisionY;
			this.collisionWidth = s.collisionWidth;
			this.collisionHeight = s.collisionHeight;
			this.transformedCollisionX = s.transformedCollisionX;
			this.transformedCollisionY = s.transformedCollisionY;
			this.transformedCollisionWidth = s.transformedCollisionWidth;
			this.transformedCollisionHeight = s.transformedCollisionHeight;
			this.isSingleFrame = s.isSingleFrame;
		//#endif
	}

	/**
	 * Defines the reference pixel for this Sprite.  The pixel is
	 * defined by its location relative to the upper-left corner of
	 * the Sprite's un-transformed frame, and it may lay outside of
	 * the frame's bounds.
	 * <p>
	 * When a transformation is applied, the reference pixel is
	 * defined relative to the Sprite's initial upper-left corner
	 * before transformation. This corner may no longer appear as the
	 * upper-left corner in the painter's coordinate system under
	 * current transformation.
	 * <p>
	 * By default, a Sprite's reference pixel is located at (0,0); that is,
	 * the pixel in the upper-left corner of the raw frame.
	 * <p>
	 * Changing the reference pixel does not change the
	 * Sprite's physical position in the painter's coordinate system;
	 * that is, the values returned by <A HREF="../../../../de/enough/polish/ui/game/Layer.html#getX()"><CODE>getX()</CODE></A> and
	 * <A HREF="../../../../de/enough/polish/ui/game/Layer.html#getY()"><CODE>getY()</CODE></A> will not change as a result of defining the
	 * reference pixel.  However, subsequent calls to methods that
	 * involve the reference pixel will be impacted by its new definition.
	 * 
	 * @param refX the horizontal location of the reference pixel, relative to the left edge of the un-transformed frame
	 * @param refY the vertical location of the reference pixel, relative to the top edge of the un-transformed frame
	 * @see #setRefPixelPosition(int, int)
	 * @see #getRefPixelX()
	 * @see #getRefPixelY()
	 */
	public void defineReferencePixel(int refX, int refY)
	{
		this.refPixelX = refX;
		this.refPixelY = refY;
		applyTransform();
	}

	/**
	 * Sets this Sprite's position such that its reference pixel is located
	 * at (x,y) in the painter's coordinate system.
	 * 
	 * @param x the horizontal location at which to place the reference pixel
	 * @param y the vertical location at which to place the reference pixel
	 * @see #defineReferencePixel(int, int)
	 * @see #getRefPixelX()
	 * @see #getRefPixelY()
	 */
	public void setRefPixelPosition(int x, int y)
	{
		//#ifdef polish.api.siemens-color-game
			//# this.move(x - this.transformedRefX, y - this.transformedRefY );
		//#else
			this.xPosition = x - this.transformedRefX;
			this.yPosition = y - this.transformedRefY;
		//#endif
	}

	/**
	 * Gets the horizontal position of this Sprite's reference pixel
	 * in the painter's coordinate system.
	 * 
	 * @return the horizontal location of the reference pixel
	 * @see #defineReferencePixel(int, int)
	 * @see #setRefPixelPosition(int, int)
	 * @see #getRefPixelY()
	 */
	public int getRefPixelX()
	{
		return this.transformedRefX + this.xPosition;
	}

	/**
	 * Gets the vertical position of this Sprite's reference pixel
	 * in the painter's coordinate system.
	 * 
	 * @return the vertical location of the reference pixel
	 * @see #defineReferencePixel(int, int)
	 * @see #setRefPixelPosition(int, int)
	 * @see #getRefPixelX()
	 */
	public int getRefPixelY()
	{
		return this.transformedRefY + this.yPosition;
	}

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Selects the current frame in the frame sequence.  
	 * <p>
	 * The current frame is rendered when 
	 * <A HREF="../../../../de/enough/polish/ui/game/Sprite.html#paint(javax.microedition.lcdui.Graphics)"><CODE>paint(Graphics)</CODE></A>
	 * is called.
	 * <p>
	 * The index provided refers to the desired entry in the frame sequence,
	 * not the index of the actual frame itself.
	 * 
	 * @param sequenceIndex the index of of the desired entry in the frame  sequence
	 * @throws IndexOutOfBoundsException if frameIndex is less than 0
	 *									 or if frameIndex is equal to or greater than the length of the current frame sequence (or the number of raw frames for the default sequence)
	 * @see #setFrameSequence(int[])
	 * @see #getFrame()
	 */
	public void setFrame(int sequenceIndex)
	{
		this.frameSequenceIndex = sequenceIndex;
		updateFrame();
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Gets the current index in the frame sequence.
	 * The index returned refers to the current entry in the frame sequence,
	 * not the index of the actual frame that is displayed.
	 * 
	 * @return the current index in the frame sequence
	 * @see #setFrameSequence(int[])
	 * @see #setFrame(int)
	 */
	public final int getFrame()
	{
		return this.frameSequenceIndex;
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Gets the number of raw frames for this Sprite.  The value returned
	 * reflects the number of frames; it does not reflect the length of the
	 * Sprite's frame sequence.  However, these two values will be the same
	 * if the default frame sequence is used.
	 * 
	 * @return the number of raw frames for this Sprite
	 * @see #getFrameSequenceLength()
	 */
	public int getRawFrameCount()
	{
		return this.rawFrameCount;
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Gets the number of elements in the frame sequence.  The value returned
	 * reflects the length of the Sprite's frame sequence; it does not reflect
	 * the number of raw frames.  However, these two values will be the same
	 * if the default frame sequence is used.
	 * 
	 * @return the number of elements in this Sprite's frame sequence
	 * @see #getRawFrameCount()
	 */
	public int getFrameSequenceLength()
	{
		if (this.frameSequence == null)
			return this.rawFrameCount;
		return this.frameSequence.length;
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Selects the next frame in the frame sequence.
	 * 
	 * The frame sequence is considered to be circular, i.e. if
	 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#nextFrame()"><CODE>nextFrame()</CODE></A> is called when at the end of the sequence,
	 * this method will advance to the first entry in the sequence.
	 * 
	 * @see #setFrameSequence(int[])
	 * @see #prevFrame()
	 */
	public void nextFrame()
	{
		this.frameSequenceIndex++;
		if (this.frameSequenceIndex >= this.getFrameSequenceLength()) {
			this.frameSequenceIndex = 0;
		}
		updateFrame();
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Selects the previous frame in the frame sequence.  <p>
	 * 
	 * The frame sequence is considered to be circular, i.e. if
	 * <A HREF="../../../../javax/microedition/lcdui/game/Sprite.html#prevFrame()"><CODE>prevFrame()</CODE></A> is called when at the start of the sequence,
	 * this method will advance to the last entry in the sequence.
	 * 
	 * @see #setFrameSequence(int[])
	 * @see #nextFrame()
	 */
	public void prevFrame()
	{
		this.frameSequenceIndex--;
		if (this.frameSequenceIndex < 0 ) {
			this.frameSequenceIndex = this.getFrameSequenceLength() - 1;
		}
		updateFrame();
	}
	//#endif

	//#ifndef polish.api.siemens-color-game-api
	/**
	 * Updates the position at which the image should be drawn,
	 * This depends on the frame-index as well as the current transformation.
	 */
	private void updateFrame() {
		int frameIndex = (this.frameSequence == null) ? this.frameSequenceIndex : this.frameSequence[this.frameSequenceIndex];
		int c = frameIndex % this.numberOfColumns;
		int r = frameIndex / this.numberOfColumns;
		
		//#ifdef polish.api.nokia-ui
			//# Image frame = this.nokiaFrames[ frameIndex ];
			//# if ( frame == null ) {
				//# frame = DirectUtils.createImage( this.frameWidth, this.frameHeight, 0x00FFFFFF );
				//# Graphics g = frame.getGraphics();
				//# // when creating an transparent image, one must not "touch"
				//# // that image with an ordinary Graphics-object --- instead
				//# // ALWAYS an DirectGraphics-object needs to be used. Sigh!
				//# //g.drawImage(this.image, -(c * this.frameWidth), -(r * this.frameHeight), Graphics.TOP | Graphics.LEFT );
				//# DirectGraphics dg = DirectUtils.getDirectGraphics(g);
				//# dg.drawImage(this.image, -(c * this.frameWidth), -(r * this.frameHeight), Graphics.TOP | Graphics.LEFT, 0 );
			//# }
			//# this.nokiaFrame = frame; 
		//#else