1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245

/*

  The contents of this file are subject to the Mozilla Public License Version
  1.1 (the "License"); you may not use this file except in compliance with
  the License. You may obtain a copy of the License at 
  
           http://www.mozilla.org/MPL/ 
  
  Software distributed under the License is distributed on an "AS IS" basis,
  WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  for the specific language governing rights and limitations under the License. 
  
  The Original Code is ASGard Framework.
  
  The Initial Developer of the Original Code is
  ALCARAZ Marc (aka eKameleon)  <ekameleon@gmail.com>.
  Portions created by the Initial Developer are Copyright (C) 2004-2009
  the Initial Developer. All Rights Reserved.
  
  Contributor(s) :
  
*/

package asgard.display 
{
    import system.data.OrderedIterator;
    import system.numeric.Mathematics;
    
    import flash.display.MovieClip;
    import flash.errors.IllegalOperationError;
    
    /**
     * This iterator control the timeline in a MovieClip target.
     * <p><b>Example :</b>With <b>container</b> a MovieClip reference added in the stage of the application, 
     * this MovieClip contains 10 frames</p>
     * <pre class="prettyprint">
     * import asgard.display.TimelineIterator ;
     * 
     * var it:TimelineIterator = new TimelineIterator( container , 2 ) ;
     * 
     * trace( "timeline current frame : " + it.currentFrame ) ;
     * trace( "timeline total frames  : " + it.totalFrames ) ;
     * 
     * var keyDown:Function = function( e:KeyboardEvent ):void
     * {
     *     var code:uint = e.keyCode ;
     *     switch(code)
     *     {
     *         case Keyboard.LEFT :
     *         {
     *             if ( it.hasPrevious() )
     *             {
     *                 it.previous() ;
     *             }
     *             else
     *             {
     *                 it.last() ;
     *             }
     *             break ;
     *         }
     *         case Keyboard.RIGHT :
     *         {
     *             if ( it.hasNext() )
     *             {
     *                 it.next() ;
     *             }
     *             else
     *             {
     *                 it.reset() ;
     *             }
     *             break ;
     *         }
     *     }
     *     trace( "timeline : " + it.currentFrame + " | " + it.totalFrames + " | frame label : " + it.currentLabel ) ;
     * }
     * 
     * stage.addEventListener( KeyboardEvent.KEY_DOWN , keyDown ) ;
     * </pre>
     */
    public class TimelineIterator implements OrderedIterator  
    {
        /**
         * Creates a new TimelineIterator instance.
         * @param target The MovieClip reference of this iterator.
         * @param framePosition the default framePosition of the specified MovieClip target (default frame 1).
         * @param stepSize (optional) the step between two frames returns by the iterator (default 1).
         * @throws ArgumentError if the <code class="prettyprint">target</code> argument of this constructor is empty.
         */
        public function TimelineIterator( target:MovieClip , framePosition:Number=NaN, stepSize:uint=1 )
        {
            if (target == null)
            {
                throw new ArgumentError( this + " can't be instanciate with an empty MovieClip reference in the first argument of the constructor.") ;    
            }
            this._target = target ;
            this._step = (DEFAULT_STEP > 1) ? stepSize : DEFAULT_STEP ; 
            if ( !isNaN(framePosition) )
            {
                this.seek(framePosition) ;    
            }
        }
        
        /**
         * The default step value in all the PageByPageIterators.
         */
        public static const DEFAULT_STEP:Number = 1 ;

        /**
         * The current label in which the playhead is located in the timeline of the MovieClip instance.
         */
        public function get currentLabel():String
        {
            return _target.currentLabel ;    
        }

        /**
         * The current frame of the iterator.
         */
        public function get currentFrame():int
        {
            return _target.currentFrame ;    
        }

        /**
         * Returns the target reference of this iterator.
         */
        public function get target():MovieClip
        {
            return _target ;    
        }

        /**
         * The current frame of the iterator.
         */
        public function get totalFrames():Number
        {
            return _target.totalFrames ;    
        }
    
        /**
         * Returns the step size of this PageByPageIterator.
         * @return the step size of this PageByPageIterator.
          */
        public function getStepSize():Number
        {
            return _step ;    
        }

        /**
         * Checks to see if there is a previous element that can be iterated to.
         * @return <code class="prettyprint">true</code> if the iterator has more elements.
         */
        public function hasPrevious() : Boolean 
        {
            return _target.currentFrame > 1 ;
        }
        
        /**
         * Returns <code class="prettyprint">true</code> if the iteration has more elements.
         * @return <code class="prettyprint">true</code> if the iterator has more elements.
         */
        public function hasNext() : Boolean 
        {
            return _target.currentFrame < _target.totalFrames ;
        }

        /**
         * Returns the current page number.
         * @return the current page number.
         */
        public function key():*
        {
            return _target.currentFrame ;
        }
        
        /**
         * Seek the key pointer of the iterator over the last frame of the timeline.
         */
        public function last():void 
        {
            _target.gotoAndStop(_target.totalFrames) ;
        }
        
        /**
         * Returns the next Array page of elements or the next element in the Array if the getStepSize() value is 1.
         * @return the next Array page of elements or the next element in the Array if the getStepSize() value is 1.
         */
        public function next():* 
        {
            var k:uint = _target.currentFrame ;
            k += _step ;
            k = (k < _target.totalFrames) ? k : _target.totalFrames ;
            _target.gotoAndStop(k) ;
            return k ;
        }
        
        /**
          * Returns the previous Array page of elements or the previous element in the Array if the getStepSize() value is 1.
         * @return the previous element from the collection.
         */
        public function previous():*
        {
            var k:uint = _target.currentFrame ;
            k -= _step ;
            k = (k > 1) ? k : 1 ;
            _target.gotoAndStop(k) ;
            return k ;
        }
        
        /**
         * Unsupported operation in this iterator.
         * @throws flash.errors.IllegalOperationError the method remove() in this iterator is unsupported. 
         */
        public function remove():*
        {
            throw new IllegalOperationError( this + " remove method is unsupported by this instance.") ;
        }

        /**
         * Resets the key pointer of the iterator.
         */
        public function reset():void 
        {
            _target.gotoAndStop(1) ;
        }

        /**
         * Seek the key pointer of the iterator.
         */
        public function seek( position:* ):void 
        {
            _target.gotoAndStop(Mathematics.clamp( position, 1, _target.totalFrames )) ;
        }
        
        /**
         * @private
         */
        private var _step:uint ;
        
        /**
         * @private
         */
        private var _target:MovieClip ;
    }
}