Functions here are sorted more or less in the way they appear in the header files. This way I am able
to keep functions covering similar tasks near each other. All function names are identical to those
from the geosSym file provided with the GeoProgrammer package. Only my extensions to geosSym
are covered by new names, but I tried to keep them in the naming convention.
This section covers the drawing package of GEOS along with text output routines.
void SetPattern (char pattern)
This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can see them together in the filling box in GeoPaint.
void GraphicsString (char *myGString)
One of the more powerfull routines of GEOS. This function calls other graphic functions depending on the given command string. See the structures chapter for a more detailed description.
Parameters to those functions are grouped in the struct window drawWindow. To speed up things and
reduce overhead this structure is bound to zero page locations, where all rectangle functions
expect their parameters. You can modify the data directly (e.g. drawWindow.top=10) or via the
InitDrawWindow function. Contents of drawWindow are guaranteed not to change when only
using graphics functions. In other cases you should keep your data in separate struct window
and use InitDrawWindow before the first call to one of the rectangle functions.
void InitDrawWindow (struct window *myWindow)
This function only copies the contents of myWindow into the system area of drawWindow. Use it
if for some reason you have to keep your window data out of the zero page space.
void Rectangle (void)
This draws on screen a rectangle filled with the current pattern.
void FrameRectangle (char pattern)
This one draws a frame with the given bit pattern (not a pattern from the GEOS palette).
void InvertRectangle (void)
Just as the name says...
void ImprintRectangle (void)
void RecoverRectangle (void)
These two functions are for copying parts of the screen to (Imprint) and from (Recover) the
backbuffer of the screen. For example when drawing a new menu box GEOS first uses
ImprintRectangle to save the area under the box, and restores it by RecoverRectangle upon
destroying the menu.
The GEOS drawing package is optimized so there are different functions for drawing vertical and horizontal lines.
void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)
This function draws a horizontal line using the given pattern. Note that pattern is not a pattern
number as set in SetPattern but a true bit pattern.
void InvertLine (char y, unsigned xStart, unsigned xEnd)
There is only a horizontal version.
void RecoverLine (char y, unsigned xStart, unsigned xEnd)
This function recovers a single line. It is utilized by RecoverRectangle. See its description
for more details.
void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)
This function draws a vertical line using the given pattern. Note that pattern is not a pattern
number as set in SetPattern but a true bit pattern.
void DrawLine (char mode, struct window *myWindow)
The top parameters of struct window describe the starting point of the line, while
bottom ones are for the ending point. If mode is DRAW_DRAW then the current pattern from
SetPattern is used for drawing. If mode is DRAW_ERASE then the line is erased from the
screen. If mode is DRAW_COPY then the line is copied from/to back/frontbuffer, according to
the dispBufferOn setting.
The parameters to these two functions are passed by a pointer to an own struct pixel filled with
proper values.
void DrawPoint (char mode, struct pixel *myPixel)
Depending on mode (see DrawLine) draws/erases/copies a single point
on the screen.
char TestPoint (struct pixel *myPixel)
This function tests if the given pixel is set and returns true (non-zero) or false (zero).
void PutChar (char character, char y, unsigned x)
This function outputs a single character using the current style and font to the screen.
void PutString (char *myString, char y, unsigned x)
Same as PutChar except the fact that you can output a whole NULL-terminated string.
See ggraph.h for the list of tokens that you can also place in the string - like CBOLDON or
COUTLINEON.
void PutDecimal (char parameter, unsigned value, char y, unsigned x)
This function converts value to its decimal representation and outputs it to the screen.
The parameter is the field width in pixels (range 1-31) and the mode bits. Depending on them
the string can be filled with zeroes (the string is always 5 characters long) or not and left or right
justified to the given pixel. See ggraph.h for predefined values for parameter.
char GetCharWidth (char character)
This function returns the real width (in pixels) of the given character with the current font. It can be used for counting the length of a string on the screen, allowing for indentation or justification.
void LoadCharSet (struct fontdesc *myFont)
This function forces GEOS to use the given font. myFont should be casted from a
pointer to the start of the area where a record from a font file (VLIR structure) was loaded.
void UseSystemFont (void)
This function forces GEOS to use the built-in BSW font.
I'm not quite sure how these functions are working (except BitmapUp) so you should
probably look into the library sources and compare it with your knowledge. Please let me know
if something is wrong or broken.
void BitmapUp (struct iconpic *myPic)
This function unpacks the bitmap and places it on the screen - just as you set it in the
struct iconpic pointer which you pass. See gstruct.h for a description of this
structure. Note that you can only use packed GEOS bitmaps - a simple Photo Scrap is in this format.
void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)
This function acts similar to BitmapUp but you can also define which parts of the bitmap are
to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap,
and the number of rows to skip from the top if it.
void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop,
struct iconpic *myPic)
Similar to the previous one with some extension. proc1 is called before reading a byte (it
returns in .A the next value), and proc2 is called every time the parser reads a byte which is
not a piece of a pattern (byte of code greater than 219). Both procedures should be written
separately in assembler and declared as __fastcall__ returning char.
Here you will find information about functions related with menus and icons.
Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up to 32 items.
Menus are initialized with DoMenu and then the Kernal takes care of everything. Your code
(called from an event handler) should be a function without parameters, returning void. You should
use DoPreviousMenu or GotoFirstMenu at least once in its code to have the screen clean.
void DoMenu (struct menu *myMenu)
This function initializes the GEOS menu processor and exits. See DoMenu structure for more
information about it. Know that many GEOS applications just initialize the screen, menu and
exit to the main Kernal loop, this proves the power of DoMenu.
void ReDoMenu (void)
This simply redraws the menu at the lowest level. It works like calling DoMenu again with
the same parameters.
void RecoverMenu (void)
This function erases the current menu from the screen. It doesn't change the menu level.
void RecoverAllMenus (void)
This calls RecoverMenu and erases all menus from the screen. Then the menu level is
set to 0 (topmost).
void DoPreviousMenu (void)
This functions causes the menu processor to go back one menu level. You should use it in menu handler code to have the screen clean.
void GotoFirstMenu (void)
This one jumps back to the topmost menu. If there is only a menu and one submenu it works the
same as DoPreviousMenu.
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 would still be active and clicking in the place where formerly an icon was would cause
an effect. Similarly if you would setup icons and then turn them off with ClearMouseMode
the bitmap would still be on the screen but clicking on it would not cause any action.
There is only one, but powerful icon function.
void DoIcons (struct icontab *myIconTab)
This function initializes all icons that are present on the screen at once. For more information
look at the Icons chapter in this manual.
This chapter covers the most powerful GEOS user interface function - DoDlgBox.
char DoDlgBox (char *dialogString)
This function returns one byte. It can be the value of one of six standard icons (see gdlgbox.h)
or whatever the closing routine passes. Register r0L also contains this value.
Read the structures chapter for the specs of the dialogString.
char RstrFrmDialogue
This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns the owner ID (or whatever caller has in the .A register).
To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox, with predefined data. In one word - these are standard DialogBoxes you can see in almost every GEOS application.
char DlgBoxYesNo (char *line1, char *line2)
char DlgBoxOkCancel (char *line1, char *line2)
void DlgBoxOk (char *line1, char *line2)
These function show two lines of text in a standard-sized DialogBox. You can read the code of the
pressed icon from the return value. E.g. for DlgBoxYesNo it can only be YES or NO.
You can pass an empty string or NULL to get a blank line.
char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)
This function prompts the user to enter a string of at most strlen characters. It is returned
in string. The two given lines of text are shown above the input line. Please remember
that there is also a CANCEL icon in the DialogBox and you should test if user confirmed his
input or gave up. The string is also shown so you can place a default input there or remember
to place NULL at start.
char DlgBoxFileSelect (char *class, char filetype, char *filename)
This routine is the standard file selector. It can return OPEN, CANCEL or disk error
on reading the directory or opening the disk.
There is also a DISK icon shown, but it is handled internally. You pass as input parameters
filetype and a pointer to a string containing the first part of a file's class. If this string is
empty (NULL at the start), then all files with given filetype will be shown.
At present this file selector handles only first 16 files of given type and supports only one (current) drive.
char MessageBox (char mode, const char *format, ...)
This function is a more general one. It works very much like printf in a
box. The only difference is the mode parameter which allows for placing
default icons (see gdlgbox.h for list of possible MB_ values).
Any too wide text will be clipped to the size of the default window. If mode
is invalid or equal to MB_EMPTY then the window will be closed
after a click. Otherwise the user must choose an icon.
Note: Use it if you really need (or if you use it in many places) as it adds quite amount of code to your program.
Note: the formatted text cannot exceed 255 bytes in length, there is no check for that.
You will find here functions related to sprite and mouse drawing and handling.
These cover the mouse - as a general pointing device, but expect users to utilize as different devices as a digital or analog joystick, a mouse, a lightpen or a koalapad (whatever it is).
void StartMouseMode (void)
This function initializes the mouse vectors - mouseVector and mouseFaultVec, and then
calls MouseUp.
void ClearMouseMode (void)
This function disables all mouse activities - icons and menus stop to respond to mouse events, but they are not cleared from the screen.
void MouseUp (void)
void MouseOff (void)
The first function turns the mouse pointer on. It appears on the next IRQ. The second one does the opposite - it turns off the pointer, but its position is still updated by the input driver.
char IsMseInRegion (struct window *myWindow)
This function tests if the mouse pointer is actually in the given range of the screen. See gsprite.h for
a description of the bits in the return values - they describe the position in detail.
You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about 40/80 column issues because GEOS128 has a pretty good sprite emulator for the VDC.
void DrawSprite (char sprite, char *mySprite)
This function initializes the sprite data. mySprite is a 63-byte table with bitmap data, which
is copied to the system sprite area (at sprpic - see gsym.h). Hardware sprite registers are
not initialized and the sprite is not yet visible.
void PosSprite (char sprite, struct pixel *myPixel)
This function positions the sprite on the screen. The given coordinates are screen ones - they are converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your sprite off the left or top to the screen.
void EnablSprite (char sprite)
void DisablSprite (char sprite)
These two functions are responsible for making the sprite visible or not.
void InitTextPrompt (char height)
This function initializes sprite 1 for a text prompt with given height. This parameter can be in
range 1-48.
void PromptOn (struct pixel *myPixel)
void PromptOff (void)
The first function places a text prompt in given place and enables blinking. The second one is pretty self-explanatory.
char GetNextChar (void)
This function gets the next character from the keyboard queue. If the queue is empty it returns
NULL, otherwise you receive the true ASCII code of a character or the value of a special (function)
key. See gsprite.h for the list of them.
This chapter covers rather low-level disk routines. You should use them with care, because you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be dangerous.
For some purposes you might consider using the dio.h interface to disk access. It is native.
All GEOS disk functions return an error code in the X register. In some cases this is returned by the
GEOSLib function (if its type is char), but in all cases the last error is saved in the __oserror
location. If it is nonzero - an error occured. See gdisk.h for the list of possible errorcodes.
You need to include errno.h to get __oserror, together with the standard errno. The
latter gives less verbose, but still usable information and can be used with strerror.
Probably you will get more information using _stroserror in a similar way.
For passing parameters use almost always a pointer to your data e.g. ReadBuff (&myTrSe).
These functions take a single data sector (256 bytes) to read or write on the disk.
char ReadBuff (struct tr_se *myTrSe)
char WriteBuff (struct tr_se *myTrSe)
These functions read and write a sector placed at diskBlkBuf.
char GetBlock (struct tr_se *myTrSe, char *buffer)
char ReadBlock (struct tr_se *myTrSe, char *buffer)
These two functions read a single block directly to the 256 byte array placed at buffer.
The difference between them is that GetBlock initializes TurboDos in the drive if it was not
enabled. ReadBlock assumes that it is already enabled thus being slightly faster.
char PutBlock (struct tr_se *myTrSe, char *buffer)
char WriteBlock (struct tr_se *myTrSe, char *buffer)
char VerWriteBlock (struct tr_se *myTrSe, char *buffer)
Similar to previous but needed for writing the disk. VerWriteBlock verifies the data after
writing. In case of an error five tries are attempted before an error code is returned.
The functions described here operate on curDirHeader where the current disk header is stored.
On larger (than 1541) capacity drives the second part of the directory header is in dir2Head.
void GetPtrCurDkNm (char *diskName)
This function fills the given character string with the name of current disk. It is converted to C
standard - the string is terminated with NULL character instead of code 160 as in Commodore DOS.
Note that the passed pointer must point to an array of at least 17 bytes.
char GetDirHead (void)
char PutDirHead (void)
These functions read and write the directory header. You should use GetDirHead before
using any functions described below, and you should use PutDirHead to save the changes on the
disk. Otherwise they will be lost. Operating area is the curDirHead.
unsigned CalcBlksFree (void)
This function returns the number of free blocks on the current disk. It is counted using data in
curDirHead so you must initialize the disk before calling it.
char ChkDskGEOS (void)
This functions checks curDirHead for the GEOS Format identifier. It returns either true or false,
and also sets isGEOS properly. You must initialize the disk before using this.
char SetGEOSDisk (void)
This function initializes disk for use with GEOS. It sets the indicator in directory header and allocates a sector for the directory of border files. You don't need to initialize the disk before using.
char FindBAMBit (struct tr_se *myTrSe)
This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is set if the sector is free to use. The returned value is always zero if the sector is already allocated. In fact, this function could be used in a following way:
#define BlockInUse FindBAMBit
...
if (!BlockInUse(&myTrSe)) {
... block not allocated ...
}
Anyway, I feel that this function is too low-level.
char BlkAlloc (struct tr_se output[], unsigned length)
char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[], unsigned length)
Both functions allocate enough disk sectors to fit length bytes in them. You
find the output in output which is a table of struct tr_se. The last entry will have the
track equal to 0 and sector equal to 255. The simplest way of using them is to use
predefined space in the GEOS data space and pass fileTrScTab, which is a predefined table.
The difference between those two is that NextBlkAlloc starts allocating from the given sector,
and BlkAlloc starts from the first nonused sector.
You need to use PutDirHead later to save any changes in BAM.
char FreeBlock (struct tr_se *myTrSe)
Simply deallocates a block in the BAM. You need to update the BAM with PutDirHead.
struct tr_se SetNextFree (struct tr_se *myTrSe)
This function finds the first free sector starting from given track and sector and allocates it.
It might return the same argument if the given block is not allocated. I wanted it to be type
clean, but this made the usage a bit tricky. To assign a value to your own struct tr_se you have to
cast both variables to unsigned. E.g.
struct tr_se myTrSe;
...
(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe);
In this example otherTrSe can be replaced by myTrSe.
Note: you must use casting to have the correct values.
Functions described here are more usable in Kernal or drivers code, less common in applications, but who knows, maybe someone will need them.
void EnterTurbo (void)
void ExitTurbo (void)
void PurgeTurbo (void)
These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit
more usable. EnterTurbo enables TurboDos unless it is already enabled. If not, then you will
have to wait a bit to transfer the TurboDos code into disk drive RAM. ExitTurbo disables TurboDos.
This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any
interaction with the Kernal in ROM you have to call InitForIO. You don't have to worry about speed.
EnterTurbo will only enable TurboDos (no code transfer) if TurboDos was disabled with
ExitTurbo. PurgeTurbo acts differently from ExitTurbo - it not only disables TurboDos,
but also removes it from drive RAM (not quite true, but it works like that). After using
PurgeTurbo the next call to EnterTurbo will reload drive RAM.
char ChangeDiskDevice (char newDevice)
This function changes the device number of the current device (in fact drives only) to the given one. It is
usable for swapping drives. There's no check if the given newDevice already exist, so if you want
to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably
hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30.
GEOS has two functions for initialization ('logging in' as they say on CP/M) of a disk.
char OpenDisk (void)
This function initializes everything for a new disk. It loads and enables TurboDos if needed.
Then the disk is initialized with NewDisk. Next, GetDirHead initializes curDirHead.
Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is
checked with ChkDkGEOS and the disk name is updated in the internal tables.
char NewDisk (void)
This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed.
This section covers the GEOS file interface.
The functions described here are common for SEQ and VLIR structures.
struct filehandle *Get1stDirEntry (void)
struct filehandle *GetNxtDirEntry (void)
These two functions are best suited for scanning the whole directory for particular files. Note that
the returned filehandles describe all file slots in the directory - even those with deleted files.
The return value can be obtained by casting both sides to unsigned - as in the SetNextFree
function or read directly after a call to those two functions from r5. The current sector number
is in r1 and the sector data itself is in diskBlkBuf.
char FindFile (char *fName)
This function scans the whole directory for the given filename. It returns either 0 (success) or 5
(FILE_NOT_FOUND, defined in gdisk.h) or any other fatal disk read error. After a successful
FindFile you will have struct filehandle at dirEntryBuf filled with the file's data and
other registers set as described in GetNxtDirEntry.
char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)
This function scans the directory and fills a table at buffer with char [17] entries.
fType is the GEOS type of the searched files and classTxt is a string for the Class field in the file
header. Class matches if the given string is equal or shorter than that found in the file's header block.
If you want just to find all files with the given GEOS type you should pass an empty string or NULL as
classTxt. Be warned that for searching NON_GEOS files you must pass NULL as classTxt.
fMaxNum is the maximal number of files to find, thus the buffer must provide an area of size
equal to 17 * fMaxNum. This function returns the number of found files, ranging from 0 to number
passed as fMaxNum. The return value can be also restored from r7H.
char DeleteFile (char *fName)
This function deletes a file by its name. It works for SEQ and VLIR files.
char RenameFile (char *oldName, char *newName)
I think it is obvious...
char GetFHdrInfo (struct filehandle *myFile)
This function loads the file header into the fileHeader buffer. Using after e.g. FindFile
you can pass the address of dirEntryBuf.
Functions described here are common for SEQ and VLIR structures because the arguments passed are the starting track and sector which may point either to the start of a chain for VLIR or the data for SEQ.
char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)
This routine loads and runs a given file fname. The file must be one of following types:
SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER, or INPUT_DEVICE. The execution
address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain
from VLIR files is loaded. If flag has bit 0 set then the load address is taken from loadaddr
and not from the file header. In this case APPLICATION files will be only loaded, not executed.
This does not apply to DESK_ACC. If either bit 6 or 7 of flag are set, then 16 bytes from
datadname are copied to dataDiskName and 16 bytes from datafname go to dataFileName
thus becoming parameters for the new application. Pass NULL for any unused parameter.
char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)
This function reads at most fLength bytes into buffer from chained sectors starting at
myTrSe.
char ReadByte (void)
This function returns the next byte from a file. Before the first call to it you must load r5
with NULL, r4 with the sector buffer address and r1 with the track and sector of the
first block of a file.
Remember to not modify r1, r4 and r5. These registers must be preserved between
calls to ReadByte.
The returned value is valid only if there was no error. The end of file is marked as BFR_OVERFLOW
in __oserror, this is set when trying to read one byte after the end of file, in this case the
returned value is invalid.
char SaveFile (char skip, struct fileheader *myHeader)
SaveFile will take care of everything needed to create a GEOS file, no matter if VLIR of SEQ
structure. All you need to do is to place the data in the proper place and prepare a header which will
contain all information about a file. The skip parameter says how many directory pages you
want to skip before searching for a free slot for the directory entry. In most cases you will put
0 there.
You have to declare a struct fileheader and fill it with proper values. There is only one
difference - the first two bytes which are a link to a nonexistent next sector are replaced by a
pointer to the DOS filename of the file.
When saving sequential files the two most important fields in struct fileheader are fileheader.load_address
and fileheader.end_address.
char FreeFile (struct tr_se myTable[])
This function deallocates all sectors contained in the passed table.
char FollowChain(struct tr_se *myTrSe, char *buffer)
This function fills a struct tr_se table at buffer with the sector numbers for a chain of
sectors starting with myTrSe. You can pass such data (buffer) to e.g. FreeFile.
Here is information about VLIR files (later called RecordFiles) and functions.
A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one
SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and
an own number. Each record pointed to by its number is described by the starting track and sector numbers.
VLIR structures allow records to be empty (tr_se of such record is equal to {NULL,$ff}),
or even non-exist ({NULL,NULL}). Any other numbers represent the starting track and sector of
a particular file.
In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information
about it is copied into memory. You can retrieve the records table at fileTrScTab (table of
128 struct tr_se) and from VLIRInfo (struct VLIR_info.
E.g. the size of whole VLIR file can be retrieved by reading VLIRInfo.fileSize.
char OpenRecordFile (char *fName)
This function finds and opens a given file. An error is returned if the file is not found or if it is not
in VLIR format. Information in VLIRInfo is initialized. VLIR track and sector table is
loaded at fileTrScTab and will be valid until a call to CloseRecordFile so don't modify it.
You should call PointRecord before trying to do something with the file.
char CloseRecordFile (void)
This function calls UpdateRecordFile and clears internal GEOS variables.
char UpdateRecordFile (void)
This function will check the VLIRInfo.fileWritten flag and if it is set, then curDirHead is
updated along with size and date stamps in the directory entry.
char PointRecord (char recordNumber)
This function will setup internal variables (and VLIRInfo.curRecord) and return the track and
sector of the given record in r1. Note that the data may not be valid (if the record is non-existing
you will get 0,0 and if it is empty - 255,0).
char NextRecord (void)
char PreviousRecord (void)
These two work like PointRecord. Names are self-explanatory.
char AppendRecord (void)
This function will append an empty record (pair of 255,0) to the current VLIR track and sector
table. It will also set VLIRInfo.curRecord to its number.
char DeleteRecord (void)
This function will remove the current record from the table, and move all current+1 records one place
back (in the table). Note that there's no BAM update and you must call UpdateRecordFile to
commit changes.
char InsertRecord (void)
This function will insert an empty record in place of VLIRInfo.curRecord and move all following
records in the table one place forward (contents of VLIRInfo.curRecord after a call to InsertRecord
can be found in VLIRInfo.curRecord + 1).
char ReadRecord (char *buffer, unsigned fLength)
char WriteRecord (char *buffer, unsigned fLength)
This function will load or save at most fLength bytes from the currently pointed record into or from
buffer.
The functions covered in this section are common for the whole C world - copying memory parts and
strings is one of the main computer tasks. GEOS also has an interface to do this. These functions
are replacements for those like memset, memcpy, strcpy etc. from standard libraries.
If you are dealing with short strings (up to 255 characters) you should use these functions
instead of standard ones, e.g. CopyString instead of strcpy. It will work faster.
However some of them have slightly different calling conventions (order of arguments to be specific), so please check their syntax here before a direct replacement.
Please note that the memory areas described here as strings are up to 255 characters (without
counting the terminating NULL), and regions can cover the whole 64K of memory.
void CopyString (char *dest, char *src)
This function copies the string from src to dest, until it reaches NULL. The NULL
is also copied.
char CmpString (char *s1, char *s2)
This function compares the strings s1 to s2 for equality - this is case sensitive, and both
strings have to have the same length. It returns either true (non-zero) or false (zero).
void CopyFString (char length, char *dest, char *src)
char CmpFString (char length, char *s1, char *s2)
These two are similar to CopyString and CmpString except the fact, that you provide
the length of the copied or compared strings. The strings can also contain several NULL
characters - they are not treated as delimiters.
unsigned CRC (char *src, unsigned length)
This function calculates the CRC checksum for the given memory range. I don't know if it is compatible with standard CRC routines.
void *FillRam (char *dest, char value, unsigned length)
void *ClearRam (char *dest, unsigned length)
Both functions are filling the given memory range. ClearRam fills with 0s, while
FillRam uses the given value. Be warned that these functions destroy r0, r1 and
r2L registers. The functions are aliases for memset and bzero, respectively.
void *MoveData (char *dest, char *src, unsigned length)
This functions copies one memory region to another. There are checks for an overlap and the
non-destructive method is chosen. Be warned that this function destroys contents of the
r0, r1 and r2 registers. This function is an alias for memcpy.
void InitRam (char *table)
This function allows to initialize multiple memory locations with single bytes or strings.
This is done with a table where everything is defined. See the structures chapter for a description of
InitRam's command string.
void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)
void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)
void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)
char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)
These functions are the interface to a REU - Ram Expansion Unit. I think that they are self-explanatory.
You can check for REU presence by taking the value of ramExpSize. You have to do it before
using any of these functions.
Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions called in specified intervals and you can put the main program to sleep without disturbing other tasks and making the user interface unresponsive.
void InitProcesses (char number, struct process *processTab)
This is the main initialization routine. After calling it processes are set up, but not
enabled. The parameters for InitProcesses are:
number - number of processesprocessTab - a table of struct process, with size equal to numberA single task is described by an entry in processTab, it contains two values - a pointer to
the task function and a number of jiffies which describe the delay between calls to task. On PAL
systems there are 50 jiffies per second, while on NTSC there are 60.
The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
if processTab would be too large it would overwrite existing data in GEOS space.
There's one important thing - the last entry in processTab has to be NULL,NULL, so the
maximum size of processTab is equal to 21.
See the description of process structure for a more detailed discussion on this.
void RestartProcess (char processNumber)
void EnableProcess (char processNumber)
These two functions start the task counter. RestartProcess should be called for each process
after InitProcesses, because it resets all flags and counters and it starts the counters.
RestartProcess enables the counters and sets their initial value to that given in processTab.
EnableProcess forces the given process to execute by simulating the timer expiring.
void BlockProcess (char processNumber)
void UnblockProcess (char processNumber)
BlockProcess disables the execution of the given process, but this does not disable the timers.
It means that if you call UnblockProcess before the timer runs out, the process will be executed.
UnblockProcess does the opposite.
void FreezeProcess (char processNumber)
void UnfreezeProcess (char processNumber)
FreezeProcess disables timer for given process. UnfreezeProcess does the opposite.
This is not equal to RestartProcess as timers are not reloaded with initial value.
void Sleep (unsigned jiffies)
This function is a 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 the app will wake up. It depends on the
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 the standard
sleep function from unistd.h.
void FirstInit (void)
This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot up. You shouldn't use this unless you know what you are doing.
void InitForIO (void)
void DoneWithIO (void)
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 the Kernal ROM routines. Note that this is rather an expensive way of turning off IRQs and enabling IO.
void MainLoop (void)
Returns control to the system. Any code between call to MainLoop and the end of current
function will never be executed. When in MainLoop the system waits for your action - using
icons, keyboard or menus to force some specific action from the program. You have to define
proper handlers before that.
void EnterDeskTop (void)
This is an alias for exit(0) so you will never burn yourself. Anyway, you should not
use it. Always use exit() instead. Library destructors and functions registered with
atexit() are called.
void ToBASIC (void)
This one is another way of terminating an 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 I doubt.
WARNING: library destructors and functions registered with atexit() will not be called
so it is quite unsafe way to terminate your program.
void Panic (void)
This calls system's Panic handler - it shows a dialog box with the message
System error at:xxxx
xxxx is last known execution address (caller). By default this is bound to the BRK
instruction, but it might be usable in debugging as kind of assert. (Note that assert
is available as a separate function and will give you more information than that).
The system is halted after a call to Panic which means that library destructors will not be
called and some data may be lost (no wonder you're panicking).
void CallRoutine (void *myFunct)
This is a system caller routine. You need to provide a pointer to a function and it will be immediately
called, unless the pointer is equal to NULL. This is the main functionality of this function -
you don't need to check if the pointer is valid.
unsigned GetSerialNumber (void)
This function returns the serial number of the system. It might be used for copy-protection. However, please remember that Free Software is a true power and you are using it right now.
char GetRandom (void)
This function returns a random number. It can be also read from random e.g.
a=random;
random is updated once a frame (50Hz PAL) and on every call to GetRandom.
Note that this is not the same as the rand function from the standard library. GetRandom
will give you unpredictable results (if IRQs occur between calls to it) while
rand conforms to the standard and for a given seed (srand) always returns with the
same sequence of values.
void SetDevice (char device)
This function sets the current device to the given. It might be used together with InitForIO,
DoneWithIO and some Kernal routines. Unless the new device is a disk drive this only sets
new value in curDevice, in the other case new disk driver is loaded from REU or internal RAM.
char get_ostype (void)
This function returns the GEOS Kernal version combined (by logical OR) with the machine type. Read
gsys.h for definitions of the returned values.
char get_tv (void)
This function returns the PAL/NTSC flag combined (by logical OR) with the 40/80 columns flag. This is
not the best way to check if the screen has 40 or 80 columns since a PAL/NTSC check is always
performed and it can take as long as a full raster frame. If you just want to know if the
screen has 40 or 80 columns use the expression graphMode & 0x80 which returns 0 for
40 columns and 0x80 for 80 columns. Remember that this value can be changed during
runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test
anything if not running under GEOS128. Use get_ostype to check it. Read gsys.h for
definitions of the returned values.