Putting it all together

To define a new application, you can create a new directory in the apps/ folder. To compile this applciation, type "make x" where "x" is the name of the folder you created. In the folder you can put an .cpp and .h files that you want for your application, but you must define the following functions somewhere inside this directory:

processStats

createSimulation

initializeKeyboardHandlers

initializeCommandLineHandlers

The definitions for these functions are in "common.h", so you need to include that file as well.

Command-Line Handlers

The first thing you need to be concerned with is installing command line handlers. These handles will allow you to process command-line arguments. By installing handlers with text descriptions, it is possible to have the application automatically print help for all command line arguments when it can't process them correctly.

Inside initializeCommandLineHandlers you really only need to call the function installCommandLineHanders. Here is an example:

installCommandLineHandler(myCLHandler, "-map", "-map <filename>", "Selects the default map to be loaded.");

A command-line handler looks something like this. It gets a pointer to the current argument list, where the first argument is the parameter for the handler. The handler then processes as many arguments as it wants, and returns how many arguments were processed.

int myCLHandler(char *argument[], int maxNumArgs) { if (maxNumArgs <= 1) return 0; strncpy(gDefaultMap, argument[1], 1024); return 2; }

Multiple handlers can be defined for the same argument. They will each get called in turn (no order guarantees) until one of the handlers returns a value greater than 0. Given the command-line arguments, you probably want to use a global variable to store any parameters that were set.

Given proper command-line arguments, you could just allocate your own simulation, run it, and then exit the program, although you may want to do this in createSimulation, after all command-line arguments have been handled, unless you can guarantee that a particular command-line argument will always be last.

Creating the Simulation

The function createSimulation is where you need to allocate a unit simulation. This is where you can also set any of the parameters set from the command-line arguments. The simulation will start running immediately. If you don't want it to start running, you can pause it here.

Here is a sample implementation:

void createSimulation(unitSimulation * &unitSim) { Map *map; if (gDefaultMap[0] == 0) map = new Map(64, 64); else map = new Map(gDefaultMap); unitSim = new unitSimulation(new mapCliqueAbstraction(map)); }

Keyboard Handlers

Keyboard handlers are similar to command-line handlers, in that you install any handlers to allow your application to respond to keyboard events. By installing handlers, the program can print out all legal key combinations it accepts. initializeKeyboardHandlers might look something like this:

void initializeKeyboardHandlers() { installKeyboardHandler(myDisplayHandler, "Toggle Abstraction", "Toggle display of the ith level of the abstraction", kAnyModifier, '0', '9'); }

In this case, any keys in the range 0..9 will be sent to the function myDisplayHandler, regardless of any modifier keys that are down. It is important to note that modifier keys such as SHIFT can often change the ASCII value that is passed to the keyboard handler. Keyboard handlers will be called with the lowercase equivalent of the key that was pressed, but SHIFT-1 will be reported as SHIFT-!, and so will not trigger this handler. Here is an example handler which implements the above functionality.

void myDisplayHandler(unitSimulation *unitSim, tKeyboardModifier mod, char key) { if (unitSim->getMapAbstractionDisplay()) unitSim->getMapAbstractionDisplay()->toggleDrawAbstraction(((mod == kControlDown)?10:0)+(key-'0')); }

Processing Stats

Each time a unit simulation is de-allocated, processStats is called first to allow your application to save the stats or do any other processing on them.

Prev: Abstractions Next: Memory

---