Package algoanim.util

Using the classes in the animalscriptapi.util package

See:
Description

Class Summary

ArrayDisplayOptions	This is a workaround for the DisplayOptions associated with an array.
CodeGroupDisplayOptions	This is a workaround for the DisplayOptions associated with a code group.
Coordinates	A concrete type of a Node.
DisplayOptions	Abstract class for handling Hidden and Timing offset in the definition for a Primitive.
Hidden	A class to flag a Primitive as hidden.
MsTiming	A concrete kind of a Timing.
Node	This is an abstract representation of a coordinate within the animation screen.
Offset	This is a concrete kind of a Node.
OffsetFromLastPosition	This is a concrete kind of a Node.
TicksTiming	TicksTiming is a certain kind of a Timing with a numeric value measured in ticks.
Timing	An abstract representation of a Timing.

Package algoanim.util Description

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.

• The other element can be another graphical object - in this case, you have to pass this object as a parameter to the constructor call.
• It can also be an other node, such as the "fifth node of this polygon" - in this case, you have to pass a Node instance to the constructor call.
• Finally, it may also be an offset from a pre-assigned ID - in this case, you have to pass the String ID of this ID.

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:

• DIRECTION_NW
• DIRECTION_N
• DIRECTION_NE
• DIRECTION_W
• DIRECTION_C
• DIRECTION_E
• DIRECTION_SW
• DIRECTION_S
• DIRECTION_SE
• DIRECTION_BASELINE_START
• DIRECTION_BASELINE_END

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.