--- /dev/null
+<!doctype linuxdoc system>
+
+<article>
+
+<!-- Title information -->
+
+<title>GEOSLib docs
+<author>Maciej Witkowiak, <htmlurl url="mailto:ytm@friko.onet.pl" name="ytm@friko.onet.pl">
+<date>v1.1, 26.12.1999, 16.03.2000, 19-22.03.2000, 11.07.2000
+<abstract>
+This is the documentation of cc65's GEOSLib, but information contained here may be also
+useful for writting GEOS applications in general.
+</abstract>
+
+<!-- Table of contents -->
+<toc>
+
+<!-- Begin the document -->
+
+<sect>Introduction
+<p>
+As we all know that the best computers in the world are c64 and c128. They have their GUI too -
+excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point
+of view. That's not true. The designers of GEOS created flexible and powerful system, which
+is easy to use and program.
+<p>
+Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65
+package and my GEOSLib you are able to create GEOS applications in no-time.
+<p>
+GEOSLib in its current stage doesn't support standard cc65 libraries. It is likely to be changed
+in next version. Note that it doesn't mean that it will not work now. I didn't bother myself to
+check if it is possible. All I needed for a start was including only <tt/geos.h/ in the source
+and nothing else.
+<p>
+I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
+available code (well, the best as for machine :). Many of the <tt/void foo (void)/ functions are
+just raw calls to Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you
+will find many definitions of standard GEOS locations. Access to these addresses is optimized by
+cc65 to simple <tt/lda/ and <tt/sta/.
+
+<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
+programs.
+
+The software needed:
+<itemize>
+ <item><em/cc65/ Excellent package containing C crosscompiler, crossassembler and linker, you
+ can get it from: <htmlurl url="http://www.von-bassewitz.de/uz/cc65/"
+ name="http://www.von-bassewitz.de/uz/cc65/">
+ <item><em/VICE/ This is portable C64, C128 and few other Commodore computers emulator, you
+ can obtain it from: <htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
+ name="http://www.cs.cmu.edu/~dsladic/vice/vice.html">
+ <item><em/Star Commander/ This tool is for DOS right now. You will need it for transferring
+ object files from PC to 1541. There's also one important ability of this
+ tool - it automatically un-converts .cvt files into GEOS native format on
+ disk image files.
+</itemize>
+<p>
+VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only
+needs cc65.
+<p>
+<em/Update:/ starting from v2.5.0 GEOSLib is a part of cc65 package as its GEOS support.
+
+<sect1>Legal
+<p>
+I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's
+Reference Guide and BSW for GEOS.
+<p>
+GEOSLib is covered by the same license as cc65. You can find the whole text among documentation.
+I would really appreciate if you would like to send me your comments, suggestions, questions,
+changes, bug reports etc. I feel that GEOSLib may be much better. After all, this is the first
+release. I will also appreciate if you will just give me a sign that you are using GEOSLib -
+not especially something big and important, mail me even if you are just playing with it.
+<p>
+You can send postcards with hellos to:
+<p>
+Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW
+<p>
+POLAND
+<p>
+e-mail: <tt/ytm@friko.onet.pl/
+
+<sect>What have you got and what to do with it?
+<p>
+This chapter describes some rules you ought to obey, and how to use GEOSLib.
+
+<sect1>General rules
+<p>
+Ulrich probably won't like it, but I don't want you to use his standard C functions. In fact, the
+best way (IMO) of programming GEOS with GEOSLib is to only use GEOS lib. You don't need anything
+else. You shouldn't need anything else.
+<p>
+If you really, really need to mix standard libraries with GEOSLib be warned that it probably won't
+work and lookout for the <tt/errno/ - it points to one place when <tt/errno.h/ is included and
+another with <tt/geos.h/.
+<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
+and in which order.
+
+<sect1>Usage
+<p>
+All in all, you just need to place
+<tscreen><verb>
+#include <geos.h>
+</verb></tscreen>
+on top of your source.
+<p>
+Please read cc65's documentation on how to compile C, assembler and link everything together.
+<p>
+GEOSLib building process isn't yet defined stable. Detailed information how to link everything
+together is in separated file together with resource compiler documentation.
+<p>
+As a general rule read the sources of example programs and read the headers. These are the most
+reliable sources of knowledge ;). You will also find there many C macros representing various
+arguments passed to functions. Please use them. You will find your sources easier to understand,
+and it will be easier to find bugs.
+<p>
+All types used in GEOSLib are <tt/unsigned/.
+<p>
+Screen coordinates are given in pixels unless stated differently.
+
+<sect1>Notes on style
+<p>
+All programs start their execution on <tt/main/ function. Unlike plain C exiting from this function
+doesn't mean end of program. GEOS is event-driven environment where applications are only executing
+events, main loop is in kernal. <tt/main/ function should setup the screen, menus etc. and return.
+Real end of the program should be called from event call, e.g. from menu item. You can force end of
+program and return to DeskTop either by standard <tt/exit (0)/ function or by <tt/EnterDeskTop()/.
+Currently they are almost the same (last minute note: don't use <tt/exit/ ever, it's broken right
+now :-).
+<p>
+Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into
+series of <tt/lda/ and <tt/sta/, so you can't do it better :-).
+<p>
+Don't hesitate to use library functions. Everything was written with size and speed in mind. In
+fact many calls are just redirections to GEOS kernal which results in simple <tt/jsr/.
+<p>
+You might wonder why I have chosen sometimes weird order of arguments in functions. It is because
+I wanted to avoid unnecessary pushing and popping arguments from stack. cc65 can pass single <tt/int/
+through CPU registers.
+<p>
+Do not try to compile in strict ANSI mode. I'm using some cc65 extensions which are not available in
+ANSI.
+
+<sect>Library Functions
+<p>
+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 <tt/geosSym/ file provided with GeoProgrammer package. Only my extensions to <tt/geosSym/
+are covered by new names, but I tried to keep them in the naming convention.
+
+<sect1>Graphics
+<p>
+This section covers drawing package of GEOS along with text output routines.
+
+<sect2>SetPattern
+<p>
+<tt/void SetPattern (char pattern)/
+<p>
+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.
+
+<sect2>GraphicsString
+<p>
+<tt/void GraphicsString (char *myGString)/
+<p>
+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.
+
+<sect2>Rectangle functions
+<p>
+Parameters to those functions are grouped in <tt/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. <tt/drawWindow.top=10/) or via
+<tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change only when
+using graphics functions. In other case you should keep your data in separate <tt/struct window/
+and use <tt/InitDrawWindow/ before first call to rectangle functions.
+
+<sect3>InitDrawWindow
+<p>
+<tt/void InitDrawWindow (struct window *myWindow)/
+<p>
+This function only copies contents of <tt/myWindow/ into system area of <tt/drawWindow/. Use it
+if for some reason you have to keep window data out of zero page space.
+
+<sect3>Rectangle
+<p>
+<tt/void Rectangle (void)/
+<p>
+This draws on screen rectangle filled with current pattern.
+
+<sect3>FrameRectangle
+<p>
+<tt/void FrameRectangle (char pattern)/
+<p>
+This one draws frame with given line pattern.
+
+<sect3>InvertRectangle
+<p>
+<tt/void InvertRectangle (void)/
+<p>
+Just as the name says...
+
+<sect3>ImprintRectangle and RecoverRectangle
+<p>
+<tt/void ImprintRectangle (void)/
+<p>
+<tt/void RecoverRectangle (void)/
+<p>
+These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/)
+backbuffer of the screen. For example GEOS drawing new menus on screen first uses
+<tt/ImprintRectangle/ to save the area under menu, and restores it by <tt/RecoverRectangle/ upon
+destroying the menu.
+
+<sect2>Line Functions
+<p>
+GEOS drawing package is optimized so there are different functions for drawing vertical and
+horizontal lines.
+
+<sect3>HorizontalLine
+<p>
+<tt/void HorizontalLine (char pattern, char y, int xStart, int xEnd)/
+<p>
+This function draws horizontal line using given pattern - here it is a true bit pattern, not
+pattern set by <tt/SetPattern/.
+
+<sect3>InvertLine
+<p>
+<tt/void InvertLine (char y, int xStart, int xEnd)/
+<p>
+There is only horizontal version.
+
+<sect3>RecoverLine
+<p>
+<tt/void RecoverLine (char y, int xStart, int xEnd)/
+<p>
+This function recovers only one line. It is utilized by <tt/RecoverRectangle/. See its description
+for more details.
+
+<sect3>VerticalLine
+<p>
+<tt/void VerticalLine (char pattern, char yStart, char yEnd, int x)/
+<p>
+This function draws vertical line using given pattern. Note that <tt/pattern/ is not a pattern
+number as set in <tt/SetPattern/ but a true bit pattern.
+
+<sect3>DrawLine
+<p>
+<tt/void DrawLine (struct window *myWindow)/
+<p>
+<tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while
+<tt/bottom/ are for the ending point. Current pattern is used for drawing.
+
+<sect2>Point Functions
+<p>
+Parameters to these two functions are passed by a pointer to own <tt/struct pixel/ filled with
+proper values.
+
+<sect3>DrawPoint
+<p>
+<tt/void DrawPoint (struct pixel *myPixel)/
+<p>
+Draws single point on the screen, no matter what the current pattern is.
+
+<sect3>TestPoint
+<p>
+<tt/char TestPoint (struct pixel *myPixel)/
+<p>
+This function tests if given pixel is set and returns true or false.
+
+<sect2>Character and string output
+
+<sect3>PutChar
+<p>
+<tt/void PutChar (char character, char y, char x)/
+<p>
+This function outputs single character using current style and font to screen.
+
+<sect3>PutString
+<p>
+<tt/void PutString (char y, int x, char *myString)/
+<p>
+Same as <tt/PutChar/ except the fact that you can output whole <tt/NULL/-terminated string.
+See <tt/ggraph.h/ for list of tokens that you can also place in the string - like <tt/CBOLDON/ or
+<tt/COUTLINEON/.
+
+<sect3>PutDecimal
+<p>
+<tt/void PutDecimal (char parameter, int value, char y, int 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/geos/ggraph.h/ for predefined
+values for <tt/parameter/.
+
+<sect2>Font Handling
+
+<sect3>GetCharWidth
+<p>
+<tt/char GetCharWidth (char character)/
+<p>
+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.
+
+<sect3>LoadCharSet
+<p>
+<tt/void LoadCharSet (struct fontdesc *myFont)/
+<p>
+This function forces GEOS to use given font instead of own. <tt/myFont/ should be casted from
+pointer to the start of area where was loaded record from font file (VLIR structure).
+
+<sect3>UseSystemFont
+<p>
+<tt/void UseSystemFont (void)/
+<p>
+This function forces GEOS to use built-in BSW font.
+
+<sect2>Bitmap handling
+<p>
+I'm not quite sure how are these functions working (except <tt/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.
+
+<sect3>BitmapUp
+<p>
+<tt/void BitmapUp (struct iconpic *myPic)/
+<p>
+This function unpacks the bitmap and places it on the screen - just as you set it in the
+<tt/struct iconpic/ pointer to which you pass. See <tt/gstruct.h/ for description of this
+structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.
+
+<sect3>BitmapClip
+<p>
+<tt/void BitmapClip (char skipLeft, char skipRight, int skipTop, struct iconpic *myPic)/
+<p>
+This function acts similar to <tt/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.
+
+<sect3>BitOtherClip
+<p>
+<tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, int skipTop,
+ struct iconpic *myPic)/
+<p>
+Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it
+returns in .A next value), and <tt/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 <tt/__fastcall__/ returning char.
+
+<sect1>Menus and Icons
+<p>
+Here you will find information about functions related with menus and icons.
+
+<sect2>Menus
+<p>
+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.
+<p>
+Menus are initialized with <tt/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 <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean.
+
+<sect3>DoMenu
+<p>
+<tt/void DoMenu (struct menu *myMenu)/
+<p>
+This function initializes GEOS menu processor and exits. See <tt/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 <tt/DoMenu/.
+
+<sect3>ReDoMenu
+<p>
+<tt/void ReDoMenu (void)/
+<p>
+This simply redraws the menu at lowest level. It works like calling <tt/DoMenu/ again with
+the same parameters.
+
+<sect3>RecoverMenu
+<p>
+<tt/void RecoverMenu (void)/
+<p>
+This function erases current menu from the screen. It doesn't change the menu level.
+
+<sect3>RecoverAllMenus
+<p>
+<tt/void RecoverAllMenus (void)/
+<p>
+This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is
+set to 0 (topmost).
+
+<sect3>DoPreviousMenu
+<p>
+<tt/void DoPreviousMenu (void)/
+<p>
+This functions causes menu processor to go back one menu level. You should use it in menu
+handler code to have the screen clean.
+
+<sect3>GotoFirstMenu
+<p>
+<tt/void GotoFirstMenu (void)/
+<p>
+This one jumps back to the topmost menu. If there is only menu and submenu it works the
+same as <tt/DoPreviousMenu/.
+
+<sect2>Icons
+<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 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 <tt/ClearMouseMode/
+the bitmap will be still on the screen.
+There is only one, but powerful icon function.
+
+<sect3>DoIcons
+<p>
+<tt/void DoIcons (struct icontab *myIconTab)/
+<p>
+This function initializes all icons that are present on the screen at once. For more information
+look at <tt/Icons/ chapter in this manual.
+
+<sect1>DialogBoxes
+<p>
+This chapter covers the most powerful GEOS function - <tt/DoDlgBox/.
+
+<sect2>GEOS standard
+
+<sect3>DoDlgBox
+<p>
+<tt/char DoDlgBox (char *dialogString)/
+<p>
+DialogBox returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/)
+or whatever closing routine passes. Register <tt/r0L/ also contains this value.
+<p>
+Read structures chapter for the specs of the <tt/dialogString/.
+
+<sect3>RstrFrmDialogue
+<p>
+<tt/char RstrFrmDialogue/
+<p>
+This function called from within DialogBox event immediately closes the DialogBox and returns
+the owner ID (or whatever caller has in the .A register).
+
+<sect2>GEOSLib extensions
+<p>
+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.
+
+<sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk
+<p>
+<tt/char DlgBoxYesNo (char *line1, char*line2)/
+<p>
+<tt/char DlgBoxOkCancel (char *line1, char*line2)/
+<p>
+<tt/void DlgBoxOk (char *line1, char*line2)/
+<p>
+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 <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/.
+
+<sect3>DlgBoxGetString
+<p>
+<tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/
+<p>
+This function prompts user for entering a string of at most <tt/strlen/ characters. It is returned
+in <tt/string/. The two given lines of text are shown above the input line. Please remember
+that there is also <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his
+input or gave up. The <tt/string/ is also shown so you can place default input there or remember
+to place <tt/NULL/ at start.
+
+<sect3>DlgBoxFileSelect
+<p>
+<tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/
+<p>
+This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error
+on reading the directory or opening the disk.
+There is also <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters
+<tt/filetype/ and pointer to string containing the first part of file's class. If this string is
+empty (<tt/NULL/ at the start), then all files with given filetype will be shown.
+<p>
+At present this file selector handles only first 16 files of given type and supports only one
+(current) drive.
+
+<sect1>Mouse, Sprites and Cursors
+<p>
+You will find here functions related to sprite and mouse drawing and handling.
+
+<sect2>Mouse related functions
+<p>
+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).
+
+<sect3>StartMouseMode
+<p>
+<tt/void StartMouseMode (void)/
+<p>
+This function initializes mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then
+calls <tt/MouseUp/.
+
+<sect3>ClearMouseMode
+<p>
+<tt/void ClearMouseMode (void)/
+<p>
+This function disables all mouse actitivies - icons and menus stop to respond to mouse events,
+but they are not cleared from the screen.
+
+<sect3>MouseUp and MouseOff
+<p>
+<tt/void MouseUp (void)/
+<p>
+<tt/void MouseOff (void)/
+<p>
+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.
+
+<sect3>IsMseInRegion
+<p>
+<tt/char IsMseInRegion (struct window *myWindow)/
+<p>
+This function tests if mouse pointer is actually in given range of screen. See <tt/gsprite.h/ for
+possible return values - they describe the position in detail.
+
+<sect2>Sprites
+<p>
+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.
+
+<sect3>DrawSprite
+<p>
+<tt/void DrawSprite (char sprite, char *mySprite)/
+<p>
+This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which
+is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Sprite visual registers are
+not initialized and sprite is not yet visible.
+
+<sect3>PosSprite
+<p>
+<tt/void PosSprite (char sprite, struct pixel *myPixel)/
+<p>
+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.
+
+<sect3>EnablSprite and DisablSprite
+<p>
+<tt/void EnablSprite (char sprite)/
+<p>
+<tt/void DisablSprite (char sprite)/
+<p>
+These two functions are responsible for the fact if the sprite will or will not appear on the
+screen.
+
+<sect2>Cursors and Console
+
+<sect3>InitTextPrompt
+<p>
+<tt/void InitTextPrompt (char height)/
+<p>
+This function initializes sprite 1 for text prompt with given <tt/height/. This parameter can be in
+range 1-48.
+
+<sect3>PromptOn and PromptOff
+<p>
+<tt/void PromptOn (struct pixel *myPixel)/
+<p>
+<tt/void PromptOff (void)/
+<p>
+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.
+
+<sect3>GetNextChar
+<p>
+<tt/char GetNextChar (void)/
+<p>
+This function gets next character from the keyboard queue. If the queue is empty it returns
+<tt/NULL/, otherwise you receive true ASCII code of a character or value of special (function)
+key. See <tt/gsprite.h/ for list of them.
+
+<sect1>Disk
+<p>
+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.
+<p>
+All GEOS disk functions return error code in X register. In some cases this is returned by
+GEOSLib function (if its type is <tt/char/), but in all cases last error is saved in <tt/errno/
+location. If it is nonzero - an error occured. See <tt/gdisk.h/ for list of errorcodes.
+<p>
+Passing parameters use always e.g. <tt/ReadBuff (&myTrSe)/.
+
+<sect2>Buffer functions
+<p>
+These functions are taking single data sector (256 bytes) to read or write on a disk.
+
+<sect3>ReadBuff and Writebuff
+<p>
+<tt/char ReadBuff (struct tr_se *myTrSe)/
+<p>
+<tt/char WriteBuff (struct tr_se *myTrSe)/
+<p>
+These functions are reading and writting sector placed at <tt/diskBlkBuf/.
+
+<sect3>GetBlock and ReadBlock
+<p>
+<tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/
+<p>
+<tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/
+<p>
+These two functions are reading a single block directly at 256 byte array placed at <tt/buffer/.
+The difference between them is that <tt/GetBlock/ will initialize TurboDos in drive if it was not
+enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster.
+
+<sect3>PutBlock, WriteBlock, VerWriteBlock
+<p>
+<tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/
+<p>
+<tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/
+<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.
+
+<sect2>Directory header
+<p>
+Functions described here are operating on <tt/curDirHeader/ where current disk header is stored.
+On larger capacity drives (than 1541) the second part of directory header in <tt/dir2Head/.
+
+<sect3>GetPtrCurDkNm
+<p>
+<tt/void GetPtrCurDkNm (char *diskName)/
+<p>
+This function fills given character string with the name of current disk. It is converted to C
+standard - string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS.
+Note that passed pointer must point to an array of at least 17 bytes.
+
+<sect3>GetDirHead and PutDirHead
+<p>
+<tt/char GetDirHead (void)/
+<p>
+<tt/char PutDirHead (void)/
+<p>
+These functions are reading and writting 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/.
+
+<sect3>CalcBlksFree
+<p>
+<tt/int CalcBlksFree (void)/
+<p>
+This function returns the number of free blocks on current disk. It is counted using data in
+<tt/curDirHead/ so you must initialize the disk before calling it.
+
+<sect3>ChkDskGEOS
+<p>
+<tt/char ChkDskGEOS (void)/
+<p>
+This functions checks <tt/curDirHead/ for GEOS Format identifier. It returns either true or false,
+and also sets <tt/isGEOS/ properly. You must initialize the disk before using this.
+
+<sect3>SetGEOSDisk
+<p>
+<tt/char SetGEOSDisk (void)/
+<p>
+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.
+
+<sect3>FindBAMBit
+<p>
+<tt/char FindBAMBit (struct tr_se *myTrSe)/
+<p>
+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. <tt/SectInUse/ and used in following way:
+<tscreen><verb>
+...
+if (!SectInUse(&myTrSe)) {
+... block not allocated ...
+}
+</verb></tscreen>
+<p>
+Anyway, I feel that this function is slightly low-level, maybe too low-level.
+
+<sect3>BlkAlloc and NxtBlkAlloc
+<p>
+<tt/char BlkAlloc (struct tr_se output[&rsqb, int length)/
+<p>
+<tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, int length)/
+<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
+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,
+and <tt/BlkAlloc/ starts from first nonused sector.
+<p>
+You need to <tt/PutDirHead/ to save any changes in BAM.
+
+<sect3>FreeBlock
+<p>
+<tt/char FreeBlock (struct tr_se *myTrSe)/
+<p>
+Simply deallocates a block in BAM. You need to update BAM with <tt/PutDirHead/.
+
+<sect3>SetNextFree
+<p>
+<tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/
+<p>
+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 <tt/struct tr_se/ you have to cast both
+variables to <tt/int/. E.g.
+<tscreen><verb>
+struct tr_se myTrSe;
+...
+(int)myTrSe=(int)SetNextFree(&otherTrSe);
+</verb></tscreen>
+<p>
+In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
+<p>
+NOTE that you <em/must/ use casting to have correct values.
+<p>
+<tt/SetNextFree/ only finds next free sector, it doesn't allocate it.
+
+<sect2>Low-level disk IO
+<p>
+Functions described here are more usable in kernal or drivers code, less common in applications,
+but who knows, maybe someone will need them.
+
+<sect3>EnterTurbo, ExitTurbo, PurgeTurbo
+<p>
+<tt/void EnterTurbo (void)/
+<p>
+<tt/void ExitTurbo (void)/
+<p>
+<tt/void PurgeTurbo (void)/
+<p>
+These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit
+more usable. <tt/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. <tt/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 <tt/InitForIO/. You don't have to worry about speed.
+<tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with
+<tt/ExitTurbo/. <tt/PurgeTurbo/ acts different from <tt/ExitTurbo/ - it not only disables TurboDos,
+but also removes it from drive RAM (not quite true, but it works like that). After a <tt/PurgeTurbo/,
+<tt/EnterTurbo/ will have to reload drive RAM.
+
+<sect3>ChangeDiskDevice
+<p>
+<tt/char ChangeDiskDevice (char newDevice)/
+<p>
+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 <tt/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 :-).
+
+<sect2>Disk Initialization
+<p>
+GEOS has two functions for initialization ('logging' as they say on CP\M) the disk.
+<sect3>OpenDisk
+<p>
+<tt/char OpenDisk (void)/
+<p>
+This function initializes everything for a new disk. It loads and enables TurboDos if needed.
+Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/.
+Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is
+checked with <tt/ChkDkGEOS/ and disk name is updated in internal tables.
+
+<sect3>NewDisk
+<p>
+<tt/char NewDisk (void)/
+<p>
+This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.
+
+<sect1>Files
+<p>
+This section cover GEOS file interface.
+
+<sect2>Directory handling
+<p>
+Functions described here are common for SEQ and VLIR structures.
+
+<sect3>Get1stDirEntry and GetNxtDirEntry
+<p>
+<tt/struct filehandle *Get1stDirEntry (void)/
+<p>
+<tt/struct filehandle *GetNxtDirEntry (void)/
+<p>
+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 <tt/int/ - as in <tt/SetNextFree/
+function, or read directly after call to those two functions from <tt/r5/. Current sector number
+is in <tt/r1/ and sector data itself is in <tt/diskBlkBuf/.
+
+<sect3>FindFile
+<p>
+<tt/char FindFile (char *fName)/
+<p>
+This function scans whole directory for given filename. It returns either 0 (success) or 5
+(FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After successful
+<tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with file's data and
+other registers set as described in <tt/GetNxtDirEntry/.
+
+<sect3>FindFTypes
+<p>
+<tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/
+<p>
+This function scans directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries.
+<tt/fType/ is GEOS type of searched files and <tt/classTxt/ is a string for Class field in file
+header. Class will match if given will be shorter than that found in file's header block. This
+way if you want just to find all files with given GEOS type you must pass empty string as
+<tt/classTxt/. <tt/fMaxNum/ is the maximal number of found files, thus the <tt/buffer/ must
+provide area of size equal to <tt/17 * fMaxNum/. This function returns errorcode. The number of
+actually found files can be restored from <tt/r7H/.
+
+<sect3>DeleteFile
+<p>
+<tt/char DeleteFile (char *fName)/
+<p>
+This function delets a file by its name. It works for SEQ and VLIR files.
+
+<sect3>RenameFile
+<p>
+<tt/char RenameFile (char *oldName, char *newName)/
+<p>
+I think it is obvious...
+
+<sect3>GetFHdrInfo
+<p>
+<tt/char GetFHdrInfo (struct filehandle *myFile)/
+<p>
+This function loads the file header into <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/
+you can pass address of <tt/dirEntryBuf/.
+
+<sect2>Common and SEQ structure
+<p>
+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.
+
+<sect3>ReadFile
+<p>
+<tt/char ReadFile (struct tr_se *myTrSe, char *buffer, int fLength)/
+<p>
+This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at
+<tt/myTrSe/.
+
+<sect3>ReadByte
+<p>
+<tt/char ReadByte (void)/
+<p>
+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 <tt/GetBlock/ and set <tt/r5/ to the offset (you will
+want to skip the link, so use the value of 2 here). Then you may call <tt/ReadByte/.
+Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/.
+<p>
+Returned value is valid only if there wasn't any error. End of file is marked as <tt/BFR_OVERFLOW/
+in <tt/errno/, this is set when trying to read one byte after the end of file.
+
+<sect3>SaveFile
+<p>
+<tt/char SaveFile (struct fileheader *myHeader)/
+<p>
+<tt/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 <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
+pointer to the DOS filename of the file.
+
+When saving files two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/
+and <tt/fileheader.end_address/.
+
+<sect3>FreeFile
+<p>
+<tt/char FreeFile (struct tr_se myTable[])/
+<p>
+This function deallocates all sectors contained in passed table.
+
+<sect3>FollowChain
+<p>
+<tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/
+<p>
+This function fills a <tt/struct tr_se/ table at <tt/buffer/ with sector numbers for chain of
+sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/.
+
+<sect2>VLIR structure
+<p>
+Here are informations about VLIR files (called later as RecordFile) and functions.
+<p>
+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 (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/),
+or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent starting track and sector of
+particular file.
+<p>
+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 <tt/fileTrScTab/ (table of
+128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/.
+E.g. size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/.
+
+<sect3>OpenRecordFile
+<p>
+<tt/char OpenRecordFile (char *fName)/
+<p>
+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 <tt/VLIRInfo/ is initialized. VLIR track and sector table is
+loaded at <tt/fileTrScTab/ and will be valid until call to <tt/CloseRecordFile/ so don't modify it.
+You should <tt/PointRecord/ before trying to do something with file.
+
+<sect3>CloseRecordFile
+<p>
+<tt/char CloseRecordFile (void)/
+<p>
+This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables.
+
+<sect3>UpdateRecordFile
+<p>
+<tt/char UpdateRecordFile (void)/
+<p>
+This function fill check <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ will
+be updated along with size and date stamps in directory entry.
+
+<sect3>PointRecord
+<p>
+<tt/char PointRecord (char recordNumber)/
+<p>
+This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and
+sector of given record in <tt/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).
+
+<sect3>NextRecord and PreviousRecord
+<p>
+<tt/char NextRecord (void)/
+<p>
+<tt/char PreviousRecord (void)/
+<p>
+These two work like <tt/PointRecord/. Names are self-explanatory.
+
+<sect3>AppendRecord
+<p>
+<tt/char AppendRecord (void)/
+<p>
+This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector
+table. It will also set <tt/VLIRInfo.curRecord/ to its number.
+
+<sect3>DeleteRecord
+<p>
+<tt/char DeleteRecord (void)/
+<p>
+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 <tt/UpdateRecordFile/ to
+commit changes.
+
+<sect3>InsertRecord
+<p>
+<tt/char InsertRecord (void)/
+<p>
+This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following
+records in table one place forward (contents of <tt/VLIRInfo.curRecord/ after call to <tt/InsertRecord/
+can be found in <tt/VLIRInfo.curRecord + 1/).
+
+<sect3>ReadRecord and WriteRecord
+<p>
+<tt/char ReadRecord (char *buffer, int fLength)/
+<p>
+<tt/char WriteRecord (char *buffer, int fLength)/
+<p>
+This function will load or save at most <tt/fLength/ bytes from currently pointed record into or from
+<tt/buffer/.
+
+<sect1>Memory and Strings
+<p>
+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 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 <tt/strings/ are up to 255 characters (without
+counting the terminating <tt/NULL/), and <tt/regions/ cover whole 64K of memory.
+
+<sect2>CopyString
+<p>
+<tt/void CopyString (char *dest, char *src)/
+<p>
+This function copies string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. <tt/NULL/
+is also copied.
+
+<sect2>CmpString
+<p>
+<tt/char CmpString (char *s1, char *s2);/
+<p>
+This function compares string <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both
+strings have to have the same length. It returns either <tt/true/ or <tt/false/.
+
+<sect2>CopyFString and CmpFString
+<p>
+<tt/void CopyFString (char length, char *dest, char *src)/
+<p>
+<tt/char CmpFString (char length, char *s1, char *s2)/
+<p>
+These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide
+the length of copied or compared strings. The strings can also contain several <tt/NULL/
+characters - they are not treated as delimiters.
+
+<sect2>CRC
+<p>
+<tt/int CRC (char *src, int length)/
+<p>
+This function calculates the CRC checksum for given memory range. I don't know if it is
+compatible with standard CRC routines.
+
+<sect2>FillRam and ClearRam
+<p>
+<tt/void FillRam (char value, char *dest, int length)/
+<p>
+<tt/void ClearRam (char *dest, int length)/
+<p>
+Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/NULLs/, while
+<tt/FillRam/ uses given <tt/value/.
+
+<sect2>MoveData
+<p>
+<tt/void MoveData (char *src, char *dest, int length)/
+<p>
+This functions copies one memory region to another. There are checks for overlap and the
+non-destructive method is chosen.
+
+<sect2>InitRam
+<p>
+<tt/void InitRam (char *table)/
+<p>
+This function allows to initialize multiple memory locations with single bytes or strings.
+This is done with <tt/table/ where everything is defined. See structures chapter for description of
+<tt/InitRam's/ command string.
+
+<sect2>Stash, Fetch, Swap, and VerifyRAM
+<p>
+<tt/void StashRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
+<p>
+<tt/void FetchRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
+<p>
+<tt/void SwapRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
+<p>
+<tt/ char VerifyRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
+<p>
+These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
+
+<sect1>Processes and Multitasking
+<p>
+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.
+
+<sect2>InitProcesses
+<p>
+<tt/void InitProcesses (char number, struct process *processTab)/
+<p>
+This is the main initialization routine. After calling this processes are set up, but not
+enabled. The parameters for <tt/InitProcesses/ are:
+<itemize>
+ <item><tt/number/ - number of processes
+ <item><tt/processTab/ - table of <tt/struct process/, with size equal to <tt/number/
+</itemize>
+<p>
+Single task is described by entry in <tt/processTab/, it contains two values - <tt/pointer/ to
+task function and number of <tt/jiffies/ which describe the delay between calls to task. On PAL
+systems there are 50 jiffies per second, while on NTSC there are 60.
+<p>
+The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
+if <tt/processTab/ would be too large it would overwrite existing data in GEOS space.
+<p>
+There's one important thing - last entry in <tt/processTab/ have to be <tt/NULL,NULL/, so the
+maximum size of <tt/processTab/ is equal to 21.
+<p>
+See description of <tt/process/ structure for more detailed discussion on this.
+
+<sect2>RestartProcess and EnableProcess
+<p>
+<tt/void RestartProcess (char processNumber)/
+<p>
+<tt/void EnableProcess (char processNumber)/
+<p>
+These two functions start the task counter. <tt/RestartProcess/ for each process should be called
+after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters.
+<p>
+<tt/RestartProcess/ enables counters and sets their initial value to that given in <tt/processTab/.
+<p>
+<tt/EnableProcess/ forces given process to execute by simulating the timer running out of time.
+
+<sect2>BlockProcess and UnBlockProcess
+<p>
+<tt/void BlockProcess (char processNumber)/
+<p>
+<tt/void UnBlockProcess (char processNumber)/
+<p>
+<tt/BlockProcess/ disables the execution of given process, but this does not disable the timers.
+<p>
+<tt/UnBlockProcess/ does the opposite.
+
+<sect2>FreezeProcess and UnFreezeProcess
+<p>
+<tt/void FreezeProcess (char processNumber)/
+<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.
+
+<sect2>Sleep
+<p>
+<tt/void Sleep (int 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.
+
+<sect1>System
+
+<sect2>FirstInit
+<p>
+<tt/void FirstInit (void)/
+<p>
+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.
+
+<sect2>InitForIO and DoneWithIO
+<p>
+<tt/void InitForIO (void)/
+<p>
+<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.
+
+<sect2>MainLoop
+<p>
+<tt/void MainLoop (void)/
+<p>
+Your programs exits to MainLoop upon exiting from <tt/main/, but you might need this function in
+menu and icon code. When in <tt/MainLoop/ systems waits for your action - using icons, keyboard
+or menus to force some specific action from program.
+
+<sect2>EnterDeskTop
+<p>
+<tt/void EnterDeskTop (void)/
+<p>
+This is default exit code of your application. It is finish of <tt/exit()/, but you may need it
+in other places of application.
+
+<sect2>ToBASIC
+<p>
+<tt/void ToBASIC (void)/
+<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.
+
+<sect2>Panic
+<p>
+<tt/void Panic (void)/
+<p>
+This calls system's <tt/Panic/ handler - it shows dialog box with message
+<tscreen><verb>
+System error at:xxxx
+</verb></tscreen>
+where <tt/xxxx/ is last known execution address (caller). By default this is binded to <tt/BRK/
+instruction, but it might be usable in debugging as kind of <tt/assert/.
+<p>
+System is halted after call to <tt/Panic/.
+
+<sect2>CallRoutine
+<p>
+<tt/void CallRoutine (void * myFunct)/
+<p>
+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 <tt/NULL/. This is the main functionality of this function -
+you need not to worry if the pointer is valid.
+
+<sect2>GetSerialNumber
+<p>
+<tt/int GetSerialNumber (void)/
+<p>
+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.
+
+<sect2>GetRandom
+<p>
+<tt/char GetRandom (void)/
+<p>
+This function returns a random number. It can be also read from <tt/random/ e.g.
+<tscreen><verb>
+a=random;
+</verb></tscreen>
+but by calling this function you are sure that the results will be always different.
+<tt/random/ is updated once a frame (50Hz) and on every call to <tt/GetRandom/
+
+<sect2>SetDevice
+<p>
+<tt/void SetDevice (char)/
+<p>
+This function sets current device to given. It might be used together with <tt/InitForIO/,
+<tt/DoneWithIO/ and some Kernal routines. Unless new device is a disk drive this only sets
+new value in <tt/curDevice/, in other case new disk driver is loaded from REU or internal RAM.
+
+<sect>Library Structures
+<p>
+To simplify using and optimize passing parameters to functions I have declared several structures
+which describe most common objects. Some of these structures are binded to static addresses in
+GEOS data space ($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.
+
+<sect1>Graphics
+
+<sect2>pixel
+<p>
+One simple structure describing point on the screen.
+
+<sect2>fontdesc
+<p>
+This structure describes font in one pointsize. There is current font - <tt/struct fontdesc/
+binded at <tt/curFontDesc/. You can also force GEOS to use your own font 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/.
+
+<sect2>window
+<p>
+This widely used structure holds description of a region of the screen. It describes top-left and
+bottom-right corners of a window.
+
+<sect2>iconpic
+<p>
+Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions -
+<tt/BitmapUp/ for example. This structure holds parameters needed to properly decode and show
+a bitmap on the screen. Bitmap has to be encoded - if you have some non-GEOS bitmaps simply
+convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/
+too.
+
+<sect1>Icons
+<p>
+These structures describe click boxes (icons) that can be placed on screen or in a dialog box.
+
+<sect2>icondef
+<p>
+This is the definition of a single click box. Please see <tt/gstruct.h/ for description of its fields.
+
+<sect2>icontab
+<p>
+This is toplevel description of icons to be placed and enabled on the screen. This structure
+has following fields:
+<itemize>
+ <item><tt/char number/ - total number of icons declared here
+ <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ mouse pointer will be placed in
+ this point allowing you to have hint for user what is default action
+ <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains
+ descriptions for all icons
+</itemize>
+
+<sect1>File and Disk
+
+<sect2>tr_se
+<p>
+This simple structure holds track and sector number of something. Do not expect the track to be
+in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K
+expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each.
+
+<sect2>f_date
+<p>
+This is placeholder for file datestamp. This structure is also present in <tt/struct filehandle/.
+GEOS is not Y2K compliant, so if current file in <tt/filehandle.date.year/ value less than 86 you
+can safely assume that it is e.g. 2085 - not 2086.
+
+<sect2>filehandle
+<p>
+This is main file descriptor. It is either entry in the directory (returned from file functions)
+or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g.
+by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/.
+
+<sect2>fileheader
+<p>
+This structure holds fileheader description. You can load file's header into <tt/fileHeader/
+fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while
+<tt/fileheader/ is a structure).
+You will also need own fileheader for <tt/SaveFile/.
+
+<sect1>System
+
+<sect2>s_date
+<p>
+This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/
+so I prepared this one. You can e.g. get or set current time using <tt/system_date.s_hour/ and
+<tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/
+pair.
+
+<sect2>process
+<p>
+You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number
+of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold
+only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to called
+function (void returning void), you will probably have to cast that pointer into int. The second
+field <tt/jiffies/ holds the amount of time between calls to that function. On PAL systems there
+are 50 jiffies per second, while NTSC have 60 of them.
+
+<sect1>Few thing in detail...
+<p>
+GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a
+kind of array of unspecified length and unspecified type. Here is how it goes:
+<tscreen><verb>
+void example = {
+ (char)3, (unsigned)3, (char)0 };
+</verb></tscreen>
+Which will be compiled to following string of bytes:
+<tscreen><verb>
+_example:
+ .byte 3
+ .word 3
+ .byte 0
+</verb></tscreen>
+As you see this way it is possible to define data of any type in any order. You must remember to
+cast each member to proper type.
+
+<sect2>DoMenu structure
+<p>
+<tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs
+are just initializing screen and menu and exit to <tt/MainLoop/. In GEOSLib it is the same as
+returning from <tt/main/ function without using <tt/exit(0)/.
+<p>
+Menu is described by two types of data - menu descriptors and menu items. Descriptor contains
+information about following menu items, and items are containing names of entries and either
+pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors.
+Note that submenu descriptor can be top-level descriptor, there's no difference in structure,
+just in the content.
+<p>
+Here is how single descriptor looks like:
+<tscreen><verb>
+void myMenu = {
+ (char)top, (char)botom, // this is the size of the menubox
+ (unsigned)left, (unsigned)right, // counting all items in current descriptor
+ (char)number_of_items | type_of_menu, // number of following items ORed with
+ // type of this menu, it can be either
+ // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed
+ // after moving mouse pointer outside the menubox. You can have at most 31 items.
+</verb></tscreen>
+This is followed by <tt/number_of_items/ of following item description.
+<tscreen><verb>
+ ...
+ "menuitemname", (char)item_type, (unsigned)pointer,
+ "nextitemname", (char)item_type, (unsigned)pointer,
+ ...
+ "lastitemname", (char)item_type, (unsigned)pointer };
+ // Note that there isn't ending <tt/NULL/ or something like that.
+</verb></tscreen>
+<tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one
+can have following values:
+<p>
+<tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on menu item
+<p>
+<tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu
+<p>
+Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function
+which will return in <tt/r0/ needed pointer (to function to execute or a submenu).
+<p>
+For creating nested menus (you can have at most 8 levels of submenus) you need to declare such
+structure for each submenu and top level menu.
+
+<sect2>DoDlgBox command string
+<p>
+<tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is
+responsible for creating dialog boxes, that is windows which task is to interact with user.
+Format of the command string is following:
+<tscreen><verb>
+ (window size and position)
+ (commands and parameters)
+ NULL
+</verb></tscreen>
+There is custom type defined for the command string: <tt/dlgBoxStr/.
+
+<sect3>Size and position
+<p>
+The first element can be specified in two ways - by using default size and position or specifying
+own. The first case results in
+<tscreen><verb>
+const dlgBoxStr example = {
+ DB_DEFPOS (pattern_of_shadow),
+ ... // commands
+ DB_END };
+</verb></tscreen>
+And the own size and position would be:
+<tscreen><verb>
+const dlgBoxStr example = {
+ DB_SETPOS (pattern, top, bottom, left, right)
+ ... // commands
+ DB_END };
+</verb></tscreen>
+
+<sect3>Commands
+<p>
+The next element of <tt/DoDlgBox/ command string are commands themselves. First six commands are
+default icons and the number of selected icon will be returned from window processor. The icons are
+<tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for use them, e.g.:
+<tscreen><verb>
+ ...
+ DB_ICON(OK, DBI_X_0, DBI_Y_0),
+ ...
+</verb></tscreen>
+Note that position is counted from top left corner of window, not entire screen and that the 'x'
+position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
+<tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), default positions
+which will make icons to appear on default window directly in the place where you would expect them.
+<p>
+<tt/DB_TXTSTR (x, y, text)/ will cause to show given text in the window.
+<p>
+<tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location
+where the address of text is stored. This is useful for information windows where only text content
+is variable. Consider following:
+<tscreen><verb>
+char text = "foo";
+ ...
+ r15=(int)text; // in code just before call to DoDlgBox
+ ...
+ DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15),
+ ...
+</verb></tscreen>
+will cause to appear the word ``foo'' in the window, but you may store the pointer to any text in
+<tt/r15/ (in this case) before call to DoDlgBox.
+<p>
+<tt/DB_GETSTR(x, y, ptr, length)/ - will add input from keyboard feature. <tt/ptr/ works as in
+previous example and points to place where text is to be stored. Note that the contents of this
+place will be shown upon creating window. <tt/length/ is the maximum number of characters to input.
+<p>
+<tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. I'm not sure, what this really
+mean.
+<p>
+<tt/DB_GRPHSTR(ptr)/ - data for this command is the pointer for <tt/GraphicsString/ commands.
+<p>
+<tt/DB_GETFILES(x, y)/ - for standard window you should pass 4 for both x and y. This function
+draws file selection box and searches current drive for files. Before call to <tt/DoDlgBox/ you
+must load <tt/r7L/ with GEOS filetype of searched files and <tt/r10/ with class text. In <tt/r5/
+you have to load pointer to a <tt/char[17]/ where selected filename will be copied. It works
+like <tt/FindFTypes/ but is limited to first 16 files.
+<p>
+<tt/DB_OPVEC(ptr)/ - this sets the new pointer for button press function, if you pass
+<tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button.
+<p>
+<tt/DB_USRICON(x, y, ptr)/ - places single user icon (click box) on window, <tt/ptr/ points at a
+<tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click
+boxes in a window, this is internal limit of GEOS Kernal.
+<p>
+<tt/DB_USRROUT(ptr)/ - this command causes to immediately call user routine pointed by <tt/ptr/.
+
+<sect2>GraphicsString command string
+<p>
+<tt/GraphicsString/ is a very powerful routine to initialize whole screen at once. There are
+predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. Last
+command have to be <tt/GSTR_END/. There is custom type defined for the command string: <tt/graphicStr/.
+<p>
+Here is an example for clearing the screen:
+<tscreen><verb>
+const graphicStr example = {
+ MOVEPENTO(0,0),
+ NEWPATTERN(0),
+ RECTANGLETO(319,199)
+ GSTR_END };
+</verb></tscreen>
+
+<sect2>InitRam table
+<p>
+This type of data is used to initialize one or more bytes in many places at once. The format is
+as following:
+<tscreen><verb>
+void example = {
+ (unsigned)address_to_store_values_at,
+ (char)number_of_bytes_that_follow,
+ (char)data,(char)data (...)
+ (...) - more such definitions
+ (unsigned)NULL - address of 0 ends the table
+ };
+</verb></tscreen>
+
+</article>
projects / cc65 / commitdiff