
                         GEM PROGRAMMING  TUTORIAL ONE
                         =============================
                               By Jonathan White

    "It ain't what you do, it's the way that you do it"

    Strange title, you might think. Well, no, for two reasons. First of all
    it describes pretty well the first problem you must overcome to program
    GEM, and second, it  describes  why  I  hope  this  tutorial might be a
    little bit different from some others...

    I will explain. I've looked at many programming tutorials, both on-line
    and in books, and they all felt wrong. I finally realised why. The bits
    were explained wrong because they  didn't  explain  things in the order
    they worked. They would jump from things you would do at the beginning,
    to things you would do later on, missing bits out you needed to know in
    between. This set, I hope, will  be  different.  It will go through the
    GEM system in the order you meet it when you write a GEM program. Seems
    logical, but it's the first one I've seen which does it. Plus I hope my
    somewhat irreverent and chatty style  (what,  you noticed..) might make
    it a little less dry than most.

    The second reason why the title  is appropriate is that GEM programming
    requires a fundamentally different  approach than standard programming.
    I'll go into this in more  detail  in  a moment (no, please, come back,
    it's not  that  horrible  honest..),  because  your  program  no longer
    controls 'the machine'. Instead, you work in co-operation with parts of
    the GEM system to get the job done. This is mainly with the application
    environment services, AES from now on.  But  as  I say, we get ahead of
    ourselves.

    Well, that's the 'mission statement' out of  the way, on we go. I'm not
    going to teach C here, although that's  the  language I am going to use
    to illustrate the work we do.  I  use  Lattice C personally, but any of
    the various C compilers are  capable  of  compiling  C programs. At the
    moment, I have no  plans  to  actually  make  an  application as we go,
    firstly because writing and testing the  code  will take as long as the
    articles do to write, and I  simply don't have time. Secondly, although
    the GEM function calls are standard,  the  way compilers build the code
    isn't. You should read the compiler  manuals and make yourself aware of
    the exact methods to make GEM programs with it, before you get into GEM
    programming. In fact, go do it now, we can wait...

    Ah, there you are. So, now you have  a  vague idea of how to make a GEM
    program, you want to dive in and  make one, yes? Well don't. First rule
    of GEM programming, even more than any  other sort, is have a good idea
    of what you want to do BEFORE you start typing ANYTHING. Or you'll just
    get in a muddle. For reasons  you  will understand soon, you can't just
    write GEM programs as you  go.  Specifically, this instalment will have
    no code whatsoever in it. I see no  point in showing code when you have
    no idea what it does..

    So, what is GEM, to the programmer? GEM is basically two things..

    1) The VDI (Virtual Device  Interface).  This  allows you to draw basic
    shapes like lines and squares and circles. It also handles bitmaps (and
    anyone  who  calls  them  'sprites'  can   go  sit  in  remedial  games
    programming..) and a few other things..

    2) The AES (I already said  what  that  stood for. PAY ATTENTION. Thank
    you). This handles, windows, keypresses and mouse clicks and most other
    things.

    There are other parts of the  system,  for example the disk services in
    GEMDOS, but I don't have  time  to  cover  them  here. Be aware of what
    Atari have said, that  AES,  VDI  and  GEMDOS  functions will remain in
    future versions of GEM, nothing else  will.  If you play with the lower
    down stuff, and a new OS  upgrade  breaks your program, IT'S YOUR FAULT
    NOT ATARI'S. Furthermore, we will show how sticking to these allows you
    to take account of hardware  not  yet  released  in  your code, so your
    programs will use any upgrades you put in your box, not just the system
    it is now.

    So, the AES and the  VDI  control  the  computer, and your program asks
    them to do things for it. And,  if  you ask nicely enough, they do them
    for you. Simple eh? Well, no not  really as you might have guessed. The
    problem is that you have to work  in  a  different style to write a GEM
    program than you would to  write,  say  a database sorting routine. GEM
    hinges on things called MESSAGES  and  EVENTS.  Events are things which
    happen (Oh, you don't say) such  as  keypresses, mouse clicks, moving a
    window, etc, etc, etc. Every  time  you  do  ANYTHING while using a GEM
    program, that's an event. What happens is, when the AES senses an event
    has happened, it sends you  a  message  if  it  thinks you need to know
    about it, or if you asked it to  tell you when it happens. Then you use
    either the AES or the VDI to react to that message.

    What does this mean in practice?  It  means  that,  apart from a bit of
    initialisation code at the beginning,  most  GEM  programs boil down to
    one whopping great if..then..else  loop  waiting  to react to messages.
    That's why you have to  get  some  idea  of  what  you expect to happen
    before you code, otherwise you  can  easily  miss  out  one of the 'IF'
    bits, and cripple your program.

    So, if you have to change the  way  you  work to get at GEM, why should
    you? Why not write your  own  interface  and  keep things simple? Well,
    firstly you will massively upset people  who  use Geneva and Mag!x, and
    MultiTOS too to a degree. The first  advantage  of  GEM is that it is a
    multitasking OS, even in it's simplest  TOS  1.0 form. The way it works
    is this. When  you  are  in  the  big  if..then  loop,  the computer is
    checking to see if it has any  messages  for you. If it doesn't, it can
    get on with other  things  while  it's  waiting  for messages from you.
    MultiTOS works in a slightly different way, but this idea is important.
    Secondly, having a GEM  interface  to  your  program  means  that, to a
    degree, people know how to work your  program before you even write it.
    Thirdly, and this is personal, I LIKE  GEM programs. Every time I see a
    program based purely around character  menus  or keypresses, it reminds
    me of DOS and I start frothing  at the mouth. Finally, GEM programs can
    be hardware independent, more or less. Since GEM handles all the actual
    input and output for you,  you  don't  have  to worry about whether the
    screen is interlaced or  pixel-packed,  what  key  has  such and such a
    code, or any of that messy junk.

    Well, you now know the basic way in  which GEM works. If you can figure
    that out, you are  half  way  there.  Everything  from  now  on is more
    specific details of the great  if..then....else  loop. If you keep that
    in mind in the future , you shouldn't go far wrong.

    At the  request  of  Peter  Hibbs,  I'll  also  be  providing  a 'quick
    reference' sheet for each articles'  functions  and  data. But not this
    week, because there really isn't much to put in it. What a good start!

    Next time, we'll go through the  steps  you  have  to take to get a GEM
    program started. More specifically, we'll  look at initialising the AES
    and VDI, the information that  it  makes  available, loading a resource
    file, maybe even opening a window.. And before you start worrying about
    making all these things  up  to  test  them,  I  will  be providing the
    skeleton parts to  work  from,  i.e.  a  resource  file.  This,  at the
    beginning, won't have very much in  it.  But  as we introduce menus and
    dialogue boxes, I'll keep sending new versions out. Your task each time
    will be to use the pieces I  give  you  to get something working on the
    screen.

    I don't care what.  That's  part  of  the  reason  there  is no 'sample
    application' with this column.  If  you  are  spoonfed  an example, you
    probably  won't  REALLY  understand  what's  going  on.  As  a  chinese
    philosopher once said..

    'I hear I forget,
     I see I remember,
     I do I understand...'
