1 <!doctype linuxdoc system>
5 <!-- Title information -->
8 <author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl">
9 <date>v1.1, 26.12.1999, 16.03.2000, 19-22.03.2000, 11,29.07.2000
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 in its current stage doesn't support standard cc65 libraries. It is likely to be changed
31 in next version. Note that it doesn't mean that it will not work now. I didn't bother myself to
32 check if it is possible. All I needed for a start was including only <tt/geos.h/ in the source
35 I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
36 available code (well, the best as for machine :). Many of the <tt/void foo (void)/ functions are
37 just raw calls to Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you
38 will find many definitions of standard GEOS locations. Access to these addresses is optimized by
39 cc65 to simple <tt/lda/ and <tt/sta/.
43 You will not need c64 or c128 for development. The only hardware requirement is a PC capable of
44 runing cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your
49 <item><em/cc65/ Excellent package containing C crosscompiler, crossassembler and linker, you
50 can get it from: <htmlurl url="http://www.von-bassewitz.de/uz/cc65/"
51 name="http://www.von-bassewitz.de/uz/cc65/">
52 <item><em/VICE/ This is portable C64, C128 and few other Commodore computers emulator, you
53 can obtain it from: <htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
54 name="http://www.cs.cmu.edu/~dsladic/vice/vice.html">
55 <item><em/Star Commander/ This tool is for DOS right now. You will need it for transferring
56 object files from PC to 1541. There's also one important ability of this
57 tool - it automatically un-converts .cvt files into GEOS native format on
61 VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only
64 <em/Update:/ starting from v2.5.0 GEOSLib is a part of cc65 package as its GEOS support.
68 I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's
69 Reference Guide and BSW for GEOS.
71 GEOSLib is covered by the same license as cc65. You can find the whole text among documentation.
72 I would really appreciate if you would like to send me your comments, suggestions, questions,
73 changes, bug reports etc. I feel that GEOSLib may be much better. After all, this is the first
74 release. I will also appreciate if you will just give me a sign that you are using GEOSLib -
75 not especially something big and important, mail me even if you are just playing with it.
77 You can send postcards with hellos to:
79 Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW
83 e-mail: <tt/ytm@elysium.pl/
85 <sect>What have you got and what to do with it?
87 This chapter describes some rules you ought to obey, and how to use GEOSLib.
91 Ulrich probably won't like it, but I don't want you to use his standard C functions. In fact, the
92 best way (IMO) of programming GEOS with GEOSLib is to only use GEOS lib. You don't need anything
93 else. You shouldn't need anything else.
95 If you really, really need to mix standard libraries with GEOSLib be warned that it probably won't
96 work and lookout for the <tt/errno/ - it points to one place when <tt/errno.h/ is included and
97 another with <tt/geos.h/.
99 Apart from this file which merely describes only standard GEOS library functions you should read
100 <tt/grc/ (GEOS resource compiler) documentation. There are informations about necessary resource
101 files (each GEOS application neeeds at least one) and the building process - what should be done
106 All in all, you just need to place
108 #include <geos.h>
110 on top of your source.
112 Please read cc65's documentation on how to compile C, assembler and link everything together.
114 GEOSLib building process isn't yet defined stable. Detailed information how to link everything
115 together is in separated file together with resource compiler documentation.
117 As a general rule read the sources of example programs and read the headers. These are the most
118 reliable sources of knowledge ;). You will also find there many C macros representing various
119 arguments passed to functions. Please use them. You will find your sources easier to understand,
120 and it will be easier to find bugs.
122 All types used in GEOSLib are <tt/unsigned/.
124 Screen coordinates are given in pixels unless stated differently.
126 <sect1>Notes on style
128 All programs start their execution on <tt/main/ function. Unlike plain C exiting from this function
129 doesn't mean end of program. GEOS is event-driven environment where applications are only executing
130 events, main loop is in kernal. <tt/main/ function should setup the screen, menus etc. and return.
131 Real end of the program should be called from event call, e.g. from menu item. You can force end of
132 program and return to DeskTop either by standard <tt/exit (0)/ function or by <tt/EnterDeskTop()/.
133 Currently they are almost the same (last minute note: don't use <tt/exit/ ever, it's broken right
136 Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into
137 series of <tt/lda/ and <tt/sta/, so you can't do it better :-).
139 Don't hesitate to use library functions. Everything was written with size and speed in mind. In
140 fact many calls are just redirections to GEOS kernal which results in simple <tt/jsr/.
142 You might wonder why I have chosen sometimes weird order of arguments in functions. It is because
143 I wanted to avoid unnecessary pushing and popping arguments from stack. cc65 can pass single <tt/int/
144 through CPU registers.
146 Do not try to compile in strict ANSI mode. I'm using some cc65 extensions which are not available in
149 <sect>Library Functions
151 Functions here are sorted more or less in the way they appear in header files. This way I am able
152 to keep functions covering similar task near each other. All function names are identical to those
153 from <tt/geosSym/ file provided with GeoProgrammer package. Only my extensions to <tt/geosSym/
154 are covered by new names, but I tried to keep them in the naming convention.
158 This section covers drawing package of GEOS along with text output routines.
162 <tt/void SetPattern (char pattern)/
164 This function sets current pattern to given. There are 32 different patterns in GEOS. You can
165 see them together in the filling box in GeoPaint.
167 <sect2>GraphicsString
169 <tt/void GraphicsString (char *myGString)/
171 One of the more powerfull routines of GEOS. This function calls other graphic functions depending
172 on given command string. See structures chapter for more detailed description of the structure of it.
174 <sect2>Rectangle functions
176 Parameters to those functions are grouped in <tt/struct window drawWindow/. To speed up things and
177 reduce overhead this structure is glued to zero page locations, where all rectangle functions
178 expect their parameters. You can modify data directly (e.g. <tt/drawWindow.top=10/) or via
179 <tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change only when
180 using graphics functions. In other case you should keep your data in separate <tt/struct window/
181 and use <tt/InitDrawWindow/ before first call to rectangle functions.
183 <sect3>InitDrawWindow
185 <tt/void InitDrawWindow (struct window *myWindow)/
187 This function only copies contents of <tt/myWindow/ into system area of <tt/drawWindow/. Use it
188 if for some reason you have to keep window data out of zero page space.
192 <tt/void Rectangle (void)/
194 This draws on screen rectangle filled with current pattern.
196 <sect3>FrameRectangle
198 <tt/void FrameRectangle (char pattern)/
200 This one draws frame with given line pattern.
202 <sect3>InvertRectangle
204 <tt/void InvertRectangle (void)/
206 Just as the name says...
208 <sect3>ImprintRectangle and RecoverRectangle
210 <tt/void ImprintRectangle (void)/
212 <tt/void RecoverRectangle (void)/
214 These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/)
215 backbuffer of the screen. For example GEOS drawing new menus on screen first uses
216 <tt/ImprintRectangle/ to save the area under menu, and restores it by <tt/RecoverRectangle/ upon
219 <sect2>Line Functions
221 GEOS drawing package is optimized so there are different functions for drawing vertical and
224 <sect3>HorizontalLine
226 <tt/void HorizontalLine (char pattern, char y, int xStart, int xEnd)/
228 This function draws horizontal line using given pattern - here it is a true bit pattern, not
229 pattern set by <tt/SetPattern/.
233 <tt/void InvertLine (char y, int xStart, int xEnd)/
235 There is only horizontal version.
239 <tt/void RecoverLine (char y, int xStart, int xEnd)/
241 This function recovers only one line. It is utilized by <tt/RecoverRectangle/. See its description
246 <tt/void VerticalLine (char pattern, char yStart, char yEnd, int x)/
248 This function draws vertical line using given pattern. Note that <tt/pattern/ is not a pattern
249 number as set in <tt/SetPattern/ but a true bit pattern.
253 <tt/void DrawLine (struct window *myWindow)/
255 <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while
256 <tt/bottom/ are for the ending point. Current pattern is used for drawing.
258 <sect2>Point Functions
260 Parameters to these two functions are passed by a pointer to own <tt/struct pixel/ filled with
265 <tt/void DrawPoint (struct pixel *myPixel)/
267 Draws single point on the screen, no matter what the current pattern is.
271 <tt/char TestPoint (struct pixel *myPixel)/
273 This function tests if given pixel is set and returns true or false.
275 <sect2>Character and string output
279 <tt/void PutChar (char character, char y, char x)/
281 This function outputs single character using current style and font to screen.
285 <tt/void PutString (char *myString, char y, int x)/
287 Same as <tt/PutChar/ except the fact that you can output whole <tt/NULL/-terminated string.
288 See <tt/ggraph.h/ for list of tokens that you can also place in the string - like <tt/CBOLDON/ or
293 <tt/void PutDecimal (char parameter, int value, char y, int x)/
295 This function converts <tt/value/ to its decimal representation and outputs it to the screen.
296 Depending on given <tt/parameter/ the string can be filled with zeroes (string always 5 characters
297 long) or not, to be left or right justified to given pixel. See <tt/ggraph.h/ for predefined
298 values for <tt/parameter/.
304 <tt/char GetCharWidth (char character)/
306 This function returns real width (in pixels) of given character with current font. It can be used
307 for counting the length of string on screen, allowing for indentation or justification.
311 <tt/void LoadCharSet (struct fontdesc *myFont)/
313 This function forces GEOS to use given font instead of own. <tt/myFont/ should be casted from
314 pointer to the start of area where was loaded record from font file (VLIR structure).
318 <tt/void UseSystemFont (void)/
320 This function forces GEOS to use built-in BSW font.
322 <sect2>Bitmap handling
324 I'm not quite sure how are these functions working (except <tt/BitmapUp/) so you should
325 probably look into library sources and compare it with your knowledge. Please let me know
326 if something is wrong or broken.
330 <tt/void BitmapUp (struct iconpic *myPic)/
332 This function unpacks the bitmap and places it on the screen - just as you set it in the
333 <tt/struct iconpic/ pointer to which you pass. See <tt/gstruct.h/ for description of this
334 structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.
338 <tt/void BitmapClip (char skipLeft, char skipRight, int skipTop, struct iconpic *myPic)/
340 This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are
341 to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap,
342 and the number of rows to skip from the top if it.
346 <tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, int skipTop,
347 struct iconpic *myPic)/
349 Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it
350 returns in .A next value), and <tt/proc2/ is called every time the parser reads a byte which is
351 not a piece of pattern (byte of code greater than 219). Both procedures should be written
352 separately in assembler and declared as <tt/__fastcall__/ returning char.
354 <sect1>Menus and Icons
356 Here you will find information about functions related with menus and icons.
360 Menus are essencial for GUI. GEOS can handle only one menu at a time, but each menu can call
361 another one, which results in submenu tree. There can be up to 8 menu levels, each one with up
364 Menus are initialized with <tt/DoMenu/ and then Kernal takes care for everything. Your code
365 (called from event handler) should be a function without parameters, returning void. You should
366 use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean.
370 <tt/void DoMenu (struct menu *myMenu)/
372 This function initializes GEOS menu processor and exits. See <tt/DoMenu structure/ for more
373 information about it. Know that many GEOS application just initializes the screen, menu and
374 exits to main Kernal loop, this proves the power of <tt/DoMenu/.
378 <tt/void ReDoMenu (void)/
380 This simply redraws the menu at lowest level. It works like calling <tt/DoMenu/ again with
385 <tt/void RecoverMenu (void)/
387 This function erases current menu from the screen. It doesn't change the menu level.
389 <sect3>RecoverAllMenus
391 <tt/void RecoverAllMenus (void)/
393 This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is
396 <sect3>DoPreviousMenu
398 <tt/void DoPreviousMenu (void)/
400 This functions causes menu processor to go back one menu level. You should use it in menu
401 handler code to have the screen clean.
405 <tt/void GotoFirstMenu (void)/
407 This one jumps back to the topmost menu. If there is only menu and submenu it works the
408 same as <tt/DoPreviousMenu/.
412 Icons are working similar to menus except the fact that there is only one level. Icons are
413 defined as a screen area filled with a bitmap, but if you would setup icons and erase the
414 screen they are still working and cliking in the place where formerly an icon was will cause
415 an effect. Similary if you would setup icons and then turn them off with <tt/ClearMouseMode/
416 the bitmap will be still on the screen.
417 There is only one, but powerful icon function.
421 <tt/void DoIcons (struct icontab *myIconTab)/
423 This function initializes all icons that are present on the screen at once. For more information
424 look at <tt/Icons/ chapter in this manual.
428 This chapter covers the most powerful GEOS function - <tt/DoDlgBox/.
434 <tt/char DoDlgBox (char *dialogString)/
436 DialogBox returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/)
437 or whatever closing routine passes. Register <tt/r0L/ also contains this value.
439 Read structures chapter for the specs of the <tt/dialogString/.
441 <sect3>RstrFrmDialogue
443 <tt/char RstrFrmDialogue/
445 This function called from within DialogBox event immediately closes the DialogBox and returns
446 the owner ID (or whatever caller has in the .A register).
448 <sect2>GEOSLib extensions
450 To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox,
451 with predefined data. In one word - these are standard DialogBoxes you can see in almost every
454 <sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk
456 <tt/char DlgBoxYesNo (char *line1, char*line2)/
458 <tt/char DlgBoxOkCancel (char *line1, char*line2)/
460 <tt/void DlgBoxOk (char *line1, char*line2)/
462 These function show two lines of text in standard-sized DialogBox. You can read the code of
463 pressed icon from return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/.
465 <sect3>DlgBoxGetString
467 <tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/
469 This function prompts user for entering a string of at most <tt/strlen/ characters. It is returned
470 in <tt/string/. The two given lines of text are shown above the input line. Please remember
471 that there is also <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his
472 input or gave up. The <tt/string/ is also shown so you can place default input there or remember
473 to place <tt/NULL/ at start.
475 <sect3>DlgBoxFileSelect
477 <tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/
479 This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error
480 on reading the directory or opening the disk.
481 There is also <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters
482 <tt/filetype/ and pointer to string containing the first part of file's class. If this string is
483 empty (<tt/NULL/ at the start), then all files with given filetype will be shown.
485 At present this file selector handles only first 16 files of given type and supports only one
488 <sect1>Mouse, Sprites and Cursors
490 You will find here functions related to sprite and mouse drawing and handling.
492 <sect2>Mouse related functions
494 These cover mouse - as a general pointing device, but expect user to utilize as different devices
495 as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).
497 <sect3>StartMouseMode
499 <tt/void StartMouseMode (void)/
501 This function initializes mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then
504 <sect3>ClearMouseMode
506 <tt/void ClearMouseMode (void)/
508 This function disables all mouse actitivies - icons and menus stop to respond to mouse events,
509 but they are not cleared from the screen.
511 <sect3>MouseUp and MouseOff
513 <tt/void MouseUp (void)/
515 <tt/void MouseOff (void)/
517 The fist function turns the mouse pointer on. It will appear on next IRQ. The second one does
518 the opposite - it turns off the pointer, but its position is still updated by input driver.
522 <tt/char IsMseInRegion (struct window *myWindow)/
524 This function tests if mouse pointer is actually in given range of screen. See <tt/gsprite.h/ for
525 possible return values - they describe the position in detail.
529 You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
530 pointer and sprite 1 can be overwritten when is used as text prompt.
534 <tt/void DrawSprite (char sprite, char *mySprite)/
536 This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which
537 is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Sprite visual registers are
538 not initialized and sprite is not yet visible.
542 <tt/void PosSprite (char sprite, struct pixel *myPixel)/
544 This function positions the sprite on the screen. Given coordinates are screen ones - they are
545 converted to sprite coords by GEOS. Due to this you cannot use this function to position your
546 sprite off the left or top to the screen.
548 <sect3>EnablSprite and DisablSprite
550 <tt/void EnablSprite (char sprite)/
552 <tt/void DisablSprite (char sprite)/
554 These two functions are responsible for the fact if the sprite will or will not appear on the
557 <sect2>Cursors and Console
559 <sect3>InitTextPrompt
561 <tt/void InitTextPrompt (char height)/
563 This function initializes sprite 1 for text prompt with given <tt/height/. This parameter can be in
566 <sect3>PromptOn and PromptOff
568 <tt/void PromptOn (struct pixel *myPixel)/
570 <tt/void PromptOff (void)/
572 The first function places text prompt in given place and enables it so it blinks and generally is
573 visible. The second function is pretty self-explanatory.
577 <tt/char GetNextChar (void)/
579 This function gets next character from the keyboard queue. If the queue is empty it returns
580 <tt/NULL/, otherwise you receive true ASCII code of a character or value of special (function)
581 key. See <tt/gsprite.h/ for list of them.
585 This chapter covers slightly low-level disk routines. You should use them with care, because
586 you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various
587 devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
590 All GEOS disk functions return error code in X register. In some cases this is returned by
591 GEOSLib function (if its type is <tt/char/), but in all cases last error is saved in <tt/errno/
592 location. If it is nonzero - an error occured. See <tt/gdisk.h/ for list of errorcodes.
594 Passing parameters use always e.g. <tt/ReadBuff (&myTrSe)/.
596 <sect2>Buffer functions
598 These functions are taking single data sector (256 bytes) to read or write on a disk.
600 <sect3>ReadBuff and Writebuff
602 <tt/char ReadBuff (struct tr_se *myTrSe)/
604 <tt/char WriteBuff (struct tr_se *myTrSe)/
606 These functions are reading and writting sector placed at <tt/diskBlkBuf/.
608 <sect3>GetBlock and ReadBlock
610 <tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/
612 <tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/
614 These two functions are reading a single block directly at 256 byte array placed at <tt/buffer/.
615 The difference between them is that <tt/GetBlock/ will initialize TurboDos in drive if it was not
616 enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster.
618 <sect3>PutBlock, WriteBlock, VerWriteBlock
620 <tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/
622 <tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/
624 <tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/
626 Similar to previous but needed for writting the disk. <tt/VerWriteBlock/ verifies the data after
627 writting. In case of error five tries are attempted before error code is returned.
629 <sect2>Directory header
631 Functions described here are operating on <tt/curDirHeader/ where current disk header is stored.
632 On larger capacity drives (than 1541) the second part of directory header in <tt/dir2Head/.
636 <tt/void GetPtrCurDkNm (char *diskName)/
638 This function fills given character string with the name of current disk. It is converted to C
639 standard - string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS.
640 Note that passed pointer must point to an array of at least 17 bytes.
642 <sect3>GetDirHead and PutDirHead
644 <tt/char GetDirHead (void)/
646 <tt/char PutDirHead (void)/
648 These functions are reading and writting the directory header. You should use <tt/GetDirHead/ before
649 using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the
650 disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/.
654 <tt/int CalcBlksFree (void)/
656 This function returns the number of free blocks on current disk. It is counted using data in
657 <tt/curDirHead/ so you must initialize the disk before calling it.
661 <tt/char ChkDskGEOS (void)/
663 This functions checks <tt/curDirHead/ for GEOS Format identifier. It returns either true or false,
664 and also sets <tt/isGEOS/ properly. You must initialize the disk before using this.
668 <tt/char SetGEOSDisk (void)/
670 This function initializes disk for use with GEOS. It sets indicator in directory header and
671 allocates a sector for the directory of border files. You don't need to initialize the disk before
676 <tt/char FindBAMBit (struct tr_se *myTrSe)/
678 This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is
679 set if the sector is free to use. Returned value is always zero if the sector is already allocated.
680 In fact, this function could be described as e.g. <tt/SectInUse/ and used in following way:
683 if (!SectInUse(&myTrSe)) {
684 ... block not allocated ...
688 Anyway, I feel that this function is slightly low-level, maybe too low-level.
690 <sect3>BlkAlloc and NxtBlkAlloc
692 <tt/char BlkAlloc (struct tr_se output[&rsqb, int length)/
694 <tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, int length)/
696 Both functions are allocating enough disk sectors to fit the number of <tt/length/ in them. You
697 will find output in <tt/output/ which is table of <tt/struct tr_se/. The last entry will have the
698 number of track equal to 0 and sector equal to 255. The simpliest way of using them is to use
699 predefined space in GEOS data space and pass <tt/fileTrScTab/, which is a predefined table.
701 The difference between those two is that <tt/NextBlkAlloc/ will start allocating from given sector,
702 and <tt/BlkAlloc/ starts from first nonused sector.
704 You need to <tt/PutDirHead/ to save any changes in BAM.
708 <tt/char FreeBlock (struct tr_se *myTrSe)/
710 Simply deallocates a block in BAM. You need to update BAM with <tt/PutDirHead/.
714 <tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/
716 This function finds first free sector starting from given track and sector. It might return the
717 same argument if the given block is not allocated. I wanted this function to be type-clean, but
718 it made usage a bit tricky. To assign a value to own <tt/struct tr_se/ you have to cast both
719 variables to <tt/int/. E.g.
723 (int)myTrSe=(int)SetNextFree(&otherTrSe);
726 In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
728 NOTE that you <em/must/ use casting to have correct values.
730 <tt/SetNextFree/ only finds next free sector, it doesn't allocate it.
732 <sect2>Low-level disk IO
734 Functions described here are more usable in kernal or drivers code, less common in applications,
735 but who knows, maybe someone will need them.
737 <sect3>EnterTurbo, ExitTurbo, PurgeTurbo
739 <tt/void EnterTurbo (void)/
741 <tt/void ExitTurbo (void)/
743 <tt/void PurgeTurbo (void)/
745 These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit
746 more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will
747 have to wait a bit to transfer TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos.
748 This is useful for sending some DOS commands for drive e.g. for formatting. Note that before any
749 interaction with Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed.
750 <tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with
751 <tt/ExitTurbo/. <tt/PurgeTurbo/ acts different from <tt/ExitTurbo/ - it not only disables TurboDos,
752 but also removes it from drive RAM (not quite true, but it works like that). After a <tt/PurgeTurbo/,
753 <tt/EnterTurbo/ will have to reload drive RAM.
755 <sect3>ChangeDiskDevice
757 <tt/char ChangeDiskDevice (char newDevice)/
759 This function changes logical number of current device (in fact drives only) with given one. It is
760 usable for swapping drives. There's no check if given <tt/newDevice/ already exist, so if you want
761 to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably
762 hung on disk access. Use safe, large numbers. Note that safe IEC range is 0-32, but devices with
763 numbers below 8 shouldn't be used (there is 'DiskDevice' in the name of this function and devices
764 0-7 are not 'DiskDevices' you know :-).
766 <sect2>Disk Initialization
768 GEOS has two functions for initialization ('logging' as they say on CP\M) the disk.
771 <tt/char OpenDisk (void)/
773 This function initializes everything for a new disk. It loads and enables TurboDos if needed.
774 Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/.
775 Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is
776 checked with <tt/ChkDkGEOS/ and disk name is updated in internal tables.
780 <tt/char NewDisk (void)/
782 This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.
786 This section cover GEOS file interface.
788 <sect2>Directory handling
790 Functions described here are common for SEQ and VLIR structures.
792 <sect3>Get1stDirEntry and GetNxtDirEntry
794 <tt/struct filehandle *Get1stDirEntry (void)/
796 <tt/struct filehandle *GetNxtDirEntry (void)/
798 These two functions are best suited for scanning whole directory for particular files. Note that
799 returned filehandles describe all file slots in directories - even those with deleted files.
800 The return value can be obtained by casting both sides to <tt/int/ - as in <tt/SetNextFree/
801 function, or read directly after call to those two functions from <tt/r5/. Current sector number
802 is in <tt/r1/ and sector data itself is in <tt/diskBlkBuf/.
806 <tt/char FindFile (char *fName)/
808 This function scans whole directory for given filename. It returns either 0 (success) or 5
809 (FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After successful
810 <tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with file's data and
811 other registers set as described in <tt/GetNxtDirEntry/.
815 <tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/
817 This function scans directory and fills a table at <tt/buffer/ with <tt/char [17]/ entries.
818 <tt/fType/ is GEOS type of searched files and <tt/classTxt/ is a string for Class field in file
819 header. Class will match if given will be equal or shorter than that found in file's header block.
820 If you want just to find all files with given GEOS type you should pass empty string or <tt/NULL/ as
821 <tt/classTxt/. Be warned that for searching NON_GEOS files must pass <tt/NULL/ as <tt/classTxt/.
822 <tt/fMaxNum/ is the maximal number of found files, thus the <tt/buffer/ must
823 provide area of size equal to <tt/17 * fMaxNum/.
824 This function returns the number of found files, ranging from 0 to number passed as fMaxNum.
825 Return value from kernal FindFTypes can be restored from <tt/r7H/.
829 <tt/char DeleteFile (char *fName)/
831 This function deletes a file by its name. It works for SEQ and VLIR files.
835 <tt/char RenameFile (char *oldName, char *newName)/
837 I think it is obvious...
841 <tt/char GetFHdrInfo (struct filehandle *myFile)/
843 This function loads the file header into <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/
844 you can pass address of <tt/dirEntryBuf/.
846 <sect2>Common and SEQ structure
848 Functions described here are common for SEQ and VLIR structures because arguments passed are
849 starting track and sector which may point either to start of a chain for VLIR or data for SEQ.
853 <tt/char ReadFile (struct tr_se *myTrSe, char *buffer, int fLength)/
855 This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at
860 <tt/char ReadByte (void)/
862 This function returns next byte from file. Before first call to this function you must load the
863 first sector of file, easiest way by using <tt/GetBlock/ and set <tt/r5/ to the offset (you will
864 want to skip the link, so use the value of 2 here). Then you may call <tt/ReadByte/.
865 Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/.
867 Returned value is valid only if there wasn't any error. End of file is marked as <tt/BFR_OVERFLOW/
868 in <tt/errno/, this is set when trying to read one byte after the end of file.
872 <tt/char SaveFile (struct fileheader *myHeader)/
874 <tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter VLIR of SEQ
875 structure. All you need to do is to place data in proper place and prepare a header which will
876 contain all information about a file.
878 You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one
879 difference - the first two bytes which are link to nonexistant next sector are replaced by a
880 pointer to the DOS filename of the file.
882 When saving files two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/
883 and <tt/fileheader.end_address/.
887 <tt/char FreeFile (struct tr_se myTable[])/
889 This function deallocates all sectors contained in passed table.
893 <tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/
895 This function fills a <tt/struct tr_se/ table at <tt/buffer/ with sector numbers for chain of
896 sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/.
898 <sect2>VLIR structure
900 Here are informations about VLIR files (called later as RecordFile) and functions.
902 VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one
903 SEQ structure file. Records are grouped together, described by common name - VLIR file name and
904 own number. Each record pointed by its number is described by starting track and sector numbers.
905 VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/),
906 or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent starting track and sector of
909 In GEOS there can be only one file opened at a time. Upon opening VLIR file some information
910 about it are copied into memory. You can retrieve records table at <tt/fileTrScTab/ (table of
911 128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/.
912 E.g. size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/.
914 <sect3>OpenRecordFile
916 <tt/char OpenRecordFile (char *fName)/
918 This function finds and opens given file. An error is returned if file is not found or it is not
919 in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is
920 loaded at <tt/fileTrScTab/ and will be valid until call to <tt/CloseRecordFile/ so don't modify it.
921 You should <tt/PointRecord/ before trying to do something with file.
923 <sect3>CloseRecordFile
925 <tt/char CloseRecordFile (void)/
927 This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables.
929 <sect3>UpdateRecordFile
931 <tt/char UpdateRecordFile (void)/
933 This function fill check <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ will
934 be updated along with size and date stamps in directory entry.
938 <tt/char PointRecord (char recordNumber)/
940 This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and
941 sector of given record in <tt/r1/. Note that the data may not be valid (if record is non-existing
942 you will get 0,0 and if it is empty - 255, 0).
944 <sect3>NextRecord and PreviousRecord
946 <tt/char NextRecord (void)/
948 <tt/char PreviousRecord (void)/
950 These two work like <tt/PointRecord/. Names are self-explanatory.
954 <tt/char AppendRecord (void)/
956 This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector
957 table. It will also set <tt/VLIRInfo.curRecord/ to its number.
961 <tt/char DeleteRecord (void)/
963 This function will remove current record from the table, and move all current+1 records one place
964 back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to
969 <tt/char InsertRecord (void)/
971 This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following
972 records in table one place forward (contents of <tt/VLIRInfo.curRecord/ after call to <tt/InsertRecord/
973 can be found in <tt/VLIRInfo.curRecord + 1/).
975 <sect3>ReadRecord and WriteRecord
977 <tt/char ReadRecord (char *buffer, int fLength)/
979 <tt/char WriteRecord (char *buffer, int fLength)/
981 This function will load or save at most <tt/fLength/ bytes from currently pointed record into or from
984 <sect1>Memory and Strings
986 Functions covered in this section are common for whole C world - copying memory parts and
987 strings is one of the main computer tasks. GEOS also has interface to do this. These functions
988 are replacement for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries.
990 However they have slighty different calling convention (order of arguments to be specific), so
991 please check their syntax here before direct replacing.
993 Please note that the memory described as <tt/strings/ are up to 255 characters (without
994 counting the terminating <tt/NULL/), and <tt/regions/ cover whole 64K of memory.
998 <tt/void CopyString (char *dest, char *src)/
1000 This function copies string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. <tt/NULL/
1005 <tt/char CmpString (char *s1, char *s2)/
1007 This function compares string <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both
1008 strings have to have the same length. It returns either <tt/true/ or <tt/false/.
1010 <sect2>CopyFString and CmpFString
1012 <tt/void CopyFString (char length, char *dest, char *src)/
1014 <tt/char CmpFString (char length, char *s1, char *s2)/
1016 These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide
1017 the length of copied or compared strings. The strings can also contain several <tt/NULL/
1018 characters - they are not treated as delimiters.
1022 <tt/int CRC (char *src, int length)/
1024 This function calculates the CRC checksum for given memory range. I don't know if it is
1025 compatible with standard CRC routines.
1027 <sect2>FillRam and ClearRam
1029 <tt/void FillRam (char value, char *dest, int length)/
1031 <tt/void ClearRam (char *dest, int length)/
1033 Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/NULLs/, while
1034 <tt/FillRam/ uses given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and
1039 <tt/void MoveData (char *src, char *dest, int length)/
1041 This functions copies one memory region to another. There are checks for overlap and the
1042 non-destructive method is chosen. Be warned that this function destroys contents of
1043 <tt/r0, r1 and r2/ registers.
1047 <tt/void InitRam (char *table)/
1049 This function allows to initialize multiple memory locations with single bytes or strings.
1050 This is done with <tt/table/ where everything is defined. See structures chapter for description of
1051 <tt/InitRam's/ command string.
1053 <sect2>Stash, Fetch, Swap, and VerifyRAM
1055 <tt/void StashRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
1057 <tt/void FetchRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
1059 <tt/void SwapRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
1061 <tt/ char VerifyRAM (char bank, int length, char *reuAddy, char *cpuAddy)/
1063 These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
1065 <sect1>Processes and Multitasking
1067 Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions
1068 called in specified intervals and you can sleep the main program without disturbing other
1071 <sect2>InitProcesses
1073 <tt/void InitProcesses (char number, struct process *processTab)/
1075 This is the main initialization routine. After calling this processes are set up, but not
1076 enabled. The parameters for <tt/InitProcesses/ are:
1078 <item><tt/number/ - number of processes
1079 <item><tt/processTab/ - table of <tt/struct process/, with size equal to <tt/number/
1082 Single task is described by entry in <tt/processTab/, it contains two values - <tt/pointer/ to
1083 task function and number of <tt/jiffies/ which describe the delay between calls to task. On PAL
1084 systems there are 50 jiffies per second, while on NTSC there are 60.
1086 The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
1087 if <tt/processTab/ would be too large it would overwrite existing data in GEOS space.
1089 There's one important thing - last entry in <tt/processTab/ have to be <tt/NULL,NULL/, so the
1090 maximum size of <tt/processTab/ is equal to 21.
1092 See description of <tt/process/ structure for more detailed discussion on this.
1094 <sect2>RestartProcess and EnableProcess
1096 <tt/void RestartProcess (char processNumber)/
1098 <tt/void EnableProcess (char processNumber)/
1100 These two functions start the task counter. <tt/RestartProcess/ for each process should be called
1101 after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters.
1103 <tt/RestartProcess/ enables counters and sets their initial value to that given in <tt/processTab/.
1105 <tt/EnableProcess/ forces given process to execute by simulating the timer running out of time.
1107 <sect2>BlockProcess and UnBlockProcess
1109 <tt/void BlockProcess (char processNumber)/
1111 <tt/void UnBlockProcess (char processNumber)/
1113 <tt/BlockProcess/ disables the execution of given process, but this does not disable the timers.
1115 <tt/UnBlockProcess/ does the opposite.
1117 <sect2>FreezeProcess and UnFreezeProcess
1119 <tt/void FreezeProcess (char processNumber)/
1121 <tt/void UnFreezeProcess (char processNumber)/
1123 <tt/FreezeProcess/ disables timer for given process. <tt/UnFreezeProcess/ does the opposite.
1124 This is not equal to <tt/RestartProcess/ as timers are not filled with initial value.
1128 <tt/void Sleep (int jiffies)/
1130 This function is multitasking sleep - the program is halted, but it doesn't block other functions.
1131 The only argument here is the number of jiffies to wait until app will wake up.
1133 You can force to sleep not only the main application routine, but also processes-tasks. Be warned
1134 that the maximum number of sleeping functions is 20. If it would be larger it will overwrite
1135 parameters of already sleeping functions in GEOS kernal data space, leading to crash.
1141 <tt/void FirstInit (void)/
1143 This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot
1144 up. You shouldn't use this unless you know what you are doing.
1146 <sect2>InitForIO and DoneWithIO
1148 <tt/void InitForIO (void)/
1150 <tt/void DoneWithIO (void)/
1152 These functions are called by some disk routines. You should call them only if you want to
1153 do something with IO registers or call one of Kernal's routines.
1157 <tt/void MainLoop (void)/
1159 Your programs exits to MainLoop upon exiting from <tt/main/, but you might need this function in
1160 menu and icon code. When in <tt/MainLoop/ systems waits for your action - using icons, keyboard
1161 or menus to force some specific action from program.
1165 <tt/void EnterDeskTop (void)/
1167 This is default exit code of your application. It is finish of <tt/exit()/, but you may need it
1168 in other places of application.
1172 <tt/void ToBASIC (void)/
1174 This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC.
1175 I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.
1179 <tt/void Panic (void)/
1181 This calls system's <tt/Panic/ handler - it shows dialog box with message
1183 System error at:xxxx
1185 where <tt/xxxx/ is last known execution address (caller). By default this is binded to <tt/BRK/
1186 instruction, but it might be usable in debugging as kind of <tt/assert/.
1188 System is halted after call to <tt/Panic/.
1192 <tt/void CallRoutine (void * myFunct)/
1194 This is system caller routine. You need to provide pointer to a function and it will be immediately
1195 called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function -
1196 you need not to worry if the pointer is valid.
1198 <sect2>GetSerialNumber
1200 <tt/int GetSerialNumber (void)/
1202 This function returns the serial number of system. It might be used for copy-protection, but you
1203 shouldn't do this. Please remember that the Free Software is a true power.
1207 <tt/char GetRandom (void)/
1209 This function returns a random number. It can be also read from <tt/random/ e.g.
1213 but by calling this function you are sure that the results will be always different.
1214 <tt/random/ is updated once a frame (50Hz) and on every call to <tt/GetRandom/
1218 <tt/void SetDevice (char)/
1220 This function sets current device to given. It might be used together with <tt/InitForIO/,
1221 <tt/DoneWithIO/ and some Kernal routines. Unless new device is a disk drive this only sets
1222 new value in <tt/curDevice/, in other case new disk driver is loaded from REU or internal RAM.
1224 <sect>Library Structures
1226 To simplify using and optimize passing parameters to functions I have declared several structures
1227 which describe most common objects. Some of these structures are binded to static addresses in
1228 GEOS data space ($8000-$8fff), so you can use their fields directly in optimized way.
1229 Please see <tt/gsym.h/ and find them. All structures are defined in <tt/gstruct.h/ and you may
1230 find also some comments there.
1236 One simple structure describing point on the screen.
1240 This structure describes font in one pointsize. There is current font - <tt/struct fontdesc/
1241 binded at <tt/curFontDesc/. You can also force GEOS to use your own font by calling
1242 <tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize
1243 somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can
1244 pass a pointer to the load adress of that pointsize to <tt/LoadCharSet/.
1248 This widely used structure holds description of a region of the screen. It describes top-left and
1249 bottom-right corners of a window.
1253 Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions -
1254 <tt/BitmapUp/ for example. This structure holds parameters needed to properly decode and show
1255 a bitmap on the screen. Bitmap has to be encoded - if you have some non-GEOS bitmaps simply
1256 convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/
1261 These structures describe click boxes (icons) that can be placed on screen or in a dialog box.
1265 This is the definition of a single click box. Please see <tt/gstruct.h/ for description of its fields.
1269 This is toplevel description of icons to be placed and enabled on the screen. This structure
1270 has following fields:
1272 <item><tt/char number/ - total number of icons declared here
1273 <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ mouse pointer will be placed in
1274 this point allowing you to have hint for user what is default action
1275 <item><tt/struct icondef tab[&rsqb/ - this table of size equal to <tt/icontab.number/ contains
1276 descriptions for all icons
1279 <sect1>File and Disk
1283 This simple structure holds track and sector number of something. Do not expect the track to be
1284 in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K
1285 expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each.
1289 This is placeholder for file datestamp. This structure is also present in <tt/struct filehandle/.
1290 GEOS is not Y2K compliant, so if current file in <tt/filehandle.date.year/ value less than 86 you
1291 can safely assume that it is e.g. 2085 - not 2086.
1295 This is main file descriptor. It is either entry in the directory (returned from file functions)
1296 or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g.
1297 by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/.
1301 This structure holds fileheader description. You can load file's header into <tt/fileHeader/
1302 fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while
1303 <tt/fileheader/ is a structure).
1304 You will also need own fileheader for <tt/SaveFile/.
1310 This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/
1311 so I prepared this one. You can e.g. get or set current time using <tt/system_date.s_hour/ and
1312 <tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/
1317 You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number
1318 of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold
1319 only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to called
1320 function (void returning void), you will probably have to cast that pointer into int. The second
1321 field <tt/jiffies/ holds the amount of time between calls to that function. On PAL systems there
1322 are 50 jiffies per second, while NTSC have 60 of them.
1324 <sect1>Few thing in detail...
1326 GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a
1327 kind of array of unspecified length and unspecified type. Here is how it goes:
1329 void example = {
1330 (char)3, (unsigned)3, (char)0 };
1332 Which will be compiled to following string of bytes:
1339 As you see this way it is possible to define data of any type in any order. You must remember to
1340 cast each member to proper type.
1342 <sect2>DoMenu structure
1344 <tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs
1345 are just initializing screen and menu and exit to <tt/MainLoop/. In GEOSLib it is the same as
1346 returning from <tt/main/ function without using <tt/exit(0)/.
1348 Menu is described by two types of data - menu descriptors and menu items. Descriptor contains
1349 information about following menu items, and items are containing names of entries and either
1350 pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors.
1351 Note that submenu descriptor can be top-level descriptor, there's no difference in structure,
1352 just in the content.
1354 Here is how single descriptor looks like:
1356 void myMenu = {
1357 (char)top, (char)botom, // this is the size of the menubox
1358 (unsigned)left, (unsigned)right, // counting all items in current descriptor
1359 (char)number_of_items | type_of_menu, // number of following items ORed with
1360 // type of this menu, it can be either
1361 // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed
1362 // after moving mouse pointer outside the menubox. You can have at most 31 items.
1364 This is followed by <tt/number_of_items/ of following item description.
1367 "menuitemname", (char)item_type, (unsigned)pointer,
1368 "nextitemname", (char)item_type, (unsigned)pointer,
1370 "lastitemname", (char)item_type, (unsigned)pointer };
1371 // Note that there isn't ending <tt/NULL/ or something like that.
1373 <tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one
1374 can have following values:
1376 <tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on menu item
1378 <tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu
1380 Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function
1381 which will return in <tt/r0/ needed pointer (to function to execute or a submenu).
1383 For creating nested menus (you can have at most 8 levels of submenus) you need to declare such
1384 structure for each submenu and top level menu.
1386 <sect2>DoDlgBox command string
1388 <tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is
1389 responsible for creating dialog boxes, that is windows which task is to interact with user.
1390 Format of the command string is following:
1392 (window size and position)
1393 (commands and parameters)
1396 There is custom type defined for the command string: <tt/dlgBoxStr/.
1398 <sect3>Size and position
1400 The first element can be specified in two ways - by using default size and position or specifying
1401 own. The first case results in
1403 const dlgBoxStr example = {
1404 DB_DEFPOS (pattern_of_shadow),
1408 And the own size and position would be:
1410 const dlgBoxStr example = {
1411 DB_SETPOS (pattern, top, bottom, left, right)
1418 The next element of <tt/DoDlgBox/ command string are commands themselves. First six commands are
1419 default icons and the number of selected icon will be returned from window processor. The icons are
1420 <tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for use them, e.g.:
1423 DB_ICON(OK, DBI_X_0, DBI_Y_0),
1426 Note that position is counted from top left corner of window, not entire screen and that the 'x'
1427 position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
1428 <tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), default positions
1429 which will make icons to appear on default window directly in the place where you would expect them.
1431 <tt/DB_TXTSTR (x, y, text)/ will cause to show given text in the window.
1433 <tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location
1434 where the address of text is stored. This is useful for information windows where only text content
1435 is variable. Consider following:
1439 r15=(int)text; // in code just before call to DoDlgBox
1441 DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &r15),
1444 will cause to appear the word ``foo'' in the window, but you may store the pointer to any text in
1445 <tt/r15/ (in this case) before call to DoDlgBox.
1447 <tt/DB_GETSTR(x, y, ptr, length)/ - will add input from keyboard feature. <tt/ptr/ works as in
1448 previous example and points to place where text is to be stored. Note that the contents of this
1449 place will be shown upon creating window. <tt/length/ is the maximum number of characters to input.
1451 <tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. I'm not sure, what this really
1454 <tt/DB_GRPHSTR(ptr)/ - data for this command is the pointer for <tt/GraphicsString/ commands.
1456 <tt/DB_GETFILES(x, y)/ - for standard window you should pass 4 for both x and y. This function
1457 draws file selection box and searches current drive for files. Before call to <tt/DoDlgBox/ you
1458 must load <tt/r7L/ with GEOS filetype of searched files and <tt/r10/ with class text. In <tt/r5/
1459 you have to load pointer to a <tt/char[17]/ where selected filename will be copied. It works
1460 like <tt/FindFTypes/ but is limited to first 16 files.
1462 <tt/DB_OPVEC(ptr)/ - this sets the new pointer for button press function, if you pass
1463 <tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button.
1465 <tt/DB_USRICON(x, y, ptr)/ - places single user icon (click box) on window, <tt/ptr/ points at a
1466 <tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click
1467 boxes in a window, this is internal limit of GEOS Kernal.
1469 <tt/DB_USRROUT(ptr)/ - this command causes to immediately call user routine pointed by <tt/ptr/.
1471 <sect2>GraphicsString command string
1473 <tt/GraphicsString/ is a very powerful routine to initialize whole screen at once. There are
1474 predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. Last
1475 command have to be <tt/GSTR_END/. There is custom type defined for the command string: <tt/graphicStr/.
1477 Here is an example for clearing the screen:
1479 const graphicStr example = {
1482 RECTANGLETO(319,199)
1486 <sect2>InitRam table
1488 This type of data is used to initialize one or more bytes in many places at once. The format is
1491 void example = {
1492 (unsigned)address_to_store_values_at,
1493 (char)number_of_bytes_that_follow,
1494 (char)data,(char)data (...)
1495 (...) - more such definitions
1496 (unsigned)NULL - address of 0 ends the table