How to Create Custom Actions

Custom actions are actions that occur in response to the movement of a slider, the click of a button or the toggling of a checkbox on the Custom Action tab in the settings windows. This document explains how to create such actions and should be used in conjunction with the demonstration source code to the Heat Bugs model, and the Hypercycles model.

The creation of custom actions is coordinated by the Model Manipulator class. SimModelImpl contains a ModelManipulator as a protected instance variable, and it is thus available to all classes that extend SimModelImpl (that is, all Repast models). ModelManipulator contains three methods for creating custom actions:

public void addSlider(String label, int min, int max, int tickInterval, 
       SliderListener listener)
public void addButton(String label, ActionListener listener)
public void addCheckBox(String label, CheckBoxListener listener, boolean isSelected)

If you want to add a slider, you use addSlider, a button, addButton, and a checkbox, addCheckBox. The arguments to these three methods are defined in greater detail in the API documentation for Model Manipulator. In all these cases however, the listener argument specifies what action should be taken when the slider is moved, the button is clicked, or the checkbox is toggled. These listener classes are abstract classes (SliderListener, CheckBoxListener) or interfaces (ActionListener) that are extended or implemented by the modeler to perform the appropriate action.

Slider Listener

Slider Listener is an abstract class that a user will extend to specify the appropriate action to take when the slider is moved. A modeler must implement a SliderListener's public void execute() method. This method is called whenever the slider is moved. There are three variables that are available from within this method:

value an int which is the current value of the slider
isAdjusting a boolean which indicates whether the slider is in the process of being moved
isSlidingLeft a boolean which indicates whether the slider is being dragged to the left

. A Slider is then created as follows:

class Incrementer extends SliderListener {
  public void execute() {
    if (isSlidingLeft) {
      someValue -= value;
    } else {
      someValue += value;
    }
  }
};

modelManipulator.addSlider("Increment", 0, 100, 10, new Incrementer());

(This could also be done more concisely as a anonymous inner class.) Here a new class Incrementer that extends SliderListener is defined. Its execute method will subtract the current value of the slider from someValue if the slider is moving left, or add the current value of the slider to someValue if the slider is moving right. The modelManipulator.addSlider method associates this behavoir with a slider. The slider will be labeled "Increment" and range for 0 to 100 with labeled ticks every 10 units.

ActionListener

The ActionListener interface is provided as part Java itself. It has a single method: public void actionPerformed(ActionEvent evt) and is used in much the same way as the SliderListener. The modeler must provide an implementation of an ActionListener, implementing the actionPerformed method. Whenever the button is clicked the actionPerformed method will be called, and so it is in this method that the modeler should code the appropriate actions. For example,

modelManipulator.addButton("Clear Space", new ActionListener() {
  public void actionPerformed(ActionEvent evt) {
    space.clear();
  }
});

(Here the ActionListener is coded as an anonymous inner class.) The ModelManipulator creates a button labeled "Clear Space" and the actionPerformed method will be executed whenever that button is clicked.

CheckBoxListener

CheckBoxListener is an abstract class that a user will extend to specify the appropriate action to take when a checkbox is clicked. Like the SliderListener, a modeler must extend this class and implement its public void execute() method. This method is called whenever the checkbox is clicked. Two variables are available from within this method:

isSelected a boolean indicating whether the checkbox is selected or not
actionEvent an ActionEvent which should not be of interest to most users. See the ActionEvent entry in the jdk javadocs for more on ActionEvents.

A checkbox is then created as follows:

CheckBoxListener showVal = new CheckBoxListener() {
  public void execute() {
    if (isSelected) {
      showValues();
    } else {
      hideValues();
    }
  }
};

modelManipulator.addCheckBox("Show Values", showVal, false);

Here when the checkbox is clicked the execute method will be called. This method then checks whether the checkbox is selected through the isSelected variable and calls showValues() or hideValues(). ModelManipulator then creates a checkbox labeled "Show Values", associates it with the showVal CheckBoxListener and sets its initial state to unselected.

The Model Manipulator

As mentioned above all models that extend SimModelImpl have acces to a ModelManipulator variable called modelManipulator. If you wish to have custom actions in your own simulations, you can use this modelManipulator. The easiest way to setup a model that will create and show the sliders etc. created via a ModelManipulator is to put all the slider etc. creation in a private method in your model, and call this method as part of your model's setup() method. Note that the first thing you want to call in this method is modelManipulator.init() The Heat Bugs and HyperCycles demonstration simulations both setup their custom actions in this way, and can be used as templates for your own custom action setup.