Functions here are sorted more or less in the way they appear in header files. This way I am able
to keep functions covering similar task near each other. All function names are identical to those
from geosSym
file provided with 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 drawing package of GEOS along with text output routines.
void SetPattern (char pattern)
This function sets current pattern to 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 given command string. See structures chapter for more detailed description of the structure of it.
Parameters to those functions are grouped in struct window drawWindow
. To speed up things and
reduce overhead this structure is glued to zero page locations, where all rectangle functions
expect their parameters. You can modify data directly (e.g. drawWindow.top=10
) or via
InitDrawWindow
function. Contents of drawWindow
are guaranteed not to change only when
using graphics functions. In other case you should keep your data in separate struct window
and use InitDrawWindow
before first call to rectangle functions.
void InitDrawWindow (struct window *myWindow)
This function only copies contents of myWindow
into system area of drawWindow
. Use it
if for some reason you have to keep window data out of zero page space.
void Rectangle (void)
This draws on screen rectangle filled with current pattern.
void FrameRectangle (char pattern)
This one draws frame with given line pattern.
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
)
backbuffer of the screen. For example GEOS drawing new menus on screen first uses
ImprintRectangle
to save the area under menu, and restores it by RecoverRectangle
upon
destroying the menu.
GEOS drawing package is optimized so there are different functions for drawing vertical and horizontal lines.
void HorizontalLine (char pattern, char y, int xStart, int xEnd)
This function draws horizontal line using given pattern - here it is a true bit pattern, not
pattern set by SetPattern
.
void InvertLine (char y, int xStart, int xEnd)
There is only horizontal version.
void RecoverLine (char y, int xStart, int xEnd)
This function recovers only one line. It is utilized by RecoverRectangle
. See its description
for more details.
void VerticalLine (char pattern, char yStart, char yEnd, int x)
This function draws vertical line using given pattern. Note that pattern
is not a pattern
number as set in SetPattern
but a true bit pattern.
void DrawLine (struct window *myWindow)
top
parameters of struct window
describe the starting point of the line, while
bottom
are for the ending point. Current pattern is used for drawing.
Parameters to these two functions are passed by a pointer to own struct pixel
filled with
proper values.
void DrawPoint (struct pixel *myPixel)
Draws single point on the screen, no matter what the current pattern is.
char TestPoint (struct pixel *myPixel)
This function tests if given pixel is set and returns true or false.
void PutChar (char character, char y, char x)
This function outputs single character using current style and font to screen.
void PutString (char *myString, char y, int x)
Same as PutChar
except the fact that you can output whole NULL
-terminated string.
See ggraph.h
for list of tokens that you can also place in the string - like CBOLDON
or
COUTLINEON
.
void PutDecimal (char parameter, int value, char y, int x)
This function converts value
to its decimal representation and outputs it to the screen.
Depending on given 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 ggraph.h
for predefined
values for parameter
.
char GetCharWidth (char character)
This function returns real width (in pixels) of given character with current font. It can be used for counting the length of string on screen, allowing for indentation or justification.
void LoadCharSet (struct fontdesc *myFont)
This function forces GEOS to use given font instead of own. myFont
should be casted from
pointer to the start of area where was loaded record from font file (VLIR structure).
void UseSystemFont (void)
This function forces GEOS to use built-in BSW font.
I'm not quite sure how are these functions working (except BitmapUp
) so you should
probably look into 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 to which you pass. See gstruct.h
for description of this
structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.
void BitmapClip (char skipLeft, char skipRight, int 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, int skipTop,
struct iconpic *myPic)
Similar to the previous one with some extension. proc1
is called before reading a byte (it
returns in .A next value), and proc2
is called every time the parser reads a byte which is
not a piece of 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 essencial 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.
Menus are initialized with DoMenu
and then Kernal takes care for everything. Your code
(called from 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 GEOS menu processor and exits. See DoMenu structure
for more
information about it. Know that many GEOS application just initializes the screen, menu and
exits to main Kernal loop, this proves the power of DoMenu
.
void ReDoMenu (void)
This simply redraws the menu at lowest level. It works like calling DoMenu
again with
the same parameters.
void RecoverMenu (void)
This function erases 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 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 menu and 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 are still working and cliking in the place where formerly an icon was will cause
an effect. Similary if you would setup icons and then turn them off with ClearMouseMode
the bitmap will be still on the screen.
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 Icons
chapter in this manual.
This chapter covers the most powerful GEOS function - DoDlgBox
.
char DoDlgBox (char *dialogString)
DialogBox returns one byte. It can be the value of one of six standard icons (see gdlgbox.h
)
or whatever closing routine passes. Register r0L
also contains this value.
Read structures chapter for the specs of the dialogString
.
char RstrFrmDialogue
This function called from within DialogBox event immediately closes the DialogBox and returns the owner ID (or whatever caller has in the .A register).
To simplify usage of DoDlgBox from C I've wrote some help 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 standard-sized DialogBox. You can read the code of
pressed icon from return value. E.g. for DlgBoxYesNo
it can only be YES
or NO
.
char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)
This function prompts user for entering 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 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 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 DISK
icon shown, but it is handled internally. You pass as input parameters
filetype
and pointer to string containing the first part of 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.
You will find here functions related to sprite and mouse drawing and handling.
These cover mouse - as a general pointing device, but expect user to utilize as different devices as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).
void StartMouseMode (void)
This function initializes mouse vectors - mouseVector
and mouseFaultVec
, and then
calls MouseUp
.
void ClearMouseMode (void)
This function disables all mouse actitivies - icons and menus stop to respond to mouse events, but they are not cleared from the screen.
void MouseUp (void)
void MouseOff (void)
The fist function turns the mouse pointer on. It will appear on next IRQ. The second one does the opposite - it turns off the pointer, but its position is still updated by input driver.
char IsMseInRegion (struct window *myWindow)
This function tests if mouse pointer is actually in given range of screen. See gsprite.h
for
possible 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 is used as text prompt.
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 system sprite area (at sprpic
- see gsym.h
). Sprite visual registers are
not initialized and sprite is not yet visible.
void PosSprite (char sprite, struct pixel *myPixel)
This function positions the sprite on the screen. Given coordinates are screen ones - they are converted to sprite coords 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 the fact if the sprite will or will not appear on the screen.
void InitTextPrompt (char height)
This function initializes sprite 1 for 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 text prompt in given place and enables it so it blinks and generally is visible. The second function is pretty self-explanatory.
char GetNextChar (void)
This function gets next character from the keyboard queue. If the queue is empty it returns
NULL
, otherwise you receive true ASCII code of a character or value of special (function)
key. See gsprite.h
for list of them.
This chapter covers slightly 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.
All GEOS disk functions return error code in X register. In some cases this is returned by
GEOSLib function (if its type is char
), but in all cases last error is saved in errno
location. If it is nonzero - an error occured. See gdisk.h
for list of errorcodes.
Passing parameters use always e.g. ReadBuff (&myTrSe)
.
These functions are taking single data sector (256 bytes) to read or write on a disk.
char ReadBuff (struct tr_se *myTrSe)
char WriteBuff (struct tr_se *myTrSe)
These functions are reading and writting sector placed at diskBlkBuf
.
char GetBlock (struct tr_se *myTrSe, char *buffer)
char ReadBlock (struct tr_se *myTrSe, char *buffer)
These two functions are reading a single block directly at 256 byte array placed at buffer
.
The difference between them is that GetBlock
will initialize TurboDos in 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 writting the disk. VerWriteBlock
verifies the data after
writting. In case of error five tries are attempted before error code is returned.
Functions described here are operating on curDirHeader
where current disk header is stored.
On larger capacity drives (than 1541) the second part of directory header in dir2Head
.
void GetPtrCurDkNm (char *diskName)
This function fills given character string with the name of current disk. It is converted to C
standard - string is terminated with NULL
character instead of code 160 as in Commodore DOS.
Note that passed pointer must point to an array of at least 17 bytes.
char GetDirHead (void)
char PutDirHead (void)
These functions are reading and writting 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
.
int CalcBlksFree (void)
This function returns the number of free blocks on 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 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 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 BAM (Block Allocation Map) for given sector. The bit is
set if the sector is free to use. Returned value is always zero if the sector is already allocated.
In fact, this function could be described as e.g. SectInUse
and used in following way:
...
if (!SectInUse(&myTrSe)) {
... block not allocated ...
}
Anyway, I feel that this function is slightly low-level, maybe too low-level.
char BlkAlloc (struct tr_se output[], int length)
char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[], int length)
Both functions are allocating enough disk sectors to fit the number of length
in them. You
will find output in output
which is table of 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
predefined space in GEOS data space and pass fileTrScTab
, which is a predefined table.
The difference between those two is that NextBlkAlloc
will start allocating from given sector,
and BlkAlloc
starts from first nonused sector.
You need to PutDirHead
to save any changes in BAM.
char FreeBlock (struct tr_se *myTrSe)
Simply deallocates a block in BAM. You need to update BAM with PutDirHead
.
struct tr_se SetNextFree (struct tr_se *myTrSe)
This function finds first free sector starting from given track and sector. It might return the
same argument if the given block is not allocated. I wanted this function to be type-clean, but
it made usage a bit tricky. To assign a value to own struct tr_se
you have to cast both
variables to int
. E.g.
struct tr_se myTrSe;
...
(int)myTrSe=(int)SetNextFree(&otherTrSe);
In this example otherTrSe
can be replaced by myTrSe
.
NOTE that you must use casting to have correct values.
SetNextFree
only finds next free sector, it doesn't allocate it.
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 interface to 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 TurboDos code into disk drive RAM. ExitTurbo
disables TurboDos.
This is useful for sending some DOS commands for drive e.g. for formatting. Note that before any
interaction with 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 different from ExitTurbo
- it not only disables TurboDos,
but also removes it from drive RAM (not quite true, but it works like that). After a PurgeTurbo
,
EnterTurbo
will have to reload drive RAM.
char ChangeDiskDevice (char newDevice)
This function changes logical number of current device (in fact drives only) with given one. It is
usable for swapping drives. There's no check if given newDevice
already exist, so if you want
to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably
hung on disk access. Use safe, large numbers. Note that safe IEC range is 0-32, but devices with
numbers below 8 shouldn't be used (there is 'DiskDevice' in the name of this function and devices
0-7 are not 'DiskDevices' you know :-).
GEOS has two functions for initialization ('logging' as they say on CP\M) the 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 disk cache on REU is cleared. Finally format is
checked with ChkDkGEOS
and disk name is updated in internal tables.
char NewDisk (void)
This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.
This section cover GEOS file interface.
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 whole directory for particular files. Note that
returned filehandles describe all file slots in directories - even those with deleted files.
The return value can be obtained by casting both sides to int
- as in SetNextFree
function, or read directly after call to those two functions from r5
. Current sector number
is in r1
and sector data itself is in diskBlkBuf
.
char FindFile (char *fName)
This function scans whole directory for given filename. It returns either 0 (success) or 5
(FILE_NOT_FOUND, defined in gdisk.h
) or any other fatal disk read error. After successful
FindFile
you will have struct filehandle
at dirEntryBuf
filled with file's data and
other registers set as described in GetNxtDirEntry
.
char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)
This function scans directory and fills a table at buffer
with char [17]
entries.
fType
is GEOS type of searched files and classTxt
is a string for Class field in file
header. Class will match if given will be equal or shorter than that found in file's header block.
If you want just to find all files with given GEOS type you should pass empty string or NULL
as
classTxt
. Be warned that for searching NON_GEOS files must pass NULL
as classTxt
.
fMaxNum
is the maximal number of found files, thus the buffer
must
provide area of size equal to 17 * fMaxNum
.
This function returns the number of found files, ranging from 0 to number passed as fMaxNum.
Return value from kernal FindFTypes can be 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 fileHeader
buffer. Using after e.g. FindFile
you can pass address of dirEntryBuf
.
Functions described here are common for SEQ and VLIR structures because arguments passed are starting track and sector which may point either to start of a chain for VLIR or data for SEQ.
char ReadFile (struct tr_se *myTrSe, char *buffer, int fLength)
This function reads at most fLength
bytes into buffer
from chained sectors starting at
myTrSe
.
char ReadByte (void)
This function returns next byte from file. Before first call to this function you must load the
first sector of file, easiest way by using GetBlock
and set r5
to the offset (you will
want to skip the link, so use the value of 2 here). Then you may call ReadByte
.
Remember to not modify r1
, r4
and r5
.
Returned value is valid only if there wasn't any error. End of file is marked as BFR_OVERFLOW
in errno
, this is set when trying to read one byte after the end of file.
char SaveFile (struct fileheader *myHeader)
SaveFile
will take care of everything needed to create a GEOS file, no matter VLIR of SEQ
structure. All you need to do is to place data in proper place and prepare a header which will
contain all information about a file.
You have to declare a 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
pointer to the DOS filename of the file.
When saving files 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 passed table.
char FollowChain(struct tr_se *myTrSe, char *buffer)
This function fills a struct tr_se
table at buffer
with sector numbers for chain of
sectors starting with myTrSe
. You can pass such data (buffer
) to e.g. FreeFile
.
Here are informations about VLIR files (called later as RecordFile) and functions.
VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one
SEQ structure file. Records are grouped together, described by common name - VLIR file name and
own number. Each record pointed by its number is described by 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 starting track and sector of
particular file.
In GEOS there can be only one file opened at a time. Upon opening VLIR file some information
about it are copied into memory. You can retrieve records table at fileTrScTab
(table of
128 struct tr_se
) and from VLIRInfo
(struct VLIR_info
.
E.g. size of whole VLIR file can be retrieved by reading VLIRInfo.fileSize
.
char OpenRecordFile (char *fName)
This function finds and opens given file. An error is returned if file is not found or 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 call to CloseRecordFile
so don't modify it.
You should PointRecord
before trying to do something with file.
char CloseRecordFile (void)
This function calls UpdateRecordFile
and clears internal GEOS variables.
char UpdateRecordFile (void)
This function fill check VLIRInfo.fileWritten
flag and if it is set, then curDirHead
will
be updated along with size and date stamps in directory entry.
char PointRecord (char recordNumber)
This function will setup internal variables (and VLIRInfo.curRecord
) and return the track and
sector of given record in r1
. Note that the data may not be valid (if 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 current VLIR track and sector
table. It will also set VLIRInfo.curRecord
to its number.
char DeleteRecord (void)
This function will remove 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 table one place forward (contents of VLIRInfo.curRecord
after call to InsertRecord
can be found in VLIRInfo.curRecord + 1
).
char ReadRecord (char *buffer, int fLength)
char WriteRecord (char *buffer, int fLength)
This function will load or save at most fLength
bytes from currently pointed record into or from
buffer
.
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 memset, memcpy, strcpy
etc. from standard libraries.
However they have slighty 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 strings
are up to 255 characters (without
counting the terminating NULL
), and regions
cover whole 64K of memory.
void CopyString (char *dest, char *src)
This function copies string from src
to dest
, until it reaches NULL
. NULL
is also copied.
char CmpString (char *s1, char *s2)
This function compares string s1
to s2
for equality - this is case sensitive, and both
strings have to have the same length. It returns either true
or false
.
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 copied or compared strings. The strings can also contain several NULL
characters - they are not treated as delimiters.
int CRC (char *src, int length)
This function calculates the CRC checksum for given memory range. I don't know if it is compatible with standard CRC routines.
void FillRam (char value, char *dest, int length)
void ClearRam (char *dest, int length)
Both functions are filling given memory range. ClearRam
fills with NULLs
, while
FillRam
uses given value
. Be warned that these functions destroy r0, r1 and
r2L
registers.
void MoveData (char *src, char *dest, int length)
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
r0, r1 and r2
registers.
void InitRam (char *table)
This function allows to initialize multiple memory locations with single bytes or strings.
This is done with table
where everything is defined. See structures chapter for description of
InitRam's
command string.
void StashRAM (char bank, int length, char *reuAddy, char *cpuAddy)
void FetchRAM (char bank, int length, char *reuAddy, char *cpuAddy)
void SwapRAM (char bank, int length, char *reuAddy, char *cpuAddy)
char VerifyRAM (char bank, int length, char *reuAddy, char *cpuAddy)
These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions called in specified intervals and you can sleep the main program without disturbing other tasks.
void InitProcesses (char number, struct process *processTab)
This is the main initialization routine. After calling this processes are set up, but not
enabled. The parameters for InitProcesses
are:
number
- number of processesprocessTab
- table of struct process
, with size equal to number
Single task is described by entry in processTab
, it contains two values - pointer
to
task function and 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 - last entry in processTab
have to be NULL,NULL
, so the
maximum size of processTab
is equal to 21.
See description of process
structure for more detailed discussion on this.
void RestartProcess (char processNumber)
void EnableProcess (char processNumber)
These two functions start the task counter. RestartProcess
for each process should be called
after InitProcesses
, because it resets all flags and counters and it starts the counters.
RestartProcess
enables counters and sets their initial value to that given in processTab
.
EnableProcess
forces given process to execute by simulating the timer running out of time.
void BlockProcess (char processNumber)
void UnBlockProcess (char processNumber)
BlockProcess
disables the execution of given process, but this does not disable the timers.
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 filled with initial value.
void Sleep (int jiffies)
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.
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.
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 Kernal's routines.
void MainLoop (void)
Your programs exits to MainLoop upon exiting from main
, but you might need this function in
menu and icon code. When in MainLoop
systems waits for your action - using icons, keyboard
or menus to force some specific action from program.
void EnterDeskTop (void)
This is default exit code of your application. It is finish of exit()
, but you may need it
in other places of application.
void ToBASIC (void)
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.
void Panic (void)
This calls system's Panic
handler - it shows dialog box with message
System error at:xxxx
where xxxx
is last known execution address (caller). By default this is binded to BRK
instruction, but it might be usable in debugging as kind of assert
.
System is halted after call to Panic
.
void CallRoutine (void * myFunct)
This is system caller routine. You need to provide 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 need not to worry if the pointer is valid.
int GetSerialNumber (void)
This function returns the serial number of system. It might be used for copy-protection, but you shouldn't do this. Please remember that the Free Software is a true power.
char GetRandom (void)
This function returns a random number. It can be also read from random
e.g.
a=random;
but by calling this function you are sure that the results will be always different.
random
is updated once a frame (50Hz) and on every call to GetRandom
void SetDevice (char)
This function sets current device to given. It might be used together with InitForIO
,
DoneWithIO
and some Kernal routines. Unless new device is a disk drive this only sets
new value in curDevice
, in other case new disk driver is loaded from REU or internal RAM.