a HOG2 app

HOG2 uses an event-based GUI, which is described here. First you should install handlers for any events that you would like to receive. Then, you hand control over to HOG2:

int main(int argc, char* argv[]) { InstallHandlers(); RunHOGGUI(argc, argv, 640, 640); return 0; }

createSimulation

initializeKeyboardHandlers

initializeCommandLineHandlers

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.

Here is an example of a comand-line handler:

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.

a window

You will be notified when a window is created via the window handler.

void MyWindowHandler(unsigned long windowID, tWindowEventType eType)

You install a window handler using the following code:

InstallWindowHandler(MyWindowHandler);

A window handler receives events (kWindowDestroyed, kWindowCreated) when windows are created or destroyed, and should setup any variables associated with that window. The windowID is a unique identifier that is used in other functions to identify that window.

A window handler should typically install a frame handler to be able to draw into the window each frame.

Handlers

Frame handlers are used for drawing each frame of the GUI.

InstallFrameHandler(MyFrameHandler, windowID, 0);

A frame handler function looks like this:

void MyFrameHandler(unsigned long windowID, unsigned int viewport, void *)

It is passed the window being drawn, the viewport of the window, and a (void *) which can pass any data.

You can call GetContext(windowID) to get contextual information about a window. In particular, a virtual display can be retrieved and drawn into:

Graphics::Display &d = GetContext(windowID)->display; d.FillRect({-1, -1, 1, 1}, Colors::lightgray);

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')); }

/////////////////////////////////////////////

/*!