The Calibration Code

The code is designed to run on OSX, Windows and Linux (via GTK)
All 3 OSs employ a WIMP UI that is based on a message driven architecture
WIMP stands for Windows, Icons, Menus and Pointers
User keyboard input messages are processed by the OS
and sent to the the app
When the app is initially loaded, it is sent a message to "paint" the screen
Thereafter, if the app needs to paint to the screen on its own
it sends the OS a request which the OS translates to another paint message
There are designated event handlers for keyboard input events
for screen display output (paint) events
wxWidgets provides an abstraction for an app and a Window
An app contains and manages a "frame" which frames the window
The app is expected to paint in it's window
Keyboard input messages are sent to this window as are paint messages

All painting to the display is handled by the graphics processor
for which there in an abstraction called the "Device Context"
At any given time or context, since there is only one graphics processor
The 'context' part of the naming refers to this aspect of the architecture
When a window is sent a paint message by the OS
it reserves the Device Context for painting, and uses it to paint
We use the Device Context to paint parts of images, some text strings and some lines

On the input side, the window receives an event when a key is pressed
This event contains information about which key was pressed
wxWidgets provides methods to retrieve this info in an OS independent manner

As far as interfacing with the OS, we are mainly concerned with these 2 methods
i.e. The paint event handler and the key down event handler
In addition, the app has to be initialised before it is displayed on the screen
A designated method in the wxApp class serves this purpose.
During initialisation the app prepres itself for the next phase of its existence
when it will be processing paint and key down messages
In our context, the app prepares images for the onscreen hex-grid
which will be displayed in the background
the onscreen keyboard that will be displayed above that
and the crosshair (like a mouse pointer) which will be moved around the screen.
It also prepares the strings that will prompt the user for varoius calibration actions
Once the app is running after initialisation
it is only processing key down messages
and dispatching actions in response (indirectly, via the OS) to its paint event handler
and painting when that message is received by the paint handler

Codebase Architecture

Since Hex-map is a simpler UI paradigm than WIMP
hex-map UI code is also simple.
The UI is designed as a set of sequential UI "modes".
The UI always operates in a single given UI mode.
The mode may switch itself out and load another mode.
A mode is composed of 3 functions.
The introductory display
which is the information that is displayed when it is first loaded.
The keyboard map
which is how it dispatches keyboard events initiated by the user.
The user action response
which is how it responds to a user action by displaying something.

As an app desginer, you have to design a set of UI modes
and implement them through these 3 functions.
That's all
Hex-map provides several utilities for dealing with the hexagonal grid
such as computing distances and angles between points on the grid

The codebase consists of a single .cpp file name kybd-cal.cpp

To build it, you go to your samples directory in your wxWidgets installation
Replace the contents of drawing.cpp with the contents of kybd-cal.cpp
while retaining its name
or change the name of the source file in Makefile
Then you run make to build the sample which is now the calibration code

kybd-cal.cpp contains all the app, frame and window wxWidgets specific code at the top
This is followed by a set of globals
that the app uses for parameter passing between high level functions

The meat of the code is a set of C functions that start backwards from the end of the file
The end of the file contains the initialisation functions
which prepare several graphic primitives to be displayed during app execution
These are preceded by the UI modes
These are preceded by some utilities used by the UI modes
The utilities are preceeded by some drawing functions
used by the UI Modes and the initialisation code
The globals precede these

download kybd-cal.cpp