Reprinted from Commodore World Issue #2
For the time being, open up your manual and study chapters 3 and 4. This will give you a basic understanding of how to assemble and link a GEOS program. Now, let's dig right in and work on a very simple application.
Begin by copying the two files, SamSeqHdr and SamSeq.lnk, from your geoProgrammer disk to a work disk or your RAM disk. You always need a *Hdr file and a *.lnk file. The header (*Hdr) file contains the information that, when assembled, will make up the 256 byte block that is considered the header block of a GEOS file. This is where the Desktop looks when you select 'info' from the file drop-down menu. The link (*.lnk) file is needed by geoLinker. It contains the info needed to properly link your assembled source code into a usable application. If you study the contents of these files, you will see parts that you may alter for your own purpose. In the *.lnk file, you would change the filenames to match the files that you are working on. For now, let's keep it simple and use these files just as they are.
What we must do now is create the source code for our 'program'. Instead of copying the SamSeq file, we will refer to it while we write our own version of it. So, on your work disk, use geoWrite to create a file called SamSeq. Get into the habit of making your source code organized and easy to read by setting up tabs to separate the elements that make up each line instead of using spaces. I've found that on an 80 column display, tabs at 1 inch, 2 inches, and 3.7 inches work pretty good. For a 40 column display, something like .5 inches, 1.5 inches, and 3 or 3.2 inches is better. You'll want to avoid having to scroll side to side if you can.
On the first page of this source code, type in the following:
.include geosSym .psectThe geosSym file contains many symbols that refer to various parts of GEOS for use in your own programming. The symbol 'EnterDesktop' is defined in this file.
Press ?> a couple of times and add a label to your program code, perhaps ProgStart, as it is in the actual SamSeq file. Even a small application needs to start out with a label--geoProgrammer doesn't seem to like it if you leave this out. The .psect tells geoProgrammer that the code following from this point is to be assembled to run beginning with the current value of the program counter. In other words, this is a 'program section' of code. We will get into this a little later.
At this point in the operation of your application, it will be in control of the machine. The ideal situation is for your application to just do what it needs to do and then put GEOS and the user back in control. If you have written programs for the native mode of your computer, you know what happens when your program ends with an 'rts'. Your program ends and control is returned to the user. This is not the case with GEOS. If you want your program to end, you need to jump to a routine called 'EnterDesktop'. Remember that we are working with a point and click environment. Built within the GEOS Kernal are many routines that have already been written for us. There is a great deal of programming already done that we can avoid including in our own programming.
If you think you are ending your application with an 'rts', you are returning control to the user and to GEOS, but your application is still in use. At this point, the GEOS Kernal is watching for some sort of user response, either from the keyboard or the mouse. If the user performs an action of some sort, GEOS will respond by reentering your application. This portion of GEOS that is running is called 'MainLoop'. Normally, outside of GEOS, you would have to have your own main loop and include the needed programming to catch the user's input. Instead, all that is needed here are lookup tables for MainLoop to look at when it gets a response from the user. If there are no lookup tables, then nothing happens, GEOS ignores the user's actions and the user gets the feeling that the computer has just locked up.
If your application simply performs a job and finishes, you can end it by jumping to EnterDesktop. But if you need some user input, such as clicking on icons or menus, you will need to tell GEOS where to find the appropriate lookup tables before you get to that first rts.
When your program gives control to MainLoop, the user might click the mouse. There is one thing you must keep in mind here. GEOS will look for an icon table. If it does not find one, there will be problems. It doesn't seem to mind if there is no table for menus, but you need to at least provide an icon table even if your application is not going to use icons. This only applies if you return to MainLoop with an rts. If you exit back to the Desktop instead of MainLoop, the user doesn't get control of the mouse anyway and likewise, MainLoop will never get control while your application is running. It all depends on what your application is going to accomplish. If you need user input, your icon table can define an icon that does not exist. This way GEOS won't have a problem. I'll show you how to do that at a later date.
In the SamSeq file supplied with geoProgrammer, you will find an icon table. It will begin with a label called 'IconTable'. This particular table consists of 9 lines. Copy this into the sample file that we are building here. You might want to put it on page 2 to keep it out of the way. Create another label after this table called 'Icon1Picture' just like in the SamSeq file. Following this will go a photo scrap of whatever icon you wish to use. So, load up geoPaint and create a graphic of some sort. Copy it into a photo scrap and then paste that scrap into your source code after the label 'Icon1Picture'. One thing you must remember here is to always put a blank line above and below any photo scrap you put in your source code, so do that now. This insures that geoAssembler knows the exact start and end of the graphic. Can you imagine having to code this graphic into your source code manually? This is pretty handy isn't it?
Within the icon table, we need to tell GEOS how wide and how tall the icon is. Here again, geoAssembler will figure this out for us. As soon as it processes the photo scrap it will place these values into two of its own internal variables, which are called picW and picH. From within your source code, you have access to these variables and can copy these values into your own symbols. This is normally done in your source code immediately following the photo scrap. So, type in the same thing as in the SamSeq file, or cut it to a text scrap and then paste it in your own file. Since you are including ICON1WIDTH =picW and ICON1HEIGHT =picH, whatever values are contained in picW and picH will be in your symbols. You will find a reference to these symbols in the icon table. This is how you get these values to show up in your icon table.
In this icon table, find the reference to DoIcon1. This is the name of the routine that GEOS will jsr to when the user clicks on your icon. For our purpose, let's change this to EnterDesktop. This way, when the user clicks on your icon, your application will simply end.
Let's go back to page 1 and build a little bit of code at the start of our application now. Later on, I will get into the use of macros with geoProgrammer. And you will find that you really can't live without them. It makes your coding so much easier. For right now, we will do without them for demonstration purposes. Anyway, use your tabs and type in the following code:
ProgStart: lda #[IconTable sta $02 lda #]IconTable sta $02+1 jsr DoIcons rtsThat is the extent of our little application here. This along with the icon table, the icon picture, and the header block, is all of the code that will be assembled and linked. Load up geoAssembler and assemble SamSeqHdr and your new SamSeq file. Then load geoLinker and link the resulting .rel files together by selecting the file called SamSeq.lnk. If everything goes good, you will have a finished application that you can load and run from the deskTop.
What our code does here is to point the required zero page register to our icon table and call a GEOS Kernal routine known as DoIcons. This register is usually referred to as r0, and after this we will always call it r0. I will get into this at a later date also. DoIcons will do a couple of things for us. It will first set up a pointer within the GEOS Kernal so that MainLoop knows where to find our icon table. Then it will perform the job of drawing our icon on the screen. Following this it returns to our application. In our case, we just do an rts now and let MainLoop take over and give control to the user.
The user now has full control of the mouse and the keyboard. There is really only one thing that GEOS will let the user do at this point. We did not tell GEOS that we are looking for keyboard input and we did not inform it of any menus either. But we did define one icon. As soon as the user clicks on this icon, GEOS will close out our application and reload the deskTop.
Our icon could have just as easily told GEOS to access another routine within our application. This is how GEOS works, and is called 'event programming'. GEOS watches for an 'event' to happen, and responds accordingly. It's a nice way to do things.