CocosNodes
==========

.. contents::
    :local:


Built-in cocosnode objects
--------------------------

CocosNode
^^^^^^^^^

In cocos2d, every object that is part of an scene is a `CocosNode` object.
For example:

    - sprites
    - labels
    - menus
    - layers
    - scenes

Every `CocosNode` object has these attributes
*(see below for some exceptions)* :

    - position
    - color
    - opacity
    - scale
    - rotation
    - visible
    - camera
    - grid

and these attributes can be modified manually.
Example::

    # place the sprite in 320,240
    sprite.position = (320,240)

or by using actions.
Example::

    # move the sprite to 320,240 in 5 seconds
    sprite.do( MoveTo( (320,240, duration=2 ) )

You can modify these attributes to **any** `CocosNode` object.
For example::

    scene.do( ScaleTo(2, duration=2) )

    layer.do( RotateBy(360, duration=3) )

    sprite.do( Blink(5, duration=1 ) )

    label.do( JumpBy( (100,100), 50, 5, duration=3) )

Another important feature common to **any** `CocosNode` object, is that
is is also a container, it can have children.
For example::

    # a scene with 2 layers
    scene.add( background_layer, z=0 )
    scene.add( game_layer, z=1 )

    # the layer with 1 sprite
    game_layer.add( sprite )

    # the sprite, with 2 sprites
    sprite.add( ship1_sprite )
    sprite.add( ship2_sprite )

and you can remove any children from any `CocosNode` object 
using *remove*. For example::

    layer.add( sprite1 )
    layer.add( sprite2, name="car" )

    # remove by reference
    layer.remove( sprite )

    # remove by name
    layer.remove( "car" )

Note that in current cocos if you add with name then you should remove by name,
else the name will become unusable for new additions.

In case you want to obtain a reference to a certain named child, you can 
use *get*.
Example::

    layer.add( sprite1, name="car")

    ...

    car_sprite = layer.get("car")


Scene
^^^^^

In the common case, contains all elements visible on the app window.

 These properties are not available:

    - color
    - opacity


Layer
^^^^^

  TODO: explain `Layer`

 These properties are not available:

    - color
    - opacity


ScrollingManager
^^^^^^^^^^^^^^^^

 These properties are not available:

    - color
    - opacity


ScrollableLayer
^^^^^^^^^^^^^^^

 These properties are not available:

    - color
    - opacity
               

Sprite
^^^^^^

Sprites allows to display a image in a rectangular area, which can be rotated,
scaled and moved.
The placement in the scene follows the standard CocosNode rules.
Also, all stock actions will work with sprites.


Animating a sprite
++++++++++++++++++

Animation as in cartoon style animation, that is, replacing the image fast
enough to give the illusion of movement, can be accomplished by:

 - using an animated .gif file as source for the image
 - passing a pyglet.image.Animation as image, which collects a number of images
 - have an array of images and let your code assign to the sprite image member

Performance Considerations
++++++++++++++++++++++++++

Sprites are not suitable for effects that piles a lot of semitransparent images
to build an effect like smoke or poissoning fog. Use particle systems or custom
CocosNode s managing vertex lists for that.

If your scene has less than 25 sprites, you can add directly to the
scene, like::

    class TLayer(cocos.layer.Layer):
       is_event_handler = True
       def __init__(self):
          cocos.layer.Layer.__init__(self)
          world_width, world_height = director.get_window_size()
          rand_color = [255, 0, 0]
          icolor = 0
          for i in range(qty_balls):
             ball = Ball((world_width*random.random(), world_height*random.random()), color=rand_color)
             rand_color[icolor] = random.randint(50, 255)
             icolor = (icolor + 1)%len(rand_color)
             self.add(ball)
          self.time = 0.0
          self.schedule(self.update)
               
When you have between 25 and 100 visible sprites, moving at each frame, you
should add one or more BatchNode s at some level in the scene and add the
sprites to them. Even only one batch can give you 4x fps::

    class TLayer(cocos.layer.Layer):
       is_event_handler = True
       def __init__(self):
          cocos.layer.Layer.__init__(self)
          batch = cocos.batch.BatchNode()
          self.add(batch) # we add a batch to the layer ...
          world_width, world_height = director.get_window_size()
          rand_color = [255, 0, 0]
          icolor = 0
          for i in range(100):
             ball = Ball((world_width*random.random(), world_height*random.random()), color=rand_color)
             rand_color[icolor] = random.randint(50, 255)
             icolor = (icolor + 1)%len(rand_color)
             batch.add(ball) # see ? we add sprites to the batch, not the layer
          self.batch = batch
          self.time = 0.0
          self.schedule(self.update)

With more than 100 visible, moving at each frame sprites, you will need to
optimize further to run at 60 fps in weak hardware like netbooks, old desktops,
cheap new dewstops.
You can look at cocos particle systems and the section graphics in pyglet
programing guide for ideas. 


Labels
^^^^^^

`Label` s provide the most simple text display.
Font family, font size, position, color, opacity and align can be specified.

`HTMLLabel` s is a slightly more powerful label, it can use mixed styles. Uses HTML syntax for text and styles.

 These properties are not available:

    - camera


ColorLayer
^^^^^^^^^^

  TODO: explain `ColorLayer`

Menu
^^^^
  
  TODO: explain `Menu`

  TODO: explain `MultiplexLayer`

 These properties are not available:

    - color
    - opacity


MenuItem
^^^^^^^^

  TODO: explain `MenuItem`

  TODO: explain `MultipleMenuItem`

  TODO: explain `ToggleMenuItem`

  TODO: explain `EntryMenuItem`

  TODO: explain pre-defined actions: `shake` , `shake_back` ,
  `zoom_in` and `zoom_out`

 These properties are not available:

    - color
    - opacity


Creating your own objects 
-------------------------

TODO: explain how to build custom cocosnode objects,
how to use `transform` , etc.
