A Guide to Writing simanim Animations
Contents
Introduction
This document is a guide to writing applet animations of simulations,
using the simanim extension to the simjava simulation
package. It deals only with the animation extensions, and does not tell
you how to write the simulations themselves. The guide also assumes some
knowledge about writing Java applets in general. For further information on
writing simulations see this companion
guide.
Animations written with the simanim extension have the
following features available:
- Entities and ports are represented by their own user-defined icons.
- Linked ports are joined together by a `wire'.
- Events sent between entities are animated travelling along the wires.
- Text string parameters can be shown next to entities to display
information about their internal state.
- The icon representing an entity can be changed during the simulation
to represent its internal state.
Have a look at an example to see
all these features in action, and to get a feel for how the applets work.
The Anim_applet class
Animations are written by extending the
Anim_applet
class in the simanim package. There are two methods which the
subclass needs to override:
anim_layout()
All the code needed to build the
simulation should be put in here, it effectively replaces the main()
method in stand-alone simulations, and is called before each simulation
run begins. Note, there is no need to call
Sim_system.initialise() at the start of this method, or
Sim_system.run() at the end, Anim_applet does this for you.
anim_init()
This method is called by
Anim_applet during its own initialisation. Any code to add GUI
objects to the applet for input should be put in here. Note that
you should not override Anim_applet's own init() method.
Anim_applet uses the border layout manager, the ``Center'' is used
for the main animation window so it gets as much space as is available, and
the ``South'' for some standard controls. The ``North'' is left empty for
the user's GUI components, which can be added
by a this.add("North", guiComponent); call from anim_init().
Should you need to display a change to the animation layout
before the simulation begins, for example if the number of entities changes,
you can do so by calling anim_relayout(), rather than calling
anim_layout() directly.
All the source files in your animation must import the two
packages eduni.simjava and eduni.simanim in order
to compile. Also, if you want your animations to be available over
the web, you will need to put a symbolic link from your animation's
directory to the "classes/eduni/" directory in the simjava
distribution. This is so the web server can find the two packages' class
files. On my system, I would do this using the command:
ln -s ./eduni /home/rmcn/summ96/simjava/classes/eduni
from the animation's directory. Note "/home/rmcn/summ96/simjava"
is the base directory of the simjava distribution on my system.
The new constructors
There are new versions of the constructors for Sim_entity
and Sim_port to provide the extra information needed for
an animation.
Sim_entity(String name, String image_name, int x, int y)
Parameters:
- name - this serves the same purpose as in the stand-alone
simulations.
- image_name - the name of the GIF image file which contains
the icon for this entity. Note the name should be given without
the ``.gif'' extension.
- x and y - the co-ordinates at which to display the
entity in the applet animation window. Note (0, 0) is in the top-left.
Sim_port(String name, String image_name, int side, int pos)
Parameters:
- name - this serves the same purpose as in the stand-alone
simulations.
- image_name - the name of the GIF image file which contains
the icon for this port. Note the name should be given without
the ``.gif'' extension.
- side - which edge of the parent entity this port should be
displayed on. Enumerated values are provided for this, they are
Anim_port.RIGHT, Anim_port.LEFT, Anim_port.TOP,
Anim_port.BOTTOM, and have the obvious meanings.
- pos - how many pixels down the side of the parent entity this
port should be displayed.
All the GIF files used for icons in the animation should be put in
a sub-directory called ``bitmaps/'' off the directory
which contains the applet's class files.
Parameters
Parameters can be used to display information about the internal state
of an entity during the animation. They can either be displayed as
a text message next to the entity, or used to change the icon
which represents the entity.
Parameters can be added to entities in their constructors, as follows:
add_param(new Anim_param(String name, int display_type,
String init_val, int x, int y));
This adds a parameter called name, which is displayed in the animation
window according to its display_type, at (x, y) pixels relative to
its parent entity's top-left corner, and has the initial value
init_val. There are several enumerated
values defined for display_type:
- Anim_param.HIDDEN - Don't show this parameter at all!
- Anim_param.VALUE - Only show the value of this parameter.
- Anim_param.NAME - Only show the name of this parameter.
- Anim_param.NAME_VALUE - Show the name and the value of this
parameter in the form "name = value".
- Anim_param.STATE - Use the value of this parameter to
determine which icon to use for its parent entity. The name of the GIF
file to used for the icon is
"<entity-name>.<state-parameter-value>.gif"
An example:
// In the constructor of an entity called "worker"
add_param(new Anim_param("State", Anim_param.STATE, "idle", 0,0));
add_param(new Anim_param("Count", Anim_param.NAME_VALUE, "4", 10,-10));
This adds two parameters to the entity. The first controls which icon
is used to display the entity, in this case the image in the file
"./bitmaps/worker.idle.gif" will be used initially. The second
will be displayed as a string 10 pixels above and to the left of the entity,
and will be "Count = 4" initially.
Trace Lines
The animations are driven by the trace output of the simulation running
underneath. There are two types of traces recognised by the animation
package, each signified by its first character.
S traces
S traces are used to display the sending of an event by
sim_schedule(). They have the standard form
"S <port-name> <event-data-string>". An example:
// In the body() of sender
sim_schedule(io, 0.0, 0);
sim_trace(1, "S io data");
The animation will display this as a blue dot with the word "data"
written next to it, moving along the wire from the port called "io"
on the sender entity, to the attached port in the receiving entity.
P traces
P traces are used to update the display of the entity's parameters.
They have the standard form
"P <param1> <param2> ... <paramN>".
An example:
// In the body() of an entity with two parameters
int addr_val = 3;
sim_trace(1, "P busy "+addr_val);
The animation will display this by updating the value of the first
parameter added to this entity to "busy", and the value of the second
parameter to the string "3".
Extending simanim
The following information may be useful if extra
animations are needed (for example, text boxes, graph widgets
attached to entities etc). See also the
design document for more details.
simanim itself extends simjava.trace_out which itself
extends java.awt.Panel. Thus extra gui components
can be added to the display by adding them to the Panel.
An example of this is in this
text area application which positions TextArea over
a couple of the entities. The source code shows that this was done by creating a new LayoutManager
for the panel (the default layout, FlowLayout, does not allow precise
positioning of widgets).
Extracting results
When a simulation run finishes, the method
anim_completed() is called.
This method can be overidden in the subclass and used to
display results. See the
simdiag guide for more details of this.
Further information and examples
All the public classes and methods are described in the package's
reference documentation
generated by the javadoc program.
There are several example simulations distributed with the simjava
package. Their source code may help with syntax and usage queries.
- Memory Cache
- An animation of a computer memory cache, with heavy use of parameters.
The source.
- Task Farm
- A work farm, with variable number of worker entities using
anim_relayout().
The source.
Known bugs and problems
If you find any new bugs please send details to the address below,
and they might even be fixed in a future release!
Bugs
Problems
- Animations take a long time to download over the net. This is
due to the large number of requests that have to be sent out for all
the class files, rather than the volume of data that has to be downloaded.
This can be reduced by using JAR files which compress all class and
bitmap files into a single archive. The omega network example (along with its
makefile) show how
jars can be created and used.
Fred Howell -
fwh@dcs.ed.ac.uk
Ross McNab
Department of Computer Science
University of Edinburgh