Using the classes in the animalscriptapi.util package

The classes in the animalscriptapi.util package are utility classes that help in creating animation content. They address three different aspects: definitions of nodes, display options, and timing.

Node Definition

Many operations in AnimalScript and thus also in the AnimalScript API expect the specification of (at least) one node. For example, each graphical object will have at least one node to specify its basic location, or to specify the first of multiple nodes that define the shape (e.g., a triangle has three nodes).

The AnimalScript API allows the following ways to define a node, based on the (empty) abstract class animalscriptapi.util.Node:

using absolute coordinates
Absolute coordinates specify the node as a pair of x and y positions. Use the classe animalscriptapi.util.Coordinates if you want to use absolute coordinates. This class expects you to pass in the int values for x and y, respectively. Of course, you can use arbitrarily complex arithmetic expressions to define the values x and y, but they will ultimately be evaluated to a fixed value when the constructor is called.Using an offset from another element
This more, represented by class animalscriptapi.util.Offset, allows you to place an object in relation to another element. In all cases, the constructor also expects the offset (dx, dy) values and the direction. Typically, you should use the following direction constants defined in class animalscriptapi.animalscript.AnimalScript: For all entries except for the last two, the offset will be determined based on the bounding box of the underlying reference element. The bounding box of an object is defined as the smallest rectangle that completely contains the object. The NW, NE, SW, SE values are thus the four corners of this bounding box; N, W, E, S are the centers of the box edges, and C is the center of the bounding box.
"Baseline" refers to the base line of a text. As text characters may extrude under their base line (e.g., for "g", "p" and "q"), the "SW" coordinate of the bounding box for a text may not have the same y coordinate as the text itself.

Display Option

Display options toggle the display of a given graphical object. They are not concerned with attributes such as color or depth of the object, but rather concerned with whether and how a given object will appear.

The base class for display options is the abstract class animalscriptapi.util.DisplayOptions. Its (empty) subclass animalscriptapi.util.Hidden should be used when a given primitive is supposed to be invisible (hidden from the viewer).

Code groups also have a special display options class, called animalscriptapi.util.CodeGroupDisplayOptions. In this class, the user can specify both the offset (how long after the start of a given step will it take before the code group starts to be displayed?) and the duration (how much time will the code group take from the offset until all elements are shown?).

Arrays also have thei own display options class: animalscriptapi.util.ArrayDisplayOptions. This class uses the offset and duration described above for code groups. Additionally, they have a boolean option isCascaded. If this option is set to true, the array will be shown element by element, instead of all elements at the same time.

Timing Specification

Timing is used in the AnimalScript API to specify when effects start and how long they take. They are based on the class animalscriptapi.util.Timing, another subclass of animalscriptapi.util.DisplayOptions described above. Currently, the AnimalScript API supports the following timing-related classes:

animalscriptapi.util.Timing
This class allows setting only one time value as an int. This method is inherited by subclasses. Please note that this class is abstract!
MsTiming
This class represents timing information measured on a millisecond (ms) base. Its constructor expects only the number of time units as an int value.
TicksTiming
This class represents timing information measured by the number of animation frames ("ticks"). Its constructor expects only the number of time units as an int value.