WWW-www.enlightenment.org pushed a commit to branch master.

http://git.enlightenment.org/website/www-content.git/commit/?id=6c13e057e026183750564e321afc14f1e3ee3388

commit 6c13e057e026183750564e321afc14f1e3ee3388
Author: Lauro Moura <lauromo...@expertisesolutions.com.br>
Date:   Fri Dec 11 15:34:22 2015 -0800

    Wiki page animator changed with summary [] by Lauro Moura
---
 pages/api/javascript/ecore/animator.txt | 218 +++++++++++++++++++++-----------
 1 file changed, 146 insertions(+), 72 deletions(-)

diff --git a/pages/api/javascript/ecore/animator.txt 
b/pages/api/javascript/ecore/animator.txt
index f8cb93e..d6c0a2f 100644
--- a/pages/api/javascript/ecore/animator.txt
+++ b/pages/api/javascript/ecore/animator.txt
@@ -2,202 +2,276 @@
 
 [[api:javascript:ecore|Back to the JS Ecore page]]
 
-WORKINPROGRESS
+**DRAFT***
+
+Ecore animators are a helper to simplify creating animations.
+
+Creating an animation is as simple as saying for how long it should be run and 
having a callback that does the animation, something like this:
+
+<code javascript>
+var my_evas_object = ...
+function _do_animation(pos)
+{
+   ... move evas object ...
+   ... do some more animating ...
+}
+....
+efl.Ecore.Animator.addTimeline(2, _do_animation);
+</code>
+
+In the sample above we create an animation to move my_evas_object in 2 seconds.
+
+If your animation will run for an unspecified amount of time you can use 
''efl.Ecore.Animator.add()'', which is like using ''efl.Ecore.Timer.add()'' 
with the interval being the framerate. Note that this has tangible benefits to 
creating a timer for each animation in terms of performance.
 
 ==== Constants ====
 
 === Position mapping ===
 
-   * ''efl.Ecore.Animator.POS_MAP_ACCELERATE''
-   * ''efl.Ecore.Animator.POS_MAP_ACCELERATE_FACTOR''
-   * ''efl.Ecore.Animator.POS_MAP_BOUNCE''
-   * ''efl.Ecore.Animator.POS_MAP_CUBIC_BEZIER''
-   * ''efl.Ecore.Animator.POS_MAP_DECELERATE''
-   * ''efl.Ecore.Animator.POS_MAP_DECELERATE_FACTOR''
-   * ''efl.Ecore.Animator.POS_MAP_DIVISOR_INTERP''
-   * ''efl.Ecore.Animator.POS_MAP_LINEAR''
-   * ''efl.Ecore.Animator.POS_MAP_SINUSOIDAL''
-   * ''efl.Ecore.Animator.POS_MAP_SINUSOIDAL_FACTOR''
-   * ''efl.Ecore.Animator.POS_MAP_SPRING''
+These constants define the mapping of position to the time for the animation.
+
+   * ''efl.Ecore.Animator.POS_MAP_ACCELERATE'' - Start slow then speed up.
+   * ''efl.Ecore.Animator.POS_MAP_ACCELERATE_FACTOR'' - Start slow then speed 
up, v1 being a power factor, 0.0 being linear, 1.0 being normal accelerate, 2.0 
being much more pronounced accelerate (squared), 3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.POS_MAP_BOUNCE'' - Start at 0.0 then "drop" like a 
ball bouncing to the ground at 1.0, and bounce v2 times, with decay factor of 
v1.
+   * ''efl.Ecore.Animator.POS_MAP_CUBIC_BEZIER'' - Follow the cubic-bezier 
curve calculated with the control points (x1, y1), (x2, y2)
+   * ''efl.Ecore.Animator.POS_MAP_DECELERATE'' - Start fast then slow down.
+   * ''efl.Ecore.Animator.POS_MAP_DECELERATE_FACTOR'' - Start fast then slow 
down, v1 being a power factor, 0.0 being linear, 1.0 being normal decelerate, 
2.0 being much more pronounced decelerate (squared), 3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.POS_MAP_DIVISOR_INTERP'' - Start at gradient * v1, 
interpolated via power of v2 curve.
+   * ''efl.Ecore.Animator.POS_MAP_LINEAR'' - Linear 0.0 -> 1.0.
+   * ''efl.Ecore.Animator.POS_MAP_SINUSOIDAL'' - Start slow, speed up then 
slow down at end.
+   * ''efl.Ecore.Animator.POS_MAP_SINUSOIDAL_FACTOR'' - Start slow, speed up 
then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 being 
normal sinusoidal, 2.0 being much more pronounced sinusoidal (squared), 3.0 
being cubed, etc.
+   * ''efl.Ecore.Animator.POS_MAP_SPRING'' - Start at 0.0 then "wobble" like a 
spring rest position 1.0, and wobble v2 times, with decay factor of v1.
 
 === Sources ===
 
-   * ''efl.Ecore.Animator.SOURCE_CUSTOM''
-   * ''efl.Ecore.Animator.SOURCE_TIMER''
+Defines the timing sources for animators.
+
+   * ''efl.Ecore.Animator.SOURCE_CUSTOM'' - The default system clock/timer 
based animator that ticks every "frametime" seconds.
+   * ''efl.Ecore.Animator.SOURCE_TIMER'' - A custom animator trigger that you 
need to call ''efl.Ecore.Animator.customTick()'' to make it tick.
 
 ==== Functions ====
 
-=== add() ===
+=== add(callback) ===
 
 Syntax
 
 <code javascript>
+function mycallback() { ... };
+var animator = efl.Ecore.Animator.add(mycallback);
 </code>
 
 Parameters
 
-   * 
+   * callback - The function to call when it ticks off.
 
 Return value
 
-   * 
+   * object - A handle to the new animator object.
+
+This function adds an animator and returns its handle on success and NULL on 
failure. The function func will be called every N seconds where N is the 
frametime interval set by ''efl.Ecore.Animator.setFrametime()''.
+
+When the animator func is called, it must return a boolean value. If it 
returns ''true'' (or ''efl.Ecore.Mainloop.CALLBACK_RENEW''), it will be called 
again at the next tick, or if it returns ''false'' (or 
''efl.Ecore.Mainloop.CALLBACK_CANCEL'') it will be deleted automatically making 
any references/handles for it invalid.
 
-=== addTimeline() ===
+=== addTimeline(runtime, callback) ===
 
 Syntax
 
 <code javascript>
-    code
+var mycallback(pos) { ... };
+var handle = efl.Ecore.Animator.addTimeline(runtime, callback)
 </code>
 
 Parameters
 
-   * parameters
+   * runtime - The time to run in seconds.
+   * callback - The callback to be called when it ticks off.
 
 Return value
 
-   * return
+   * object - A handle to the new animator.
 
-=== customTick(args) ===
+This function is just like ''efl.Ecore.Animator.add()'' except the animator 
only runs for a limited time specified in seconds by runtime. Once the runtime 
the animator has elapsed (animator finished) it will automatically be deleted. 
The callback function func can return ''efl.Ecore.Mainloop.CALLBACK_RENEW'' to 
keep the animator running or ''efl.Ecore.Mainloop.CALLBACK_CANCEL'' to stop it 
and have it be deleted automatically at any time.
+
+The func will ALSO be passed a position parameter that will be in value from 
0.0 to 1.0 to indicate where along the timeline (0.0 start, 1.0 end) the 
animator run is at. If the callback wishes not to have a linear transition it 
can "map" this value to one of several curves and mappings via 
''efl.Ecore.Animator.posMap()''.
+
+<note important>
+The default frametime value is 1/30th of a second.
+</note>
+
+=== customTick() ===
 
 Syntax
 
 <code javascript>
-    code
+efl.Ecore.Animator.customTick()
 </code>
 
-Parameters
+When animator source is set to ''efl.Ecore.Animator.SOURCE_CUSTOM'', then 
calling this function triggers a run of all animators currently registered with 
Ecore as this indicates a "frame tick" happened. This will do nothing if the 
animator source(set by ''efl.Ecore.Animator.setSource()'') is not set to 
''efl.Ecore.Animator.SOURCE_CUSTOM''.
+
+=== getFrametime() ===
 
-   * parameters
+Syntax
+
+<code javascript>
+var frametime = efl.Ecore.Animator.getFrametime()
+</code>
 
 Return value
 
-   * return
+   * number - The time in second in between animator ticks.
+
+This function retrieves the time in seconds between animator ticks.
 
-=== getFrametime(args) ===
+=== getSource() ===
 
 Syntax
 
 <code javascript>
-    code
+var sourceType = efl.Ecore.Animator.getSource()
 </code>
 
-Parameters
-
-   * parameters
-
 Return value
 
-   * return
+   * one of ''efl.Ecore.Animator.SOURCE_*'' constants - The current animator 
source.
 
-=== getSource(args) ===
+This gets the current animator source.
+
+=== posMap(pos, map, v1, v2) ===
 
 Syntax
 
 <code javascript>
-    code
+var mapped = efl.Ecore.Animator.posMap(pos, map, v1, v2);
 </code>
 
 Parameters
 
-   * parameters
+   * pos - The input position to map.
+   * map - The mapping to use. One of the ''efl.Ecore.Animator.POS_MAP_*'' 
values.
+   * v1 - A parameter use by the mapping (pass 0.0 if not used).
+   * v2 - A parameter use by the mapping (pass 0.0 if not used).
 
 Return value
 
-   * return
+   * number - The mapped value
+
+Takes an input position (0.0 to 1.0) and maps to a new position (normally 
between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it has 
"overshot" the mark) using some interpolation (mapping) algorithm.
+
+This function useful to create non-linear animations. It offers a variety of 
possible animation curves to be used:
 
-=== posMap(args) ===
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_LINEAR'' - Linear, returns pos
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_ACCELERATE'' - Start slow then speed up
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DECELERATE'' - Start fast then slow 
down
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SINUSOIDAL'' - Start slow, speed up 
then slow down at end
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_ACCELERATE_FACTOR'' - Start slow then 
speed up, v1 being a power factor, 0.0 being linear, 1.0 being 
ECORE_POS_MAP_ACCELERATE, 2.0 being much more pronounced accelerate (squared), 
3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DECELERATE_FACTOR'' - Start fast then 
slow down, v1 being a power factor, 0.0 being linear, 1.0 being 
ECORE_POS_MAP_DECELERATE, 2.0 being much more pronounced decelerate (squared), 
3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SINUSOIDAL_FACTOR'' - Start slow, 
speed up then slow down at end, v1 being a power factor, 0.0 being linear, 1.0 
being ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal 
(squared), 3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DIVISOR_INTERP'' - Start at gradient * 
v1, interpolated via power of v2 curve
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_BOUNCE'' - Start at 0.0 then "drop" 
like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay 
factor of v1
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SPRING'' - Start at 0.0 then "wobble" 
like a spring rest position 1.0, and wobble v2 times, with decay factor of v1
+
+=== posMapN(pos, map, v) ===
 
 Syntax
 
 <code javascript>
-    code
+var mapped = efl.Ecore.Animator.pos_map_n(pos, map, v)
 </code>
 
 Parameters
 
-   * parameters
+   * pos - The input position to map.
+   * map - The mapping to use.
+   * v - An array with the double parameters to be used by the mapping. null 
if not used.
 
 Return value
 
-   * return
+   * number - The mapped value
+
+Takes an input position (0.0 to 1.0) and maps to a new position (normally 
between 0.0 and 1.0, but it may go above/below 0.0 or 1.0 to show that it has 
"overshot" the mark) using some interpolation (mapping) algorithm.
+
+This function useful to create non-linear animations. It offers a variety of 
possible animation curves to be used:
 
-=== posMapN(args) ===
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_LINEAR'' - Linear, returns pos
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_ACCELERATE'' - Start slow then speed up
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DECELERATE'' - Start fast then slow 
down
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SINUSOIDAL'' - Start slow, speed up 
then slow down at end
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_ACCELERATE_FACTOR'' - Start slow then 
speed up, v[0] being a power factor, 0.0 being linear, 1.0 being 
ECORE_POS_MAP_ACCELERATE, 2.0 being much more pronounced accelerate (squared), 
3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DECELERATE_FACTOR'' - Start fast then 
slow down, v[0] being a power factor, 0.0 being linear, 1.0 being 
ECORE_POS_MAP_DECELERATE, 2.0 being much more pronounced decelerate (squared), 
3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SINUSOIDAL_FACTOR'' - Start slow, 
speed up then slow down at end, v[0] being a power factor, 0.0 being linear, 
1.0 being ECORE_POS_MAP_SINUSOIDAL, 2.0 being much more pronounced sinusoidal 
(squared), 3.0 being cubed, etc.
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_DIVISOR_INTERP'' - Start at gradient * 
v[0], interpolated via power of v2 curve
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_BOUNCE'' - Start at 0.0 then "drop" 
like a ball bouncing to the ground at 1.0, and bounce v2 times, with decay 
factor of v[0]
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_SPRING'' - Start at 0.0 then "wobble" 
like a spring rest position 1.0, and wobble v2 times, with decay factor of v[0]
+   * ''efl.Ecore.Animator.ECORE_POS_MAP_CUBIC_BEZIER'' - Use an interpolated 
cubic-bezier curve ajusted with parameters from v[0] to v[3].
+
+=== setCustomSourceTickBeginCallback(callback) ===
 
 Syntax
 
 <code javascript>
-    code
+function mycallback() {...};
+efl.Ecore.Animator.setCustomSourceTickBeginCallback(callback)
 </code>
 
 Parameters
 
-   * parameters
+   * func - The function to call when ticking is to begin.
 
-Return value
+The Ecore Animator infrastructure handles tracking if animators are needed or 
not and which ones need to be called and when, but when the tick source is 
custom, you have to provide a tick source by calling 
''efl.Ecore.Animator.customTick()'' to indicate a frame tick happened. In order 
to allow the source of ticks to be dynamically enabled or disabled as needed, 
the func when set is called to enable the tick source to produce tick events 
that call ''efl.Ecore.Animator.customTick()''. If f [...]
 
-   * return
+<note warning>
+Do not use this function unless you know what you are doing.
+</note>
 
-=== setCustomSourceTickBeginCallback(args) ===
+=== setCustomSourceTickEndCallback(callback) ===
 
 Syntax
 
 <code javascript>
-    code
+function mycallback() {...};
+efl.Ecore.Animator.setCustomSourceTickEndCallback(callback)
 </code>
 
 Parameters
 
-   * parameters
+   * func - The function to call when ticking is to end.
 
-Return value
+This function is a matching pair to the function set by 
''efl.Ecore.Animator.setCustomSourceTickBeginCallback()'' and is called when 
ticking is to stop. If func is NULL then no function will be called to stop 
ticking. For more information please see 
''efl.Ecore.Animator.setCustomSourceTickBeginCallback()''.
 
-   * return
 
-=== setCustomSourceTickEndCallback(args) ===
+=== setFrametime(frametime) ===
 
 Syntax
 
 <code javascript>
-    code
+efl.Ecore.Animator.frametime_set( frametime)
 </code>
 
 Parameters
 
-   * parameters
-
-Return value
+   * frametime - The time in seconds in between animator ticks.
 
-   * return
-
-=== setFrametime(args) ===
+=== setSource(source) ===
 
 Syntax
 
 <code javascript>
-    code
+efl.Ecore.Animator.source_set(source)
 </code>
 
 Parameters
 
-   * parameters
+   * source - The source of animator ticks to use.
 
-Return value
+This sets the source of animator ticks. When an animator is active the 
mainloop will "tick" over frame by frame calling all animators that are 
registered until none are. The mainloop will tick at a given rate based on the 
animator source. The default source is the system clock timer source - 
''efl.Ecore.Animator.SOURCE_TIMER''. This source uses the system clock to tick 
over every N seconds (specified by ''efl.Ecore.Animator.setFrametime()'', with 
the default being 1/30th of a second unle [...]
 
-   * return
+==== Methods ====
 
-=== setSource(args) ===
+=== animator.del() ===
 
 Syntax
 
 <code javascript>
-    code
+animatorObj.del()
 </code>
 
-Parameters
-
-   * parameters
-
-Return value
-
-   * return
\ No newline at end of file
+Deletes an animator.
\ No newline at end of file

-- 


Reply via email to