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:

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:

Sim_port(String name, String image_name, int side, int pos)
Parameters: 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: 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.

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


Fred Howell - fwh@dcs.ed.ac.uk
Ross McNab
Department of Computer Science
University of Edinburgh