com.transmote.nest
Class NestSprite

java.lang.Object
  java.util.Observable
      com.transmote.nest.events.EventDispatcher
          com.transmote.nest.NestSprite

All Implemented Interfaces:

Observer

Direct Known Subclasses:

NestButton, NestImageSprite, NestSpriteContainer, NestTextInput, NestTextSprite

public class NestSprite
extends EventDispatcher

A NestSprite instance is a single element in the Nest display list. Any on-screen element using the Nest framework is an instance of NestSprite, or of a subclass of NestSprite. Nest is modeled on the display list at the core of Adobe's ActionScript programming language; NestSprite is in turn modeled on ActionScript's Sprite class, and offers much of the same functionality.

NestSprite instances can be translated, rotated, and scaled via public properties such as x, rotationZ, and scaleY. NestSprite methods provide for addition to (addChild(NestSprite)), removal from (removeChild(NestSprite)), and manipulation of (e.g. swapChildren(NestSprite, NestSprite)), the display list. NestSprite also allows for comparing between coordinate spaces, with methods such as mousePt() and screenPt().

Every frame, each NestSprite instance on the display list will automatically call update(PApplet), then each NestSprite instance on the display list will call draw(PApplet). To implement specific functionality, such as animation or rendering, developers should subclass NestSprite and implement these methods as desired.

NestSprite instances in the display list transport events through the display list. See Event for more detail on the event flow. To handle a mouse or key event, a NestSprite subclass must implement the event handler corresponding to the type of mouse event to handle. For mouse events to respect the bounds rect of the NestSprite, the bounds rect must be set and updated manually.

Note that NestSprite instances will not call update(PApplet) or draw(PApplet), nor receive mouse or key events, until they are added to the display list.

Author:

Eric Socolofsky

Field Summary

int	blendMode For best performance, set blendMode as high up the display list as possible.
float	boundsLeft The left edge of the graphic content of this NestSprite instance.
float	boundsTop The top edge of the graphic content of this NestSprite instance.
boolean	handleCaptureEvents Specifies whether input events (e.g.
float	height The height of the graphic content of this NestSprite instance.
boolean	inFront Disables GL depth testing for this NestSprite instance and all its descendants.
boolean	inputChildren Specifies whether children of this NestSprite instance receive input events, such as MouseEvents and KeyEvents.
boolean	inputEnabled Specifies whether this NestSprite instance receives input events, such as MouseEvents and KeyEvents.
static int	NO_BLEND_MODE Signifies that this NestSprite does not set its own blendMode, but lets display list ancestors do so.
float	rotationX The rotation of this NestSprite instance along the x-axis, in radians.
float	rotationY The rotation of this NestSprite instance along the y-axis, in radians.
float	rotationZ The rotation of this NestSprite instance along the z-axis, in radians.
float	scaleX The scale of this NestSprite instance along the x-axis.
float	scaleY The scale of this NestSprite instance along the y-axis.
float	scaleZ The scale of this NestSprite instance along the z-axis.
boolean	visible The on-screen visibility of this NestSprite instance (and its descendants).
float	width The width of the graphic content of this NestSprite instance.
float	x The position of the centerpoint (aka 'registration point') of this NestSprite instance on the x-axis of its parent.
float	y The position of the centerpoint (aka 'registration point') of this NestSprite instance on the y-axis of its parent.
float	z The position of the centerpoint (aka 'registration point') of this NestSprite instance on the z-axis of its parent.

Constructor Summary

NestSprite()
Creates a new NestSprite instance with a zero bounds rect.

NestSprite(float width, float height)
Creates a new NestSprite instance with a bounds rect positioned at (0,0), of a specified width and height.

NestSprite(float boundsLeft, float boundsTop, float width, float height)
Creates a new NestSprite instance with a bounds rect with its upper-left corner at a specified location, with a specified width and height.

NestSprite(Rectangle2D.Float bounds)
Creates a new NestSprite instance with a specified bounds rect.

Method Summary

void	addChild(int index, NestSprite sprite) Adds a NestSprite as a child to this NestSprite instance.
void	addChild(NestSprite sprite) Adds a NestSprite as a child to this NestSprite instance.
Rectangle2D.Float	bounds() The bounds rect of the graphic content of this NestSprite instance, in the coordinate system of this NestSprite.
void	dispatchEvent(Event evt) Dispatch a Nest Event to all registered Observers.
void	dispose() Frees up this NestSprite for garbage collection.
void	dispose(boolean disposeChildren) Frees up this NestSprite for garbage collection.
NestSprite	getChildAt(int index) Returns the NestSprite at the specified index in the child list of this NestSprite instance.
int	getChildIndex(NestSprite sprite) Return the index of the specified NestSprite in the child list of this NestSprite instance.
Point2D.Float	globalToLocal(Point2D globalPt) Transform a point from the coordinate space of the top-level NestSpriteContainer to the local coordinate space of this NestSprite instance.
boolean	hitTest(Point2D pt) Check if a point is within the bounds rect of this NestSprite instance or the bounds rect of any of its children.
boolean	hitTest(Point2D pt, boolean testChildren) Check if a point is within the bounds rect of this NestSprite instance or the bounds rect of any of its children.
boolean	isDisposed() Returns true if dispose() has been called, and this NestSprite instance is prepared for garbage collection.
Point2D.Float	localToGlobal(Point2D localPt) Transform a point from the local coordinate space of this NestSprite instance to the coordinate space of the top-level NestSpriteContainer.
Point2D.Float	mousePt() Returns the x and y coordinates of the mouse relative to the coordinate system of this NestSprite instance.
float	mouseX() Returns the x coordinate of the mouse relative to the coordinate system of this NestSprite instance.
float	mouseY() Returns the y coordinate of the mouse relative to the coordinate system of this NestSprite instance.
int	numChildren() Returns the number of children in the child list of this NestSprite instance.
PApplet	pApplet() Returns the PApplet instance used in this application.
NestSprite	parent() The NestSprite that contains this NestSprite instance.
NestSprite	removeChild(int index) Removes the NestSprite at the specified index from the child list of this NestSprite instance.
NestSprite	removeChild(NestSprite sprite) Removes the specified NestSprite from the child list of this NestSprite instance.
PGraphics	renderer() PGraphics renderer used to manipulate and draw this NestSprite instance.
Point2D.Float	screenPt() Returns the x and y coordinates of this NestSprite instance relative to the coordinate system of the application.
float	screenX() Returns the x coordinate of this NestSprite instance relative to the coordinate system of the application.
float	screenY() Returns the y coordinate of this NestSprite instance relative to the coordinate system of the application.
void	setBounds(float x, float y, float width, float height) Manually update the bounds rect of the graphic content of this NestSprite instance.
void	setBounds(Rectangle2D.Float bounds) Manually update the bounds rect of the graphic content of this NestSprite instance.
void	setChildIndex(int index, NestSprite sprite) Move a child of this NestSprite instance to a specified index in the child list.
void	setDraw() When setDraw() is called without parameters, it removes the draw functionality set by any previous setDraw() call.
void	setDraw(Object caller, String methodName) Specify behavior to be performed during this instance's draw() phase.
void	setRenderer(PGraphics renderer) Set PGraphics renderer used to manipulate and draw this NestSprite instance.
void	setRenderer(PGraphics renderer, boolean setChildren) Set PGraphics renderer used to manipulate and draw this NestSprite instance.
void	setUpdate() When setUpdate() is called without parameters, it removes the update functionality set by any previous setUpdate() call.
void	setUpdate(Object caller, String methodName) Specify behavior to be performed during this instance's update() phase.
void	swapChildren(int index1, int index2) Swap the index positions of two child NestSprites, given the indices of the two children in the child list.
void	swapChildren(NestSprite sprite1, NestSprite sprite2) Swap the index positions of two child NestSprites, given the two children.

Methods inherited from class com.transmote.nest.events.EventDispatcher

addObserver, deleteObserver, dispatchEvent, owner, update

Methods inherited from class java.util.Observable

countObservers, deleteObservers, hasChanged, notifyObservers, notifyObservers

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NO_BLEND_MODE

public static final int NO_BLEND_MODE

Signifies that this NestSprite does not set its own blendMode, but lets display list ancestors do so. If no ancestors set blendMode, the default Processing blend mode will be used.

See Also:

Constant Field Values

x

public float x

The position of the centerpoint (aka 'registration point') of this NestSprite instance on the x-axis of its parent.

y

public float y

The position of the centerpoint (aka 'registration point') of this NestSprite instance on the y-axis of its parent.

z

public float z

The position of the centerpoint (aka 'registration point') of this NestSprite instance on the z-axis of its parent.

width

public float width

The width of the graphic content of this NestSprite instance.

NestSprite calculates its bounds() using width, height, boundsLeft, and boundsRight. Setting any of these properties will change the bounds rect of this NestSprite instance, and setting the bounds rect via setBounds(java.awt.geom.Rectangle2D.Float) will, in turn, update those properties.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, width and height must both be set manually. Additionally, if the upper-left corner of the graphic content is not at (0,0), boundsLeft and boundsTop must be set to indicate this; width and height should be measured from the upper-left corner of the graphic content.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

See Also:

height, boundsLeft, boundsTop, bounds(), setBounds(java.awt.geom.Rectangle2D.Float)

+Example

/*
 * MouseEvents_Bounds
 * 
 * NestSprite provides a simple API for handling mouse events.
 * See MouseEvents_Simple for an introduction.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  Unlike ActionScript 3.0,
 * Nest requires that developers manually
 * update the bounds of NestSprite instances using bounds(),
 * or boundsLeft, boundsTop, width, and height.
 * 
 * If a NestSprite instance has not set its bounds via these
 * properties or methods, it will not respond properly to
 * mouse events that respond to the NestSprite's bounds.
 * 
 * If a future version of Nest updates a
 * NestSprite's bounds rect automatically as it changes, I will be happy.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach a ButtonSprite instance to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 200;
  spriteLeft.y = 200;
  spriteContainer.addChild(spriteLeft);
}

height

public float height

The height of the graphic content of this NestSprite instance.

NestSprite calculates its bounds() using width, height, boundsLeft, and boundsRight. Setting any of these properties will change the bounds rect of this NestSprite instance, and setting the bounds rect via setBounds(java.awt.geom.Rectangle2D.Float) will, in turn, update those properties.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, width and height must both be set manually. Additionally, if the upper-left corner of the graphic content is not at (0,0), boundsLeft and boundsTop must be set to indicate this; width and height should be measured from the upper-left corner of the graphic content.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

See Also:

width, boundsLeft, boundsTop, bounds(), setBounds(java.awt.geom.Rectangle2D.Float)

+Example

/*
 * MouseEvents_Bounds
 * 
 * NestSprite provides a simple API for handling mouse events.
 * See MouseEvents_Simple for an introduction.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  Unlike ActionScript 3.0,
 * Nest requires that developers manually
 * update the bounds of NestSprite instances using bounds(),
 * or boundsLeft, boundsTop, width, and height.
 * 
 * If a NestSprite instance has not set its bounds via these
 * properties or methods, it will not respond properly to
 * mouse events that respond to the NestSprite's bounds.
 * 
 * If a future version of Nest updates a
 * NestSprite's bounds rect automatically as it changes, I will be happy.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach a ButtonSprite instance to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 200;
  spriteLeft.y = 200;
  spriteContainer.addChild(spriteLeft);
}

boundsLeft

public float boundsLeft

The left edge of the graphic content of this NestSprite instance.

NestSprite calculates its bounds() using width, height, boundsLeft, and boundsRight. Setting any of these properties will change the bounds rect of this NestSprite instance, and setting the bounds rect via setBounds(java.awt.geom.Rectangle2D.Float) will, in turn, update those properties.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, width and height must both be set manually. Additionally, if the upper-left corner of the graphic content is not at (0,0), boundsLeft and boundsTop must be set to indicate this; width and height should be measured from the upper-left corner of the graphic content.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

See Also:

width, height, boundsTop, bounds(), setBounds(java.awt.geom.Rectangle2D.Float)

+Example

/*
 * MouseEvents_Bounds
 * 
 * NestSprite provides a simple API for handling mouse events.
 * See MouseEvents_Simple for an introduction.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  Unlike ActionScript 3.0,
 * Nest requires that developers manually
 * update the bounds of NestSprite instances using bounds(),
 * or boundsLeft, boundsTop, width, and height.
 * 
 * If a NestSprite instance has not set its bounds via these
 * properties or methods, it will not respond properly to
 * mouse events that respond to the NestSprite's bounds.
 * 
 * If a future version of Nest updates a
 * NestSprite's bounds rect automatically as it changes, I will be happy.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach a ButtonSprite instance to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 200;
  spriteLeft.y = 200;
  spriteContainer.addChild(spriteLeft);
}

boundsTop

public float boundsTop

The top edge of the graphic content of this NestSprite instance.

NestSprite calculates its bounds() using width, height, boundsLeft, and boundsRight. Setting any of these properties will change the bounds rect of this NestSprite instance, and setting the bounds rect via setBounds(java.awt.geom.Rectangle2D.Float) will, in turn, update those properties.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, width and height must both be set manually. Additionally, if the upper-left corner of the graphic content is not at (0,0), boundsLeft and boundsTop must be set to indicate this; width and height should be measured from the upper-left corner of the graphic content.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

See Also:

width, height, boundsLeft, bounds(), setBounds(java.awt.geom.Rectangle2D.Float)

+Example

/*
 * MouseEvents_Bounds
 * 
 * NestSprite provides a simple API for handling mouse events.
 * See MouseEvents_Simple for an introduction.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  Unlike ActionScript 3.0,
 * Nest requires that developers manually
 * update the bounds of NestSprite instances using bounds(),
 * or boundsLeft, boundsTop, width, and height.
 * 
 * If a NestSprite instance has not set its bounds via these
 * properties or methods, it will not respond properly to
 * mouse events that respond to the NestSprite's bounds.
 * 
 * If a future version of Nest updates a
 * NestSprite's bounds rect automatically as it changes, I will be happy.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach a ButtonSprite instance to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 200;
  spriteLeft.y = 200;
  spriteContainer.addChild(spriteLeft);
}

scaleX

public float scaleX

The scale of this NestSprite instance along the x-axis.

scaleY

public float scaleY

The scale of this NestSprite instance along the y-axis.

scaleZ

public float scaleZ

The scale of this NestSprite instance along the z-axis.

rotationX

public float rotationX

The rotation of this NestSprite instance along the x-axis, in radians.

rotationY

public float rotationY

The rotation of this NestSprite instance along the y-axis, in radians.

rotationZ

public float rotationZ

The rotation of this NestSprite instance along the z-axis, in radians.

blendMode

public int blendMode

For best performance, set blendMode as high up the display list as possible. For example, if all of the children of a NestSprite have the same non-default blendMode, rather than setting the blendMode on each of those children, it's best to set the blendMode only on the parent NestSprite. To reset the blendMode for this NestSprite instance (to let ancestor NestSprites determine how this NestSprite will be drawn), set it to NO_BLEND_MODE. Defaults to NO_BLEND_MODE. TODO: set back to whatever blendmode was used before NestSpriteContainer.update, once the processing API exposes it (currently resets to PROCESSING_DEFAULT_BLEND_MODE)

visible

public boolean visible

The on-screen visibility of this NestSprite instance (and its descendants). If visible == false, neither this NestSprite instance nor its descendants will receive input events.

inFront

public boolean inFront

Disables GL depth testing for this NestSprite instance and all its descendants. Setting inFront = true will eliminate flickering caused by other shapes drawn at the same plane (z-coordinate). This does not bring a NestSprite instance to the front of the stack; it is used only to eliminate GL-induced flickering. If not using a GL renderer, this field is ignored.

inputEnabled

public boolean inputEnabled

Specifies whether this NestSprite instance receives input events, such as MouseEvents and KeyEvents. The default value is true, which means that by default any NestSprite on the display list receives input events.

Any children of this instance on the display list are not affected. To prevent or enable input events reaching children of this instance, use inputChildren.

inputChildren

public boolean inputChildren

Specifies whether children of this NestSprite instance receive input events, such as MouseEvents and KeyEvents. The default value is true, which means that by default all children of this instance receive input events.

handleCaptureEvents

public boolean handleCaptureEvents

Specifies whether input events (e.g. MouseEvent, KeyEvent) in the CAPTURE phase will be handled by input event handlers. Setting to true does not affect handling of input events in the AT_TARGET or CAPTURE phases.

Note that due to the implementation used in Nest, which entails running a hitTest() on all descendants of this NestSprite instance, setting to true may result in decreased performance. The implementation can probably use some optimization.

Defaults to false.

Constructor Detail

NestSprite

public NestSprite()

Creates a new NestSprite instance with a zero bounds rect.

NestSprite

public NestSprite(float width,
                  float height)

Creates a new NestSprite instance with a bounds rect positioned at (0,0), of a specified width and height.

Parameters:

width - Width of the bounds rect.

height - Height of the bounds rect.

NestSprite

public NestSprite(float boundsLeft,
                  float boundsTop,
                  float width,
                  float height)

Creates a new NestSprite instance with a bounds rect with its upper-left corner at a specified location, with a specified width and height.

Parameters:

boundsLeft - Left edge of the bounds rect.

boundsTop - Top edge of the bounds rect.

width - Width of the bounds rect.

height - Height of the bounds rect.

NestSprite

public NestSprite(Rectangle2D.Float bounds)

Creates a new NestSprite instance with a specified bounds rect.

Parameters:

bounds - The specified bounds rect.

Method Detail

addChild

public void addChild(NestSprite sprite)

Adds a NestSprite as a child to this NestSprite instance. The child is added to the front (top) of all other children of this NestSprite instance.

Parameters:

sprite - The NestSprite instance to add as a child.

+Example

/*
 * AddChild
 * 
 * Nest provides a simple display list architecture
 * modeled on the ActionScript 3.0 display list.
 * 
 * A NestSpriteContainer lives at the top of a display list.
 * Adding NestSprite children to it will subject them to the
 * same transformations (translation, rotation, scale)
 * applied to their parents.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;
RectSprite sprite1;
RectSprite sprite2;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  
  // calling NestSpriteContainer.update() will automatically
  // loop through all its descendant NestSprite instances,
  // call update() on each, and then call draw() on each.
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create an instance of RectSprite, a NestSprite subclass.
  sprite1 = new RectSprite(200, 200);
  
  // position the RectSprite in the center of the screen.
  sprite1.x = 0.5f * width;
  sprite1.y = 0.5f * height;
  
  // create another instance of RectSprite,
  // and set its properties.
  sprite2 = new RectSprite(100, 100);
  sprite2.x = 50;
  sprite2.y = 50;
  
  // create a NestSpriteContainer to hold all other NestSprites.
  spriteContainer = new NestSpriteContainer(this);
  
  // add sprite1 to the NestSpriteContainer to make it appear on screen.
  spriteContainer.addChild(sprite1);
  
  // add sprite2 as a child of sprite1.
  // children draw in front of their parents,
  // and are subject to all transformations
  // (position, scale, rotation) applied to
  // their parents and ancestors.
  sprite1.addChild(sprite2);
}

addChild

public void addChild(int index,
                     NestSprite sprite)

Adds a NestSprite as a child to this NestSprite instance. The child is added at the index specified.

Parameters:

index - The index in the child list at which the child is added.

sprite - The NestSprite instance to add as a child.

+Example

/*
 * AddChild
 * 
 * Nest provides a simple display list architecture
 * modeled on the ActionScript 3.0 display list.
 * 
 * A NestSpriteContainer lives at the top of a display list.
 * Adding NestSprite children to it will subject them to the
 * same transformations (translation, rotation, scale)
 * applied to their parents.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;
RectSprite sprite1;
RectSprite sprite2;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  
  // calling NestSpriteContainer.update() will automatically
  // loop through all its descendant NestSprite instances,
  // call update() on each, and then call draw() on each.
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create an instance of RectSprite, a NestSprite subclass.
  sprite1 = new RectSprite(200, 200);
  
  // position the RectSprite in the center of the screen.
  sprite1.x = 0.5f * width;
  sprite1.y = 0.5f * height;
  
  // create another instance of RectSprite,
  // and set its properties.
  sprite2 = new RectSprite(100, 100);
  sprite2.x = 50;
  sprite2.y = 50;
  
  // create a NestSpriteContainer to hold all other NestSprites.
  spriteContainer = new NestSpriteContainer(this);
  
  // add sprite1 to the NestSpriteContainer to make it appear on screen.
  spriteContainer.addChild(sprite1);
  
  // add sprite2 as a child of sprite1.
  // children draw in front of their parents,
  // and are subject to all transformations
  // (position, scale, rotation) applied to
  // their parents and ancestors.
  sprite1.addChild(sprite2);
}

removeChild

public NestSprite removeChild(NestSprite sprite)

Removes the specified NestSprite from the child list of this NestSprite instance.

Parameters:

sprite - The NestSprite instance to remove.

Returns:

The removed NestSprite instance.

removeChild

public NestSprite removeChild(int index)

Removes the NestSprite at the specified index from the child list of this NestSprite instance.

Parameters:

index - The index in the child list of this NestSprite instance of the child to remove.

Returns:

The removed NestSprite instance.

getChildAt

public NestSprite getChildAt(int index)

Returns the NestSprite at the specified index in the child list of this NestSprite instance.

Parameters:

index - The index in the child list of this NestSprite instance of the child to return.

getChildIndex

public int getChildIndex(NestSprite sprite)

Return the index of the specified NestSprite in the child list of this NestSprite instance.

Parameters:

sprite - The NestSprite instance whose index will be returned.

Returns:

index The index of the specified NestSprite instance.

setChildIndex

public void setChildIndex(int index,
                          NestSprite sprite)
                   throws IndexOutOfBoundsException,
                          IllegalArgumentException

Move a child of this NestSprite instance to a specified index in the child list.

Parameters:

index - The index to which to move the specified NestSprite instance.

sprite - The NestSprite child to move.

Throws:

IndexOutOfBoundsException - Thrown if the specified index position does not exist in the child list.

IllegalArgumentException - Thrown if the specified NestSprite is not a child of this NestSprite instance.

swapChildren

public void swapChildren(NestSprite sprite1,
                         NestSprite sprite2)
                  throws IllegalArgumentException

Swap the index positions of two child NestSprites, given the two children.

Parameters:

sprite1 - One child to swap.

sprite2 - The other child to swap.

Throws:

IllegalArgumentException - Thrown if either specified NestSprite is not a child of this NestSprite instance.

swapChildren

public void swapChildren(int index1,
                         int index2)
                  throws IndexOutOfBoundsException

Swap the index positions of two child NestSprites, given the indices of the two children in the child list.

Parameters:

index1 - The index of one child to swap.

index2 - The index of the other child to swap.

Throws:

IllegalArgumentException - Thrown if either specified index position does not exist in the child list.

IndexOutOfBoundsException

numChildren

public int numChildren()

Returns the number of children in the child list of this NestSprite instance.

bounds

public Rectangle2D.Float bounds()

The bounds rect of the graphic content of this NestSprite instance, in the coordinate system of this NestSprite.

NestSprite calculates its bounds() using width, height, boundsLeft, and boundsRight. Setting any of these properties will change the bounds rect of this NestSprite instance, and setting the bounds rect via setBounds(java.awt.geom.Rectangle2D.Float) will, in turn, update those properties.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, width and height must both be set manually. Additionally, if the upper-left corner of the graphic content is not at (0,0), boundsLeft and boundsTop must be set to indicate this; width and height should be measured from the upper-left corner of the graphic content.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

See Also:

width, height, boundsLeft, boundsTop, bounds(), setBounds(java.awt.geom.Rectangle2D.Float)

setBounds

public void setBounds(float x,
                      float y,
                      float width,
                      float height)

Manually update the bounds rect of the graphic content of this NestSprite instance.

See setBounds(Rectangle2D.Float) for more details.

Parameters:

x - Bounds left edge.

y - Bounds top edge.

width - Bounds width.

height - Bounds height.

setBounds

public void setBounds(Rectangle2D.Float bounds)

Manually update the bounds rect of the graphic content of this NestSprite instance.

In order for this NestSprite instance to handle mouse events that require the cursor be over its graphic content, its bounds rect must be set manually. This can be done by setting width, height, boundsLeft, and boundsTop, or using the setBounds() method.

Perhaps, someday, Nest will be smart enough to update its bounds rect automatically as its graphic content changes, but for now, it's up to the application developer to manually update the bounds rect.

Parameters:

bounds - Rectangle to use as bounds.

See Also:

width, height, boundsLeft, boundsTop, bounds(), setBounds(float, float, float, float)

+Example

/*
 * MouseEvents_Bounds
 * 
 * NestSprite provides a simple API for handling mouse events.
 * See MouseEvents_Simple for an introduction.
 * 
 * Many mouse events are only handled if they are within the bounds
 * of the NestSprite instance.  Unlike ActionScript 3.0,
 * Nest requires that developers manually
 * update the bounds of NestSprite instances using bounds(),
 * or boundsLeft, boundsTop, width, and height.
 * 
 * If a NestSprite instance has not set its bounds via these
 * properties or methods, it will not respond properly to
 * mouse events that respond to the NestSprite's bounds.
 * 
 * If a future version of Nest updates a
 * NestSprite's bounds rect automatically as it changes, I will be happy.
 */

import com.transmote.nest.*;
import com.transmote.nest.events.*;

NestSpriteContainer spriteContainer;

void setup () {
  size(400, 400);
  setupSprites();
}

void draw () {
  background(0);
  spriteContainer.updateDisplayList();
}

void setupSprites () {
  // create a NestSpriteContainer to hold all other NestSprites
  spriteContainer = new NestSpriteContainer(this);
  
  // attach a ButtonSprite instance to the SpriteContainer
  ButtonSprite spriteLeft = new ButtonSprite();
  spriteLeft.x = 200;
  spriteLeft.y = 200;
  spriteContainer.addChild(spriteLeft);
}

pApplet

public PApplet pApplet()

Returns the PApplet instance used in this application.

parent

public NestSprite parent()

The NestSprite that contains this NestSprite instance. The parent is the NestSprite immediately above (behind) this NestSprite instance in the display list.

isDisposed

public boolean isDisposed()

Returns true if dispose() has been called, and this NestSprite instance is prepared for garbage collection.

mouseX

public float mouseX()

Returns the x coordinate of the mouse relative to the coordinate system of this NestSprite instance.

mouseY

public float mouseY()

Returns the y coordinate of the mouse relative to the coordinate system of this NestSprite instance.

mousePt

public Point2D.Float mousePt()

Returns the x and y coordinates of the mouse relative to the coordinate system of this NestSprite instance.

screenX

public float screenX()

Returns the x coordinate of this NestSprite instance relative to the coordinate system of the application.

screenY

public float screenY()

Returns the y coordinate of this NestSprite instance relative to the coordinate system of the application.

screenPt

public Point2D.Float screenPt()

Returns the x and y coordinates of this NestSprite instance relative to the coordinate system of the application.

setUpdate

public void setUpdate()

When setUpdate() is called without parameters, it removes the update functionality set by any previous setUpdate() call.

setUpdate

public void setUpdate(Object caller,
                      String methodName)

Specify behavior to be performed during this instance's update() phase. methodName is the name of a public method that is a member of the caller object. This method must receive two arguments: a PApplet and a NestSprite instance. e.g.:

 public void lazyUpdate (PApplet p, NestSprite sprite) {
     // update() implementation here
 }
 // ...
 NestSprite lazySprite = new NestSprite();
 lazySprite.setUpdate(this, "lazyUpdate");
 

Pass null for methodName to remove the custom update() behavior. Note: Scope within the specified method will be the caller object; i.e. within the specified method, the this keyword will refer to the caller object. To access this NestSprite instance, use the NestSprite parameter passed into the specified method.

Parameters:

caller - The object whose member method will be assigned as the new update() behavior for this NestSprite instance.

methodName - The name of the method to use for the new update() behavior.

setDraw

public void setDraw()

When setDraw() is called without parameters, it removes the draw functionality set by any previous setDraw() call.

setDraw

public void setDraw(Object caller,
                    String methodName)

Specify behavior to be performed during this instance's draw() phase. methodName is the name of a public method that is a member of the caller object. This method must receive two arguments: a PApplet and a NestSprite instance. e.g.:

 public void lazyDraw (PApplet p, NestSprite sprite) {
     // draw() implementation here
 }
 // ...
 NestSprite lazySprite = new NestSprite();
 lazySprite.setDraw(this, "lazyDraw");
 

Pass null for methodName to remove the custom draw() behavior. Note: Scope within the specified method will be the caller object; i.e. within the specified method, the this keyword will refer to the caller object. To access this NestSprite instance, use the NestSprite parameter passed into the specified method.

Parameters:

caller - The object whose member method will be assigned as the new draw() behavior for this NestSprite instance.

methodName - The name of the method to use for the new draw() behavior.

renderer

public PGraphics renderer()

PGraphics renderer used to manipulate and draw this NestSprite instance. Will return null until this NestSprite is added to the display list. Unless explicitly set, will use the parent NestSprite's value; by default, this is the PGraphics property of the main PApplet. Note: If using a PGraphics buffer, NestSprite subclasses and update()/draw() implementations should use methods of PGraphics rather than PApplet. e.g. Instead of p.line(), call g.line(). TODO: changing during an update()/render() (e.g. within an update() or draw() body) will break things horribly. postpone change until next cycle. TODO: example of rendering into a buffer, printing to PDF.

setRenderer

public void setRenderer(PGraphics renderer)

Set PGraphics renderer used to manipulate and draw this NestSprite instance. Equivalent to setRenderer(PGraphics, boolean) with true for setChildren.

Parameters:

renderer - PGraphics renderer.

setRenderer

public void setRenderer(PGraphics renderer,
                        boolean setChildren)

Set PGraphics renderer used to manipulate and draw this NestSprite instance.

Parameters:

renderer - PGraphics renderer.

setChildren - If true, the PGraphics renderer for all descendants will also be set.

dispose

public void dispose()

Frees up this NestSprite for garbage collection. Does not call dispose() on children. NOTE: not yet tested, nor verified in a profiler.

Overrides:

dispose in class EventDispatcher

dispose

public void dispose(boolean disposeChildren)

Frees up this NestSprite for garbage collection. NOTE: not yet tested, nor verified in a profiler.

Parameters:

disposeChildren - Pass true to also dispose of all children.

localToGlobal

public Point2D.Float localToGlobal(Point2D localPt)

Transform a point from the local coordinate space of this NestSprite instance to the coordinate space of the top-level NestSpriteContainer.

Parameters:

localPt - A point, in the local coordinate space, to transform.

globalToLocal

public Point2D.Float globalToLocal(Point2D globalPt)

Transform a point from the coordinate space of the top-level NestSpriteContainer to the local coordinate space of this NestSprite instance.

Parameters:

globalPt - A point, in the coordinate space of the top-level NestSpriteContainer, to transform.

hitTest

public boolean hitTest(Point2D pt)

Check if a point is within the bounds rect of this NestSprite instance or the bounds rect of any of its children.

Parameters:

pt - Point, in the coordinate system of this NestSprite, to check against bounds of this NestSprite instance and all descendants of this NestSprite instance.

Returns:

Returns true if the Point is within the bounds rect of this NestSprite instance or any of its descendants.

hitTest

public boolean hitTest(Point2D pt,
                       boolean testChildren)

Check if a point is within the bounds rect of this NestSprite instance or the bounds rect of any of its children.

Parameters:

pt - Point, in the coordinate system of this NestSprite, to check against bounds of this NestSprite instance.

testChildren - If true, the hit test will be performed against all descendants of this NestSprite instance.

Returns:

Returns true if the Point is within the bounds rect of this NestSprite instance or, if testChildren is true, the bounds rect of any of its descendants.

dispatchEvent

public void dispatchEvent(Event evt)

Description copied from class: EventDispatcher

Dispatch a Nest Event to all registered Observers. Dispatching an event via this method will store a reference to the owner of this EventDispatcher instance in the event, as Event.target. This is the preferred method for event-based communication within the NestSprite framework. However, since this method is wrapping the Java Observable pattern, a generic Object can be dispatched instead.

Overrides:

dispatchEvent in class EventDispatcher

Parameters:

evt - The Event to dispatch to all Observers.

See Also:

Event.target(), EventDispatcher.owner(), EventDispatcher.handleEvent(Event), EventDispatcher.dispatchEvent(Object)