<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.
<sect3>DrawPoint
<p>
-<tt/void DrawPoint (struct pixel *myPixel)/
+<tt/void DrawPoint (char mode, struct pixel *myPixel)/
<p>
-Draws single point on the screen, no matter what the current pattern is.
+Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point
+on the screen.
<sect3>TestPoint
<p>
<sect3>PutChar
<p>
-<tt/void PutChar (char character, char y, char x)/
+<tt/void PutChar (char character, char y, unsigned x)/
<p>
This function outputs single character using current style and font to screen.
<sect3>PutDecimal
<p>
-<tt/void PutDecimal (char parameter, int value, char y, unsigned x)/
+<tt/void PutDecimal (char parameter, unsigned value, char y, unsigned x)/
<p>
This function converts <tt/value/ to its decimal representation and outputs it to the screen.
-Depending on given <tt/parameter/ the string can be filled with zeroes (string always 5 characters
-long) or not, to be left or right justified to given pixel. See <tt/ggraph.h/ for predefined
-values for <tt/parameter/.
+The <tt/parameter/ is the field width in pixels (range 1-31) and mode bits. Depending on them
+the string can be filled with zeroes (string always 5 characters long) or not and left or right
+justified to given pixel. See <tt/ggraph.h/ for predefined values for <tt/parameter/.
<sect2>Font Handling
<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.
At present this file selector handles only first 16 files of given type and supports only one
(current) drive.
+<sect3>MessageBox
+<p>
+<tt/char MessageBox (char mode, const char *format, ...)/
+<p>
+This function is a more general one. It works very much like <tt/printf/ in a
+box. The only difference is <tt/mode/ parameter which allows for placing
+default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values).
+Any too wide text will be clipped to the size of the default window. If mode
+parameter is invalid or equal to <tt/MB_EMPTY/ then the window will be closed
+after a click. Otherwise the user must choose an icon.
+<p>
+Note: use it if you really need (or if you will use it in many places) as
+it adds quite amount of code to your program.
+<p>
+Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check
+for that.
+
<sect1>Mouse, Sprites and Cursors
<p>
You will find here functions related to sprite and mouse drawing and handling.
<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,
<p>
In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
<p>
-NOTE that you <em/must/ use casting to have correct values.
+Note: you <em/must/ use casting to have correct values.
<sect2>Low-level disk IO
<p>
<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/.
Functions covered in this section are common for whole C world - copying memory parts and
strings is one of the main computer tasks. GEOS also has interface to do this. These functions
are replacement for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries.
-
-However some of them have slighty different calling convention (order of arguments to be specific),
+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 slightly different calling convention (order of arguments to be specific),
so please check their syntax here before direct replacing.
-
-Please note that the memory described as <em/strings/ are up to 255 characters (without
-counting the terminating <tt/NULL/), and <em/regions/ cover whole 64K of memory.
+<p>
+Please note that the memory areas described here as <em/strings/ are up to 255 characters (without
+counting the terminating <tt/NULL/), and <em/regions/ can cover whole 64K of memory.
<sect2>CopyString
<p>
<sect2>FillRam and ClearRam
<p>
-<tt/void FillRam (char *dest, char value, unsigned length)/
+<tt/void *FillRam (char *dest, char value, unsigned length)/
<p>
-<tt/void ClearRam (char *dest, unsigned length)/
+<tt/void *ClearRam (char *dest, unsigned length)/
<p>
-Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/NULLs/, while
+Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/0s/, while
<tt/FillRam/ uses given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and
-r2L/ registers. <tt/FillRam/ is an alias for <tt/memset/.
+r2L/ registers. These are aliases for <tt/memset/ and <tt/bzero/, respectively.
<sect2>MoveData
<p>
-<tt/void MoveData (char *dest, char *src, unsigned length)/
+<tt/void *MoveData (char *dest, char *src, unsigned length)/
<p>
This functions copies one memory region to another. There are checks for overlap and the
non-destructive method is chosen. Be warned that this function destroys contents of
<tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
<p>
These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
-You can check for REU presence by taking value of <tt/ramExpSize/.
+You can check for REU presence by taking value of <tt/ramExpSize/. You have to do it before
+using any of these functions.
<sect1>Processes and Multitasking
<p>
<tt/void UnFreezeProcess (char processNumber)/
<p>
<tt/FreezeProcess/ disables timer for given process. <tt/UnFreezeProcess/ does the opposite.
-This is not equal to <tt/RestartProcess/ as timers are not filled with initial value.
+This is not equal to <tt/RestartProcess/ as timers are not reloaded with initial value.
<sect2>Sleep
<p>
<tt/void Sleep (unsigned jiffies)/
<p>
-This function is multitasking sleep - the program is halted, but it doesn't block other functions.
-The only argument here is the number of jiffies to wait until app will wake up.
-<p>
-You can force to sleep not only the main application routine, but also processes-tasks. Be warned
-that the maximum number of sleeping functions is 20. If it would be larger it will overwrite
-parameters of already sleeping functions in GEOS kernal data space, leading to crash.
+This function is multitasking sleep - the program is halted, but it doesn't block other functions
+e.g. callbacks from menus and icons.
+The only argument here is the number of jiffies to wait until app will wake up. It depends on
+video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively).
+If you don't want to worry about it and need only full second resolution, call standard
+<tt/sleep/ function from <tt/unistd.h/.
<sect1>System Functions
<tt/void DoneWithIO (void)/
<p>
These functions are called by some disk routines. You should call them only if you want to
-do something with IO registers or call one of Kernal's routines.
+do something with IO registers or call one of Kernal ROM routines. Note that this is rather an
+expensive way of turning off IRQs and enabling IO.
<sect2>MainLoop
<p>
<p>
<tt/void EnterDeskTop (void)/
<p>
-Calling this function will instantly terminate your program and bring you back to DeskTop.
-WARNING! It is not an equivalent of <tt/exit()/, library destructors code and functions
-registered with <tt/atexit()/ will not be called. In fact, you should always use
-<tt/exit()/ instead.
+This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not
+use it. Always use <tt/exit()/ instead. Library destructors and functions registered with
+<tt/atexit()/ are called.
<sect2>ToBASIC
<p>
<p>
This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC.
I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.
-It has the same dangerous features as <tt/EnterDeskTop/.
+<p>
+<em/WARNING:/ library destructors and functions registered with <tt/atexit()/ will not be called
+so it is quite unsafe way to finish your program.
<sect2>Panic
<p>
<p>
To simplify usage and optimize passing parameters to functions I have declared several structures
which describe most common objects. Some of these structures are bound to static addresses in
-GEOS data space ($8000-$8fff), so you can use their fields directly in optimized way.
+GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in optimized way.
Please see <tt/gsym.h/ and find them. All structures are defined in <tt/gstruct.h/ and you may
find also some comments there.
<p>
This structure describes a font in one pointsize. There is current font - <tt/struct fontdesc/
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
+<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>
It is possible to intercept and hook in the GEOS Kernal using vectors. Here is a little example:
<tscreen><verb>
-void (*oldVector)(void);
+void_func oldVector;
void NewVectorHandler(void) {
// do something and at the end call the old vector routine
<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