Millennium Time Capsule/AC2000.BIN/disks/ac16disk/articles/features/prog_gem/prog_gem.asc

Text File | 1999-10-06 | 5.3 KB | 119 lines

Our Little GEM

Mark Wherry takes the first step on a guided tour of the unknown...


One thing that all Atari programmers will eventually have to face is GEM.
The Graphics Environment Manager provides support for four modules, the
AES, the VDI, the BIOS and GEMDOS.  In these articles we will be focusing
upon the AES and the VDI.

The Application Environment Services handles windows, icons, resource
files, dialogues, alert boxes, file selectors, menus and graphical based
inputs (eg. moving a window).  When we talk about AES replacements, the
above are the operations that are rewritten. If you're interested in how
the AES is written, why not take a look at the source code for XaAES or
oAESis.

The VDI (Virtual Device Interface) provides a set of graphics functions
that are independent of physical hardware and enable you to create a
virtual workstation, in which you can define and output graphics to a
device.  The popular utility NVDI (New Virtual Device Interface) replaces
the original VDI with faster, superior code that is a dramatic
improvement. If you are an NVDI user (and if not why not?!), you don't
have to worry about compatibility because, the way NVDI is accessed by GEM
is exactly the same as the real VDI.

For these articles, I'm going to use the high-level language 'C'; for many
reasons.  I like 'C' (!), it's popular and ideally suited to the task.  In
my opinion GEM programming is more difficult in something like GFA Basic!
However, Pascal or Modula-2 programmers shouldn't have too much difficulty
in adapting the listings.

The first thing we must do at the start of our program is to initialise
the AES and the VDI.  Remember also, to include the relevant header files,
eg. <aes.h> and <vdi.h>.  For the AES, simply include the statement:
ap_id=appl_init(); where ap_id is an integer that will contain an
identifier given to your application by the AES.

To initialise the VDI is slightly more complicated.  We start by using the
graf_handle function, which returns an id number for the screen which is
being used by the AES. This is known as the physical handle:
vhandle=graf_handle(&char_height,&char_width,&cell_height,&cell_width);
The shorts char_height and char_width return the height and width of each
character, while cell_width and cell_height return the size of the
rectangular box it occupies.  Usually this information isn't needed, so we
can call the function like this:
vhandle=graf_handle(&junk,&junk,&junk,&junk);

As you know, most GEM programs work happily in any resolution, but, this
is only because of a special function, called v_opnvwk (open virtual
screen workstation).  This automatically finds out the size of the screen
and how many colours can be displayed on it.  v_opnvwk uses arrays of
integers which are usually called work_in, and work_out, and should be
defined at the start of your program as:
int work_in[11]={1,1,1,1,1,1,1,1,1,1,1,2};
int work_out[57];
We will look at what these numbers mean later on, but if you're desperate,
try looking in your compiler's manual.  But finally, we call v_opnvwk like
this:
v_opnvwk(work_in,&vhandle,work_out);


Now that wasn't so bad, was it?  Well, now for something really clever,
let's define a window.  For this, the following identifiers will need to
be defined as follows:
int whandle;
int wx,wy,ww,wh;
short gx,gy,gw,gh;
char *title;


First of all, we need to create a new window in the AES, this will not
appear on screen just yet though.  To do this we use the wind_create
function, which returns a handle.  This handle has nothing to do with the
physical (VDI) handle (or even a GEMDOS handle).  The returned window
handle uniquely identifies our window from any other currently managed by
the AES:
whandle=wind_create(PROPERTIES,wx,wy,ww,wh);
PROPERTIES can include any of the following:
NAME, title bar with title.
CLOSE, a close box.
FULL, a full box.
MOVE, the window can be moved.
INFO, an information line below the title bar.
SIZE, a sizer box.
UPARROW, an up arrow.
DNARROW, a down arrow.
VSLIDE, a vertical slider.
LFARROW, a left arrow.
RTARROW, a right arrow.
HSLIDE, a horizontal slider.

So, for example, to define a moveable window with a titlebar and closer,
you would do this:
whandle=wind_create(NAME|CLOSE|MOVE,wx,wy,ww,wh);
If you haven't already guessed, the integers wx,wy,ww and wh define the x
and y coordinates, and the width and height of the window.  It's good
practice to do this as oppose to using values directly, as you will only
get tangled up later!

Before we finally open the window we must first set the title for our
window, and this is achieved by the wind_set command:
wind_set(whandle,WF_NAME,ADDR(title),0,0);
WF_NAME is the request sent to the wind_set function.  There are many
other requests you can send to wind_set to set other window parameters
which we will cover later. The title address character pointer must be
split into the high and low words.  Don't worry about this though, you can
simply use the ADDR macro as shown.

After all this, we can finally open the window like this:
wind_open(whandle,wx,wy,ww,wh);

.....and that's all there is to it!

And that's how to put a window on the screen.  There is however one thing
that might surprise you when you run this program, and that's what we'll
look at next time, see you then.  A complete listing is on the reader disk
(hopefully), if you run into any problems.