A Guide to GEM Programming in C using AHCC

We will be using the include libraries for AHCC (not the short int versions, in sinclude). Unfortunately, as at version 5.3, some of the constants we require are not in "include/aes.h". You need to copy the values from "sinclude/aes.h". These missing constants include:

If you get "missing constant" messages from AHCC, first see if they are missing from "include/aes.h".

Structure of a project file:

The usual things to change in the above project are:

The standard library comes in four versions (thanks to Eero Tamminen for explaining this):

When AHCC starts, it is initially set to use the libraries in "sinclude". These use a 'short int' data type.

Before trying the programs here, set AHCC to use the libraries in "include". Do this by opening the Config dialog (Alt-O), finding the "Options for the compiler", and checking the line for "-i include".

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.

The different components of a GEM window:

A GEM program typically does the following:

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

We must begin and end our GEM application with some startup and teardown code. These register our application with the operating system, and provide a unique reference to identify our application.

I place this code in main, with a call out to a function to run our own application (for a complete listing, including header files and variable definitions, see the source code which accompanies this guide):

Functions (2) and (3) must be provided by ourselves. (2) is a standard process to open a virtual workstation (to obtain access to the screen), as shown below. An important part of this is to create a reference to the screen, through the call to graf_handle; this reference is stored in the variable app_handle.

Each window in our application will display some information to the user. A window may respond to many events: it can be moved around the screen, be made smaller or larger, have its sliders moved, and must always keep its contents up to date. There are, therefore, many pieces of information which a window must be aware of. For this reason, I use a struct to store all data relevant to a single window. My basic win_data is as follows:

As we proceed through this guide, the contents of win_data will expand. In addition, your application will have various data that are relevant to the window. This should also be stored or referred to in win_data: for now, we use text as our example application’s specific data.

Creating a window requires setting up an instance of win_data with the relevant data, creating a window, and then showing it. The following code appears in "windows.c", in the start_program function.

The functions wind_set and wind_get will be met frequently as you work with windows. They both take a window handle as their first parameter, and then an identifier for some component/information of that window. Handle 0 is used to refer to the desktop.

The identifier refers to different parts of the window. Some of the values we will use include:

Notice in wind_create we include the flags NAME|CLOSER. These tell our window to include space for a title, and for a close box. We set the title through WF_NAME, as above. The close box is used to exit the program, and we discuss how this works when we cover the event loop, below. Windows can contain many parts, and to use them we include them in the list of flags. Some common flags are:

The function start_program continues as follows:

A function draw_example is used to draw the window contents on the screen. Our example simply displays the given text in the window.

All GEM programs work in an "event driven" manner. This means that the program waits for the user or operating system to send it an event: something to do. The program then does what it wants in response to that event, before returning to the loop. For example, clicking on the close icon at the top-left of a window will send a message to our program. Our program must then do the appropriate thing, in this case, we must close the window and end the program.

For the example we will use the function evnt_mesag to obtain events for our program. In any real GEM program, you will use its big brother evnt_multi (or AHCC’s EvntMulti), which lets you spot events from the mouse, keyboard or other sources as well as those relating to your window; we discuss other events in a later section. For now, to keep things simple, we will only need to respond to window events, so we use this call.

In later sections, we will respond to more kinds of events within the loop. We will then discuss the other values that can be used in msg_buf.

At this point, we have a window which displays some text inside it. However, if you drag a window over the top of it, the contents will disappear. Also, none of the widgets (except for close) do anything: we cannot move the window, bring it to the top when we click on another window, etc. Also, the background shows through in our window, particularly a problem if you are running a multi-tasking OS, such as MINT.

Look again at our function draw_example: the call to v_gtext does not refer to our window, only the screen. Our drawing code could, in theory, write anywhere on the screen we want. However, this would break the illusion of our program providing a window onto some information. A better solution is to set up a clip area: this is a rectangle we define, so that if our VDI calls go outside that area, they will be clipped to only appear within the given rectangle.

We thus wrap our call to draw_example in a function draw_interior, which sets up a clip area and also clears the display of our window for us. The following draw_interior function does a lot of useful work for us. First, it hides the mouse, so we don’t draw over it. Second, it sets a clip area (set_clip is defined in "windows.c"), so that all VDI calls will only show within the given rectangle. We then get the dimensions of the working area of our window. This is the same wind_get call we made before, except now we ask for the working area of our window, instead of the desktop. The working area will exclude the window boundaries, any sliders, etc. A call to clear the window and we can then call out to our application’s drawing code. Finally the clipping is turned off, and the mouse reshown.

One of the technically more complex aspects of handling windows in GEM is the concept of the rectangle list, and how to manage it. In essence, the idea is very simple. Assume our program’s window is obscured by several windows. One of these windows is closed. Our program will be told to redraw the area which was underneath the window which has now closed.

However, we cannot blindly fill that area with the contents of our window, because there may be other windows partially obscuring this area. Hence, we must take a look at every other window on the system, find those which are obscuring our window, and make sure we avoid drawing over them.

For example, consider the following two images. In the first image, we have three windows,all overlapping each other. We now close the top window: how should the back window, the one showing the list "Classic 1" etc, be updated?

The second image shows the scene with the top window closed. The highlighted rectangle indicates the area that needs to be redrawn, and only this area. If we redraw any other parts of the bottom window, we will overwrite the contents of the window now on top.

The process to ensure we only update the required areas is called "walking the rectangle list". Our application receives the total area that was revealed by closing the top window, and which needs updating. Our application compares that area to the other windows that are obscuring it, before locating the highlighted rectangle to draw.

Walking the rectangle list is controlled by two get operations:

This continues while the w and h values retrieved are non-zero values: when they are both zero, we have reached the end of the rectangle list.

All we check is whether the rectangles in the list intersect our rectangle to update and, if so, we draw the intersected area.

(Note that rc_intersect is provided within AHCC’s library.)

What does the AES do when it thinks our window needs updating? It sends us a REDRAW event. Along with the event, it tells us the handle of the window we need to update, and also a rectangle: this rectangle is the area of our window it wants us to update.

For a redraw event, we receive the following information in msg_buf:

This part of the program does a lot of hard work. To recap, every time our program must redraw part of its screen, it will receive a REDRAW event, containing the window handle and screen area to redraw. We pass these to do_redraw which walks the rectangle list, ensuring we draw on only those parts of the window which are not obscured by other windows in the operating system. do_redraw then calls, for each unobscured rectangle, draw_interior, which sets the clipping region to the unobscured rectangle and draws our application’s data into just that region.

The good news is two-fold. First, having written all this code, it will probably be pretty-much the same for any GEM program. The main part you need to change is draw_example, or its equivalent. Second, this sequence is called every time the computer thinks you need to update the screen, and so you don’t have to do anything extra to keep the window updated in many cases. In particular, your program will receive a REDRAW event when it starts up, which means we can delete the call to draw_example we had in start_program.

This version includes the REDRAW events, walking the rectangle list, and the code to clear the display background. When you run the code, the display should now look a lot better. Try dragging another window over the top of your program: notice how the display updates itself, keeping your window’s display exactly as you want it.

However, it is now time to use some of the other possible window controls, and manage the events they trigger.

When several windows are open, only one is "on top". You can bring a window to the top by clicking on it, or if it is "behind" another window which is closed.

When our window is brought to the top, our application is sent the message WM_TOPPED. The handle of our window is provided in msg_buf. All we need to do is use wind_set to bring our window to the top.

In our event loop, we add the following code:

You may wonder how a window that has been partially obscured by another window will be redrawn when you bring it to the top. The answer is that I lied a little when I said all we need to do is the above: AES will trigger a REDRAW event for a window, when you set it to the top, so our program will have to redraw the window contents. However, as we already handle REDRAW events, we have nothing else to do - our previous code and AES do everything for us already.

Windows can be moved, usually, by holding the top bar and dragging them. For this to be available, you need to include the MOVER option in the parts list for your window when you create it (see the section on creating windows).

When our window is moved, all we need to do is set the window’s coordinates to the new location. The new location is provided in msg_buf, positions 4-7.

In our event loop, we add the following code:

The AES copies our window’s contents directly to its new location. (The AES also sends redraw messages to any windows which our window was obscuring - but we can ignore those.)

We do, however, have to look more closely at our drawing code, now that the window can move anywhere on the screen. Remember that the code that draws on the screen does so through the VDI, and we do not provide any reference to our window when we do so. When we move our window, we need to draw the contents of our window in a different location. To do this, we pass the coordinates of where we want the contents drawn to our draw function. The provided x,y coordinates then represent the origin we need to use for our drawing code. We pass these coordinates to our drawing code from draw_interior.

Version 3 now includes these two events. Notice also the inclusion of MOVER when the window is created, and the updated draw_example and draw_interior functions.

Our window is now a respectable GEM program. It redraws itself when requested, does not disturb any other windows in the system, can be moved around the screen and brought back to the top. If you are content with a fixed size window, you now have enough to implement a GEM application.

The FULL widget is used to expand our window to its maximum size. This maximum size was set when you created the window, but is usually the extent of the desktop: using WF_FULLXYWH in a call to wind_set will retrieve this maximum size. Once fulled, a window can be restored by again clicking the FULL widget. The AES enables us to retrieve the previous dimensions of a window using WF_PREVXYWH in a call to wind_get.

Fortunately, the AES will ensure the display is kept updated, in two ways. First, if the window is just made smaller, then nothing needs updating in your program, as the display has simply been truncated. Second, if the window is made full, it becomes larger, so a REDRAW event is sent to your application, to redraw the new rectangle(s). As we already handle these events, nothing extra is needed.

The function to handle the fulled event is as follows. It is divided into two parts: if the window is already full, then we need to retrieve its previous size and set the current window size to those older values. If the window is not already full, then we need to retrieve the maximum size, and set the current window size to the maximum (full) values. In addition, it is traditional to display a little animation of the window growing or shrinking to its new size, hence the calls to graf_shrinkbox. (This may not be visible on a fast computer: I can’t detect them on the Firebee!)

Notice the function is_full_window, which returns true if the window is currently at its maximum size. This function merely checks the current and full dimensions of the window, to see if they are the same. The function is:

Finally, to respond to size events, include WM_FULLED in the event loop, as follows:

The sizer allows the user to adjust the window dimensions to any size she chooses. The AES will tell your application when the sizer has been adjusted, and also tell you the new size of the window (in msg_buf). Your program must alter the size of the window, and make any other adjustments required to make the window contents suit its new size (this is particularly important when you have sliders as well, for which see the next section).

Fortunately, the AES will ensure the display is kept updated, just as with the fulled event, above.

The code to actually resize our window is, at this stage, simple. All we need to do is set the current dimensions of the window to the new size. We add a simple check that the new dimensions are not too small, so the user cannot reduce the window beyond a given minimum.

To respond to size events, include WM_SIZED in the event loop, as follows:

Version 4 now supports more of the window’s widgets: you can resize the window using the button at the bottom-right, and also make the window switch between full screen and its original size.

To make the display more interesting, the window contains several lines of a poem. You need to resize the window to see more of the poem. How much you can see will depend on the size of your screen. To see the rest of the poem, we somehow need to move the window "over" the poem being displayed - this introduces our next topic, sliders.

Adding the sliders and arrows is done in the parts list when creating our window. We need to add the slider and its two arrows. A complete parts list, including all the previously mentioned windows widgets, is:

The AES makes some space for the sliders, as with the other window widgets, and leaves the remaining room for us to draw in. This is why, when doing operations such as FULL, we use WF_CURRXYWH to get or set the current window dimensions, but, for drawing within the window, we use WF_WORKXYWH to get the current working area of the window.

Each slider has two parameters: its size and its position. The size must reflect the portion of the window contents we can currently see. The position must reflect where our current window contents are, in relation to the whole.

Before we can start, we need to decide a few details about what our window will be displaying, and how using the sliders will affect what is displayed. For example, for a window displaying text, we would expect a click on the down arrow to move the display up by a single line of text. A click on page down would move the display up by a page of text, moving the currently bottom line to the top of the screen. The vertical slider should reflect the number of lines of text displayed in proportion to the total number of lines available to display. Similarly, the horizontal arrows would move the text by a character, in either direction.

Hence, the first two details we need to decide are the size of a vertical step, and the size of a horizontal step. For a text display, this will be the height and width of a character, respectively. For graphical displays, other kinds of step size might be appropriate: in the Sokoban program (see later), I chose the size of a displayed cell as the step size; when displaying an image, perhaps a single pixel would be the required step size.

This step size is an important feature of the window: I store it in the win_data structure, and set it when creating the window.

Four other items of information are also stored in win_data. These are:

These size items are added to win_data as follows:

The following diagram illustrates each of these six slots (the blue rectangle illustrates the displayed window onto the background text):

The size of a slider must indicate the proportion of text actually shown against the total amount of text that could be shown. In our example, the poem has a number of lines to it. If all of the poem is showing in the window, then the vertical slider must be at its maximum - there is nothing to scroll. If however the window is shorter, so only some of the lines are showing, then the slider size must reflect the proportion of text showing against the total number of lines in the poem. Similar considerations apply to the horizontal slider.

The following function returns a number from 0 to 1000 based on the required size of the slider. This is calculated based on the number of lines or characters available (which the size of window would permit) and the number of lines or characters actually shown (which are displayed by the draw code).

The position of the slider depends on three parameters: the number of lines or characters available, the number shown, and the current offset from the top or left. Again, if the number available exceeds the number to be shown, then the slider is simply at position 0 (the top or left).

Before working out the proportion, we need to compute the "scrollable region". This is the number of positions along which the slider can move. For example, if we have a 500 line text, and 50 lines can be displayed at a time, the top line can be moved from line 1 to line 450: so the scrollable region for the vertical slider is 450 lines.

The position of the slider is then computed as 1000 * offset / scrollable_region.

As the ST does not support floating point calculations, the code below computes that fraction using integer division and modulus, and can be used everywhere.

Given the above two functions, it is now straightforward to update the sliders. Our function simply finds the available numbers of lines and columns, based on the work area of the screen, and then each slider size and position can be updated. The offset to the sliders is recorded in wd→vert_posn and wd→horz_posn: these will be updated when the events, such as moving down a line, are processed.

There is no point having sliders if our window contents do not respond to the position of the sliders. In addition, our drawing code must record the amount of vertical and horizontal space taken up by the contents, to use when setting the size and position of the sliders.

To record the amount of space taken up by the contents, I update the number of lines shown every time a line of text is shown, and the number of columns shown by the maximum width of text.

The vertical slider position is accounted for by ignoring the number of lines in the display equal to the slider position.

The horizontal slider position is accounted for by printing the text offset to the left by the slider position.

Note, I don’t worry about text being displayed off screen, as this is taken care of by the clipping, set in draw_interior.

The display of the window contents will depend on your window. The example above is suitable for lines of text. For a graphical display, you may have a fixed size for the window, which means some of the calculations can be simplified.

The sliders must be checked and changed whenever the window size or contents are altered. In practice, we need only alter the sliders when we update the contents of the window. The most suitable place for this is at the end of draw_interior.

The sliders need adapting also whenever the window size changes. We do this within do_sized by changing the horz_posn and vert_posn values to reflect the change in size of the window. If, for example, a window is made larger, then it will display more information, and we can reduce the number of lines off the top of the window.

The sliders themselves will be updated automatically as setting a new window size will trigger a redraw event, which also updates the slider sizes and positions. Unfortunately, that redraw event will only apply to the newly exposed parts of the window: if we have moved the horizontal or vertical position, then all the contents will need redrawing, and we will need to trigger that redraw ourselves.

The sliders can be moved directly, by dragging them with the mouse. These events have their own message type, one for the vertical and one for the horizontal slider. msg_buf[4] contains the new position of the slider, as a number between 0 (top/left) and 1000 (bottom/right).

The code to handle the slider update requires us to compute any change to the top line. The new vertical position reflects the location of the new slider position along the scrollable region.

The code for handling the horizontal slider is very similar.

The remaining events are all known as "arrow" events: the AES sends the application a message that an arrow event has occurred, and passes the arrow type in msg_buf[4].

do_arrow simply calls the appropriate function based on the arrow type.

There are 8 arrow types. In each slider we can move in either direction by one step, or by a "page". The horizontal slider arrow events are handled identically to the vertical ones, except with the obvious change in orientation. For the vertical slider, the move up or move down is again the same, except for minor changes. I shall describe here just the UPLINE event, which moves the window down by a single step, and the UPPAGE event, which moves the window down by a whole page of text. We start with UPPAGE, which is simpler:

We could, in theory, treat UPLINE in an identical manner. Instead of changing wd→vert_posn by a page of text, we would change it by 1. The only aesthetic problem is that it makes the display flicker: there is a better technique, which gives smooth scrolling. The better technique copies the unchanged, existing image down by one line, and then simply redraws the new exposed line.

The following function uses this better technique. The first four lines compute the new vert_posn in the same way as for do_uppage. We then set up a call to vro_cpyfm. This VDI function copies screen data from one place to another. In pxy[0-3] we place the location of the start display, and in pxy[4-7] we place the location of the end display, which is the same location but one line down. Finally, we adjust the rectangle so we redraw just the top, exposed parts of the display.

The above two functions are repeated four times, for the four different directions of movement. See the source code for all the variations, and also do_arrow.

This version includes all the functions required for handling the sliders. As can be seen by comparing versions 4 and 5, the code for the sliders dominates the final program: version 4 has approximately 240 lines of code, whereas version 5 has around 550 lines, more than double the size.

The critical change is to make the win_data structure a list of instances of such structures. We achieve this by adding a single field to win_data, which is a pointer to the next window in the list:

As we create each window, we add its pointer to the end of the current window list. In our example I create the three windows inside start_program; for a larger program, you may want to put this in a separate window-creation function.

We still pass the start of the list of windows to event_loop. However now, because each event could apply to any one of our windows, we must find the correct instance of win_data for each event. This is done in its own function, by looking for the window’s handle. The following function simply walks along the list of win_data instances, until it finds the one with a handle matching the target handle:

Finally, each event which requires an instance of win_data must first find the correct win_data based on the window handle which triggered the event. For example, the REDRAW event now looks like:

The close event may need some care. In this example, clicking close for any window will quit the application. If you wish to have a more dynamic system, with windows that can open and close at arbitrary times, you will need to process the closed event based on the window handle. For an example of doing this see Version 7 of the sample program.

Version 6 provides a display with three displayed poems. Notice how few changes were required to the source code, but the final system is very flexible: each window can be moved, resized and handled separately.

Before our program can use a menu, we need to build the menu in a resource construction program (such as Resource Master) and save it as a RSC file. Our program also needs a way of associating the clicked on menu item with the information sent in the message event. This information is contained in a set of symbol definitions, saved by the resource construction program in a .rsh file (or equivalent).

As we create each menu item, we associate with that menu item a symbol, used to name it. When we export the C header file, we get a file containing symbol definitions for each menu item. For Resource Master, the output looks something like the following. Note that the symbol 'ABOUT' attached to the 'About' menu item has been prefixed with the symbol for the main menu itself.

Before we can use the RSC file, we need to include the .rsh file in our source code. We do this by adding a line in "windows.h", for example:

Before we can show the menu, our program must open the .RSC file. We must check the file has opened successfully before proceeding. Having done this, we can locate the menu bar and show it. Once our program has finished, we should remove the menu bar. Our start_program function is accordingly modified, as follows:

Menu events are passed to our program using the MN_SELECTED event type. msg_buf[4] contains the reference to the actual menu selected. These references are defined in the .rsh file.

Within the event_loop function switch function, we add the following case to respond to menu events:

Notice how GEM highlights the selected menu item whilst the event is carried out. Our program is responsible for returning the item to normal once it has finished.

The do_menu function simply dispatches to a function to deal with each of the possible menu items.

The do_about function displays a simple information dialog - we discuss dialogs in a later section.

How about the QUIT option? When the user selects quit, we don’t have to do anything except exit the event loop. This is easily done in the while condition:

An individual menu item can be enabled or disabled. A disabled menu item cannot be selected, and is shown greyed out on the menu bar. Whether a menu item is enabled or not is controlled using:

where

Each menu item can also show an optional check (or 'tick') mark beside it. The code to control this takes the same parameters as menu_ienable:

Finally, it is possible to change the text showing on a menu item, with the call:

The sample program does not have a good reason to use checked menu items or to disable items, so there is a menu provided just to try out these options. One menu item controls whether the other is enabled or not, and shows a check mark if it is enabled. For good measure, the altered menu item also has its text changed. We store the state for this as a global variable, menu_state; in a real application the state will likely depend on the top-most window’s contents, and so be stored within win_data.

The action is handled directly in do_menu:

The traditional evnt_multi function is an extension of the evnt_mesag we have been using so far. It offers the advantage of being documented in the Atari literature, and will be familiar to most programmers. However, it does require care in defining and presenting different reference variables to hold various return values.

The call to evnt_multi looks as follows:

Many of these variables define values describing the kinds of events to listen for. ev_mflags indicates the event types, such as mouse and keyboard. ev_mbclicks describe the number of clicks that will trigger an event, etc.

The reference variables (pointers to ints) are used for return values. For example, ev_mkreturn will hold the code of a pressed key. ev_mmgpbuff is a pointer to the message buffer for AES messages.

The following is a complete list:

The return value from evnt_multi gives the actual event type that occurred. For example, if we wish to listen for an AES message, mouse click or keyboard event, we would call evnt_multi with the flags:

result would then hold one of the flag values, depending on which event type occurred.

The following excerpt from version 7 of our sample program illustrates how evnt_multi is used. In this version we listen for the standard AES messages regarding the menus and window events, but additionally look out for a keyboard event:

AHCC’s custom EvntMulti offers the advantage of a simpler calling routine. Instead of defining separate variables for the possible return values, we simply define one instance of EVENT, and pass its address to EvntMulti. The return values and the msgbuf are all then stored within our instance of EVENT. (The only small downside is that the slot names are not very intuitive.)

The struct EVENT has a slot for each of the arguments to evnt_multi, as discussed above (except that ev_mbmask is called ev_bmask and ev_mmbutton is called ev_mmobutton). Instead of passing the values by position in the function call, input values are set and output values are stored in the relevant slots.

We use EvntMulti just like evnt_multi. First we set the input data for the events we want to listen for, then we call EvntMulti, and use its return value to decide which kind of event has occurred. Information about the event is stored in the relevant output slots of EVENT.

The following excerpt is from our example program, version 7. It does the same as was done using the evnt_multi call above:

In the 'clock' folder of the source code which accompanies this guide is a simple clock program. To be a little different, this displays clock times in binary. (This program looks best in colour.)

The program illustrates the use of the timer event, along with the usual close/top/move/redraw messages for a GEM window. The program simply redraws its display after each second.

In version 7 of the program, we include a menu. The menu provides an 'about' dialog, a way to quit the program, and a menu to select which poem to show.

The menu was created in Resource Master, and saved into the RSC file. The C header was exported, creating the .rsh file. The .rsh file is needed for compiling, and the RSC file for running the program.

The 'Quit' option may be triggered via the menu or by keyboard, so this version uses multiple events in the event loop; two event loops are provided, one for the traditional approach, and one using AHCC’s custom one. The 'About' option displays a simple dialog box: this uses the built in form_alert call to construct a dialog. I explain more about this and dialogs in general in the next section.

Finally, this version allows us to open and close poems as we wish. So the window creation code has been changed to allow for a more dynamic set of windows, and the window close code has been changed, to only close the selected window, not exit the program. The program is only exited with the 'QUIT' option.

This is an important and useful dialog, enabling the user to select a filename to save or open. The main function to use is fsel_exinput. This works on all TOS versions from 1.04 up. The function will call whichever file selector the user has installed: either the basic TOS file selector, the one supplied by XaAES, or even a custom third-party file selector.

We call the function in the following way:

Note how we need some space for the path and filename. These need to be large enough to accommodate nested folders, and also, if you are using a modern AES, long filenames. The file mask added to the end of the path may be general, like "*.\*" or more restricted, like "*.C" or "*.TXT". The file selector will initially show the files at the given path using any mask, and will modify the path and name values based on what the user selects. button is returned with the value 0 for cancel and 1 for OK.

(If you are using a very old version of TOS, replace fsel_exinput with fsel_input, which works the same except that there is no message label.)

The form alert is the simplest kind of dialog. The user is presented with up to 5 lines of text, and up to 3 buttons to choose from. An optional icon may also be displayed.

Creating and showing a dialog is very simple. The dialog’s description is created in a string, made of three parts:

The call is simply:

For example, a query about whether the program should overwrite an existing file might go:

More complex user-defined dialogs may be built using your resource construction program, such as ResourceMaster. The definitions are saved within the RSC file, and can be retrieved by our program. (The sample code in this section is taken from the temperature conversion sample program.)

Creating and deleting a dialog is fairly straightforward:

The main interactions with a dialog are through any text that the user may input, and buttons that the user may click. (Different versions of AES and Resource Construction programs may offer additional widgets.)

The dialog is managed using a version of the event loop, already familiar to us. Dialogs have their own event function, form_do.

Strings are handled by locating a pointer to the string in the dialog box. The following function locates a given string:

Strings can be read from and displayed on the dialog directly from the returned pointer. For example, the sample program has the following sequence:

Version 8 of the program now includes an option to open a file stored on disk as a text file, illustrating the use of a file selector dialog. A useful part of the code combines the path and name from the file selector into a complete filename:

This sample program, in the folder "TEMPCONV", is a standalone program. It provides a simple dialog which converts temperatures from fahrenheit to celsius. It illustrates how to access information in text fields, and how to respond to button clicks.

GEM allows us to determine the mouse pointer’s appearance. The function that does this is:

form takes one of the values in the following list, and sets the mouse form:

mouse_form is used for form USER_DEF, the user-defined mouse form. In most cases, we don’t use this argument, and can provide 0L as its value (as is done in draw_interior in the sample code). CManShip contains an example of creating a custom mouse form; see the code for chapter 12.

There are two kinds of events for the mouse which EvntMulti can respond to. The first is a click/double-click on the screen - the event type is MU_BUTTON. The second is when the mouse moves in or out of a region; up to two regions can be monitored at a time - the event types are MU_M1 and MU_M2.

The following code, from the Sketch example program, illustrates these three events. The code looks for a single mouse click down or release in the window, and whether the mouse is within the working area of the window or not. The mouse cursor is changed to a cross hair when within the working area.

For the MU_BUTTON events, which listen for the mouse button events, we must determine if we are listening for single or double clicks, and for one or both of the buttons.

Once an MU_BUTTON event has occurred, we receive various information about the event:

For the sample program, we create a simple drawing program "Sketch". This provides a simple window, and is purely to illustrate the use of the mouse events. While the mouse is over the window, the pointer will show as a cross hair, returning to an arrow when outside its window. Holding the left button down will start a line; releasing the left button will draw the line on the screen. Note: there is no record maintained of the lines, so the drawn lines will disappear if you obscure the window. This program is also badly behaved, as it’s possible to draw lines outside its window.

I will simply give two functions here, which firstly find the location of the scrap folder, and secondly update any other users of the scrap folder when we have changed it.

The following function requires a reference to some allocated space, and will place into that space a full path name to a file "SCRAP.TXT" in the scrap folder. If the scrap folder does not already exist, it will be created.

The following code can be used to update the clipboard observers, given the path of the scrap folder. The message types and appl_search functions are only suitable for later versions of TOS 4.0+, so don’t use this function on TOS 2.06 or earlier on your Atari ST.

Of my own programs, only BibFind uses the scrap library.

For a sophisticated use of the scrap library, and indeed GEM in general, see GEMClip: http://gemdict.org/gemclip