Inherits from PXInteractiveObject : PXDisplayObject : PXEventDispatcher : NSObject
Conforms to NSFastEnumeration
Declared in PXDisplayObjectContainer.h
PXDisplayObjectContainer.m

Overview

A PXDisplayObjectContainer is the abstract base class for setting up the display list. A PXDisplayObjectContainer is a display object that can hold children. A PXDisplayObjectContainer should never be made directly, if you wish to have a display object that holds children, then use a PXSprite or PXSimpleSprite instead.

When a PXDisplayObjectContainer is deallocated it removes all of its children, which invokes the remove event on each one. This behavior differs from that of Flash because all containers in Objective-C must remove their contents once deallocated (to avoid child.parent pointing to a zombie).

Tasks

  •   touchChildren

    Determines whether or not the children of this object can be sent touch events.

         property
  •   numChildren

    The number of display objects within this container.

         property
  • – addChild:

    Adds a child to the display list, increasing its retain count by 1.
  • – addChild:atIndex:

    Adds a child to the display list at the specified index, increasing its retain count by 1.
  • – containsChild:

    Determines whether the specified object is a child of this container or any of its children.
  • – childAtIndex:

    Retrieves the child at the specified index. If no child was found at the index, then nil is returned instead. If the index is out of bounds then a PXRangeException is thrown.
  • – childByName:

    Retrieves the child with the specified name. If no child was found with the specified name, then nil is returned instead.
  • – indexOfChild:

    Retrieves the index of the specified child. If the specified child is not part of this container, then -1 is returned instead and a PXArgumentException is thrown.
  • – removeChild:

    Removes the child from the container, and decreases its retain count by 1. If the specified object is not a child of this container, then a PXArgumentException is thrown. All of the other children move down a position to fill the gap left by the removed child.
  • – removeChildAtIndex:

    Removes the child from the container, and decreases its retain count by 1. If the object is not a child of this container, then a PXRangeException is thrown. All of the other children move down a position to fill the gap left by the removed child.
  • – setIndex:ofChild:

    Changes the position of the child to the specified index. This will decrease the position all of the children that are between the original index and the new index.
  • – swapChild:withChild:

    Swaps the two children’s position, all other children remain in the position they were at prior to the swap taking place.
  • – swapChildAtIndex:withChildAtIndex:

    Swaps the two children’s position, all other children remain in the position they were at prior to the swap taking place.
  • – removeAllChildren

    Removes all of the children from the container, reducing each of the object’s retain counts by 1.
  • – objectsUnderPoint:

    Makes a list of objects that are under the given point. These objects can be any child, grandchild, etc. of this container, as long as they are under the point.

Properties

numChildren

The number of display objects within this container.

@property (readonly) unsigned short numChildren

Declared In

PXDisplayObjectContainer.h

touchChildren

Determines whether or not the children of this object can be sent touch events.

@property (nonatomic, assign) BOOL touchChildren

Discussion

This unfortunately-named property is the result of trying to faithfully reproduce ActionScript’s naming convention. The original was named mouseChildren.

Declared In

PXDisplayObjectContainer.h

Instance Methods

addChild:

Adds a child to the display list, increasing its retain count by 1.

- (PXDisplayObject *)addChild:(PXDisplayObject *)child

Parameters

child

The object to be added.

Return Value

The display object passed by the child parameter.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
// add1 has a retain count of 1
[simpleSprite addChild:add1];
// add1 has a retain count of 2

Declared In

PXDisplayObjectContainer.m

addChild:atIndex:

Adds a child to the display list at the specified index, increasing its retain count by 1.

- (PXDisplayObject *)addChild:(PXDisplayObject *)child atIndex:(int)index

Parameters

child

The object to be added.

index

The index at which to add the display object. An index of 0 represents the very back of the screen, while higher indecies are closer to the top.

Return Value

The display object passed by the child parameter.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
// add1 has a retain count of 1
[simpleSprite addChild:add1 atIndex:0];
// add1 has a retain count of 2

Declared In

PXDisplayObjectContainer.m

childAtIndex:

Retrieves the child at the specified index. If no child was found at the index, then nil is returned instead. If the index is out of bounds then a PXRangeException is thrown.

- (PXDisplayObject *)childAtIndex:(int)index

Parameters

index

The index.

Return Value

The child at the specified index.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
PXSimpleSprite *retrievedChild = (PXSimpleSprite *)[simpleSprite getChildAtIndex:0];
// retrievedChild == add1

Declared In

PXDisplayObjectContainer.m

childByName:

Retrieves the child with the specified name. If no child was found with the specified name, then nil is returned instead.

- (PXDisplayObject *)childByName:(NSString *)name

Parameters

name

The case sensitive name of the child.

Return Value

The child with the specified name.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
add1.name = @"Orange";
[simpleSprite addChild:add1];
PXSimpleSprite *retrievedChild = (PXSimpleSprite *)[simpleSprite getChildByName:@"Orange"];
// retrievedChild == add1

Declared In

PXDisplayObjectContainer.m

containsChild:

Determines whether the specified object is a child of this container or any of its children.

- (BOOL)containsChild:(PXDisplayObject *)childToCheck

Parameters

child

The child to be checked.

Return Value

YES if the specified child is a decendant of this container.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
BOOL containsChild = [simpleSprite containsChild:add1];
// containsChild is YES
[simpleSprite removeChild:add1];
containsChild = [simpleSprite containsChild:add1];
// containsChild is NO

Declared In

PXDisplayObjectContainer.m

indexOfChild:

Retrieves the index of the specified child. If the specified child is not part of this container, then -1 is returned instead and a PXArgumentException is thrown.

- (int)indexOfChild:(PXDisplayObject *)childToCheck

Parameters

child

The child in question.

Return Value

index The index of the child.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];

int index = [simpleSprite getIndexOfChild:add1];
// index == 0
index = [simpleSprite getIndexOfChild:add2];
// index == 1
[simpleSprite removeChild:add1];
index = [simpleSprite getIndexOfChild:add1];
//index == -1

Declared In

PXDisplayObjectContainer.m

objectsUnderPoint:

Makes a list of objects that are under the given point. These objects can be any child, grandchild, etc. of this container, as long as they are under the point.

- (NSArray *)objectsUnderPoint:(PXPoint *)point

Parameters

point

The point to check for objects under in global coordinates.

Example:

PXSprite *container = [[PXSprite alloc] init];

PXSprite *square1 = [[PXSprite alloc] init];
[square1.graphics beginFill:0xFFCC00 alpha:1.0f];
[square1.graphics drawRectWithX:0 y:0 width:40 height:40];

PXSprite *square2 = [[PXSprite alloc] init];
[square2.graphics beginFill:0x00CCFF alpha:1.0f];
[square2.graphics drawRectWithX:20 y:0 width:30 height:40];

[container addChild:square1];
[container addChild:square2];

PXPoint *pt;
NSArray *objects;

pt = [PXPoint pointWithX:10 y:20];
objects = [container objectsUnderPoint:pt];
NSLog (@"list count = %d\n", [objects count]); // 1

pt = [PXPoint pointWithX:35 y:20];
objects = [container objectsUnderPoint:pt];
NSLog (@"list count = %d\n", [objects count]); // 2

[square1 release];
[square2 release];

[container release];

Declared In

PXDisplayObjectContainer.m

removeAllChildren

Removes all of the children from the container, reducing each of the object’s retain counts by 1.

- (void)removeAllChildren

Discussion

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
// add1 and add2 have a retain count of 1
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
// simpleSprite contains two children now
// add1 and add2 have a retain count of 2
[add1 release];
[add2 release];
// add1 and add2 have a retain count of 1
[simpleSprite removeAllChildren];
// simpleSprite has no children now
// add1 and add2 have a retain count of 0

Declared In

PXDisplayObjectContainer.m

removeChild:

Removes the child from the container, and decreases its retain count by 1. If the specified object is not a child of this container, then a PXArgumentException is thrown. All of the other children move down a position to fill the gap left by the removed child.

- (void)removeChild:(PXDisplayObject *)child

Parameters

child

The child to be removed.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
// add1 has a retain count of 1, and no index
// add2 has a retain count of 1, and no index
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
// add1 has a retain count of 2, and an index of 0
// add2 has a retain count of 2, and an index of 1
[simpleSprite removeChild:add1];
// add1 has a retain count of 1, and no index
// add2 has a retain count of 2, and an index of 0

Declared In

PXDisplayObjectContainer.m

removeChildAtIndex:

Removes the child from the container, and decreases its retain count by 1. If the object is not a child of this container, then a PXRangeException is thrown. All of the other children move down a position to fill the gap left by the removed child.

- (void)removeChildAtIndex:(int)index

Parameters

index

The index of the child to be removed.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
// add1 has a retain count of 1, and no index
// add2 has a retain count of 1, and no index
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
// add1 has a retain count of 2, and an index of 0
// add2 has a retain count of 2, and an index of 1
[simpleSprite removeChildAtIndex:0];
// add1 has a retain count of 1, and no index
// add2 has a retain count of 2, and an index of 0

Declared In

PXDisplayObjectContainer.m

setIndex:ofChild:

Changes the position of the child to the specified index. This will decrease the position all of the children that are between the original index and the new index.

- (void)setIndex:(int)index ofChild:(PXDisplayObject *)child

Parameters

index

New index of the child.

child

Child to be repositioned.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
PXSimpleSprite *add3 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
[simpleSprite addChild:add3];
// add1 has an index of 0, add2 has an index of 1, add3 has an index of 2.
[simpleSprite setIndex:2 ofChild:add1];
// add1 has an index of 2, add2 has an index of 0, add3 has an index of 1.
[simpleSprite setIndex:2 ofChild:add3];
// add1 has an index of 1, add2 has an index of 0, add3 has an index of 2.

Discussion

If the index provided is less than 0, then the object is moved to index 0. If the index is higher than the number of children, then the object is moved to the last index.

Declared In

PXDisplayObjectContainer.m

swapChild:withChild:

Swaps the two children’s position, all other children remain in the position they were at prior to the swap taking place.

- (void)swapChild:(PXDisplayObject *)child1 withChild:(PXDisplayObject *)child2

Parameters

child1

The first child.

child2

The second child.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
// add1 has an index of 0, add2 has an index of 1
[simpleSprite swapChild:add1 withChild:add2];
// add1 has an index of 1, add2 has an index of 0

Declared In

PXDisplayObjectContainer.m

swapChildAtIndex:withChildAtIndex:

Swaps the two children’s position, all other children remain in the position they were at prior to the swap taking place.

- (void)swapChildAtIndex:(int)index1 withChildAtIndex:(int)index2

Parameters

index1

Index of the first child.

index2

Index of the second child.

Example:

PXSimpleSprite *simpleSprite = [PXSimpleSprite new];
PXSimpleSprite *add1 = [PXSimpleSprite new];
PXSimpleSprite *add2 = [PXSimpleSprite new];
[simpleSprite addChild:add1];
[simpleSprite addChild:add2];
// add1 has an index of 0, add2 has an index of 1
[simpleSprite swapChildAtIndex:0 withChildAtIndex:1];
// add1 has an index of 1, add2 has an index of 0

@exception PXArgumentException Throws if either child parameter is not a child of this object.

Discussion

It is more efficent not to reference a child by index. If at all possible you should avoid using this method, and use swapChild:withChild: instead.

Declared In

PXDisplayObjectContainer.m