SPDisplayObjectContainer Class Reference
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
-
– addChild:
Adds a child to the container. It will be at the topmost position.
-
– addChild:atIndex:
Adds a child to the container at a certain index.
-
– containsChild:
Determines if a certain object is a child of the container (recursively).
-
– childAtIndex:
Returns a child object at a certain index.
-
– childByName:
Returns a child object with a certain name (non-recursively).
-
– childIndex:
Returns the index of a child within the container.
-
– setIndex:ofChild:
Moves a child to a certain index. Children at and after the replaced position move up.
-
– removeChild:
Removes a child from the container. If the object is not a child, nothing happens.
-
– removeChildAtIndex:
Removes a child at a certain index. Children above the child will move down.
-
– removeAllChildren
Removes all children from the container.
-
– swapChild:withChild:
Swaps the indexes of two children.
-
– swapChildAtIndex:withChildAtIndex:
Swaps the indexes of two children.
-
– sortChildren:
Sorts the children using the given NSComparator block.
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:
propertyNO
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