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.