Class Documentation

Name:Animation
Version:1.0
ID:ID_ANIMATION
Status:Unspecified
Category:GUI
Date:April 2002
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2002. All rights reserved.
Short:  Creates animations within graphical areas.



Description

The Animation is a graphical class that demonstrates the power of splitting rendered graphics into animated frames. Unlike conventional animation techniques where the graphics may be pre-rendered or drawn using a paint package and saved as animated gif files, frame based animation is calculated in real-time. This technique uses a minimal amount of memory and gives you the ability to animate rendered graphics as well as images. For example, an individual line could be be animated to give the illusion of rotation, or a circle could expand and shrink with a simple set-up.

Here is a basic animation that switches between a rectangle and circle shape every second:

  <render center width="20%" height="20%" colour="#a0a0a0">
    <animation speed="1" framecount="2"/>
    <box width="10" height="10" border="#000000" center frame="1">
    <ellipse width="10" height="10" center frame="2" border="#000000">
  </render>

The two most important fields that you need to set are the Speed and FrameCount fields. The Speed field determines the amount of frames per second (FPS) to be used when drawing the animation. The FrameCount is a compulsory setting that determines the total amount of frames included in the animation. In most cases, this is all that you need to worry about.

Any objects that you use in the animation must be able to support frames. Most graphical objects support a Frame field as standard, but check the documentation to make sure. Objects that do not support frames or have not been given a frame setting will inevitably be drawn to the graphics container in all conditions - i.e. they will ignore the Animation object.

Structure

The Animation object consists of the following public fields:

Drawable  Refers to the drawable that the Animation is being applied to.
Frame  Reflects the current frame number.
FrameCount  The total number of frames being used in the animation.
Sequence  Detailed frame sequencing can be set in this field.
Speed  Sets the speed of the animation in frames per second.
Field:Drawable
Short:Refers to the drawable that the Animation is being applied to.
Type:OBJECTID
Status:Read/Write

In most cases, when you create a new Animation it should be contained by a drawable area, such as a Render object. If you do this correctly then the Animation will detect the drawable area and set this field to the drawable object. However, there may be occasions where you want to initialise a Animation object to a non-graphical owner. If this is the case then you must set the Drawable field to point to a valid drawable area, such as a Render object.


Field:Frame
Short:Reflects the current frame number.
Type:LONG
Status:Read/Write

The current frame number is always reflected in this field. It can sometimes be desirable to set this field on initialisation to force the starting frame number. The range of the Frame value is from 0 to one less than the value in the FrameCount field.


Field:FrameCount
Short:The total number of frames being used in the animation.
Type:LONG
Status:Read/Write

This field must be set to the total number of frames that you want to use in the animation. The minimum FrameCount that you can set is 1.


Field:Sequence
Short:Detailed frame sequencing can be set in this field.
Type:STRING
Status:Set

Normally an animation object will follow a simple frame sequence, starting from frame 1 and ending at the frame determined by the FrameCount field. You can change this default behaviour and create a


Field:Speed
Short:Sets the speed of the animation in frames per second.
Type:FLOAT
Status:Read/Write

The speed of the animation may be set with this field. The setting must be calculated in frames per second - so a value of 1 would change frames as every second passes. The maximum value is 100 frames per second, but it is recommended that 25 frames per second is specified for most purposes.