1 <!doctype linuxdoc system>
5 <!-- Title information -->
8 <author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl">
9 <date>v1.3, 26.12.1999, 16.03.2000, 19-22.03.2000, 11,29.07.2000, 3-4,15.07.2001, 27.10.2001
11 This is the documentation of cc65's GEOSLib, but information contained here may be also
12 useful for writting GEOS applications in general.
15 <!-- Table of contents -->
18 <!-- Begin the document -->
22 As we all know that the best computers in the world are c64 and c128. They have their GUI too -
23 excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point
24 of view. That's not true. The designers of GEOS created flexible and powerful system, which
25 is easy to use and program.
27 Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65
28 package and my GEOSLib you are able to create GEOS applications in no-time.
30 GEOSLib supports a subset of standard cc65 libraries. Whenever possible native Kernal functions
31 are used (e.g. <tt/memset/ is an alias for <tt/FillRam/), however not all are supported. E.g.
32 string functions like <tt/strcmp/, <tt/strcpy/ are doubled with native <tt/CmpString/,
33 <tt/CopyString/ because the latter can handle only 256 byte strings. Keep this in mind when
34 you will write your program. If you don't need long strings simply use functions from Kernal,
35 resulting code will be smaller.
37 <tt/dio/ - direct disk access is available, but you might have problems with devices other
38 than 1541, 1571 or 1581. RAM drives emulating these should work.
40 <tt/conio/ - simple console input-output is available for command line applications.
41 This implementation assumes that one character will fit in 8x8 cell, so output with
42 default BSW font, which is has 9 points, might be a bit messy.
43 <tt/cputs/ will output characters with fixed width, for proportional spacing use
44 <tt/cpputs/ but this function does not update cursor. There is no color support in
45 GEOS 2.0 so color functions are disabled. Both 40 and 80 columns modes are supported
46 and automatically detected.
48 <tt/tgi/ - TGI driver for GEOS that supports both 40 and 80 columns modes but mode can not be
49 changed between <tt/tgi_init/ and <tt/tgi_done/.
51 <tt/joy/ - JOY driver for GEOS supports only joystick, not current pointing device.
53 It is safe to use these standard includes and their contents:
54 <tt/assert.h, conio.h, dio.h, errno.h, em.h, geos.h, joystick.h, modload.h, mouse.h, stdlib.h, string.h, tgi.h, time.h/
56 It was not tested enough, but functions from these includes might work under GEOS:
59 Functions from the headers above are either standard C library functions or cc65-specific, in
60 either case they are not GEOS specific and so they are not described here.
62 I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
63 available code (well, the best as for machine :). Many of the <tt/void foo (void)/ functions are
64 just raw calls to Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you
65 will find many definitions of standard GEOS locations. Access to these addresses is optimized by
66 cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax.
70 You will not need c64 or c128 for development. The only hardware requirement is a PC capable of
71 runing cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your
76 <item><em/cc65/ Excellent package containing C crosscompiler, crossassembler and linker, you
77 can get it from: <htmlurl url="http://www.von-bassewitz.de/uz/cc65/"
78 name="http://www.von-bassewitz.de/uz/cc65/">
79 <item><em/VICE/ This is portable C64, C128 and few other Commodore computers emulator, you
80 can obtain it from: <htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
81 name="http://www.cs.cmu.edu/~dsladic/vice/vice.html">. VICE package contains
82 c1541 program that is able to convert/unconvert GEOS files to disk images.
83 <item><em/Star Commander/ This tool is only for DOS. You will need it for transferring
84 object files from PC to 1541. There's also one important ability of this
85 tool - it automatically un-converts .cvt files into GEOS native format on
87 <item><em/cbm4linux/ A Linux kernel module that allows for communication with 1541 and
88 other Commodore IEC bus drives. It can be replacement for Star Commander if
89 you want only to transfer files to a disk and uncovert using GEOS program for
90 this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/"
91 name="http://www.lb.shuttle.de/puffin/cbm4linux">
94 VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only
97 <em/Update:/ starting from v2.5.0 GEOSLib is a part of cc65 package as its GEOS support.
101 I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's
102 Reference Guide and BSW for GEOS.
104 GEOSLib is covered by the same license as cc65. You can find the whole text among documentation.
105 I would really appreciate if you would like to send me your comments, suggestions, questions,
106 changes, bug reports etc. I will also appreciate if you will just give me a sign that you are
107 using GEOSLib - not especially something big and important, mail me even if you are just playing
110 You can send postcards with hellos to:
112 Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW
116 e-mail: <tt/ytm@elysium.pl/
118 <sect>What have you got and what to do with it?
120 This chapter describes some rules you ought to obey, and how to use GEOSLib.
124 Apart from this file, which merely describes only standard GEOS library functions, you should read
125 <tt/grc/ (GEOS resource compiler) documentation. There are informations about necessary resource
126 files (each GEOS application neeeds at least one) and the building process - what should be done
127 and in what order. Please also read cc65's documentation on how to compile C, assembler and link
130 All in all, you just need to place
132 #include <geos.h>
134 on top of your source.
136 As a general rule read the sources of example programs and read the headers. These are the most
137 reliable sources of knowledge ;). You will also find there many C macros representing various
138 arguments passed to functions. Please use them. You will find your sources easier to understand,
139 and it will be easier to find bugs.
141 All types used in GEOSLib are <tt/unsigned/.
143 Screen coordinates are given in pixels unless stated differently.
145 <sect1>Notes on style
147 Contrary to typical GEOS assembly program which has a main function called after loading that
148 setups the screen, menus, icons etc. exiting from <tt/main/ function in C is equivalent to
149 calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT
150 USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered
151 with <tt/atexit/ will not be called.
153 For GEOS GUI applications the recommended program structure is to have everything initialized
154 in <tt/main/ function and at the end of it a call to <tt/MainLoop()/ function. WARNING! This
155 function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not
156 be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu
157 handler or via DialogBox action).
159 Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into
160 series of <tt/lda/ and <tt/sta/, so you can't do it better :-).
162 Don't hesitate to use library functions. Everything was written with size and speed in mind. In
163 fact many calls are just redirections to GEOS kernal which results in simple <tt/jsr/.
165 You might wonder why I have chosen sometimes weird order of arguments in functions. I just
166 wanted to avoid unnecessary pushing and popping arguments from stack because cc65 can pass single
167 <tt/unsigned int/ through CPU registers.
169 Do not try to compile in strict ANSI mode. Library uses cc65 extensions which are not available in
172 It is possible to use dynamicaly loaded modules, three such modules are provided:
173 GEOS TGI driver, GEOS EMD driver (for VDC extended memory) and GEOS JOY driver.
174 Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special
175 recommendations, read cc65 documentation about modules and demo programs source code.
177 <sect>Library Functions
179 Functions here are sorted more or less in the way they appear in header files. This way I am able
180 to keep functions covering similar task near each other. All function names are identical to those
181 from <tt/geosSym/ file provided with GeoProgrammer package. Only my extensions to <tt/geosSym/
182 are covered by new names, but I tried to keep them in the naming convention.
186 This section covers drawing package of GEOS along with text output routines.
190 <tt/void SetPattern (char pattern)/
192 This function sets current pattern to given. There are 32 different patterns in GEOS. You can
193 see them together in the filling box in GeoPaint.
195 <sect2>GraphicsString
197 <tt/void GraphicsString (char *myGString)/
199 One of the more powerfull routines of GEOS. This function calls other graphic functions depending
200 on given command string. See structures chapter for more detailed description of the structure of it.
202 <sect2>Rectangle functions
204 Parameters to those functions are grouped in <tt/struct window drawWindow/. To speed up things and
205 reduce overhead this structure is glued to zero page locations, where all rectangle functions
206 expect their parameters. You can modify data directly (e.g. <tt/drawWindow.top=10/) or via
207 <tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change only when
208 using graphics functions. In other case you should keep your data in separate <tt/struct window/
209 and use <tt/InitDrawWindow/ before first call to rectangle functions.
211 <sect3>InitDrawWindow
213 <tt/void InitDrawWindow (struct window *myWindow)/
215 This function only copies contents of <tt/myWindow/ into system area of <tt/drawWindow/. Use it
216 if for some reason you have to keep window data out of zero page space.
220 <tt/void Rectangle (void)/
222 This draws on screen rectangle filled with current pattern.
224 <sect3>FrameRectangle
226 <tt/void FrameRectangle (char pattern)/
228 This one draws frame with given bit pattern (not a pattern from GEOS palette).
230 <sect3>InvertRectangle
232 <tt/void InvertRectangle (void)/
234 Just as the name says...
236 <sect3>ImprintRectangle and RecoverRectangle
238 <tt/void ImprintRectangle (void)/
240 <tt/void RecoverRectangle (void)/
242 These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/)
243 backbuffer of the screen. For example when drawing new menu box GEOS first uses
244 <tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon
247 <sect2>Line Functions
249 GEOS drawing package is optimized so there are different functions for drawing vertical and
252 <sect3>HorizontalLine
254 <tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/
256 This function draws horizontal line using given pattern - here it is a true bit pattern, not
257 pattern set by <tt/SetPattern/.
261 <tt/void InvertLine (char y, unsigned xStart, unsigned xEnd)/
263 There is only horizontal version.
267 <tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/
269 This function recovers only one line. It is utilized by <tt/RecoverRectangle/. See its description
274 <tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/
276 This function draws vertical line using given pattern. Note that <tt/pattern/ is not a pattern
277 number as set in <tt/SetPattern/ but a true bit pattern.
281 <tt/void DrawLine (struct window *myWindow)/
283 <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while
284 <tt/bottom/ are for the ending point. Current pattern from <tt/SetPattern/ is used for drawing.
286 <sect2>Point Functions
288 Parameters to these two functions are passed by a pointer to own <tt/struct pixel/ filled with
293 <tt/void DrawPoint (struct pixel *myPixel)/
295 Draws single point on the screen, no matter what the current pattern is.
299 <tt/char TestPoint (struct pixel *myPixel)/
301 This function tests if given pixel is set and returns <tt/true/ (non-zero) or <tt/false/ (zero).
303 <sect2>Character and string output
307 <tt/cpputsxy (char x, char y, char *myString)/
309 <tt/cpputs (char *myString)/
311 Actually this is a part of <tt/conio/, but this function is non-standard. It is
312 a variety of <tt/cputs/ that will output string with proportional spacing, not
313 fixed like <tt/cputs/.
317 <tt/void PutChar (char character, char y, char x)/
319 This function outputs single character using current style and font to screen.
323 <tt/void PutString (char *myString, char y, unsigned x)/
325 Same as <tt/PutChar/ except the fact that you can output whole <tt/NULL/-terminated string.
326 See <tt/ggraph.h/ for list of tokens that you can also place in the string - like <tt/CBOLDON/ or
331 <tt/void PutDecimal (char parameter, int value, char y, unsigned x)/
333 This function converts <tt/value/ to its decimal representation and outputs it to the screen.
334 Depending on given <tt/parameter/ the string can be filled with zeroes (string always 5 characters
335 long) or not, to be left or right justified to given pixel. See <tt/ggraph.h/ for predefined
336 values for <tt/parameter/.
342 <tt/char GetCharWidth (char character)/
344 This function returns real width (in pixels) of given character with current font. It can be used
345 for counting the length of string on screen, allowing for indentation or justification.
349 <tt/void LoadCharSet (struct fontdesc *myFont)/
351 This function forces GEOS to use given font instead of own. <tt/myFont/ should be casted from
352 pointer to the start of area where was loaded record from font file (VLIR structure).
356 <tt/void UseSystemFont (void)/
358 This function forces GEOS to use built-in BSW font.
360 <sect2>Bitmap handling
362 I'm not quite sure how are these functions working (except <tt/BitmapUp/) so you should
363 probably look into library sources and compare it with your knowledge. Please let me know
364 if something is wrong or broken.
368 <tt/void BitmapUp (struct iconpic *myPic)/
370 This function unpacks the bitmap and places it on the screen - just as you set it in the
371 <tt/struct iconpic/ pointer to which you pass. See <tt/gstruct.h/ for description of this
372 structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.
376 <tt/void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)/
378 This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are
379 to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap,
380 and the number of rows to skip from the top if it.
384 <tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop,
385 struct iconpic *myPic)/
387 Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it
388 returns in .A next value), and <tt/proc2/ is called every time the parser reads a byte which is
389 not a piece of pattern (byte of code greater than 219). Both procedures should be written
390 separately in assembler and declared as <tt/__fastcall__/ returning char.
392 <sect1>Menus and Icons
394 Here you will find information about functions related with menus and icons.
398 Menus are essencial for GUI. GEOS can handle only one menu at a time, but each menu can call
399 another one, which results in submenu tree. There can be up to 8 menu levels, each one with up
402 Menus are initialized with <tt/DoMenu/ and then Kernal takes care for everything. Your code
403 (called from event handler) should be a function without parameters, returning void. You should
404 use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean.
408 <tt/void DoMenu (struct menu *myMenu)/
410 This function initializes GEOS menu processor and exits. See <tt/DoMenu structure/ for more
411 information about it. Know that many GEOS application just initializes the screen, menu and
412 exits to main Kernal loop, this proves the power of <tt/DoMenu/.
416 <tt/void ReDoMenu (void)/
418 This simply redraws the menu at lowest level. It works like calling <tt/DoMenu/ again with
423 <tt/void RecoverMenu (void)/
425 This function erases current menu from the screen. It doesn't change the menu level.
427 <sect3>RecoverAllMenus
429 <tt/void RecoverAllMenus (void)/
431 This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is
434 <sect3>DoPreviousMenu
436 <tt/void DoPreviousMenu (void)/
438 This functions causes menu processor to go back one menu level. You should use it in menu
439 handler code to have the screen clean.
443 <tt/void GotoFirstMenu (void)/
445 This one jumps back to the topmost menu. If there is only menu and submenu it works the
446 same as <tt/DoPreviousMenu/.
448 <sect2>Icon Functions
450 Icons are working similar to menus except the fact that there is only one level. Icons are
451 defined as a screen area filled with a bitmap, but if you would setup icons and erase the
452 screen they are still active and clicking in the place where formerly an icon was will cause
453 an effect. Similary if you would setup icons and then turn them off with <tt/ClearMouseMode/
454 the bitmap will be still on the screen but clicking on it would not cause any action.
455 There is only one, but powerful icon function.
459 <tt/void DoIcons (struct icontab *myIconTab)/
461 This function initializes all icons that are present on the screen at once. For more information
462 look at <tt/Icons/ chapter in this manual.
466 This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/.
472 <tt/char DoDlgBox (char *dialogString)/
474 DialogBox returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/)
475 or whatever closing routine passes. Register <tt/r0L/ also contains this value.
477 Read structures chapter for the specs of the <tt/dialogString/.
479 <sect3>RstrFrmDialogue
481 <tt/char RstrFrmDialogue/
483 This function called from within DialogBox event immediately closes the DialogBox and returns
484 the owner ID (or whatever caller has in the .A register).
486 <sect2>GEOSLib extensions
488 To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox,
489 with predefined data. In one word - these are standard DialogBoxes you can see in almost every
492 <sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk
494 <tt/char DlgBoxYesNo (char *line1, char *line2)/
496 <tt/char DlgBoxOkCancel (char *line1, char *line2)/
498 <tt/void DlgBoxOk (char *line1, char *line2)/
500 These function show two lines of text in standard-sized DialogBox. You can read the code of
501 pressed icon from return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/.
503 <sect3>DlgBoxGetString
505 <tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/
507 This function prompts user for entering a string of at most <tt/strlen/ characters. It is returned
508 in <tt/string/. The two given lines of text are shown above the input line. Please remember
509 that there is also <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his
510 input or gave up. The <tt/string/ is also shown so you can place default input there or remember
511 to place <tt/NULL/ at start.
513 <sect3>DlgBoxFileSelect
515 <tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/
517 This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error
518 on reading the directory or opening the disk.
519 There is also <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters
520 <tt/filetype/ and pointer to string containing the first part of file's class. If this string is
521 empty (<tt/NULL/ at the start), then all files with given filetype will be shown.
523 At present this file selector handles only first 16 files of given type and supports only one
526 <sect1>Mouse, Sprites and Cursors
528 You will find here functions related to sprite and mouse drawing and handling.
530 <sect2>Mouse related functions
532 These cover mouse - as a general pointing device, but expect user to utilize as different devices
533 as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).
535 <sect3>StartMouseMode
537 <tt/void StartMouseMode (void)/
539 This function initializes mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then
542 <sect3>ClearMouseMode
544 <tt/void ClearMouseMode (void)/
546 This function disables all mouse actitivies - icons and menus stop to respond to mouse events,
547 but they are not cleared from the screen.
549 <sect3>MouseUp and MouseOff
551 <tt/void MouseUp (void)/
553 <tt/void MouseOff (void)/
555 The first function turns the mouse pointer on. It will appear on next IRQ. The second one does
556 the opposite - it turns off the pointer, but its position is still updated by input driver.
560 <tt/char IsMseInRegion (struct window *myWindow)/
562 This function tests if mouse pointer is actually in given range of screen. See <tt/gsprite.h/ for
563 description of bits in return values - they describe the position in detail.
567 You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
568 pointer and sprite 1 can be overwritten when using text prompt. You don't have to worry about
569 40/80 column issues because GEOS128 has pretty good sprite emulator for VDC.
573 <tt/void DrawSprite (char sprite, char *mySprite)/
575 This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which
576 is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are
577 not initialized and sprite is not yet visible.
581 <tt/void PosSprite (char sprite, struct pixel *myPixel)/
583 This function positions the sprite on the screen. Given coordinates are screen ones - they are
584 converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your
585 sprite off the left or top to the screen.
587 <sect3>EnablSprite and DisablSprite
589 <tt/void EnablSprite (char sprite)/
591 <tt/void DisablSprite (char sprite)/
593 These two functions are responsible for making the sprite visible or not.
595 <sect2>Cursors and Console
597 <sect3>InitTextPrompt
599 <tt/void InitTextPrompt (char height)/
601 This function initializes sprite 1 for text prompt with given <tt/height/. This parameter can be in
604 <sect3>PromptOn and PromptOff
606 <tt/void PromptOn (struct pixel *myPixel)/
608 <tt/void PromptOff (void)/
610 The first function places text prompt in given place and enables blinking.
611 The second one is pretty self-explanatory.
615 <tt/char GetNextChar (void)/
617 This function gets next character from the keyboard queue. If the queue is empty it returns
618 <tt/NULL/, otherwise you receive true ASCII code of a character or value of special (function)
619 key. See <tt/gsprite.h/ for list of them.
623 This chapter covers slightly low-level disk routines. You should use them with care, because
624 you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various
625 devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
628 For some purposes you might consider using <tt/dio.h/ interface to disk access. It is native.
630 All GEOS disk functions return error code in X register. In some cases this is returned by
631 GEOSLib function (if its type is <tt/char/), but in all cases last error is saved in <tt/__oserror/
632 location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes.
633 You need to include <tt/errno.h/ to get <tt/__oserror/, together with standard <tt/errno/. The
634 latter gives less verbose, but still usable information and can be used with <tt/strerror/.
635 Probably you will get more information using <tt/_stroserror/ in similar way.
637 For passing parameters use almost always pointer to your data e.g. <tt/ReadBuff (&myTrSe)/.
639 <sect2>Buffer functions
641 These functions are taking single data sector (256 bytes) to read or write on a disk.
643 <sect3>ReadBuff and Writebuff
645 <tt/char ReadBuff (struct tr_se *myTrSe)/
647 <tt/char WriteBuff (struct tr_se *myTrSe)/
649 These functions read and write sector placed at <tt/diskBlkBuf/.
651 <sect3>GetBlock and ReadBlock
653 <tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/
655 <tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/
657 These two functions are reading a single block directly at 256 byte array placed at <tt/buffer/.
658 The difference between them is that <tt/GetBlock/ will initialize TurboDos in drive if it was not
659 enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster.
661 <sect3>PutBlock, WriteBlock, VerWriteBlock
663 <tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/
665 <tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/
667 <tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/
669 Similar to previous but needed for writting the disk. <tt/VerWriteBlock/ verifies the data after
670 writting. In case of error five tries are attempted before error code is returned.
672 <sect2>Directory header
674 Functions described here are operating on <tt/curDirHeader/ where current disk header is stored.
675 On larger capacity drives (than 1541) the second part of directory header in <tt/dir2Head/.
679 <tt/void GetPtrCurDkNm (char *diskName)/
681 This function fills given character string with the name of current disk. It is converted to C
682 standard - string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS.
683 Note that passed pointer must point to an array of at least 17 bytes.
685 <sect3>GetDirHead and PutDirHead
687 <tt/char GetDirHead (void)/
689 <tt/char PutDirHead (void)/
691 These functions are reading and writting the directory header. You should use <tt/GetDirHead/ before
692 using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the
693 disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/.
697 <tt/unsigned CalcBlksFree (void)/
699 This function returns the number of free blocks on current disk. It is counted using data in
700 <tt/curDirHead/ so you must initialize the disk before calling it.
704 <tt/char ChkDskGEOS (void)/
706 This functions checks <tt/curDirHead/ for GEOS Format identifier. It returns either true or false,
707 and also sets <tt/isGEOS/ properly. You must initialize the disk before using this.
711 <tt/char SetGEOSDisk (void)/
713 This function initializes disk for use with GEOS. It sets indicator in directory header and
714 allocates a sector for the directory of border files. You don't need to initialize the disk before
719 <tt/char FindBAMBit (struct tr_se *myTrSe)/
721 This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is
722 set if the sector is free to use. Returned value is always zero if the sector is already allocated.
723 In fact, this function could be used in a following way:
725 #define BlockInUse FindBAMBit
727 if (!BlockInUse(&myTrSe)) {
728 ... block not allocated ...
732 Anyway, I feel that this function is too low-level.
734 <sect3>BlkAlloc and NxtBlkAlloc
736 <tt/char BlkAlloc (struct tr_se output[&rsqb, unsigned length)/
738 <tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, unsigned length)/
740 Both functions are allocating enough disk sectors to fit the number of <tt/length/ in them. You
741 will find output in <tt/output/ which is table of <tt/struct tr_se/. The last entry will have the
742 number of track equal to 0 and sector equal to 255. The simpliest way of using them is to use
743 predefined space in GEOS data space and pass <tt/fileTrScTab/, which is a predefined table.
745 The difference between those two is that <tt/NextBlkAlloc/ will start allocating from given sector,
746 and <tt/BlkAlloc/ starts from the first nonused sector.
748 You need to use <tt/PutDirHead/ later to save any changes in BAM.
752 <tt/char FreeBlock (struct tr_se *myTrSe)/
754 Simply deallocates a block in BAM. You need to update BAM with <tt/PutDirHead/.
758 <tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/
760 This function finds the first free sector starting from given track and sector and allocates it.
761 It might return the same argument if the given block is not allocated. I wanted it to be type
762 clean, but it made usage a bit tricky. To assign a value to own <tt/struct tr_se/ you have to
763 cast both variables to <tt/unsigned/. E.g.
767 (unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe);
770 In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
772 NOTE that you <em/must/ use casting to have correct values.
774 <sect2>Low-level disk IO
776 Functions described here are more usable in kernal or drivers code, less common in applications,
777 but who knows, maybe someone will need them.
779 <sect3>EnterTurbo, ExitTurbo, PurgeTurbo
781 <tt/void EnterTurbo (void)/
783 <tt/void ExitTurbo (void)/
785 <tt/void PurgeTurbo (void)/
787 These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit
788 more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will
789 have to wait a bit to transfer TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos.
790 This is useful for sending some DOS commands for drive e.g. for formatting. Note that before any
791 interaction with Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed.
792 <tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with
793 <tt/ExitTurbo/. <tt/PurgeTurbo/ acts different from <tt/ExitTurbo/ - it not only disables TurboDos,
794 but also removes it from drive RAM (not quite true, but it works like that). After using
795 <tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM.
797 <sect3>ChangeDiskDevice
799 <tt/char ChangeDiskDevice (char newDevice)/
801 This function changes logical number of current device (in fact drives only) with given one. It is
802 usable for swapping drives. There's no check if given <tt/newDevice/ already exist, so if you want
803 to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably
804 hang on disk access. Use safe, large numbers. Note that safe IEC range is 8-31.
806 <sect2>Disk Initialization
808 GEOS has two functions for initialization ('logging' as they say on CP\M) the disk.
811 <tt/char OpenDisk (void)/
813 This function initializes everything for a new disk. It loads and enables TurboDos if needed.
814 Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/.
815 Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is
816 checked with <tt/ChkDkGEOS/ and disk name is updated in internal tables.
820 <tt/char NewDisk (void)/
822 This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.
826 This section cover GEOS file interface.
828 <sect2>Directory handling
830 Functions described here are common for SEQ and VLIR structures.
832 <sect3>Get1stDirEntry and GetNxtDirEntry
834 <tt/struct filehandle *Get1stDirEntry (void)/
836 <tt/struct filehandle *GetNxtDirEntry (void)/
838 These two functions are best suited for scanning whole directory for particular files. Note that
839 returned filehandles describes all file slots in the directory - even those with deleted files.
840 The return value can be obtained by casting both sides to <tt/unsigned/ - as in <tt/SetNextFree/
841 function or read directly after call to those two functions from <tt/r5/. Current sector number
842 is in <tt/r1/ and sector data itself is in <tt/diskBlkBuf/.
846 <tt/char FindFile (char *fName)/
848 This function scans whole directory for the given filename. It returns either 0 (success) or 5
849 (FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After successful
850 <tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with file's data and
851 other registers set as described in <tt/GetNxtDirEntry/.
855 <tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/
857 This function scans directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries.
858 <tt/fType/ is GEOS type of searched files and <tt/classTxt/ is a string for Class field in file
859 header. Class will match if given will be equal or shorter than that found in file's header block.
860 If you want just to find all files with given GEOS type you should pass empty string or <tt/NULL/ as
861 <tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files must pass <tt/NULL/ as <tt/classTxt/.
862 <tt/fMaxNum/ is the maximal number of found files, thus the <tt/buffer/ must
863 provide area of size equal to <tt/17 * fMaxNum/.
864 This function returns the number of found files, ranging from 0 to number passed as <tt/fMaxNum/.
865 Return value can be also restored from <tt/r7H/.
869 <tt/char DeleteFile (char *fName)/
871 This function deletes a file by its name. It works for SEQ and VLIR files.
875 <tt/char RenameFile (char *oldName, char *newName)/
877 I think it is obvious...
881 <tt/char GetFHdrInfo (struct filehandle *myFile)/
883 This function loads the file header into <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/
884 you can pass address of <tt/dirEntryBuf/.
886 <sect2>Common and SEQ structure
888 Functions described here are common for SEQ and VLIR structures because arguments passed are
889 starting track and sector which may point either to start of a chain for VLIR or data for SEQ.
893 <tt/char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)/
895 This routine loads and runs a given file <tt/fname/. The file must be one of following types:
896 <tt/SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,/ or <tt/INPUT_DEVICE/. The execution
897 address is taken from file header. If it is zero, then file is only loaded. Only the first chain
898 from VLIR files is loaded. If <tt/flag/ has bit 0 set then load address is taken from <tt/loadaddr/
899 and not from file header. In this case <tt/APPLICATION/ files will be only loaded, not executed.
900 This does not apply to <tt/DESK_ACC/. If either bit 6 or 7 of <tt/flag/ are set, then 16 bytes from
901 <tt/datadname/ is copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ goes to <tt/dataFileName/
902 thus becoming parameters for the new application. Pass <tt/NULL/ as any unused parameter.
907 <tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/
909 This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at
914 <tt/char ReadByte (void)/
916 This function returns next byte from a file. Before the first call to it you must load <tt/r5/
917 with <tt/NULL/, <tt/r4/ with sector buffer address and <tt/r1/ with track and sector of the
918 first block of a file.
919 Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between
920 calls to <tt/ReadByte/.
922 Returned value is valid only if there was no error. End of file is marked as <tt/BFR_OVERFLOW/
923 in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case
924 returned value is invalid.
928 <tt/char SaveFile (char skip, struct fileheader *myHeader)/
930 <tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter VLIR of SEQ
931 structure. All you need to do is to place data in proper place and prepare a header which will
932 contain all information about a file. The <tt/skip/ parameter says how many directory pages you
933 want to skip before searching for a free slot for directory entry. In most cases you will put
936 You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one
937 difference - the first two bytes which are link to nonexistant next sector are replaced by a
938 pointer to the DOS filename of the file.
940 When saving sequential files two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/
941 and <tt/fileheader.end_address/.
945 <tt/char FreeFile (struct tr_se myTable[])/
947 This function deallocates all sectors contained in passed table.
951 <tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/
953 This function fills a <tt/struct tr_se/ table at <tt/buffer/ with sector numbers for chain of
954 sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/.
956 <sect2>VLIR structure
958 Here are informations about VLIR files (called later as RecordFile) and functions.
960 VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one
961 SEQ structure file. Records are grouped together, described by common name - VLIR file name and
962 own number. Each record pointed by its number is described by starting track and sector numbers.
963 VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/),
964 or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent starting track and sector of
967 In GEOS there can be only one file opened at a time. Upon opening VLIR file some information
968 about it are copied into memory. You can retrieve records table at <tt/fileTrScTab/ (table of
969 128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/.
970 E.g. size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/.
972 <sect3>OpenRecordFile
974 <tt/char OpenRecordFile (char *fName)/
976 This function finds and opens given file. An error is returned if file is not found or if it is not
977 in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is
978 loaded at <tt/fileTrScTab/ and will be valid until call to <tt/CloseRecordFile/ so don't modify it.
979 You should <tt/PointRecord/ before trying to do something with file.
981 <sect3>CloseRecordFile
983 <tt/char CloseRecordFile (void)/
985 This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables.
987 <sect3>UpdateRecordFile
989 <tt/char UpdateRecordFile (void)/
991 This function will check <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is
992 updated along with size and date stamps in directory entry.
996 <tt/char PointRecord (char recordNumber)/
998 This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and
999 sector of given record in <tt/r1/. Note that the data may not be valid (if record is non-existing
1000 you will get 0,0 and if it is empty - 255, 0).
1002 <sect3>NextRecord and PreviousRecord
1004 <tt/char NextRecord (void)/
1006 <tt/char PreviousRecord (void)/
1008 These two work like <tt/PointRecord/. Names are self-explanatory.
1012 <tt/char AppendRecord (void)/
1014 This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector
1015 table. It will also set <tt/VLIRInfo.curRecord/ to its number.
1019 <tt/char DeleteRecord (void)/
1021 This function will remove current record from the table, and move all current+1 records one place
1022 back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to
1027 <tt/char InsertRecord (void)/
1029 This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following
1030 records in table one place forward (contents of <tt/VLIRInfo.curRecord/ after call to <tt/InsertRecord/
1031 can be found in <tt/VLIRInfo.curRecord + 1/).
1033 <sect3>ReadRecord and WriteRecord
1035 <tt/char ReadRecord (char *buffer, unsigned fLength)/
1037 <tt/char WriteRecord (char *buffer, unsigned fLength)/
1039 This function will load or save at most <tt/fLength/ bytes from currently pointed record into or from
1042 <sect1>Memory and Strings
1044 Functions covered in this section are common for whole C world - copying memory parts and
1045 strings is one of the main computer tasks. GEOS also has interface to do this. These functions
1046 are replacement for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries.
1048 However some of them have slighty different calling convention (order of arguments to be specific),
1049 so please check their syntax here before direct replacing.
1051 Please note that the memory described as <em/strings/ are up to 255 characters (without
1052 counting the terminating <tt/NULL/), and <em/regions/ cover whole 64K of memory.
1056 <tt/void CopyString (char *dest, char *src)/
1058 This function copies string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. <tt/NULL/
1063 <tt/char CmpString (char *s1, char *s2)/
1065 This function compares string <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both
1066 strings have to have the same length. It returns either <tt/true/ (non-zero) or <tt/false/ (zero).
1068 <sect2>CopyFString and CmpFString
1070 <tt/void CopyFString (char length, char *dest, char *src)/
1072 <tt/char CmpFString (char length, char *s1, char *s2)/
1074 These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide
1075 the length of copied or compared strings. The strings can also contain several <tt/NULL/
1076 characters - they are not treated as delimiters.
1080 <tt/unsigned CRC (char *src, unsigned length)/
1082 This function calculates the CRC checksum for given memory range. I don't know if it is
1083 compatible with standard CRC routines.
1085 <sect2>FillRam and ClearRam
1087 <tt/void FillRam (char *dest, char value, unsigned length)/
1089 <tt/void ClearRam (char *dest, unsigned length)/
1091 Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/NULLs/, while
1092 <tt/FillRam/ uses given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and
1093 r2L/ registers. <tt/FillRam/ is an alias for <tt/memset/.
1097 <tt/void MoveData (char *dest, char *src, unsigned length)/
1099 This functions copies one memory region to another. There are checks for overlap and the
1100 non-destructive method is chosen. Be warned that this function destroys contents of
1101 <tt/r0, r1 and r2/ registers. This is also alias for <tt/memcpy/
1105 <tt/void InitRam (char *table)/
1107 This function allows to initialize multiple memory locations with single bytes or strings.
1108 This is done with <tt/table/ where everything is defined. See structures chapter for description of
1109 <tt/InitRam's/ command string.
1111 <sect2>Stash, Fetch, Swap, and VerifyRAM
1113 <tt/void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1115 <tt/void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1117 <tt/void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1119 <tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1121 These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
1122 You can check for REU presence by taking value of <tt/ramExpSize/.
1124 <sect1>Processes and Multitasking
1126 Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions
1127 called in specified intervals and you can put the main program to sleep without disturbing other
1128 tasks and making user interface unresponsive.
1130 <sect2>InitProcesses
1132 <tt/void InitProcesses (char number, struct process *processTab)/
1134 This is the main initialization routine. After calling it processes are set up, but not
1135 enabled. The parameters for <tt/InitProcesses/ are:
1137 <item><tt/number/ - number of processes
1138 <item><tt/processTab/ - table of <tt/struct process/, with size equal to <tt/number/
1141 Single task is described by entry in <tt/processTab/, it contains two values - <tt/pointer/ to
1142 task function and number of <tt/jiffies/ which describe the delay between calls to task. On PAL
1143 systems there are 50 jiffies per second, while on NTSC there are 60.
1145 The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
1146 if <tt/processTab/ would be too large it would overwrite existing data in GEOS space.
1148 There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the
1149 maximum size of <tt/processTab/ is equal to 21.
1151 See description of <tt/process/ structure for more detailed discussion on this.
1153 <sect2>RestartProcess and EnableProcess
1155 <tt/void RestartProcess (char processNumber)/
1157 <tt/void EnableProcess (char processNumber)/
1159 These two functions start the task counter. <tt/RestartProcess/ for each process should be called
1160 after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters.
1162 <tt/RestartProcess/ enables counters and sets their initial value to that given in <tt/processTab/.
1164 <tt/EnableProcess/ forces given process to execute by simulating the timer running out of time.
1166 <sect2>BlockProcess and UnBlockProcess
1168 <tt/void BlockProcess (char processNumber)/
1170 <tt/void UnBlockProcess (char processNumber)/
1172 <tt/BlockProcess/ disables the execution of given process, but this does not disable the timers.
1174 <tt/UnBlockProcess/ does the opposite.
1176 <sect2>FreezeProcess and UnFreezeProcess
1178 <tt/void FreezeProcess (char processNumber)/
1180 <tt/void UnFreezeProcess (char processNumber)/
1182 <tt/FreezeProcess/ disables timer for given process. <tt/UnFreezeProcess/ does the opposite.
1183 This is not equal to <tt/RestartProcess/ as timers are not filled with initial value.
1187 <tt/void Sleep (unsigned jiffies)/
1189 This function is multitasking sleep - the program is halted, but it doesn't block other functions.
1190 The only argument here is the number of jiffies to wait until app will wake up.
1192 You can force to sleep not only the main application routine, but also processes-tasks. Be warned
1193 that the maximum number of sleeping functions is 20. If it would be larger it will overwrite
1194 parameters of already sleeping functions in GEOS kernal data space, leading to crash.
1196 <sect1>System Functions
1200 <tt/void FirstInit (void)/
1202 This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot
1203 up. You shouldn't use this unless you know what you are doing.
1205 <sect2>InitForIO and DoneWithIO
1207 <tt/void InitForIO (void)/
1209 <tt/void DoneWithIO (void)/
1211 These functions are called by some disk routines. You should call them only if you want to
1212 do something with IO registers or call one of Kernal's routines.
1216 <tt/void MainLoop (void)/
1218 Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current
1219 function will never be executed. When in <tt/MainLoop/ systems waits for your action - using
1220 icons, keyboard or menus to force some specific action from program. You have to define
1221 proper handlers before that.
1225 <tt/void EnterDeskTop (void)/
1227 Calling this function will instantly terminate your program and bring you back to DeskTop.
1228 WARNING! It is not an equivalent of <tt/exit()/, library destructors code and functions
1229 registered with <tt/atexit()/ will not be called. In fact, you should always use
1230 <tt/exit()/ instead.
1234 <tt/void ToBASIC (void)/
1236 This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC.
1237 I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.
1238 It has the same dangerous features as <tt/EnterDeskTop/.
1242 <tt/void Panic (void)/
1244 This calls system's <tt/Panic/ handler - it shows dialog box with message
1246 System error at:xxxx
1248 where <tt/xxxx/ is last known execution address (caller). By default this is bound to <tt/BRK/
1249 instruction, but it might be usable in debugging as kind of <tt/assert/.
1251 System is halted after call to <tt/Panic/ which means that library destructors will not be
1252 called and some data may be lost (no wonder you're panicking).
1256 <tt/void CallRoutine (void *myFunct)/
1258 This is system caller routine. You need to provide pointer to a function and it will be immediately
1259 called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function -
1260 you don't need to check if the pointer is valid.
1262 <sect2>GetSerialNumber
1264 <tt/unsigned GetSerialNumber (void)/
1266 This function returns the serial number of system. It might be used for copy-protection.
1267 However, please remember that the Free Software is a true power and you are using it
1272 <tt/char GetRandom (void)/
1274 This function returns a random number. It can be also read from <tt/random/ e.g.
1278 but by calling this function you are sure that the results will be always different.
1279 <tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/.
1281 Note that it is not the same as <tt/rand/ function from the standard library. <tt/GetRandom/
1282 will give you unpredictable results (if IRQs will occur between calls to it) while
1283 <tt/rand/ conforms to the standard and for given seed (<tt/srand/) it always returns with the
1284 same sequence of values.
1288 <tt/void SetDevice (char device)/
1290 This function sets current device to given. It might be used together with <tt/InitForIO/,
1291 <tt/DoneWithIO/ and some Kernal routines. Unless new device is a disk drive this only sets
1292 new value in <tt/curDevice/, in other case new disk driver is loaded from REU or internal RAM.
1296 <tt/char get_ostype (void)/
1298 This function returns GEOS Kernal version combined (by logical OR) with machine type. Read
1299 <tt/gsys.h/ for definitions of returned values.
1303 <tt/char get_tv (void)/
1305 This function returns PAL/NTSC flag combined (by logical OR) with 40/80 columns flag. This is
1306 not the best way to check if screen has 40 or 80 columns since PAL/NTSC check is always
1307 performed and it can take as long as full raster frame. If you just want to know if
1308 screen has 40 or 80 columns use expression <tt/graphMode & 0x80/ which returns <tt/0/ for
1309 40 columns and <tt/0x80/ for 80 columns. Remember that this parameter can be changed during
1310 runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test
1311 anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for
1312 definitions of returned values.
1314 <sect>Library Structures
1316 To simplify usage and optimize passing parameters to functions I have declared several structures
1317 which describe most common objects. Some of these structures are bound to static addresses in
1318 GEOS data space ($8000-$8fff), so you can use their fields directly in optimized way.
1319 Please see <tt/gsym.h/ and find them. All structures are defined in <tt/gstruct.h/ and you may
1320 find also some comments there.
1322 <sect1>Graphics Structures
1326 One simple structure describing a point on the screen.
1330 This structure describes a font in one pointsize. There is current font - <tt/struct fontdesc/
1331 bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling
1332 <tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize
1333 somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can
1334 pass a pointer to the load adress of that pointsize to <tt/LoadCharSet/.
1338 This widely used structure holds description of a region of the screen. It describes top-left and
1339 bottom-right corners of a window.
1343 Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions -
1344 <tt/BitmapUp/ for example. This structure holds parameters needed to properly decode and show
1345 a bitmap on the screen. Bitmap has to be encoded - if you have some non-GEOS bitmaps simply
1346 convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/
1351 These structures describe click boxes (icons) that can be placed on screen or in a dialog box.
1355 This is the definition of a single click box. Please see <tt/gstruct.h/ for description of its fields.
1359 This is toplevel description of icons to be placed and enabled on the screen. This structure
1360 has following fields:
1362 <item><tt/char number/ - total number of icons declared here
1363 <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ mouse pointer will be placed in
1364 this point allowing you to have hint for user what is default action
1365 <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains
1366 descriptions for all icons
1369 <sect1>File and Disk
1373 This simple structure holds track and sector number of something. Do not expect the track to be
1374 in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K
1375 expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each. However assuming that
1376 track number equal to 0 is illegal might be wise.
1380 This is placeholder for file datestamp. This structure is also present in <tt/struct filehandle/.
1381 GEOS is not Y2K compliant, so if current file has in <tt/filehandle.date.year/ value less than 86
1382 you can safely assume that it is e.g. 2004 and not 1904.
1386 This is main file descriptor. It is either entry in the directory (returned from file functions)
1387 or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g.
1388 by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/.
1392 This structure holds fileheader description. You can load file's header into <tt/fileHeader/
1393 fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while
1394 <tt/fileheader/ is a structure).
1395 You will also need own fileheader for <tt/SaveFile/.
1397 <sect1>System Structures
1401 This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/
1402 so I prepared this one. You can e.g. get or set current time using <tt/system_date.s_hour/ and
1403 <tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/
1408 You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number
1409 of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold
1410 only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to called
1411 function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/.
1412 The second field <tt/jiffies/ holds the amount of time between calls to that function.
1413 On PAL systems there are 50 jiffies per second, while NTSC have 60 of them.
1415 <sect1>Few thing in detail...
1417 GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a
1418 kind of array of unspecified length and unspecified type. Here is how it goes:
1420 void example = {
1421 (char)3, (unsigned)3, (char)0 };
1423 Which will be compiled to following string of bytes:
1430 As you see this way it is possible to define data of any type in any order. You must remember to
1431 cast each member to proper type.
1433 <sect2>DoMenu structure
1435 <tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs
1436 are just initializing screen and menu and exit to <tt/MainLoop/. In GEOSLib it is the same as
1437 returning from <tt/main/ function without using <tt/exit(0)/.
1439 Menu is described by two types of data - menu descriptors and menu items. Descriptor contains
1440 information about following menu items, and items are containing names of entries and either
1441 pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors.
1442 Note that submenu descriptor can be top-level descriptor, there's no difference in structure,
1443 just in the content.
1445 Here is how single descriptor looks like:
1447 void myMenu = {
1448 (char)top, (char)botom, // this is the size of the menubox
1449 (unsigned)left, (unsigned)right, // counting all items in current descriptor
1450 (char)number_of_items | type_of_menu, // number of following items ORed with
1451 // type of this menu, it can be either
1452 // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed
1453 // after moving mouse pointer outside the menubox. You can have at most 31 items.
1455 This is followed by <tt/number_of_items/ of following item description.
1458 "menuitemname", (char)item_type, (unsigned)pointer,
1459 "nextitemname", (char)item_type, (unsigned)pointer,
1461 "lastitemname", (char)item_type, (unsigned)pointer };
1462 // Note that there isn't ending <tt/NULL/ or something like that.
1464 <tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one
1465 can have following values:
1467 <tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on menu item
1469 <tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu
1471 Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function
1472 which will return in <tt/r0/ needed pointer (to function to execute or a submenu).
1474 For creating nested menus (you can have at most 8 levels of submenus) you need to declare such
1475 structure for each submenu and top level menu.
1477 <sect2>DoDlgBox command string
1479 <tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is
1480 responsible for creating dialog boxes, that is windows which task is to interact with user.
1481 Format of the command string is following:
1483 (window size and position)
1484 (commands and parameters)
1487 There is custom type defined for the command string: <tt/dlgBoxStr/.
1489 <sect3>Size and position
1491 The first element can be specified in two ways - by using default size and position or specifying
1492 own. The first case results in
1494 const dlgBoxStr example = {
1495 DB_DEFPOS (pattern_of_shadow),
1499 And the own size and position would be:
1501 const dlgBoxStr example = {
1502 DB_SETPOS (pattern, top, bottom, left, right)
1509 The next element of <tt/DoDlgBox/ command string are commands themselves. First six commands are
1510 default icons and the number of selected icon will be returned from window processor. The icons are
1511 <tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for use them, e.g.:
1514 DB_ICON(OK, DBI_X_0, DBI_Y_0),
1517 Note that the position is counted from top left corner of window, not entire screen and that the 'x'
1518 position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
1519 <tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), default positions
1520 which will make icons to appear on default window exactly where you would expect them.
1522 <tt/DB_TXTSTR (x, y, text)/ will cause to show given text in the window.
1524 <tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location
1525 where the address of text is stored. This is useful for information windows where only text content
1526 is variable. Consider following:
1530 r15=(unsigned)text; // in code just before call to DoDlgBox
1532 DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15),
1535 will cause to appear the word ``foo'' in the window, but you may store the pointer to any text in
1536 <tt/r15/ (in this case) before call to DoDlgBox.
1538 <tt/DB_GETSTR(x, y, ptr, length)/ - will add input from keyboard feature. <tt/ptr/ works as in
1539 previous example and points to place where text is to be stored. Note that the contents of this
1540 place will be shown upon creating window. <tt/length/ is the maximum number of characters to input.
1542 <tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. It is called on every keypress.
1544 <tt/DB_GRPHSTR(ptr)/ - data for this command is the pointer for <tt/GraphicsString/ commands.
1546 <tt/DB_GETFILES(x, y)/ - for standard window you should pass 4 for both x and y. This function
1547 draws file selection box and searches current drive for files. Before call to <tt/DoDlgBox/ you
1548 must load <tt/r7L/ with GEOS filetype of searched files and <tt/r10/ with class text. In <tt/r5/
1549 you have to load pointer to a <tt/char[17]/ where selected filename will be copied. It works
1550 like <tt/FindFTypes/ but is limited to first 16 files.
1552 <tt/DB_OPVEC(ptr)/ - this sets the new pointer for button press function, if you pass
1553 <tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button.
1555 <tt/DB_USRICON(x, y, ptr)/ - places single user icon (click box) on window, <tt/ptr/ points at a
1556 <tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click
1557 boxes in a window, this is internal limit of GEOS Kernal.
1559 <tt/DB_USRROUT(ptr)/ - this command causes to immediately call user routine pointed by <tt/ptr/.
1561 <sect2>GraphicsString command string
1563 <tt/GraphicsString/ is a very powerful routine to initialize whole screen at once. There are
1564 predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. Last
1565 command have to be <tt/GSTR_END/. There is custom type defined for the command string: <tt/graphicStr/.
1567 Here is an example for clearing the screen:
1569 const graphicStr example = {
1572 RECTANGLETO(319,199)
1576 <sect2>InitRam table
1578 This type of data is used to initialize one or more bytes in many places at once. The format is
1581 void example = {
1582 (unsigned)address_to_store_values_at,
1583 (char)number_of_bytes_that_follow,
1584 (char)data,(char)data (...)
1585 (...) - more such definitions
1586 (unsigned)NULL - address of 0 ends the table