<title>GEOSLib docs
<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl">
-<date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003
+<date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003, 2005
<abstract>
This is the documentation of cc65's GEOSLib, but information contained here may be also
-useful for writting GEOS applications in general.
+useful for writing GEOS applications in general.
</abstract>
<!-- Table of contents -->
It is safe to use these standard includes and their contents:
<tt/assert.h, conio.h, dio.h, errno.h, em.h, geos.h, joystick.h, modload.h, mouse.h, stdlib.h, string.h, tgi.h, time.h/
<p>
+For <tt/time.h/ functions <tt/systime()/ and <tt/clock()/ note that the resolution is one second.
+<p>
It was not tested enough, but functions from these includes might work under GEOS:
<tt/rs232.h, zlib.h/
<p>
<sect1>Requirements
<p>
You will not need c64 or c128 for development. The only hardware requirement is a PC capable of
-runing cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your
+running cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your
programs.
The software needed:
disk image files.
<item><em/cbm4linux/ A Linux kernel module that allows for communication with 1541 and
other Commodore IEC bus drives. It can be replacement for Star Commander if
- you want only to transfer files to a disk and uncovert using GEOS program for
+ you want only to transfer files to a disk and unconvert using GEOS program for
this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/"
name="http://www.lb.shuttle.de/puffin/cbm4linux">
</itemize>
<p>
Apart from this file, which merely describes only standard GEOS library functions, you should read
<tt/grc/ (GEOS resource compiler) documentation. There are informations about necessary resource
-files (each GEOS application neeeds at least one) and the building process - what should be done
+files (each GEOS application needs at least one) and the building process - what should be done
and in what order. Please also read cc65's documentation on how to compile C, assembler and link
everything together.
<p>
Do not try to compile in strict ANSI mode. Library uses cc65 extensions which are not available in
ANSI.
<p>
-It is possible to use dynamicaly loaded modules, three such modules are provided:
+It is possible to use dynamically loaded modules, three such modules are provided:
GEOS TGI driver, GEOS EMD driver (for VDC extended memory) and GEOS JOY driver.
Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special
recommendations, read cc65 documentation about modules and demo programs source code.
<sect2>Menus
<p>
-Menus are essencial for GUI. GEOS can handle only one menu at a time, but each menu can call
+Menus are essential for GUI. GEOS can handle only one menu at a time, but each menu can call
another one, which results in submenu tree. There can be up to 8 menu levels, each one with up
to 32 items.
<p>
Icons are working similar to menus except the fact that there is only one level. Icons are
defined as a screen area filled with a bitmap, but if you would setup icons and erase the
screen they are still active and clicking in the place where formerly an icon was will cause
-an effect. Similary if you would setup icons and then turn them off with <tt/ClearMouseMode/
+an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/
the bitmap will be still on the screen but clicking on it would not cause any action.
There is only one, but powerful icon function.
<p>
<tt/void ClearMouseMode (void)/
<p>
-This function disables all mouse actitivies - icons and menus stop to respond to mouse events,
+This function disables all mouse activities - icons and menus stop to respond to mouse events,
but they are not cleared from the screen.
<sect3>MouseUp and MouseOff
<p>
<tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/
<p>
-Similar to previous but needed for writting the disk. <tt/VerWriteBlock/ verifies the data after
-writting. In case of error five tries are attempted before error code is returned.
+Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after
+writing. In case of error five tries are attempted before error code is returned.
<sect2>Directory header
<p>
<p>
<tt/char PutDirHead (void)/
<p>
-These functions are reading and writting the directory header. You should use <tt/GetDirHead/ before
+These functions are reading and writing the directory header. You should use <tt/GetDirHead/ before
using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the
disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/.
<p>
Both functions are allocating enough disk sectors to fit the number of <tt/length/ in them. You
will find output in <tt/output/ which is table of <tt/struct tr_se/. The last entry will have the
-number of track equal to 0 and sector equal to 255. The simpliest way of using them is to use
+number of track equal to 0 and sector equal to 255. The simplest way of using them is to use
predefined space in GEOS data space and pass <tt/fileTrScTab/, which is a predefined table.
<p>
The difference between those two is that <tt/NextBlkAlloc/ will start allocating from given sector,
<tt/datadname/ is copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ goes to <tt/dataFileName/
thus becoming parameters for the new application. Pass <tt/NULL/ as any unused parameter.
-
<sect3>ReadFile
<p>
<tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/
contain all information about a file. The <tt/skip/ parameter says how many directory pages you
want to skip before searching for a free slot for directory entry. In most cases you will put
<tt/0/ there.
-
+<p>
You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one
-difference - the first two bytes which are link to nonexistant next sector are replaced by a
+difference - the first two bytes which are link to nonexistent next sector are replaced by a
pointer to the DOS filename of the file.
-
+<p>
When saving sequential files two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/
and <tt/fileheader.end_address/.
If you are dealing with short strings (up to 255 characters) you should use these functions
instead of standard ones. E.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster.
<p>
-However some of them have slighty different calling convention (order of arguments to be specific),
+However some of them have slightly different calling convention (order of arguments to be specific),
so please check their syntax here before direct replacing.
<p>
Please note that the memory areas described here as <em/strings/ are up to 255 characters (without
bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling
<tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize -
somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can
-pass a pointer to the load adress of that pointsize to <tt/LoadCharSet/. (Note that although
+pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although
it has 'Load' in the name, that function loads only GEOS internal data structures, not data
from disk).
<p>
In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to GEOS
kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/.
+Be warned that vectors are most likely to be changed by GEOS kernal also by other functions (like
+<tt/GotoFirstMenu/, <tt/DoDlgBox/ and its derivatives etc.). It depends on what kernal functions
+you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete
+list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of
+information contained there should be still valid for GEOS 2.0. When calling a function that restores
+the vector you should add a <tt/hook_into_system()/ call right after it.
+<p>
It is critical to restore old vector values before exiting the program. If you have more than one
place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to
be called upon exiting with <tt/atexit(&remove_hook);/ call. This way you will ensure that
projects / cc65 / blobdiff