PCanvas.getLayer() is misleading

[GoogleCodeExporter]

PCanvas.getLayer()'s name implies that only one layer can be attached to the 
canvas. 
In reality though any number of layers can be attached to a PCanvas by 
attaching them to the PCanvas' camera.

So, a new user of the library would be limiting their options if they read the 
code and take it at face value.

I suggest deprecating getLayer and replacing it with getFirstLayer, or even 
removing getLayer completely since 
it's just a bit of sugar that's equivalent to PCanvas.getCamera().getLayer(0).

I'm open to other suggestions, I just want to voice my concern regarding this.

Original issue reported on code.google.com by allain.lalonde on 31 Jul 2009 at 6:21

[GoogleCodeExporter]

+1 for firstLayer. Add it soon, make getLayer() deprecated.

Original comment by mr0...@mro.name on 31 Jul 2009 at 6:25

[GoogleCodeExporter]

I thought the same and didn't include getLayer() in POffscreenCanvas.  It is a 
nice
bit of sugar though, and a nice conceptual shortcut as well.  One typically adds
child nodes either to the camera (for "sticky" nodes) or to the layer (for 
typical
behavior).  I was thinking of adding it, with sufficient documentation, and 
suggest
we leave it in PCanvas, with improvement to the documentation:

/**
 * Return the layer for this canvas, that is the first layer
 * in the list of layers viewed by the camera associated with
 * this canvas.  Note that the camera associated with this
 * canvas may view more than one layer.
 *
 * @see PCamera#getLayer(int)
 * @return the layer for this canvas
 */
public PLayer getLayer()

Original comment by heue...@gmail.com on 31 Jul 2009 at 6:40

[GoogleCodeExporter]

After having thought about it a little while, I've thought of this approach:

Change PCanvas to have getLayer(index) as opposed to getLayer().

It wouldn't hide anything and it'd only be marginally more annoying.

If we don't do it this way and go with getFirstLayer(), the next question would 
be...
where's getLayer(index) anyway.

Thoughts?

Original comment by allain.lalonde on 1 Aug 2009 at 12:32

[GoogleCodeExporter]

After speaking with heuermh, I've decided that changing it without giving it 
more
thought is out of the question. It's too integral a part of the way most users 
use
Piccolo to remove without having a sufficient replacement in place.  

I have a hunch that the problem will go away by introducing a SceneBuilder of 
some
kind, but regardless, this change will be made in discussions for v 2.0.

Original comment by allain.lalonde on 1 Aug 2009 at 2:56

[GoogleCodeExporter]

Original comment by heue...@gmail.com on 26 Nov 2013 at 9:11

• Added labels: Milestone-2.1
• Removed labels: Milestone-2.0