Home page Section 2

1. Introduction

This document is a guide to writing GEM applications in C using AHCC. I will walk through the implementation of a sample GEM application, in full detail. The program initially displays a single window containing some text. We build the program through various versions to create a multi-window system using sliders and other window widgets. The program is developed further to use menus, file dialogs and other features of AES.

Why AHCC? Although there are many options for C programming on the Atari platform, AHCC is kept up to date and runs natively on (all?) Atari computers and clones. It is a complete IDE, including an editor as well as compiler and linker: I use this program extensively on my Firebee, and also on my Atari STE. AHCC is available from: http://members.chello.nl/h.robbers/ Although written for AHCC, most of what follows will apply to other C compilers for the Atari, but the examples may need some changes in their header files and project/make files.

There are other guides out there. I learnt much of the following using CManShip, written by Clayton Walnum, and available from AtariForge:

However, the examples in CManShip require several changes to compile with AHCC (my updated files for AHCC are at https://github.com/petercrlane/cmanship). In particular:

  • C89 syntax (especially function signatures)

  • changes to headers and library calls for compatibility

AES has also changed in some respects, particularly if you are running MINT with XaAES or MyAES, with new messages and possibilities not available on the Atari ST. For example, it is possible to use menus internal to a window with XaAES, and also create toolbars at the top of windows.

After working through CManShip, I tried writing a few different programs, and, partly through trial and error, and partly with the help of contributors at http://atari-forum.com, I now feel able to put together some simple GEM programs. This document is, in part, my attempt to record what I have learnt from this process. Also, it is an attempt to simplify and unify the techniques I am using. However, this document is, in many ways, a statement of the limits of my own knowledge, so take anything I write with a healthy degree of skepticism, and let me know of any errors and improvements.

I will assume you already know the C programming language (in particular, C89), and also that you know what a GEM program is. However, I shall try to cover what you need to write in C to get a GEM program working and interacting with the operating system. I will not say much about creating an RSC file - refer to your own program’s documentation. (I use ResourceMaster 3.65.)

This guide is not a complete reference to GEM programming through AES / VDI. Apart from CManShip, I use the following references for lists of constants and function definitions:

  • Katherine Peel’s "The Concise ATARI ST 68000 Programmer’s Reference Guide"

  • http://toshyp.atari.org (also available as a hyp file, to download).

Alternative resources include:

This guide has been typed on a Firebee using QED. The guide was previewed using Neso and NetSurf, and finally converted to pdf with asciidoc on a computer running Ubuntu. The examples were tested using version 5.3 of the AHCC C compiler on a Firebee and, where appropriate, an Hatari-emulated Atari ST.

Source code for the guide and its example code is available at: https://github.com/petercrlane/gemguide