Inherits from PXEventDispatcher : NSObject
Declared in PXDisplayObject.h
PXDisplayObject.m

Overview

The base class for all elements drawn to the stage. PXDisplayObject is an abstract class that represent a single element in the display list.

Every display object has the following main components:

  • A transformation matrix representing the translation, rotation, scaling, and skewing of the display object in relation to its parent’s (ie. local coordinates).
  • A color transform representing the display object’s color offset in relation to its parents' (ie. local color space).
  • A reference to the display object’s parent, as well as the global stage and root objects.
  • An optional non-unique name. (for easy dereferencing)
  • A visibility toggle.

To abstract away the details of setting transformation matrices and color transforms, the following properties are available:

Helper methods are available for getting the bounding-box of a display object and performing hit-tests:

The PXDisplayObject class should never be instantiated directly. Instead use one of its concrete subclasses or create your own.

Tasks

  •   userData

    A value defined and kept by the user. This is a useful pointer for anyone who wants to associate a display object with something else.

         property
  •   alpha

    A value between 0 and 1 representing the display object’s transparency. an alpha value of 1 will make the object fully opaque while a value of 0 will make the object completely transparent.

         property
  •   rotation

    The angle of rotation of the display object in degrees. Positive rotation values result in clock-wise rotation.

         property
  •   scaleX

    A scaling value along the horizontal axis. A value between 0 and 1 will squeeze the display object, while a value greater than 1 will stretch it out.

         property
  •   scaleY

    A scaling value along the vertical axis. A value between 0 and 1 will squeeze the display object, while a value greater than 1 will stretch it out.

         property
  •   x

    The offset of the display object’s position across the horizontal axis. Translation in Pixelwave is always measured in points, within the parent’s local coordinate space.

         property
  •   y

    The offset of the display object’s position across the vertical axis. Translation in Pixelwave is always measured in points, within the parent’s local coordinate space.

         property
  •   width

    The width, in points of the object’s axis-aligned bounding box, within its parent’s coordinate space.

         property
  •   height

    The height, in points of the object’s axis-aligned bounding box, within its parent’s coordinate space.

         property
  •   visible

    A boolean representing the display object’s visibility. If set to YES, the display object is rendered as usual. If set to NO, the display object is ignored during the render phase, and will not recieve any touch interaction events.

         property
  •   transform

    Represents the display object’s local space and color transformation.

         property
  •   name

    A non-unique name. name may never be nil. If a name isn’t assigned, one will be automatically generated.

         property
  •   parent

    The display object’s container, or nil if the display object is not on a display list.

         property
  •   root

    The global root display object. Will equal nil if the display object isn’t part of a display list descending from the root display object.

         property
  •   stage

    The global stage display object. Will equal nil if the display object isn’t part of the main display list.

         property
  •   scale

    Represents both the scaleX and scaleY properties. Setting this property will set the values of scaleX and scaleY to the given value.

         property
  •   touchX

    The horizontal position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then 0.0f is returned.

         property
  •   touchY

    The vertical position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then 0.0f is returned.

         property
  •   touchPosition

    The position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then nil is returned.

         property
  •   touchPositions

    A list of PXPoint s that represent the positions of every touch on the screen in this PXDisplayObject’s coordinate space. If there are no current touches on the screen, nil is returned.

         property
  • – positionOfTouch:

    Finds the position of the touch in this display object’s coordinate system.
  • – boundsWithCoordinateSpace:

    Finds the bounding box of this display object in the target coordinate space.
  • – rectWithCoordinateSpace:

    For the time being, both rectWithCoordinateSpace and boundsWithCoordinateSpace do the same thing.
  • – globalToLocal:

    Converts a stage coordinate point to the display object’s coordinate system.
  • – localToGlobal:

    Converts a display object’s coordinate system point to the stage’s coordinate system.
  • – hitTestObject:

    Tests if the bounding box of the given object is within the bounding box of this object.
  • – hitTestPointWithX:y:

    Tests if the given horizontal and vertical coordinate are within the bounding box of this display object.
  • – hitTestPointWithX:y:shapeFlag:

    Tests if the given horizontal and vertical coordinate are within the display object.

Properties

alpha

A value between 0 and 1 representing the display object’s transparency. an alpha value of 1 will make the object fully opaque while a value of 0 will make the object completely transparent.

@property (nonatomic) float alpha

Discussion

Default: 1.0f

Declared In

PXDisplayObject.h

height

The height, in points of the object’s axis-aligned bounding box, within its parent’s coordinate space.

@property (nonatomic) float height

Discussion

Note that modifying the height property affects the value of the scaleX and scaleY properties and vice-versa

Default: 0.0f

Declared In

PXDisplayObject.h

name

A non-unique name. name may never be nil. If a name isn’t assigned, one will be automatically generated.

@property (nonatomic, copy) NSString *name

Discussion

@throws PXArgumentException if a nil value is set.

See Also

Declared In

PXDisplayObject.h

parent

The display object’s container, or nil if the display object is not on a display list.

@property (nonatomic, readonly) PXDisplayObjectContainer *parent

Declared In

PXDisplayObject.h

root

The global root display object. Will equal nil if the display object isn’t part of a display list descending from the root display object.

@property (nonatomic, readonly) PXDisplayObject *root

Declared In

PXDisplayObject.h

rotation

The angle of rotation of the display object in degrees. Positive rotation values result in clock-wise rotation.

@property (nonatomic) float rotation

Discussion

Default: 0.0f

Declared In

PXDisplayObject.h

scale

Represents both the scaleX and scaleY properties. Setting this property will set the values of scaleX and scaleY to the given value.

@property (nonatomic) float scale

Discussion

If the #scaleX and scaleY properties are equal, this property will be equal to their value. If their values differ, this property will be equal to 1.0.

See Also

Declared In

PXDisplayObject.h

scaleX

A scaling value along the horizontal axis. A value between 0 and 1 will squeeze the display object, while a value greater than 1 will stretch it out.

@property (nonatomic) float scaleX

Discussion

A negative value flips the object.

Note that modifying the scaleX property may change the value of the width and height properties and vice-versa

Default: 1.0f

Declared In

PXDisplayObject.h

scaleY

A scaling value along the vertical axis. A value between 0 and 1 will squeeze the display object, while a value greater than 1 will stretch it out.

@property (nonatomic) float scaleY

Discussion

A negative value flips the object.

Note that modifying the scaleY property may change the value of the width and height properties and vice-versa

Default: 1.0f

Declared In

PXDisplayObject.h

stage

The global stage display object. Will equal nil if the display object isn’t part of the main display list.

@property (nonatomic, readonly) PXStage *stage

Discussion

If a display object isn’t on the main display list it can’t be rendered to the screen.

Declared In

PXDisplayObject.h

touchPosition

The position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then nil is returned.

@property (nonatomic, readonly) PXPoint *touchPosition

Declared In

PXDisplayObject.h

touchPositions

A list of PXPoint s that represent the positions of every touch on the screen in this PXDisplayObject’s coordinate space. If there are no current touches on the screen, nil is returned.

@property (nonatomic, readonly) NSArray *touchPositions

Declared In

PXDisplayObject.h

touchX

The horizontal position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then 0.0f is returned.

@property (nonatomic, readonly) float touchX

Declared In

PXDisplayObject.h

touchY

The vertical position of the first touch on the screen in this PXDisplayObject’s coordinate space. If there are no fingers (touches) on the screen, then 0.0f is returned.

@property (nonatomic, readonly) float touchY

Declared In

PXDisplayObject.h

transform

Represents the display object’s local space and color transformation.

@property (nonatomic, assign) PXTransform *transform

See Also

Declared In

PXDisplayObject.h

userData

A value defined and kept by the user. This is a useful pointer for anyone who wants to associate a display object with something else.

@property (nonatomic) void *userData

Discussion

Default: NULL

If you free/delete/release the object pointed to by userData, remember to set userData to NULL to avoid memory access bugs, headaches, frustration, and possibly suicidal thoughts. Don’t say we didn’t warn you.

Declared In

PXDisplayObject.h

visible

A boolean representing the display object’s visibility. If set to YES, the display object is rendered as usual. If set to NO, the display object is ignored during the render phase, and will not recieve any touch interaction events.

@property (nonatomic) BOOL visible

Discussion

Default: YES

Declared In

PXDisplayObject.h

width

The width, in points of the object’s axis-aligned bounding box, within its parent’s coordinate space.

@property (nonatomic) float width

Discussion

Note that modifying the width property affects the value of the scaleX and scaleY properties and vice-versa

Default: 0.0f

Declared In

PXDisplayObject.h

x

The offset of the display object’s position across the horizontal axis. Translation in Pixelwave is always measured in points, within the parent’s local coordinate space.

@property (nonatomic) float x

Discussion

Default: 0.0f

Declared In

PXDisplayObject.h

y

The offset of the display object’s position across the vertical axis. Translation in Pixelwave is always measured in points, within the parent’s local coordinate space.

@property (nonatomic) float y

Discussion

Default: 0.0f

Declared In

PXDisplayObject.h

Instance Methods

boundsWithCoordinateSpace:

Finds the bounding box of this display object in the target coordinate space.

- (PXRectangle *)boundsWithCoordinateSpace:(PXDisplayObject *)targetCoordinateSpace

Parameters

targetCoordinateSpace

The coordinate space for the bounds

Return Value

The bounding box in the target coordinate system.

Example:

PXShape *shape1 = [[PXShape alloc] init];
PXShape *shape2 = [[PXShape alloc] init];

[self addChild:shape1];
[self addChild:shape2];

[shape1 release];
[shape2 release];

shape1.x = 50.0f;
shape1.y = 25.0f;
shape2.x = 100.0f;
shape2.y = 75.0f;

[shape1.graphics beginFill:0xFF0000 alpha:1.0f];
[shape1.graphics drawRectWithX:0.0f y:0.0f width:100.0f height:200.0f];
[shape1.graphics endFill];

[shape2.graphics beginFill:0x0000FF alpha:1.0f];
[shape2.graphics drawRectWithX:0.0f y:0.0f width:200.0f height:100.0f];
[shape2.graphics endFill];

PXRectangle *bounds;

bounds = [shape1 boundsWithCoordinateSpace:shape2];
NSLog (@"shape1 in shape2 = %@\n", [bounds description]);
// bounds = (x=-50.0f, y=-50.0f, w=100.0f, h=200.0f)

shape2.scale = 0.5f;
bounds = [shape1 boundsWithCoordinateSpace:shape2];
NSLog (@"shape1 in shape2 = %@\n", [bounds description]);
// bounds = (x=-100.0f, y=-100.0f, w=200.0f, h=400.0f)

bounds = [shape1 boundsWithCoordinateSpace:shape1];
NSLog (@"shape1 in shape1 = %@\n", [bounds description]);
// bounds = (x=0.0f, y=0.0f, w=100.0f, h=200.0f)

bounds = [shape1 boundsWithCoordinateSpace:self];
NSLog (@"shape1 in root = %@\n", [bounds description]);
// bounds = (x=50.0f, y=-25.0f, w=100.0f, h=200.0f)

Declared In

PXDisplayObject.m

globalToLocal:

Converts a stage coordinate point to the display object’s coordinate system.

- (PXPoint *)globalToLocal:(PXPoint *)point

Parameters

point

A point in the stage coordinate system.

Return Value

The converted point to this display object’s coordinate system.

Example:

PXShape *shape = [[PXShape alloc] init];
[self addChild:shape];
[shape release];

shape.x = 50.0f;
shape.y = 25.0f;

[shape.graphics beginFill:0xFF0000 alpha:1.0f];
[shape.graphics drawRectWithX:0.0f y:0.0f width:100.0f height:200.0f];
[shape.graphics endFill];

PXPoint *point = [PXPoint pointWithX:10.0f y:20.0f];
PXPoint *localPoint = [shape globalToLocal:point];
// Point will be at (x=10.0f, y=20.0f), localPoint = (x=-40.0f, y=-5.0f).

Declared In

PXDisplayObject.m

hitTestObject:

Tests if the bounding box of the given object is within the bounding box of this object.

- (BOOL)hitTestObject:(PXDisplayObject *)obj

Parameters

obj

The object for testing.

Return Value

YES if the bounding box of the given object is within the bounding box of this object.

Example:

PXTexture *tex1 = [PXTexture textureWithContentsOfFile:@"image.png"];
PXTexture *tex2 = [PXTexture textureWithContentsOfFile:@"image.png"];

[self addChild:tex1];
[self addChild:tex2];

BOOL collides;

tex2.x = 0.0f;
collides = [tex1 hitTestObject:tex2];
NSLog (@"collides = %@\n", (collides ? @"YES" : @"NO"));
// collides = YES

tex2.x = (tex1.x + tex1.width) *    1.2f;
collides = [tex1 hitTestObject:tex2];
NSLog (@"collides = %@\n", (collides ? @"YES" : @"NO"));
// collides = NO

Declared In

PXDisplayObject.m

hitTestPointWithX:y:

Tests if the given horizontal and vertical coordinate are within the bounding box of this display object.

- (BOOL)hitTestPointWithX:(float)x y:(float)y

Parameters

x

The horizontal coordinate (in stage coordinates) for testing.

y

The vertical coordinate (in stage coordinates) for testing.

Return Value

YES if point is contained within the bounding box of this display object.

Example:

PXTexture *tex = [PXTexture textureWithContentsOfFile:@"image.png"];
[self addChild:tex];

tex.width  = 100.0f;
tex.height = 100.0f;

BOOL collides;

tex.x = 0.0f;
tex.y = 0.0f;
collides = [tex hitTestPointWithX:50.0f y:25.0f];
// collides = YES

tex.x = 75.0f;
tex.y = 75.0f;
collides = [tex hitTestPointWithX:50.0f y:25.0f];
// collides = NO

Declared In

PXDisplayObject.m

hitTestPointWithX:y:shapeFlag:

Tests if the given horizontal and vertical coordinate are within the display object.

- (BOOL)hitTestPointWithX:(float)x y:(float)y shapeFlag:(BOOL)shapeFlag

Parameters

x

The horizontal coordinate (in stage coordinates) for testing.

y

The vertical coordinate (in stage coordinates) for testing.

shapeFlag

If YES a detailed collision detection is done of the actual object. If NO just the bounding box is tested.

Return Value

YES if point is contained within the bounding box of this display object.

Example:

PXShape *shape = [[PXShape alloc] init];
[self addChild:shape];
[shape release];

[shape.graphics beginFill:0xFF0000 alpha:1.0f];
[shape.graphics drawCircleWithX:50.0f y:50.0f radius:50.0f];
[shape.graphics endFill];

BOOL collides;

collides = [tex hitTestPointWithX:1.0f y:1.0f shapeFlag:NO];
// collides = YES

collides = [tex hitTestPointWithX:1.0f y:1.0f shapeFlag:YES];
// collides = NO

Declared In

PXDisplayObject.m

localToGlobal:

Converts a display object’s coordinate system point to the stage’s coordinate system.

- (PXPoint *)localToGlobal:(PXPoint *)point

Parameters

point

A point in this display object’s coordinate system.

Return Value

The converted point to the stage’s coordinate system.

Example:

PXShape *shape = [[PXShape alloc] init];
[self addChild:shape];
[shape release];

shape.x = 50.0f;
shape.y = 25.0f;

[shape.graphics beginFill:0xFF0000 alpha:1.0f];
[shape.graphics drawRectWithX:0.0f y:0.0f width:100.0f height:200.0f];
[shape.graphics endFill];

PXPoint *point = [PXPoint pointWithX:10.0f y:20.0f];
PXPoint *globalPoint = [shape localToGlobal:point];
// Point will be at (x=10.0f, y=20.0f), localPoint = (x=-60.0f, y=45.0f).

Declared In

PXDisplayObject.m

positionOfTouch:

Finds the position of the touch in this display object’s coordinate system.

- (PXPoint *)positionOfTouch:(UITouch *)nativeTouch

Parameters

nativeTouch

The touch to find the position of.

Return Value

The position of the touch in this display object’s coordinate system.

Example:

- (void) onTouchDown:(PXTouchEvent *)event
{
    PXPoint *touchPosition = [self positionOfTouch:event.nativeTouch];
}

Declared In

PXDisplayObject.m

rectWithCoordinateSpace:

For the time being, both rectWithCoordinateSpace and boundsWithCoordinateSpace do the same thing.

- (PXRectangle *)rectWithCoordinateSpace:(PXDisplayObject *)targetCoordinateSpace

Declared In

PXDisplayObject.m