Genuts API

com.genuts.gameui
Class PlayField

java.lang.Object
  extended byjava.awt.Component
      extended byjava.awt.Canvas
          extended bycom.genuts.gameui.PlayField
All Implemented Interfaces:
javax.accessibility.Accessible, java.awt.image.ImageObserver, java.awt.MenuContainer, java.lang.Runnable, java.io.Serializable
Direct Known Subclasses:
DebugPlayField

public class PlayField
extends java.awt.Canvas
implements java.lang.Runnable

A playfield is an AWT Component that can contain Sprite objects.

Sprites added to a playfield are tracked in a list. The order of the list will define the sprites' back-to-front stacking order within the playfield. If no index is specified when adding a sprite to a playfield, it will be added to the end of the list (the sprite with a lowest id is displayed before a sprite a sprite with a high id).

The collision manager associated with a playfield checks collision when a sprite moves.

To perform animation, a playfield has its own thread. It can advise objects which implement the Tickable interface. It can be a sprite or something else. This is another stacking order, the first in is the first called.
We recommand to use the Tickable interface rather than its own Thread for an object.
At start, the playfield is in pause mode, you have to activate it by setting the pause to false. When you want to stop or to dispose the playfield, don't forget to stop it. Otherwise, the associated thread will not stop.

The display manager associated with a playfield draws efficiently the background of the playfield and all sprites.

By default, a playfield has a double buffering rendering. This will reduce the flicking effect when an object is drawn.
The size of the display could be different from the size of the playfield. Therefore the size of this display is set to the preferred size of the playfield. The setOffset method sets the offset of the specified visual location. It should be useful for scrolling.

See Also:
addSprite(Sprite, int), getSpriteIndex(Sprite), setPause(boolean), stop(), setOffset(int, int), Tickable, CollisionManager, DisplayManager, Serialized Form

Nested Class Summary
 
Nested classes inherited from class java.awt.Canvas
java.awt.Canvas.AccessibleAWTCanvas
 
Nested classes inherited from class java.awt.Component
java.awt.Component.AccessibleAWTComponent, java.awt.Component.BltBufferStrategy, java.awt.Component.FlipBufferStrategy
 
Field Summary
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
PlayField()
          Initializes the simple playfield.
PlayField(CollisionManager collisionManager)
          Initializes the simple playfield with a collision manager.
PlayField(CollisionManager collisionManager, DisplayManager displayManager, int w, int h)
          Initializes the playfield with a collision manager and a size.
PlayField(CollisionManager collisionManager, int w, int h)
          Initializes the playfield with a size and a collision manager.
PlayField(DisplayManager displayManager)
          Initializes the simple playfield with a display manager.
PlayField(DisplayManager displayManager, int w, int h)
          Initializes the playfield with a size and a display manager.
PlayField(int w, int h)
          Initializes the playfield with a size.
 
Method Summary
 void addSprite(Sprite s)
          Adds the specified sprite to the end of this playfield.
 void addSprite(Sprite s, int index)
          Adds the specified sprite to this playfield at the given position.
 void addTickable(Tickable t)
          Adds a tickable object to this playfield to the end of list.
 void addTickable(Tickable t, int index)
          Adds a tickable object to this playfield at the given position in the list.
 void checkAllCollisions()
          Checks collisions of sprites with all other sprites in this playfield, and with the edges of this playfield.
 void checkCollision(Sprite sprite)
          Checks collision of the given sprite with all other sprites in this playfield, and with the edges of this playfield.
protected  void fireCollisionEvent(Sprite s1, Sprite s2)
          Fires collision event to both sprites.
protected  boolean firePreCollisionEvent(Sprite s1, Sprite s2)
          Fires pre-collision event to sprite.
 java.awt.Image getBackgroundImage()
          Returns the background image of this playfield.
 CollisionManager getCollisionManager()
          Gets the collision manager of this playfield.
 DisplayManager getDisplayManager()
          Gets the display manager of this playfield.
 int getHeight()
           
 int getPreferredHeight()
          Returns the preferred height of this playfield.
 java.awt.Dimension getPreferredSize()
          Returns the preferred size of this playfield.
 int getPreferredWidth()
          Returns the preferred width of this playfield.
 int getSleepTime()
          Returns the time delay between 2 ticks.
 Sprite getSprite(int n)
          Gets the nth sprite in this playfield.
 int getSpriteCount()
          Gets the number of sprites in this playfield.
 int getSpriteIndex(Sprite sprite)
          Returns the index of the given sprite in this playfield.
 int getTicks()
          Returns the number of ticks from the start of the this playfield.
 int getWidth()
           
 int getXOffset()
          Gets the X offset of the display image.
 int getYOffset()
          Gets the Y offset of the display image.
 void invalidate()
          Invalidates this playfield.
 void invalidateSprite(Sprite sprite)
          Invalidates a sprite for this playfield.
 boolean isPaused()
          Gets pause state for this playfield.
 boolean isRunning()
          Indicates if the playfield is running or not.
 void paint(java.awt.Graphics g)
          Paints this playfield and all visible sprites.
 void paintPlayField(java.awt.Graphics g)
          Paints this playfield.
 boolean preCheckCollision(Sprite sprite)
          Checks pre-collision of the given sprite with all other sprites in this playfield, and with the edges of this playfield.
 void removeAllSprites()
          Removes all sprites from this playfield.
 void removeSprite(int index)
          Removes the sprite, specified by index, from this playfield.
 void removeSprite(Sprite s)
          Removes the specified sprite from this playfield
 void removeTickable(Tickable t)
          Removes a tickable object from this playfield.
 void run()
          Used to send ticks.
protected  void sendTicks()
          Send a tick to all tickable objects in this playfield.
 void setBackgroundImage(java.awt.Image bg)
          Sets the background image for this playfield.
 void setCollisionManager(CollisionManager manager)
          Sets the collision manager for this playfield.
 void setDisplayManager(DisplayManager manager)
          Sets the display manager for this playfield.
 void setOffset(int x, int y)
          Sets the paint offset of the display image.
 void setPause(boolean pause)
          Sets pause state for this playfield.
 void setPause(int n)
          Sets pause state for this playfield during n cycles.
 void setPreferredSize(int width, int height)
          Sets the preferred size for this playfield.
 void setSize(int width, int height)
          Resizes this playfield so that it has width width and height.
 void setSleepTime(int sleep)
          Sets the time delay between 2 ticks.
protected  void setTicks(int ticks)
          Sets the number of ticks from the start of the this playfield.
 void stop()
          Stops explicitly the execution of this playfield.
 void update(java.awt.Graphics g)
          Overrides update to not erase the background before painting.
 void validateSprite(Sprite sprite)
          Validates a sprite for this playfield.
 
Methods inherited from class java.awt.Canvas
addNotify, createBufferStrategy, createBufferStrategy, getAccessibleContext, getBufferStrategy
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, bounds, checkImage, checkImage, coalesceEvents, contains, contains, createImage, createImage, createVolatileImage, createVolatileImage, deliverEvent, disable, disableEvents, dispatchEvent, doLayout, enable, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, getAlignmentX, getAlignmentY, getBackground, getBounds, getBounds, getColorModel, getComponentAt, getComponentAt, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeys, getFocusTraversalKeysEnabled, getFont, getFontMetrics, getForeground, getGraphics, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getListeners, getLocale, getLocation, getLocation, getLocationOnScreen, getMaximumSize, getMinimumSize, getMouseListeners, getMouseMotionListeners, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getSize, getToolkit, getTreeLock, getX, getY, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isDoubleBuffered, isEnabled, isFocusable, isFocusCycleRoot, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isOpaque, isShowing, isValid, isVisible, keyDown, keyUp, layout, list, list, list, list, list, locate, location, lostFocus, minimumSize, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, paramString, postEvent, preferredSize, prepareImage, prepareImage, print, printAll, processComponentEvent, processEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processKeyEvent, processMouseEvent, processMouseMotionEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, repaint, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, reshape, resize, resize, setBackground, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setEnabled, setFocusable, setFocusTraversalKeys, setFocusTraversalKeysEnabled, setFont, setForeground, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setVisible, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle, validate
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

PlayField

public PlayField(CollisionManager collisionManager,
                 DisplayManager displayManager,
                 int w,
                 int h)
Initializes the playfield with a collision manager and a size.

Parameters:
collisionManager - Collision manager associated with this playfield.
displayManager - Display manager associated with this playfield.
w - Width and Preferred width of the playfield.
h - Height and Preferred height of the playfield.

PlayField

public PlayField(CollisionManager collisionManager)
Initializes the simple playfield with a collision manager.

The default display manager is a SpriteDisplayManager.
The default display step is set to 32.

Parameters:
collisionManager - Collision manager associated with this playfield.

PlayField

public PlayField(DisplayManager displayManager)
Initializes the simple playfield with a display manager.

The default collision manager is a SpriteCollisionManager.
The default collision step is set to 32.

Parameters:
displayManager - Display manager associated with this playfield.

PlayField

public PlayField(int w,
                 int h)
Initializes the playfield with a size.

The default collision manager is a SpriteCollisionManager.
The default collision step is set to 32.

The default display manager is a SpriteDisplayManager.
The default display step is set to 32.

Parameters:
w - Width and Preferred width of the playfield.
h - Height and Preferred height of the playfield.
See Also:
SpriteCollisionManager

PlayField

public PlayField(CollisionManager collisionManager,
                 int w,
                 int h)
Initializes the playfield with a size and a collision manager.

The default display manager is a SpriteDisplayManager.
The default display step is set to 32.

Parameters:
collisionManager - Collision manager associated with this playfield.
w - Width and Preferred width of the playfield.
h - Height and Preferred height of the playfield.
See Also:
SpriteCollisionManager

PlayField

public PlayField(DisplayManager displayManager,
                 int w,
                 int h)
Initializes the playfield with a size and a display manager.

The default collision manager is a SpriteCollisionManager.
The default collision step is set to 32.

Parameters:
displayManager - Display manager associated with this playfield.
w - Width and Preferred width of the playfield.
h - Height and Preferred height of the playfield.
See Also:
SpriteCollisionManager

PlayField

public PlayField()
Initializes the simple playfield.

The default collision manager is a SpriteCollisionManager.
The default collision step is set to 32.

The default display manager is a SpriteDisplayManager.
The default display step is set to 32.

See Also:
SpriteCollisionManager
Method Detail

setBackgroundImage

public void setBackgroundImage(java.awt.Image bg)
Sets the background image for this playfield.

Parameters:
bg - Background image for this playfield.

getBackgroundImage

public java.awt.Image getBackgroundImage()
Returns the background image of this playfield.

Returns:
The Background image of this playfield.

setSize

public void setSize(int width,
                    int height)
Resizes this playfield so that it has width width and height. Be careful with sprites when the size of the playfield change, some of them could be out of the playfield.

Parameters:
width - The new width of this playfield in pixels.
height - The new height of this playfield in pixels.

getWidth

public int getWidth()

getHeight

public int getHeight()

setCollisionManager

public void setCollisionManager(CollisionManager manager)
Sets the collision manager for this playfield. All sprites already added in this playfield are added to the collision manager.

Parameters:
manager - Collision manager to set for this playfield.

getCollisionManager

public CollisionManager getCollisionManager()
Gets the collision manager of this playfield.

Returns:
The collision manager of this playfield.

setDisplayManager

public void setDisplayManager(DisplayManager manager)
Sets the display manager for this playfield. All sprites already added in this playfield are added to the display manager.

Parameters:
manager - Display manager to set for this playfield.

getDisplayManager

public DisplayManager getDisplayManager()
Gets the display manager of this playfield.

Returns:
The display manager of this playfield.

getPreferredSize

public java.awt.Dimension getPreferredSize()
Returns the preferred size of this playfield.

Returns:
an instance of Dimension that represents the preferred size of this playfield.

getPreferredWidth

public int getPreferredWidth()
Returns the preferred width of this playfield.

Returns:
The preferred width of this playfield.

getPreferredHeight

public int getPreferredHeight()
Returns the preferred height of this playfield.

Returns:
The preferred height of this playfield.

setPreferredSize

public void setPreferredSize(int width,
                             int height)
Sets the preferred size for this playfield.
All Sprites are removed from this playfield.

Parameters:
width - Preferred width for this playfield.
height - Preferred height for this playfield.

addTickable

public void addTickable(Tickable t)
Adds a tickable object to this playfield to the end of list.
This method doesn't assume if the object is already present in the list.

Parameters:
t - Tickable object to add

addTickable

public void addTickable(Tickable t,
                        int index)
Adds a tickable object to this playfield at the given position in the list.
This method doesn't assume if the object is already present in the list.

Parameters:
t - Tickable object to add
index - the position at which to insert the tickable, or -1 to insert the tickable at the end.

removeTickable

public void removeTickable(Tickable t)
Removes a tickable object from this playfield.
This method doesn't assume if the object has multiple occurence in the list, it will remove the first one.

Parameters:
t - Tickable object to remove

getSpriteCount

public int getSpriteCount()
Gets the number of sprites in this playfield.

Returns:
The number of sprites in this playfield

removeAllSprites

public void removeAllSprites()
Removes all sprites from this playfield.

See Also:
addSprite(Sprite, int), removeSprite(int)

addSprite

public void addSprite(Sprite s,
                      int index)
Adds the specified sprite to this playfield at the given position.

Parameters:
s - Sprite to add.
index - the position at which to insert the sprite, or -1 to insert the sprite at the end.

addSprite

public void addSprite(Sprite s)
Adds the specified sprite to the end of this playfield.

Parameters:
s - Sprite to add

removeSprite

public void removeSprite(int index)
Removes the sprite, specified by index, from this playfield.

Parameters:
index - the index of the sprite to remove
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the index value does not exist

removeSprite

public void removeSprite(Sprite s)
Removes the specified sprite from this playfield

Parameters:
s - Sprite to remove

preCheckCollision

public boolean preCheckCollision(Sprite sprite)
Checks pre-collision of the given sprite with all other sprites in this playfield, and with the edges of this playfield.

If one or more collisions are detected, firePreCollisionEvent(Sprite, Sprite) is called.

The action is delgated to the collision manager associated with this playfield.

Return the validate state given by the collision manager or true if there is no collision manager associated with this playfield.

Parameters:
sprite - Sprite to check
See Also:
CollisionManager.checkCollision(Sprite), firePreCollisionEvent(Sprite, Sprite)

checkCollision

public void checkCollision(Sprite sprite)
Checks collision of the given sprite with all other sprites in this playfield, and with the edges of this playfield.

If one or more collisions are detected, fireCollisionEvent(Sprite, Sprite) is called.

The action is delgated to the collision manager associated with this playfield.

Parameters:
sprite - Sprite to check
See Also:
CollisionManager.checkCollision(Sprite), fireCollisionEvent(Sprite, Sprite)

checkAllCollisions

public void checkAllCollisions()
Checks collisions of sprites with all other sprites in this playfield, and with the edges of this playfield.

If one or more collisions are detected, fireCollisionEvent(Sprite, Sprite) is called.

The action is delgated to the collision manager associated with this playfield.

See Also:
CollisionManager.checkCollision(Sprite), fireCollisionEvent(Sprite, Sprite)

invalidateSprite

public void invalidateSprite(Sprite sprite)
Invalidates a sprite for this playfield.
Invalidates the sprite for playfield's collision and display managers.

Parameters:
sprite - Sprite to invalidate.

validateSprite

public void validateSprite(Sprite sprite)
Validates a sprite for this playfield.
Validates the sprite for playfield's collision and display managers.

Parameters:
sprite - Sprite to validate.

getSprite

public Sprite getSprite(int n)
Gets the nth sprite in this playfield.

Parameters:
n - the index of the sprite to get.
Returns:
the nth sprite in this playfield.
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the nth value does not exist

getSpriteIndex

public int getSpriteIndex(Sprite sprite)
Returns the index of the given sprite in this playfield.

Parameters:
sprite - The sprite to look for.
Returns:
The index of the given sprite or -1 if the sprite was not found.

firePreCollisionEvent

protected boolean firePreCollisionEvent(Sprite s1,
                                        Sprite s2)
Fires pre-collision event to sprite.

Calls the method preCollisionWith(Sprite) of both sprites.

Parameters:
s1 - Sprite 1 to send the event.
s2 - Sprite 2 to send the event.
Returns:
true if a pre-collision is confirmed.
See Also:
Sprite.preCollisionWith(Sprite)

fireCollisionEvent

protected void fireCollisionEvent(Sprite s1,
                                  Sprite s2)
Fires collision event to both sprites.

Parameters:
s1 - Sprite 1 to send the event.
s2 - Sprite 2 to send the event.

invalidate

public void invalidate()
Invalidates this playfield. This playfield and all parents above it are marked as needing to be laid out. This method can be called often, so it needs to execute quickly.


setOffset

public void setOffset(int x,
                      int y)
Sets the paint offset of the display image.

Useful when the display image is greater than the size of the playfield. This feature can be used to scroll in the playfield.

Parameters:
x - X offset of the image
y - Y offset of the image

getXOffset

public int getXOffset()
Gets the X offset of the display image.

Returns:
The X offset of the display image

getYOffset

public int getYOffset()
Gets the Y offset of the display image.

Returns:
The Y offset of the display image

paintPlayField

public void paintPlayField(java.awt.Graphics g)
Paints this playfield.
By default, paints the background image if it exists.

Parameters:
g - The graphics context to use for painting.

update

public void update(java.awt.Graphics g)
Overrides update to not erase the background before painting.

Parameters:
g - The graphics context to use for painting.

paint

public void paint(java.awt.Graphics g)
Paints this playfield and all visible sprites.

Parameters:
g - The graphics context to use for painting.

getSleepTime

public int getSleepTime()
Returns the time delay between 2 ticks.

By default, sleep time is of 40ms.

Returns:
Number of milliseconds between 2 ticks.

setSleepTime

public void setSleepTime(int sleep)
Sets the time delay between 2 ticks.

Parameters:
sleep - Number of milliseconds between 2 ticks.

getTicks

public int getTicks()
Returns the number of ticks from the start of the this playfield.

Returns:
The number of ticks of this playfield, every 100000 ticks the counter restarts to 0.

setTicks

protected void setTicks(int ticks)
Sets the number of ticks from the start of the this playfield.

Parameters:
ticks - The number of ticks of this playfield, every 100000 ticks the counter restarts to 0.

setPause

public void setPause(int n)
Sets pause state for this playfield during n cycles.

Parameters:
n - Number of cycles to be in pause.

setPause

public void setPause(boolean pause)
Sets pause state for this playfield.

Parameters:
pause - true to set the playfield in pause state, false otherwise.

isPaused

public boolean isPaused()
Gets pause state for this playfield.

Returns:
true to set the playfield in pause state, false otherwise.

isRunning

public boolean isRunning()
Indicates if the playfield is running or not.

Returns:
true if the playfield is running, false otherwise.

stop

public void stop()
Stops explicitly the execution of this playfield. This has to be done, when the playfield has to be disposed.
Otherwise, the thread associated with this playfield will not stop.


run

public final void run()
Used to send ticks.

Specified by:
run in interface java.lang.Runnable

sendTicks

protected void sendTicks()
Send a tick to all tickable objects in this playfield.


Genuts API

Genuts API