Section 2 Home page Section 4

3. Overview of a GEM Program

If you are familiar with GUI programming on a more modern computer, kindly forget everything you know. Programming in GEM is primitive. With a modern toolkit, you have many kinds of widgets, from buttons and spinboxes, to complete text editors supporting copy and paste and scrollable display areas. Widgets can be combined with layout managers into complex arrangements. Multi-threading can be used to keep the display refreshed while your program is busy computing some results.

None of this is available in GEM.

In GEM there are, essentially, three elements: menus, dialog boxes (which can contain several "widgets", such as buttons or text fields) and windows. The part that will take most of our time is learning to handle the window: a window is the part of the screen in which your application has free reign. You have complete control over the contents of the window. You decide what gets drawn there, how what you draw there responds to the user moving the sliders around, and you must also ensure what you draw in the window remains there (and only there) as your window interacts with the windows of other applications (in MINT) or desk accessories.

3.1. Outline of Material

The following sections progressively build up a GEM program to illustrate window handling, resulting in a program that responds to all the expected window events, has sliders, and co-exists happily with other windows, preserving its own contents, and not disturbing the neighbours. Each successive version is provided complete in the source code for this guide, and can be compiled using AHCC.

After getting to grips with windows, we move onto an easier aspect of GEM programming: menus. Menus are defined in the program’s RSC file, and all we need to do is respond to a message indicating they have been selected. We will also look at how to respond to keyboard commands, so we can use keyboard shortcuts to menu items.

We then move on to dialog boxes. The main issue with dialog boxes is displaying them, and then retrieving any data the user has input. Dialog boxes are the only place you find widgets such as buttons, text fields and labels (unless you are using an advanced AES permitting toolbars). Again, dialog boxes are defined in the program’s RSC file.

Although there is a lot of code required for managing GEM, with a little discipline it is possible to preserve most of this code between projects. The examples here follow my own practice in managing this. I shall try to make clear which parts of the examples are GEM requirements, and which are my own suggestions.

The different components of a GEM window:


A GEM program typically does the following:

  1. initialise the application

  2. open a VDI screen, and obtain a handle to access it

  3. optionally open an RSC file and set up the menu

  4. open an initial window or windows

  5. enter the event loop, responding to all window / other events until the application is quit

  6. free any resources

  7. free the VDI screen

  8. exit the application

3.2. Some GEM Terms

GEM comes with some terminology of its own, which may not be familiar to the novice GEM programmer.


the part of the operating system which handles the windows, dialogs, menus, mouse etc.


is how GEM informs our program that the user has clicked or dragged on a window widget or menu item, or that we must redraw the display in a window.


is a number assigned to identify a window or application. Your application may have several windows open, and will need to identify which window the user is attempting to interact with. The window handle is used as a unique reference for each window in your application. Similarly, there may be several applications running at once, and each application is given a unique application handle to identify it.


the information sent to our application about an event. For example, a redraw event would have information about the new window dimensions.

RSC file

is a file which accompanies our GEM program, and contains definitions of the menus and any user-defined dialogs which our program requires. The RSC file is created in an external program, such as ResourceMaster. The advantage of using RSC files is that it is easy to distribute versions of the RSC for different languages, making our GEM programs international.


the part of the operating system responsible for drawing graphics and text on the screen.

virtual workstation

is the name given to the screen display. When a GEM program starts, it is assigned a handle to access the screen, which we call the app_handle. In theory, workstations may be created on other screens and/or devices, but in practice this will always be the screen.


are the components of a GEM window or dialog which we can click or interact with, usually by clicking or dragging with the mouse. For example, the close button and sliders on a window are widgets, as is a button in a dialog.