1 /*
  2  *Copyright (c) 2009, TellurianRing.com
  3  *All rights reserved.
  4  *
  5  *Redistribution and use in source and binary forms, with or without modification,
  6  *are permitted provided that the following conditions are met:
  7  *
  8  *   Redistributions of source code must retain the above copyright notice, this
  9  *   list of conditions and the following disclaimer.
 10  *   Redistributions in binary form must reproduce the above copyright notice,
 11  *   this list of conditions and the following disclaimer in the documentation
 12  *   and/or other materials provided with the distribution.
 13  *   Neither the name of the Organization (TellurianRing.com) nor the names of
 14  *   its contributors may be used to endorse or promote products derived from
 15  *   this software without specific prior written permission.
 16  *
 17  *THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 18  *ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 19  *WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 20  *DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR
 21  *ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 22  *(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 23  *LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
 24  *ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 25  *(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 26  *SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 27  */
 28 
 29 /**
 30  * @class A Scene represents the root level of content within a Stage.
 31  * @param {Object} _details A JSON object with the following properties:
 32  * <table cellpadding="0" cellspacing="1" border="0" class="constructor_details">
 33  *    <tr><th>Property</th> <th>Required</th> <th>Default</th></tr>
 34  *    <tr><td>content</td>  <td>no</td>       <td>new Array()</td></tr>
 35  *    <tr><td>name</td>     <td>no</td>       <td>""</td></tr>
 36  * </table>
 37  *    Properties:
 38  *    name: The name of this Scene.
 39  *    content: The content of this Scene.
 40  * @example
 41  * var myScene = Scene({
 42  *    name: "MyScene",
 43  *    content: [
 44  *       Graphic({url: "./images/ball.png"})
 45  *    ]
 46  * });
 47  * <div id="scene_example_1"></div>
 48  * <script type="text/javascript">
 49  *    var myScene = Scene({
 50  *       name: "MyScene",
 51  *       content: [
 52  *          Graphic({url: "./images/ball.png"})
 53  *       ]
 54  *    });
 55  *    Stage({
 56  *       container_id: "scene_example_1",
 57  *       width: 120, height: 100,
 58  *       update_time: 500,
 59  *       scene: myScene
 60  *    });
 61  * </script>
 62  */
 63 function Scene(_details) { // {{{
 64    /** @constructs */
 65    function _Scene(_details) { // {{{
 66       // Private Members {{{
 67       var content = check(_details.content, new Array());
 68       var name = check(_details.name, "");
 69       var stage = null;
 70       // }}}
 71 
 72       // Public Members {{{
 73       this.details = _details;
 74 
 75       /**
 76        * Adds the given SceneContent to this Scene. This function
 77        * calls the load function on the given SceneContent before adding it to
 78        * the Scene's content list, so that it will be loaded before getting
 79        * picked up by the Stage's fun loop.
 80        * @function
 81        * @param SceneContent _content The SceneContent to be added to this
 82        * Scene.
 83        */
 84       this.addContent = function(_content) {
 85          _content.load(this, this);
 86          content.push(_content);
 87       }
 88       /**
 89        * Calls draw on each child content with the given canvas context.
 90        * @function
 91        * @param _context The drawing context from the Stage's canvas element.
 92        */
 93       this.draw = function(_context) { // {{{
 94          for(var index in content) {
 95             var component = content[index];
 96             if(component.isActive() && component.isVisible()) {
 97                component.draw(_context);
 98             }
 99          }
100       } // }}} draw
101 
102       /**
103        * This extends the provided child function with this instance.
104        * @function
105        * @param _child The child function to be extended.
106        */
107       this.extend = function(_child) { // {{{
108          _child.prototype = this;
109       } // }}} extend
110 
111       /**
112        * Uses Stage.getSize() to retrieve the size of the stage, and
113        * returns a Bounds({x: 0, y: 0, w: stage_size.w, h: stage_size.h}).
114        * @function
115        * @return Bounds({x: 0, y: 0, w: stage_size.w, h: stage_size.h})
116        */
117       this.getBounds = function() { // {{{
118          var stage_size = stage.getSize();
119          return Bounds({x: 0, y: 0, w: stage_size.w, h: stage_size.h});
120       } // }}}
121 
122       /**
123        * Always returns null. The Scene always represents the root
124        * level of content within a Stage.
125        * @function
126        * @return null
127        */
128       this.getParent = function() { // {{{
129          return null;
130       } // }}}
131 
132       /**
133        * Gets the Stage this scene belongs to.
134        * @function
135        * @return Stage object this scene belongs to.
136        */
137       this.getStage = function() { // {{{
138          return stage;
139       } // }}} getStage
140 
141       /**
142        * Returns a reference to itself.
143        * @function
144        * @return A reference to this Scene.
145        */
146       this.getScene = function() { // {{{
147          return this;
148       } // }}}
149 
150       /**
151        * Loads this Scene in the given Stage. This function loops
152        * through the Scene content and calls load on each component, passing a
153        * reference to this Scene.
154        * @function
155        * @param Stage _stage The Stage this scene belongs to.
156        */
157       this.load = function(_stage) { // {{{
158          this.loadContent(_stage);
159       } // }}} load
160 
161       /**
162        * Loads this Scene's content in the given Stage. This function
163        * loops through the Scene content and calls load on each component,
164        * passing a reference to this Scene.
165        * @function
166        * @param Stage _stage The Stage this scene belongs to.
167        */
168       this.loadContent = function(_stage) { // {{{
169          stage = _stage;
170          stage[name] = this;
171          for(var index in content) {
172             var component = content[index];
173             component.load(this, this);
174          }
175       } // }}} load
176 
177       /**
178        * Scene's can't be moved. This method does nothing.
179        * @function
180        */
181       this.moveBy = function(_distance) { // {{{
182       } // }}}
183 
184       /**
185        * Scene's can't be moved. This method does nothing.
186        * @function
187        */
188       this.moveTo = function(_point) { // {{{
189       } // }}}
190 
191       /**
192        * Updates this Scene with the time since the Stage loaded.
193        * This function loops through the Scene content and calls the update
194        * method on each component.
195        * @function
196        * @param _runtime The time since the Stage was loaded.
197        */
198       this.update = function(_runtime) { // {{{
199          this.updateContent(_runtime);
200       } // }}} update
201 
202       /**
203        * Updates this Scene's content with the time since the Stage
204        * loaded. This function loops through the Scene content and calls the
205        * update method on each component.
206        * @function
207        * @param _runtime The time since the Stage was loaded.
208        */
209       this.updateContent = function(_runtime) { // {{{
210          for(var index in content) {
211             var component = content[index];
212             if(component.isActive()) {
213                component.update(_runtime);
214             }
215          }
216       } // }}} update
217 
218       // }}} Public Members
219 
220    } // }}} _Scene
221 
222    var theScene = new _Scene(_details);
223    return theScene;
224 } // }}} Scene
225 // These properties are for jEdit - Programmer's Text Editor.
226 // Load this file in jEdit to see what they do.
227 // ::folding=explicit:mode=javascript:noTabs=true:collapseFolds=4::
228