Inherits from SPDisplayObject : SPEventDispatcher : NSObject
Conforms to NSFastEnumeration
Declared in SPDisplayObjectContainer.h

Overview

An SPDisplayObjectContainer represents a collection of display objects.

It is the base class of all display objects that act as a container for other objects. By maintaining an ordered list of children, it defines the back-to-front positioning of the children within the display tree.

A container does not have size in itself. The width and height properties represent the extents of its children. Changing those properties will scale all children accordingly.

As this is an abstract class, you can’t instantiate it directly, but have to use a subclass instead. The most lightweight container class is SPSprite.

Adding and removing children

The class defines methods that allow you to add or remove children. When you add a child, it will be added at the foremost position, possibly occluding a child that was added before. You can access the children via an index. The first child will have index 0, the second child index 1, etc.

Adding and removing objects from a container triggers non-bubbling events.

  • SPEventTypeAdded: the object was added to a parent.
  • SPEventTypeAddedToStage: the object was added to a parent that is connected to the stage, thus becoming visible now.
  • SPEventTypeRemoved: the object was removed from a parent.
  • SPEventTypeRemovedFromStage: the object was removed from a parent that is connected to the stage, thus becoming invisible now.

Especially the ADDED_TO_STAGE event is very helpful, as it allows you to automatically execute some logic (e.g. start an animation) when an object is rendered the first time.

Sorting children

The sortChildren: method allows you to sort the children of a container by a custom criteria. Below is an example how to depth-sort children by their y-coordinate; this will put objects that are lower on the screen in front of those higher on the screen.

[container sortChildren:^(SPDisplayObject *child1, SPDisplayObject *child2) 
{
    if (child1.y < child2.y) return NSOrderedAscending;
    else if (child1.y > child2.y) return NSOrderedDescending;
    else return NSOrderedSame;
}];

Tasks

Methods

Properties

  •   numChildren

    The number of children of this container.

    property
  •   touchGroup

    If a container is a ‘touchGroup’, it will act as a single touchable object. Touch events will have the container as target, not the touched child (similar to ‘mouseChildren’ in Flash, but with inverted logic). Default: NO

    property

Properties

numChildren

The number of children of this container.

@property (nonatomic, readonly) int numChildren

Discussion

The number of children of this container.

Declared In

SPDisplayObjectContainer.h

touchGroup

If a container is a ‘touchGroup’, it will act as a single touchable object. Touch events will have the container as target, not the touched child (similar to ‘mouseChildren’ in Flash, but with inverted logic). Default: NO

@property (nonatomic, assign) BOOL touchGroup

Discussion

If a container is a ‘touchGroup’, it will act as a single touchable object. Touch events will have the container as target, not the touched child (similar to ‘mouseChildren’ in Flash, but with inverted logic). Default: NO

Declared In

SPDisplayObjectContainer.h

Instance Methods

addChild:

Adds a child to the container. It will be at the topmost position.

- (void)addChild:(SPDisplayObject *)child

Discussion

Adds a child to the container. It will be at the topmost position.

Declared In

SPDisplayObjectContainer.h

addChild:atIndex:

Adds a child to the container at a certain index.

- (void)addChild:(SPDisplayObject *)child atIndex:(int)index

Discussion

Adds a child to the container at a certain index.

Declared In

SPDisplayObjectContainer.h

childAtIndex:

Returns a child object at a certain index.

- (SPDisplayObject *)childAtIndex:(int)index

Discussion

Returns a child object at a certain index.

Declared In

SPDisplayObjectContainer.h

childByName:

Returns a child object with a certain name (non-recursively).

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

Discussion

Returns a child object with a certain name (non-recursively).

Declared In

SPDisplayObjectContainer.h

childIndex:

Returns the index of a child within the container.

- (int)childIndex:(SPDisplayObject *)child

Discussion

Returns the index of a child within the container.

Declared In

SPDisplayObjectContainer.h

containsChild:

Determines if a certain object is a child of the container (recursively).

- (BOOL)containsChild:(SPDisplayObject *)child

Discussion

Determines if a certain object is a child of the container (recursively).

Declared In

SPDisplayObjectContainer.h

removeAllChildren

Removes all children from the container.

- (void)removeAllChildren

Discussion

Removes all children from the container.

Declared In

SPDisplayObjectContainer.h

removeChild:

Removes a child from the container. If the object is not a child, nothing happens.

- (void)removeChild:(SPDisplayObject *)child

Discussion

Removes a child from the container. If the object is not a child, nothing happens.

Declared In

SPDisplayObjectContainer.h

removeChildAtIndex:

Removes a child at a certain index. Children above the child will move down.

- (void)removeChildAtIndex:(int)index

Discussion

Removes a child at a certain index. Children above the child will move down.

Declared In

SPDisplayObjectContainer.h

setIndex:ofChild:

Moves a child to a certain index. Children at and after the replaced position move up.

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

Discussion

Moves a child to a certain index. Children at and after the replaced position move up.

Declared In

SPDisplayObjectContainer.h

sortChildren:

Sorts the children using the given NSComparator block.

- (void)sortChildren:(NSComparator)comparator

Discussion

Sorts the children using the given NSComparator block.

Declared In

SPDisplayObjectContainer.h

swapChild:withChild:

Swaps the indexes of two children.

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

Discussion

Swaps the indexes of two children.

Declared In

SPDisplayObjectContainer.h

swapChildAtIndex:withChildAtIndex:

Swaps the indexes of two children.

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

Discussion

Swaps the indexes of two children.

Declared In

SPDisplayObjectContainer.h