(Programming Guide) Animation, Signals, Actions, documentation

Change-Id: Ia8f44bfe6b854f7e8f001b64337506b64f8eaba9

diff --git a/docs/content/images/example-documentation/example-code.png b/docs/content/images/example-documentation/example-code.png
deleted file mode 100644 (file)
index 7d9cab6..0000000
Binary files a/docs/content/images/example-documentation/example-code.png and /dev/null differ

diff --git a/docs/content/main.md b/docs/content/main.md
index 96b8507..d2dd55a 100644 (file)
--- a/docs/content/main.md
+++ b/docs/content/main.md
@@ -11,14 +11,14 @@
   + [Coordinate System](@ref coordinate-system)
   + [Scene Graph](@ref scene-graph)
   + [Handle / Body Idiom](@ref handle-body-idiom)
   + [Coordinate System](@ref coordinate-system)
   + [Scene Graph](@ref scene-graph)
   + [Handle / Body Idiom](@ref handle-body-idiom)

-  + Signals
+  + [Signals](@ref signals)

   + [Properties](@ref properties)
   + [Properties](@ref properties)

-  + Actions
+  + [Actions](@ref actions)

  + Tutorial
   + [Hello World](@ref hello-world)
 
 ### Getting Started
  + Tutorial
   + [Hello World](@ref hello-world)
 
 ### Getting Started

- + How to build DALi on Ubuntu Desktop
+ + [How to build DALi on Ubuntu Desktop](@ref build-ubuntu)

 
 ### Programming Guide
  + [Programming Languages:](@ref programming-languages)
 
 ### Programming Guide
  + [Programming Languages:](@ref programming-languages)


@@ -31,10 +31,9 @@
   + [Event Handling](@ref event-system)
   + [Layouting](@ref size-negotiation)
   + [Image Actor](@ref image-actor)
   + [Event Handling](@ref event-system)
   + [Layouting](@ref size-negotiation)
   + [Image Actor](@ref image-actor)

- + Animation
-  + AnimateTo
-  + AnimateBy
-  + Key Frame Animations
+ + [Animation](@ref animation)
+  + [Basic Framework](@ref animation-basics)
+  + [Key Frame Animations](@ref animation-key-frame)

   + Path Animations
   + [Constraints](@ref constraints)
    + Equal To Constraint
   + Path Animations
   + [Constraints](@ref constraints)
    + Equal To Constraint


@@ -43,8 +42,6 @@
    + Path Constrainer
   + [Multi-threading Notes](@ref animation-multi-threading-notes)
   + [Shader Animation](@ref animation-shader)
    + Path Constrainer
   + [Multi-threading Notes](@ref animation-multi-threading-notes)
   + [Shader Animation](@ref animation-shader)

-  + [Example and Usage](@ref animation-example)
-  + [Rotation with quaternions](@ref animation-rotation)

 
 ### Resources
  + Resource Image
 
 ### Resources
  + Resource Image

diff --git a/docs/content/programming-guide/animation-example.h b/docs/content/programming-guide/animation-example.h
deleted file mode 100644 (file)
index 347fc5e..0000000
--- a/docs/content/programming-guide/animation-example.h
+++ /dev/null
@@ -1,63 +0,0 @@
-/*! \page animation-example Example and Usage
-
-   We will start by showing the steps for animating an actors position and opacity so the actor moves whilst the opacity changes.
-
-   Next more interesting animations methods (effects) with individual timing will be explained.
-
-   \section simple-anim Simple Animation moving an actor whilst altering opacity.
-
-   We declare an animation called myAnimation
-
-   @code
-   Dali::Animation myAnimation
-   @endcode
-
-   A new animation instance is created with a specified duration.  Here the duration of the animation will be 0.5 seconds.
-   Some other settings are incorporated by default and will be explained later.
-   @code
-   myAnimation = Animation::New(0.5f);
-   @endcode
-
-   Here we add the animators, these are the building blocks (functions) of the animation and define what we want to see
-   @code
-   myAnimation.AnimateTo(Property(actor, Actor::Property::OPACITY), 1.0f);
-   myAnimation.AnimateTo(Property(actor, Actor::Property::POSITION), Vector3(x, y, z));
-   @endcode
-
-   start animation, when this is called we want the animation to start playing so here the actor will move whilst the opacity changes.
-   @code
-   myAnimation.Play();
-   @endcode
-   \section advanced-anims Adding more advanced animators, if simply moving the actor is not enough we have further animations methods.
-
-   AnimateBy and AnimateTo, method names are appended by 'By' or 'To' either animate to a supplied value or animate by a supplied value.  For example an actor at (10,10,10) calling AnimateBy(Property(actor, Actor::Property::POSITION), 50,0,0) would mean its location is (60,0,0) whilst AnimateTo(Property(actor, Actor::Property::POSITION), 50,0,0) would result in a location (50,0,0).
-
-   Dali::AlphaFunction can be used to give interesting effects to the animation, for example the MOVEment of an actor on screen can speed up and slow down following a sine curve by using the Dali::AlphaFunction::EASE_IN_OUT_SINE instead of AlphaFunction::LINEAR
-
-   @code
-   myAnimation.AnimateTo(Property(actor, Actor::Property::POSITION), Vector3(x, y, z), AlphaFunction::LINEAR, delay, ANIMATOR_DURATION);
-   myAnimation.AnimateTo(Property(actor, Actor::Property::SIZE), actorSize, AlphaFunction::EASE_IN, delay, ANIMATOR_DURATION);
-   @endcode
-   \section playback-control Controlling a playing animation
-
-   The 3 controls we have are start, pause and stop
-   @code
-   Dali::Animation::Play();
-   Dali::Animation::Stop();
-   Dali::Animation::Pause();
-   @endcode
-
-   \section default-settings Default settings
-   The call Dali::Animation::New provides some default settings but each has a setter function if the defaults are not suitable. (Getters also exist)
-   @code
-   Dali::Animation::SetEndAction
-   Dali::Animation::SetLooping
-   Dali::Animation::SetDefaultAlphaFunction
-   @endcode
-
-   \section end-signal End Signal
-   The following signal can be connected to if it is required to know when an animation is complete.
-   /code Dali::Animation::SignalFinish(); /endcode
-
- */
-

diff --git a/docs/content/programming-guide/animation-rotation.h b/docs/content/programming-guide/animation-rotation.h
deleted file mode 100644 (file)
index 0bd51a0..0000000
--- a/docs/content/programming-guide/animation-rotation.h
+++ /dev/null
@@ -1,29 +0,0 @@
-/*! \page animation-rotation Rotation with quaternions
- *
- * \ref Dali::Quaternion "Quaternions" are used to specify unique orientations on actors. They are also
- * very useful for calculating smooth transitions between orientations.
- *
- * The Dali::Actor class provides the ability to set the orientation
- * by both angle+axis and quaternion. It also allows you to rotate the
- * actor around another quaternion.
- *
- * @code
- * Dali::Actor actor;
- * actor.SetOrientation(Quaternion(Radian(Degree(45.0f)).value, Vector3::XAXIS)),
- *
- * Quaternion q(Radian(Degree(30.0f)).value, Vector3(1.0f, 1.0f, 0.0f));
- * actor.RotateBy(q);
- * @endcode
- *
- * The Dali::Animation class provides several AnimateTo methods that
- * use \ref Dali::Quaternion "Quaternions" directly to change the orientation.
- *
- * @code
- * mAnimation = Animation::New(5.0f); // 5 seconds
- * Quaternion q(Radian(Degree(45.0f)).value, Vector3::YAXIS);
- * Quaternion r(Radian(Degree(30.0f)).value, Vector3::ZAXIS);
- * q *= r;
- * mAnimation.AnimateTo(Property(mActor, Actor::Property::ORIENTATION), q, AlphaFunction::EASE_IN_OUT);
- * mAnimation.Play();
- * @endcode
- */

diff --git a/docs/content/shared-javascript-and-cpp-documentation/animation.md b/docs/content/shared-javascript-and-cpp-documentation/animation.md
new file mode 100644 (file)
index 0000000..fcca831
--- /dev/null
+++ b/docs/content/shared-javascript-and-cpp-documentation/animation.md
@@ -0,0 +1,83 @@
+<!--
+/**-->
+
+# Animation {#animation}
+
+DALi provides a rich and easy to use animation framework which allows the creation of visually rich applications.
+Dali::Animation can be used to animate the properties of any number of objects, typically Actors.
+
+## Creating a basic Animation {#animation-basics}
+
+Create an animation object that will take place over 3 seconds:
+~~~{.cpp}
+Dali::Animation animation = Animation::New( 3.0f );
+~~~
+
+### Animating Properties
+
+There are two distint ways in which properties can be animated within DALi:
+- **AnimateTo:** The property will animate **TO** the value in the given time.
+- **AnimateBy:** The property will animate **BY** the value in the given time.
+
+(Assume actor1 & actor2 are at position 10.0f, 10.0f, 0.0f at the start of the animation)
+~~~{.cpp}
+// Animate the position of actor1 TO 10.0f, 50.0f, 0.0f
+animation.AnimateTo( Property( actor1, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f) ); // End Position: 10.0f, 50.0f, 0.0f
+
+// Animate the position of actor2 BY 10.0f, 50.0f, 0.0f
+animation.AnimateBy( Property( actor2, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f) ); // End Position: 20.0f, 60.0f, 0.0f
+~~~
+
+### Playback Control
+
+When an animation is created, it can be played:
+~~~{.cpp}
+animation.Play();
+~~~
+
+Stop and Pause are also supported.
+~~~{.cpp}
+animation.Stop();
+animation.Pause();
+~~~
+
+### Notifications
+
+Using DALi's signal framework, applications can be notified when the animation finishes:
+
+~~~{.cpp}
+
+void ExampleCallback( Animation& source )
+{
+  std::cout << "Animation has finished" << std::endl;
+}
+...
+animation.FinishedSignal().Connect( ExampleCallback );
+~~~
+
+### Alpha Functions
+
+Alpha functions are used in animations to specify the rate of change of the animation parameter over time.
+The built in supported functions can be viewed in Dali::AlphaFunction::BuiltinFunction.
+
+It is possible to specify a different alpha function for each animator in an Animation object:
+~~~{.cpp}
+animation.AnimateTo( Property( actor1, Dali::Actor::Property::POSITION ), Vector3(10.0f, 50.0f, 0.0f), Dali::AlphaFunction::EASE_IN );
+~~~
+
+### Other Actions
+
+An animation can be looped:
+~~~{.cpp}
+animation.SetLooping( true );
+~~~
+
+By default, when an animation ends, the properties that it was animating are BAKED.
+However, the property changes can be **discarded** when the animation ends (or is stopped):
+~~~{.cpp}
+animation.SetEndAction( Animation::Discard );
+~~~
+
+## Key-Frame Animation {#animation-key-frame}
+
+TODO
\ No newline at end of file

diff --git a/docs/content/shared-javascript-and-cpp-documentation/build-guide.md b/docs/content/shared-javascript-and-cpp-documentation/build-guide.md
new file mode 100644 (file)
index 0000000..d6cd7e1
--- /dev/null
+++ b/docs/content/shared-javascript-and-cpp-documentation/build-guide.md
@@ -0,0 +1,80 @@
+<!--
+/**-->
+# Build Guide {#build-guide}
+
+## Ubuntu {#build-ubuntu}
+
+These instructions explain how to build the DALi library for the Ubuntu 14.04 desktop environment.
+
+### Minimum Requirements
+
++ Ubuntu 14.04
++ Ensure ALL sources are selected:
+ + Go to Ubuntu Settings and then to "Software & Updates".
+ + In the "Ubuntu Software" tab, ensure ALL software sources are ticked. (This is required because we install some community-maintained free & open-source software).
+
+### Creating a DALi environment
+
+DALi provides a script to set up your desktop environment. This script can be found in the dali-core repository.
+
++ Fetch ALL 4 repositories from tizen.org.
++ In the parent directory of these repositories, run the following command:
+  ~~~{.sh}
+  dali-core/build/scripts/dali_env -c
+  ~~~
+  This will also download any dependencies that the dali repositories require.
+
++ You can save the environment variables to a file:
+  ~~~{.sh}
+  dali-env/opt/bin/dali_env -s > setenv
+  ~~~
+
+The last few steps only need to be done once.
+
+You will have to source your environment variables every time you open up a new terminal (or you can add to .bashrc if you prefer).
+You can do this by sourcing the '''setenv''' script you created above:
+~~~{.sh}
+. setenv
+~~~
+
+### Building the repositories
+
+#### dali-core
+~~~{.sh}
+cd dali-core/build/tizen
+autoreconf --install
+./configure --prefix=$DESKTOP_PREFIX
+make install -j8
+~~~
+
+#### dali-adaptor
+~~~{.sh}
+cd dali-adaptor/build/tizen
+autoreconf --install
+./configure --prefix=$DESKTOP_PREFIX --enable-profile=UBUNTU --enable-gles=20
+make install -j8
+~~~
+
+#### dali-toolkit
+~~~{.sh}
+cd dali-toolkit/build/tizen
+autoreconf --install
+./configure --prefix=$DESKTOP_PREFIX
+make install -j8
+~~~
+
+#### dali-demo
+~~~{.sh}
+cd dali-demo/build/tizen
+cmake -DCMAKE_INSTALL_PREFIX=$DESKTOP_PREFIX .
+make install -j8
+~~~
+
+### Running dali-demo
+
+Ensure you have sourced your environment as mentioned above and then just run:
+~~~{.sh}
+dali-demo
+~~~
+
+*/

diff --git a/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md b/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md
index 42c4d25..af3b3e7 100644 (file)
--- a/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md
+++ b/docs/content/shared-javascript-and-cpp-documentation/documentation-guide.md
@@ -29,10 +29,26 @@ The space between the brackets is the alternative text. This means you will neve
 ~~~
   
 ## Example
 ~~~
   
 ## Example

-![ ](../assets/img/example-documentation/example-code.png)
-![ ](example-code.png)

 
 

+Please have a look at the numerous markdown files to see the header and footer requirements.

 
 

+You can add tags to your headings as follows:
+~~~{.md}
+# MyChapter {#my-chapter}
+~~~
+Which will allow you to link to this section as follows:
+~~~{.md}
+[Go To MyChapter](@ref my-chapter)
+~~~
+
+Code blocks can be enclosed within 2 blocks of 3 tildas(~).
+
+You can even specify your language type, for example:
+~~~{.md}
+~~~{.cpp}
+...
+~~~{.js}
+~~~

 
 #### Why use GitHub flavoured markdown?
  - Table support is good and language specific code blocks are easier to define ( javascript/C++).
 
 #### Why use GitHub flavoured markdown?
  - Table support is good and language specific code blocks are easier to define ( javascript/C++).

diff --git a/docs/content/shared-javascript-and-cpp-documentation/signals-actions.md b/docs/content/shared-javascript-and-cpp-documentation/signals-actions.md
new file mode 100644 (file)
index 0000000..89a4130
--- /dev/null
+++ b/docs/content/shared-javascript-and-cpp-documentation/signals-actions.md
@@ -0,0 +1,21 @@
+<!--
+/**-->
+# Signals & Actions {#signals-actions}
+
+## Signals {#signals}
+
+Classes in DALi provide signals which are emitted whenever a certain action or event occurs.
+The application can connect to these signals using if it wishes to be informed of this occurrence.
+Standard C Style functions can be used to connect to these signals if no local data needs to be accessed, otherwise a class method can also be connected.
+
+Applications can manually disconnect from signals when required but DALi also provides safe signal disconnection.
+This means that when the connecting object is deleted, the signal is automatically disconnected.
+
+## Actions {#actions}
+
+Classes in DALi can perform a certain number of actions.
+For example, an animation provides the ability to "play" or "stop" using an action.
+DALi provides a framework which allows users to set up actions for their classes.
+This is particularly helpful when trying to invoke an action using scripting.
+
+*/