Merge pull request #175 from easycoder/dev

Add documentation for 'animate'

Author: easycoder

iwsy/resources/help/action-animate.md

@@ -0,0 +1,35 @@
+~page:contents:Contents~
+
+# The `animate` action
+
+This action a visual effect on the content of a bock. At present there is only pan/zoom, used to create the "Ken Burns" effect that makes still photos look a little like video.
+
+This action performs a visual effect on one or more blocks. Each of the blocks has content which contains a special Markdown extension that defines the visual effect to be applied. The format is
+
+~m:~vfx:100% manarola~~
+
+where ~m:manarola~ is the name of the effect in the ~m:VFX~ section of the script. You can have any number of animations in a single content block, though more than one is usually over-doing it.
+
+The parameters needed for the effect are as follows:
+
+~img:https://easycoder.github.io/iwsy/resources/help/img/animate.png|100%~
+
+Here the type is defined as a ~m:panzoom~ (it's currently the only option available). The name then follows. Next we have the aspect ratio of the container that holds the image being manipulated, the URL of that image and the duration of the effect in seconds.
+
+The effect works by magnifying the image and using the container as a "window" onto a part of the magnified image. By moving the window and altering the magnification we achieve the pan and zoom effect.
+
+There are 2 groups of 3 parameters, one for the start of the effect and the other for the end. Each of the sets of values are as follows:
+
+ 1. the size (magnification).
+ 1. the offset of the left-hand edge of the image from the left-hand edge of the container. Negative values cause the image to position to the left of the container, so in general the values will all be negative or zero.
+ 1. the offset of the top edge of the image from the top of the container. Negative values cause the top of the image to position above the container.
+
+In all cases the values are expressed as a percentage of the container width or height.
+
+The animation follows a cosine function that causes it to start slowly, accelerate towards the middle of the effect the deccelerate towards the end, giving a smooth start and finish.
+
+To use a sequence of images, each with its own Ken Burns specification, fade down the current item and fade up the next, in each case with the ~m:continue~ flag set to ~m:yes~, then follow these with the animation itself. With the right fade duration this will give you a smooth transition during the period the animation is moving at its slowest. You may also have to ensure the images are preloaded (cached) to avoid stuttering as a new animation starts.
+
+You can see an example running on the ~page:iwsy:Home~ page of this documentation.
+
+Next: ~page:action-pause:Pause~

iwsy/resources/help/action-transition.md

@@ -29,4 +29,4 @@ When the color of text is to be changed, the size values in both **Block** and *
 
 Fades and other animated effects run at 25 frames/sec, as a compromise between visual smoothness and processing requirements.
 
-Next: ~page:action-pause:Pause~
+Next: ~page:action-animate:Animate~

iwsy/resources/help/contents.md

@@ -30,6 +30,8 @@
 
 ~page:action-transition:The "transition" action~
 
+~page:action-animate:The "animate" action~
+
 ~page:action-pause:The "pause" action~
 
 ~page:action-chain:The "chain" action~

iwsy/resources/help/img/animate.png

@@ -5,7 +5,7 @@
 The right-hand side of the screen holds the Project panel. When you start up - or after you click the ~img:https://easycoder.github.io/iwsy/resources/icon/new.png|icon~(New) button - it looks like this:
 ~img:https://easycoder.github.io/iwsy/resources/help/img/project.png|100%~
 
-There are 3 main sections.
+There are 5 sections.
 
 ## 1 - Steps
 
@@ -28,3 +28,13 @@ It's common to use the same layout for multiple slides in a presentation, and on
 This lists all the content text items used in your presentation. Each one is named. In the step editor you assign content to blocks by clicking names from a drop-down list. This makes it much easier to see what is where than by having the full text visible at each point.
 
 All content text is written using **_MarkDown_**; a format that is mostly plain text, plus simple markup tags to define headers and other text features. ~iwsy~ provides a set of custom MarkDown extensions that define image and other attributes. These help pages are written using the same system. See ~page:addContent:Adding content~.
+
+## 4 - VFX
+
+VFX stands for "Visual Effects". At this time we only have one; a pan and zoom. With this you can implement the "Ken Burns Effect", named after its inventor, a New York based documentary film maker. The effect is widely used in television to bring movement to still photos, without which the eye rapidly gets bored. The amount of movement can be very slight but the eye is tricked into thinking it's looking at video. The effect is demonstrated on our ~page:iwsy:Home and Introduction~ page.
+
+This section is where you supply all the data needed to achieve the effect for a single image.
+
+## 5 - JSON
+
+In this section you have a listing of the entire script as a JSON file. You can view and edit any of the sections or copy/paste.

iwsy/resources/help/project.md

@@ -14,7 +14,7 @@ Click the **Blocks** button over in the right-hand panel, then click the ~img:ht
 
 ~img:https://easycoder.github.io/iwsy/resources/help/quickstart/newblock.png|100%~
 
-Most of these default values are fine as they are; they describe a block that occupies the whole window area. Let's just change the ~m:name~ property to ~m:background~ and the ~m:background~ property to ~m:url('https://easycoder.github.io/iwsy/resources/help/quickstart/SemoigoDawn.jpg')~. When the presentation runs, the effect will be to display a full-size image. This is what the panel should look like now:
+Most of these default values are fine as they are; they describe a block that occupies the whole window area. Let's just change the ~m:name~ property to ~m:background~ and the ~m:background~ property to ~m:url('https://easycoder.github.io/iwsy/resources/help/quickstart/SemoigoDawn.jpg')~. Be sure to use single-quotes as shown. When the presentation runs, the effect will be to display a full-size image. This is what the panel should look like now:
 
 ~img:https://easycoder.github.io/iwsy/resources/help/quickstart/first-block.png|100%~