]> git.sur5r.net Git - cc65/blob - doc/geos.sgml
grc is now named grc65.
[cc65] / doc / geos.sgml
1 <!doctype linuxdoc system>
2
3 <article>
4
5 <!-- Title information -->
6
7 <title>GEOSLib docs
8 <author>Maciej Witkowiak, <htmlurl url="mailto:ytm@elysium.pl" name="ytm@elysium.pl">
9 <date>v1.5, 26.12.1999, 2000, 2001, 2002, 2003, 2005
10 <abstract>
11 This is the documentation of cc65's GEOSLib, but information contained here may be also
12 useful for writing GEOS applications in general.
13 </abstract>
14
15 <!-- Table of contents -->
16 <toc>
17
18 <!-- Begin the document -->
19
20 <sect>Introduction
21 <p>
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.
26 <p>
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.
29 <p>
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.
36 <p>
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.
39 <p>
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.
47 <p>
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/.
50 <p>
51 <tt/joy/ - JOY driver for GEOS supports only joystick, not current pointing device.
52 <p>
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/
55 <p>
56 For <tt/time.h/ functions <tt/systime()/ and <tt/clock()/ note that the resolution is one second.
57 <p>
58 It was not tested enough, but functions from these includes might work under GEOS:
59 <tt/rs232.h, zlib.h/
60 <p>
61 Functions from the headers above are either standard C library functions or cc65-specific, in
62 either case they are not GEOS specific and so they are not described here.
63 <p>
64 I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
65 available code (well, the best as for machine :). Many of the <tt/void foo (void)/ functions are
66 just raw calls to Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you
67 will find many definitions of standard GEOS locations. Access to these addresses is optimized by
68 cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax.
69
70 <sect1>Requirements
71 <p>
72 You will not need c64 or c128 for development. The only hardware requirement is a PC capable of
73 running cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your
74 programs.
75
76 The software needed:
77 <itemize>
78     <item><em/cc65/ Excellent package containing C crosscompiler, crossassembler and linker, you
79                 can get it from: <htmlurl url="http://www.von-bassewitz.de/uz/cc65/"
80                 name="http://www.von-bassewitz.de/uz/cc65/">
81     <item><em/VICE/ This is portable C64, C128 and few other Commodore computers emulator, you
82                 can obtain it from: <htmlurl url="http://www.cs.cmu.edu/~dsladic/vice/vice.html"
83                 name="http://www.cs.cmu.edu/~dsladic/vice/vice.html">. VICE package contains
84                 c1541 program that is able to convert/unconvert GEOS files to disk images.
85     <item><em/Star Commander/ This tool is only for DOS. You will need it for transferring
86                 object files from PC to 1541. There's also one important ability of this
87                 tool - it automatically un-converts .cvt files into GEOS native format on
88                 disk image files.
89     <item><em/cbm4linux/ A Linux kernel module that allows for communication with 1541 and
90                 other Commodore IEC bus drives. It can be replacement for Star Commander if
91                 you want only to transfer files to a disk and unconvert using GEOS program for
92                 this purpose. Check out: <htmlurl url="http://www.lb.shuttle.de/puffin/cbm4linux/"
93                 name="http://www.lb.shuttle.de/puffin/cbm4linux">
94 </itemize>
95 <p>
96 VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only
97 needs cc65.
98 <p>
99 <em/Update:/ starting from v2.5.0 GEOSLib is a part of cc65 package as its GEOS support library.
100
101 <sect1>Legal
102 <p>
103 I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's
104 Reference Guide and BSW for GEOS.
105 <p>
106 GEOSLib is covered by the same license as cc65. You can find the whole text
107 among documentation. I would really appreciate if you would like to send me
108 your comments, suggestions, questions, changes, bug reports etc. I will also
109 appreciate if you will just give me a sign that you are using GEOSLib - not
110 especially something big and important, mail me even if you are just playing
111 with it.
112 <p>
113 You can send postcards with hellos to:
114 <p>
115 Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW
116 <p>
117 POLAND
118 <p>
119 e-mail: <tt/ytm@elysium.pl/
120
121 <sect>What have you got and what to do with it?
122 <p>
123 This chapter describes some rules you ought to obey, and how to use GEOSLib.
124
125 <sect1>Usage
126 <p>
127 Apart from this file, which merely describes only standard GEOS library
128 functions, you should read <tt/grc65/ (GEOS resource compiler) documentation.
129 There are informations about necessary resource files (each GEOS application
130 needs at least one) and the building process - what should be done and in what
131 order. Please also read cc65's documentation on how to compile C, assembler
132 and link everything together.
133 <p>
134 All in all, you just need to place
135 <tscreen><verb>
136 &num;include &lt;geos.h&gt;
137 </verb></tscreen>
138 on top of your source.
139 <p>
140 As a general rule read the sources of example programs and read the headers.
141 These are the most reliable sources of knowledge ;). You will also find there
142 many C macros representing various arguments passed to functions. Please use
143 them. You will find your sources easier to understand, and it will be easier
144 to find bugs.
145 <p>
146 All types used in GEOSLib are <tt/unsigned/.
147 <p>
148 Screen coordinates are given in pixels unless stated differently.
149
150 <sect1>Notes on style
151 <p>
152 Contrary to typical GEOS assembly program which has a main function called after loading that
153 setups the screen, menus, icons etc. exiting from <tt/main/ function in C is equivalent to
154 calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT
155 USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered
156 with <tt/atexit/ will not be called.
157 <p>
158 For GEOS GUI applications the recommended program structure is to have everything initialized
159 in <tt/main/ function and at the end of it a call to <tt/MainLoop()/ function. WARNING! This
160 function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not
161 be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu
162 handler or via DialogBox action).
163 <p>
164 Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into
165 series of <tt/lda/ and <tt/sta/, so you can't do it better :-).
166 <p>
167 Don't hesitate to use library functions. Everything was written with size and speed in mind. In
168 fact many calls are just redirections to GEOS kernal which results in simple <tt/jsr/.
169 <p>
170 The <tt/main/ function receives the standard <tt/argc/ and <tt/argv/ parameters. There are
171 always either 1 or 3 parameters. DOS application name is always set as <tt/argv[0]/.
172 If present, <tt/argv[1]/ and <tt/argv[2]/ will be set to data filename and data diskname (it only
173 works if user double-clicks on data file associated with your application). Note that it is up
174 to your application to determine which of the available (up to four) disk drives has the disk
175 with given diskname inside. If this fails your program should ask to insert the proper disk into
176 one of available drives.
177 <p>
178 You might wonder why I have chosen sometimes weird order of arguments in functions. I just
179 wanted to avoid unnecessary pushing and popping arguments from stack because cc65 can pass single
180 <tt/unsigned int/ through CPU registers.
181 <p>
182 Do not try to compile in strict ANSI mode. Library uses cc65 extensions which are not available in
183 ANSI.
184 <p>
185 It is possible to use dynamically loaded modules, three such modules are provided:
186 GEOS TGI driver, GEOS EMD driver (for VDC extended memory) and GEOS JOY driver.
187 Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special
188 recommendations, read cc65 documentation about modules and demo programs source code.
189
190 <sect>Library Functions
191 <p>
192 Functions here are sorted more or less in the way they appear in header files. This way I am able
193 to keep functions covering similar task near each other. All function names are identical to those
194 from <tt/geosSym/ file provided with GeoProgrammer package. Only my extensions to <tt/geosSym/
195 are covered by new names, but I tried to keep them in the naming convention.
196
197 <sect1>Graphics
198 <p>
199 This section covers drawing package of GEOS along with text output routines.
200
201 <sect2>SetPattern
202 <p>
203 <tt/void SetPattern (char pattern)/
204 <p>
205 This function sets current pattern to given. There are 32 different patterns in GEOS. You can
206 see them together in the filling box in GeoPaint.
207
208 <sect2>GraphicsString
209 <p>
210 <tt/void GraphicsString (char *myGString)/
211 <p>
212 One of the more powerfull routines of GEOS. This function calls other graphic functions depending
213 on given command string. See structures chapter for more detailed description of the structure of it.
214
215 <sect2>Rectangle functions
216 <p>
217 Parameters to those functions are grouped in <tt/struct window drawWindow/. To speed up things and
218 reduce overhead this structure is glued to zero page locations, where all rectangle functions
219 expect their parameters. You can modify data directly (e.g. <tt/drawWindow.top=10/) or via
220 <tt/InitDrawWindow/ function. Contents of <tt/drawWindow/ are guaranteed not to change only when
221 using graphics functions. In other case you should keep your data in separate <tt/struct window/
222 and use <tt/InitDrawWindow/ before first call to rectangle functions.
223
224 <sect3>InitDrawWindow
225 <p>
226 <tt/void InitDrawWindow (struct window *myWindow)/
227 <p>
228 This function only copies contents of <tt/myWindow/ into system area of <tt/drawWindow/. Use it
229 if for some reason you have to keep window data out of zero page space.
230
231 <sect3>Rectangle
232 <p>
233 <tt/void Rectangle (void)/
234 <p>
235 This draws on screen rectangle filled with current pattern.
236
237 <sect3>FrameRectangle
238 <p>
239 <tt/void FrameRectangle (char pattern)/
240 <p>
241 This one draws frame with given bit pattern (not a pattern from GEOS palette).
242
243 <sect3>InvertRectangle
244 <p>
245 <tt/void InvertRectangle (void)/
246 <p>
247 Just as the name says...
248
249 <sect3>ImprintRectangle and RecoverRectangle
250 <p>
251 <tt/void ImprintRectangle (void)/
252 <p>
253 <tt/void RecoverRectangle (void)/
254 <p>
255 These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/)
256 backbuffer of the screen. For example when drawing new menu box GEOS first uses
257 <tt/ImprintRectangle/ to save the area under the box, and restores it by <tt/RecoverRectangle/ upon
258 destroying the menu.
259
260 <sect2>Line Functions
261 <p>
262 GEOS drawing package is optimized so there are different functions for drawing vertical and
263 horizontal lines.
264
265 <sect3>HorizontalLine
266 <p>
267 <tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/
268 <p>
269 This function draws horizontal line using given pattern - here it is a true bit pattern, not
270 pattern set by <tt/SetPattern/.
271
272 <sect3>InvertLine
273 <p>
274 <tt/void InvertLine (char y, unsigned xStart, unsigned xEnd)/
275 <p>
276 There is only horizontal version.
277
278 <sect3>RecoverLine
279 <p>
280 <tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/
281 <p>
282 This function recovers only one line. It is utilized by <tt/RecoverRectangle/. See its description
283 for more details.
284
285 <sect3>VerticalLine
286 <p>
287 <tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/
288 <p>
289 This function draws vertical line using given pattern. Note that <tt/pattern/ is not a pattern
290 number as set in <tt/SetPattern/ but a true bit pattern.
291
292 <sect3>DrawLine
293 <p>
294 <tt/void DrawLine (char mode, struct window *myWindow)/
295 <p>
296 <tt/top/ parameters of <tt/struct window/ describe the starting point of the line, while
297 <tt/bottom/ are for the ending point. If <tt/mode/ is <tt/DRAW_DRAW/ then current pattern from
298 <tt/SetPattern/ is used for drawing. If <tt/mode/ is <tt/DRAW_ERASE/ then line is erased from the
299 screen. If <tt/mode/ is <tt/DRAW_COPY/ then line is copied from/to back/frontbuffer, according to
300 <tt/dispBufferOn/ setting.
301
302 <sect2>Point Functions
303 <p>
304 Parameters to these two functions are passed by a pointer to own <tt/struct pixel/ filled with
305 proper values.
306
307 <sect3>DrawPoint
308 <p>
309 <tt/void DrawPoint (char mode, struct pixel *myPixel)/
310 <p>
311 Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point
312 on the screen.
313
314 <sect3>TestPoint
315 <p>
316 <tt/char TestPoint (struct pixel *myPixel)/
317 <p>
318 This function tests if given pixel is set and returns <tt/true/ (non-zero) or <tt/false/ (zero).
319
320 <sect2>Character and string output
321
322 <sect3>cpputs
323 <p>
324 <tt/cpputsxy (char x, char y, char *myString)/
325 <p>
326 <tt/cpputs (char *myString)/
327 <p>
328 Actually this is a part of <tt/conio/, but this function is non-standard. It is
329 a variety of <tt/cputs/ that will output string with proportional spacing, not
330 fixed like <tt/cputs/.
331
332 <sect3>PutChar
333 <p>
334 <tt/void PutChar (char character, char y, unsigned x)/
335 <p>
336 This function outputs single character using current style and font to screen.
337
338 <sect3>PutString
339 <p>
340 <tt/void PutString (char *myString, char y, unsigned x)/
341 <p>
342 Same as <tt/PutChar/ except the fact that you can output whole <tt/NULL/-terminated string.
343 See <tt/ggraph.h/ for list of tokens that you can also place in the string - like <tt/CBOLDON/ or
344 <tt/COUTLINEON/.
345
346 <sect3>PutDecimal
347 <p>
348 <tt/void PutDecimal (char parameter, unsigned value, char y, unsigned x)/
349 <p>
350 This function converts <tt/value/ to its decimal representation and outputs it to the screen.
351 The <tt/parameter/ is the field width in pixels (range 1-31) and mode bits. Depending on them
352 the string can be filled with zeroes (string always 5 characters long) or not and left or right
353 justified to given pixel. See <tt/ggraph.h/ for predefined values for <tt/parameter/.
354
355 <sect2>Font Handling
356
357 <sect3>GetCharWidth
358 <p>
359 <tt/char GetCharWidth (char character)/
360 <p>
361 This function returns real width (in pixels) of given character with current font. It can be used
362 for counting the length of string on screen, allowing for indentation or justification.
363
364 <sect3>LoadCharSet
365 <p>
366 <tt/void LoadCharSet (struct fontdesc *myFont)/
367 <p>
368 This function forces GEOS to use given font instead of own. <tt/myFont/ should be casted from
369 pointer to the start of area where was loaded record from font file (VLIR structure).
370
371 <sect3>UseSystemFont
372 <p>
373 <tt/void UseSystemFont (void)/
374 <p>
375 This function forces GEOS to use built-in BSW font.
376
377 <sect2>Bitmap handling
378 <p>
379 I'm not quite sure how are these functions working (except <tt/BitmapUp/) so you should
380 probably look into library sources and compare it with your knowledge. Please let me know
381 if something is wrong or broken.
382
383 <sect3>BitmapUp
384 <p>
385 <tt/void BitmapUp (struct iconpic *myPic)/
386 <p>
387 This function unpacks the bitmap and places it on the screen - just as you set it in the
388 <tt/struct iconpic/ pointer to which you pass. See <tt/gstruct.h/ for description of this
389 structure. Note that you can only use packed GEOS bitmaps - simple Photo Scrap is in this format.
390
391 <sect3>BitmapClip
392 <p>
393 <tt/void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)/
394 <p>
395 This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are
396 to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap,
397 and the number of rows to skip from the top if it.
398
399 <sect3>BitOtherClip
400 <p>
401 <tt/void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop,
402         struct iconpic *myPic)/
403 <p>
404 Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it
405 returns in .A next value), and <tt/proc2/ is called every time the parser reads a byte which is
406 not a piece of pattern (byte of code greater than 219). Both procedures should be written
407 separately in assembler and declared as <tt/__fastcall__/ returning char.
408
409 <sect1>Menus and Icons
410 <p>
411 Here you will find information about functions related with menus and icons.
412
413 <sect2>Menus
414 <p>
415 Menus are essential for GUI. GEOS can handle only one menu at a time, but each menu can call
416 another one, which results in submenu tree. There can be up to 8 menu levels, each one with up
417 to 32 items.
418 <p>
419 Menus are initialized with <tt/DoMenu/ and then Kernal takes care for everything. Your code
420 (called from event handler) should be a function without parameters, returning void. You should
421 use <tt/DoPreviousMenu/ or <tt/GotoFirstMenu/ at least once in its code to have the screen clean.
422
423 <sect3>DoMenu
424 <p>
425 <tt/void DoMenu (struct menu *myMenu)/
426 <p>
427 This function initializes GEOS menu processor and exits. See <tt/DoMenu structure/ for more
428 information about it. Know that many GEOS application just initializes the screen, menu and
429 exits to main Kernal loop, this proves the power of <tt/DoMenu/.
430
431 <sect3>ReDoMenu
432 <p>
433 <tt/void ReDoMenu (void)/
434 <p>
435 This simply redraws the menu at lowest level. It works like calling <tt/DoMenu/ again with
436 the same parameters.
437
438 <sect3>RecoverMenu
439 <p>
440 <tt/void RecoverMenu (void)/
441 <p>
442 This function erases current menu from the screen. It doesn't change the menu level.
443
444 <sect3>RecoverAllMenus
445 <p>
446 <tt/void RecoverAllMenus (void)/
447 <p>
448 This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is
449 set to 0 (topmost).
450
451 <sect3>DoPreviousMenu
452 <p>
453 <tt/void DoPreviousMenu (void)/
454 <p>
455 This functions causes menu processor to go back one menu level. You should use it in menu
456 handler code to have the screen clean.
457
458 <sect3>GotoFirstMenu
459 <p>
460 <tt/void GotoFirstMenu (void)/
461 <p>
462 This one jumps back to the topmost menu. If there is only menu and submenu it works the
463 same as <tt/DoPreviousMenu/.
464
465 <sect2>Icon Functions
466 <p>
467 Icons are working similar to menus except the fact that there is only one level. Icons are
468 defined as a screen area filled with a bitmap, but if you would setup icons and erase the
469 screen they are still active and clicking in the place where formerly an icon was will cause
470 an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/
471 the bitmap will be still on the screen but clicking on it would not cause any action.
472 There is only one, but powerful icon function.
473
474 <sect3>DoIcons
475 <p>
476 <tt/void DoIcons (struct icontab *myIconTab)/
477 <p>
478 This function initializes all icons that are present on the screen at once. For more information
479 look at <tt/Icons/ chapter in this manual.
480
481 <sect1>DialogBoxes
482 <p>
483 This chapter covers the most powerful GEOS user interface function - <tt/DoDlgBox/.
484
485 <sect2>GEOS standard
486
487 <sect3>DoDlgBox
488 <p>
489 <tt/char DoDlgBox (char *dialogString)/
490 <p>
491 DialogBox returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/)
492 or whatever closing routine passes. Register <tt/r0L/ also contains this value.
493 <p>
494 Read structures chapter for the specs of the <tt/dialogString/.
495
496 <sect3>RstrFrmDialogue
497 <p>
498 <tt/char RstrFrmDialogue/
499 <p>
500 This function called from within DialogBox event immediately closes the DialogBox and returns
501 the owner ID (or whatever caller has in the .A register).
502
503 <sect2>GEOSLib extensions
504 <p>
505 To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox,
506 with predefined data. In one word - these are standard DialogBoxes you can see in almost every
507 GEOS application.
508
509 <sect3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk
510 <p>
511 <tt/char DlgBoxYesNo (char *line1, char *line2)/
512 <p>
513 <tt/char DlgBoxOkCancel (char *line1, char *line2)/
514 <p>
515 <tt/void DlgBoxOk (char *line1, char *line2)/
516 <p>
517 These function show two lines of text in standard-sized DialogBox. You can read the code of
518 pressed icon from return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/.
519 You can pass an empty string or NULL to get a blank line.
520
521 <sect3>DlgBoxGetString
522 <p>
523 <tt/char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)/
524 <p>
525 This function prompts user for entering a string of at most <tt/strlen/ characters. It is returned
526 in <tt/string/. The two given lines of text are shown above the input line. Please remember
527 that there is also <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his
528 input or gave up. The <tt/string/ is also shown so you can place default input there or remember
529 to place <tt/NULL/ at start.
530
531 <sect3>DlgBoxFileSelect
532 <p>
533 <tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/
534 <p>
535 This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error
536 on reading the directory or opening the disk.
537 There is also <tt/DISK/ icon shown, but it is handled internally. You pass as input parameters
538 <tt/filetype/ and pointer to string containing the first part of file's class. If this string is
539 empty (<tt/NULL/ at the start), then all files with given filetype will be shown.
540 <p>
541 At present this file selector handles only first 16 files of given type and supports only one
542 (current) drive.
543
544 <sect3>MessageBox
545 <p>
546 <tt/char MessageBox (char mode, const char *format, ...)/
547 <p>
548 This function is a more general one. It works very much like <tt/printf/ in a
549 box. The only difference is <tt/mode/ parameter which allows for placing
550 default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values).
551 Any too wide text will be clipped to the size of the default window. If mode
552 parameter is invalid or equal to <tt/MB_EMPTY/ then the window will be closed
553 after a click. Otherwise the user must choose an icon.
554 <p>
555 Note: use it if you really need (or if you will use it in many places) as
556 it adds quite amount of code to your program.
557 <p>
558 Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check
559 for that.
560
561 <sect1>Mouse, Sprites and Cursors
562 <p>
563 You will find here functions related to sprite and mouse drawing and handling.
564
565 <sect2>Mouse related functions
566 <p>
567 These cover mouse - as a general pointing device, but expect user to utilize as different devices
568 as digital or analog joystick, mouse, lightpen or koalapad (whatever it is).
569
570 <sect3>StartMouseMode
571 <p>
572 <tt/void StartMouseMode (void)/
573 <p>
574 This function initializes mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then
575 calls <tt/MouseUp/.
576
577 <sect3>ClearMouseMode
578 <p>
579 <tt/void ClearMouseMode (void)/
580 <p>
581 This function disables all mouse activities - icons and menus stop to respond to mouse events,
582 but they are not cleared from the screen.
583
584 <sect3>MouseUp and MouseOff
585 <p>
586 <tt/void MouseUp (void)/
587 <p>
588 <tt/void MouseOff (void)/
589 <p>
590 The first function turns the mouse pointer on. It will appear on next IRQ. The second one does
591 the opposite - it turns off the pointer, but its position is still updated by input driver.
592
593 <sect3>IsMseInRegion
594 <p>
595 <tt/char IsMseInRegion (struct window *myWindow)/
596 <p>
597 This function tests if mouse pointer is actually in given range of screen. See <tt/gsprite.h/ for
598 description of bits in return values - they describe the position in detail.
599
600 <sect2>Sprites
601 <p>
602 You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
603 pointer and sprite 1 can be overwritten when using text prompt. You don't have to worry about
604 40/80 column issues because GEOS128 has pretty good sprite emulator for VDC.
605
606 <sect3>DrawSprite
607 <p>
608 <tt/void DrawSprite (char sprite, char *mySprite)/
609 <p>
610 This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which
611 is copied to system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are
612 not initialized and sprite is not yet visible.
613
614 <sect3>PosSprite
615 <p>
616 <tt/void PosSprite (char sprite, struct pixel *myPixel)/
617 <p>
618 This function positions the sprite on the screen. Given coordinates are screen ones - they are
619 converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your
620 sprite off the left or top to the screen.
621
622 <sect3>EnablSprite and DisablSprite
623 <p>
624 <tt/void EnablSprite (char sprite)/
625 <p>
626 <tt/void DisablSprite (char sprite)/
627 <p>
628 These two functions are responsible for making the sprite visible or not.
629
630 <sect2>Cursors and Console
631
632 <sect3>InitTextPrompt
633 <p>
634 <tt/void InitTextPrompt (char height)/
635 <p>
636 This function initializes sprite 1 for text prompt with given <tt/height/. This parameter can be in
637 range 1-48.
638
639 <sect3>PromptOn and PromptOff
640 <p>
641 <tt/void PromptOn (struct pixel *myPixel)/
642 <p>
643 <tt/void PromptOff (void)/
644 <p>
645 The first function places text prompt in given place and enables blinking.
646 The second one is pretty self-explanatory.
647
648 <sect3>GetNextChar
649 <p>
650 <tt/char GetNextChar (void)/
651 <p>
652 This function gets next character from the keyboard queue. If the queue is empty it returns
653 <tt/NULL/, otherwise you receive true ASCII code of a character or value of special (function)
654 key. See <tt/gsprite.h/ for list of them.
655
656 <sect1>Disk
657 <p>
658 This chapter covers slightly low-level disk routines. You should use them with care, because
659 you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various
660 devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
661 dangerous.
662 <p>
663 For some purposes you might consider using <tt/dio.h/ interface to disk access. It is native.
664 <p>
665 All GEOS disk functions return error code in X register. In some cases this is returned by
666 GEOSLib function (if its type is <tt/char/), but in all cases last error is saved in <tt/__oserror/
667 location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes.
668 You need to include <tt/errno.h/ to get <tt/__oserror/, together with standard <tt/errno/. The
669 latter gives less verbose, but still usable information and can be used with <tt/strerror/.
670 Probably you will get more information using <tt/_stroserror/ in similar way.
671 <p>
672 For passing parameters use almost always pointer to your data e.g. <tt/ReadBuff (&amp;myTrSe)/.
673
674 <sect2>Buffer functions
675 <p>
676 These functions are taking single data sector (256 bytes) to read or write on a disk.
677
678 <sect3>ReadBuff and Writebuff
679 <p>
680 <tt/char ReadBuff (struct tr_se *myTrSe)/
681 <p>
682 <tt/char WriteBuff (struct tr_se *myTrSe)/
683 <p>
684 These functions read and write sector placed at <tt/diskBlkBuf/.
685
686 <sect3>GetBlock and ReadBlock
687 <p>
688 <tt/char GetBlock (struct tr_se *myTrSe, char *buffer)/
689 <p>
690 <tt/char ReadBlock (struct tr_se *myTrSe, char *buffer)/
691 <p>
692 These two functions are reading a single block directly at 256 byte array placed at <tt/buffer/.
693 The difference between them is that <tt/GetBlock/ will initialize TurboDos in drive if it was not
694 enabled. <tt/ReadBlock/ assumes that it is already enabled thus being slightly faster.
695
696 <sect3>PutBlock, WriteBlock, VerWriteBlock
697 <p>
698 <tt/char PutBlock (struct tr_se *myTrSe, char *buffer)/
699 <p>
700 <tt/char WriteBlock (struct tr_se *myTrSe, char *buffer)/
701 <p>
702 <tt/char VerWriteBlock (struct tr_se *myTrSe, char *buffer)/
703 <p>
704 Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after
705 writing. In case of error five tries are attempted before error code is returned.
706
707 <sect2>Directory header
708 <p>
709 Functions described here are operating on <tt/curDirHeader/ where current disk header is stored.
710 On larger capacity drives (than 1541) the second part of directory header in <tt/dir2Head/.
711
712 <sect3>GetPtrCurDkNm
713 <p>
714 <tt/void GetPtrCurDkNm (char *diskName)/
715 <p>
716 This function fills given character string with the name of current disk. It is converted to C
717 standard - string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS.
718 Note that passed pointer must point to an array of at least 17 bytes.
719
720 <sect3>GetDirHead and PutDirHead
721 <p>
722 <tt/char GetDirHead (void)/
723 <p>
724 <tt/char PutDirHead (void)/
725 <p>
726 These functions are reading and writing the directory header. You should use <tt/GetDirHead/ before
727 using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the
728 disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/.
729
730 <sect3>CalcBlksFree
731 <p>
732 <tt/unsigned CalcBlksFree (void)/
733 <p>
734 This function returns the number of free blocks on current disk. It is counted using data in
735 <tt/curDirHead/ so you must initialize the disk before calling it.
736
737 <sect3>ChkDskGEOS
738 <p>
739 <tt/char ChkDskGEOS (void)/
740 <p>
741 This functions checks <tt/curDirHead/ for GEOS Format identifier. It returns either true or false,
742 and also sets <tt/isGEOS/ properly. You must initialize the disk before using this.
743
744 <sect3>SetGEOSDisk
745 <p>
746 <tt/char SetGEOSDisk (void)/
747 <p>
748 This function initializes disk for use with GEOS. It sets indicator in directory header and
749 allocates a sector for the directory of border files. You don't need to initialize the disk before
750 using.
751
752 <sect3>FindBAMBit
753 <p>
754 <tt/char FindBAMBit (struct tr_se *myTrSe)/
755 <p>
756 This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is
757 set if the sector is free to use. Returned value is always zero if the sector is already allocated.
758 In fact, this function could be used in a following way:
759 <tscreen><verb>
760 &num;define BlockInUse FindBAMBit
761 ...
762 if (!BlockInUse(&amp;myTrSe)) &lcub;
763 ... block not allocated ...
764 &rcub;
765 </verb></tscreen>
766 <p>
767 Anyway, I feel that this function is too low-level.
768
769 <sect3>BlkAlloc and NxtBlkAlloc
770 <p>
771 <tt/char BlkAlloc (struct tr_se output&lsqb;&rsqb, unsigned length)/
772 <p>
773 <tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output&lsqb;&rsqb, unsigned length)/
774 <p>
775 Both functions are allocating enough disk sectors to fit the number of <tt/length/ in them. You
776 will find output in <tt/output/ which is table of <tt/struct tr_se/. The last entry will have the
777 number of track equal to 0 and sector equal to 255. The simplest way of using them is to use
778 predefined space in GEOS data space and pass <tt/fileTrScTab/, which is a predefined table.
779 <p>
780 The difference between those two is that <tt/NextBlkAlloc/ will start allocating from given sector,
781 and <tt/BlkAlloc/ starts from the first nonused sector.
782 <p>
783 You need to use <tt/PutDirHead/ later to save any changes in BAM.
784
785 <sect3>FreeBlock
786 <p>
787 <tt/char FreeBlock (struct tr_se *myTrSe)/
788 <p>
789 Simply deallocates a block in BAM. You need to update BAM with <tt/PutDirHead/.
790
791 <sect3>SetNextFree
792 <p>
793 <tt/struct tr_se SetNextFree (struct tr_se *myTrSe)/
794 <p>
795 This function finds the first free sector starting from given track and sector and allocates it.
796 It might return the same argument if the given block is not allocated. I wanted it to be type
797 clean, but it made usage a bit tricky. To assign a value to own <tt/struct tr_se/ you have to
798 cast both variables to <tt/unsigned/. E.g.
799 <tscreen><verb>
800 struct tr_se myTrSe;
801 ...
802 (unsigned)myTrSe=(unsigned)SetNextFree(&amp;otherTrSe);
803 </verb></tscreen>
804 <p>
805 In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/.
806 <p>
807 Note: you <em/must/ use casting to have correct values.
808
809 <sect2>Low-level disk IO
810 <p>
811 Functions described here are more usable in kernal or drivers code, less common in applications,
812 but who knows, maybe someone will need them.
813
814 <sect3>EnterTurbo, ExitTurbo, PurgeTurbo
815 <p>
816 <tt/void EnterTurbo (void)/
817 <p>
818 <tt/void ExitTurbo (void)/
819 <p>
820 <tt/void PurgeTurbo (void)/
821 <p>
822 These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit
823 more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will
824 have to wait a bit to transfer TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos.
825 This is useful for sending some DOS commands for drive e.g. for formatting. Note that before any
826 interaction with Kernal in ROM you have to call <tt/InitForIO/. You don't have to worry about speed.
827 <tt/EnterTurbo/ will only enable TurboDos (no code transfer) if TurboDos was disabled with
828 <tt/ExitTurbo/. <tt/PurgeTurbo/ acts different from <tt/ExitTurbo/ - it not only disables TurboDos,
829 but also removes it from drive RAM (not quite true, but it works like that). After using
830 <tt/PurgeTurbo/ the next call to <tt/EnterTurbo/ will reload drive RAM.
831
832 <sect3>ChangeDiskDevice
833 <p>
834 <tt/char ChangeDiskDevice (char newDevice)/
835 <p>
836 This function changes logical number of current device (in fact drives only) with given one. It is
837 usable for swapping drives. There's no check if given <tt/newDevice/ already exist, so if you want
838 to change the logical number of drive 8 to 9 and you have drive number 9 then GEOS will probably
839 hang on disk access. Use safe, large numbers. Note that safe IEC range is 8-31.
840
841 <sect2>Disk Initialization
842 <p>
843 GEOS has two functions for initialization ('logging in' as they say on CP&bsol;M) the disk.
844 <sect3>OpenDisk
845 <p>
846 <tt/char OpenDisk (void)/
847 <p>
848 This function initializes everything for a new disk. It loads and enables TurboDos if needed.
849 Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/.
850 Disk names are compared and if they differ then disk cache on REU is cleared. Finally format is
851 checked with <tt/ChkDkGEOS/ and disk name is updated in internal tables.
852
853 <sect3>NewDisk
854 <p>
855 <tt/char NewDisk (void)/
856 <p>
857 This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed.
858
859 <sect1>Files
860 <p>
861 This section cover GEOS file interface.
862
863 <sect2>Directory handling
864 <p>
865 Functions described here are common for SEQ and VLIR structures.
866
867 <sect3>Get1stDirEntry and GetNxtDirEntry
868 <p>
869 <tt/struct filehandle *Get1stDirEntry (void)/
870 <p>
871 <tt/struct filehandle *GetNxtDirEntry (void)/
872 <p>
873 These two functions are best suited for scanning whole directory for particular files. Note that
874 returned filehandles describes all file slots in the directory - even those with deleted files.
875 The return value can be obtained by casting both sides to <tt/unsigned/ - as in <tt/SetNextFree/
876 function or read directly after call to those two functions from <tt/r5/. Current sector number
877 is in <tt/r1/ and sector data itself is in <tt/diskBlkBuf/.
878
879 <sect3>FindFile
880 <p>
881 <tt/char FindFile (char *fName)/
882 <p>
883 This function scans whole directory for the given filename. It returns either 0 (success) or 5
884 (FILE_NOT_FOUND, defined in <tt/gdisk.h/) or any other fatal disk read error. After successful
885 <tt/FindFile/ you will have <tt/struct filehandle/ at <tt/dirEntryBuf/ filled with file's data and
886 other registers set as described in <tt/GetNxtDirEntry/.
887
888 <sect3>FindFTypes
889 <p>
890 <tt/char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)/
891 <p>
892 This function scans directory and fills a table at <tt/buffer/ with <tt/char &lsqb;17&rsqb;/ entries.
893 <tt/fType/ is GEOS type of searched files and <tt/classTxt/ is a string for Class field in file
894 header. Class will match if given will be equal or shorter than that found in file's header block.
895 If you want just to find all files with given GEOS type you should pass empty string or <tt/NULL/ as
896 <tt/classTxt/. Be warned that for searching <tt/NON_GEOS/ files must pass <tt/NULL/ as <tt/classTxt/.
897 <tt/fMaxNum/ is the maximal number of found files, thus the <tt/buffer/ must
898 provide area of size equal to <tt/17 * fMaxNum/.
899 This function returns the number of found files, ranging from 0 to number passed as <tt/fMaxNum/.
900 Return value can be also restored from <tt/r7H/.
901
902 <sect3>DeleteFile
903 <p>
904 <tt/char DeleteFile (char *fName)/
905 <p>
906 This function deletes a file by its name. It works for SEQ and VLIR files.
907
908 <sect3>RenameFile
909 <p>
910 <tt/char RenameFile (char *oldName, char *newName)/
911 <p>
912 I think it is obvious...
913
914 <sect3>GetFHdrInfo
915 <p>
916 <tt/char GetFHdrInfo (struct filehandle *myFile)/
917 <p>
918 This function loads the file header into <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/
919 you can pass address of <tt/dirEntryBuf/.
920
921 <sect2>Common and SEQ structure
922 <p>
923 Functions described here are common for SEQ and VLIR structures because arguments passed are
924 starting track and sector which may point either to start of a chain for VLIR or data for SEQ.
925
926 <sect3>GetFile
927 <p>
928 <tt/char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)/
929 <p>
930 This routine loads and runs a given file <tt/fname/. The file must be one of following types:
931 <tt/SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,/ or <tt/INPUT_DEVICE/. The execution
932 address is taken from file header. If it is zero, then file is only loaded. Only the first chain
933 from VLIR files is loaded. If <tt/flag/ has bit 0 set then load address is taken from <tt/loadaddr/
934 and not from file header. In this case <tt/APPLICATION/ files will be only loaded, not executed.
935 This does not apply to <tt/DESK_ACC/. If either bit 6 or 7 of <tt/flag/ are set, then 16 bytes from
936 <tt/datadname/ is copied to <tt/dataDiskName/ and 16 bytes from <tt/datafname/ goes to <tt/dataFileName/
937 thus becoming parameters for the new application. Pass <tt/NULL/ as any unused parameter.
938
939 <sect3>ReadFile
940 <p>
941 <tt/char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)/
942 <p>
943 This function reads at most <tt/fLength/ bytes into <tt/buffer/ from chained sectors starting at
944 <tt/myTrSe/.
945
946 <sect3>ReadByte
947 <p>
948 <tt/char ReadByte (void)/
949 <p>
950 This function returns next byte from a file. Before the first call to it you must load <tt/r5/
951 with <tt/NULL/, <tt/r4/ with sector buffer address and <tt/r1/ with track and sector of the
952 first block of a file.
953 Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between
954 calls to <tt/ReadByte/.
955 <p>
956 Returned value is valid only if there was no error. End of file is marked as <tt/BFR_OVERFLOW/
957 in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case
958 returned value is invalid.
959
960 <sect3>SaveFile
961 <p>
962 <tt/char SaveFile (char skip, struct fileheader *myHeader)/
963 <p>
964 <tt/SaveFile/ will take care of everything needed to create a GEOS file, no matter VLIR of SEQ
965 structure. All you need to do is to place data in proper place and prepare a header which will
966 contain all information about a file. The <tt/skip/ parameter says how many directory pages you
967 want to skip before searching for a free slot for directory entry. In most cases you will put
968 <tt/0/ there.
969 <p>
970 You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one
971 difference - the first two bytes which are link to nonexistent next sector are replaced by a
972 pointer to the DOS filename of the file.
973 <p>
974 When saving sequential files two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/
975 and <tt/fileheader.end_address/.
976
977 <sect3>FreeFile
978 <p>
979 <tt/char FreeFile (struct tr_se myTable&lsqb;&rsqb;)/
980 <p>
981 This function deallocates all sectors contained in passed table.
982
983 <sect3>FollowChain
984 <p>
985 <tt/char FollowChain(struct tr_se *myTrSe, char *buffer)/
986 <p>
987 This function fills a <tt/struct tr_se/ table at <tt/buffer/ with sector numbers for chain of
988 sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/.
989
990 <sect2>VLIR structure
991 <p>
992 Here are informations about VLIR files (called later as RecordFile) and functions.
993 <p>
994 VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one
995 SEQ structure file. Records are grouped together, described by common name - VLIR file name and
996 own number. Each record pointed by its number is described by starting track and sector numbers.
997 VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/&lcub;NULL,$ff&rcub;/),
998 or even non-exist (<tt/&lcub;NULL,NULL&rcub;/). Any other numbers represent starting track and sector of
999 particular file.
1000 <p>
1001 In GEOS there can be only one file opened at a time. Upon opening VLIR file some information
1002 about it are copied into memory. You can retrieve records table at <tt/fileTrScTab/ (table of
1003 128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/.
1004 E.g. size of whole VLIR file can be retrieved by reading <tt/VLIRInfo.fileSize/.
1005
1006 <sect3>OpenRecordFile
1007 <p>
1008 <tt/char OpenRecordFile (char *fName)/
1009 <p>
1010 This function finds and opens given file. An error is returned if file is not found or if it is not
1011 in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is
1012 loaded at <tt/fileTrScTab/ and will be valid until call to <tt/CloseRecordFile/ so don't modify it.
1013 You should <tt/PointRecord/ before trying to do something with file.
1014
1015 <sect3>CloseRecordFile
1016 <p>
1017 <tt/char CloseRecordFile (void)/
1018 <p>
1019 This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables.
1020
1021 <sect3>UpdateRecordFile
1022 <p>
1023 <tt/char UpdateRecordFile (void)/
1024 <p>
1025 This function will check <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is
1026 updated along with size and date stamps in directory entry.
1027
1028 <sect3>PointRecord
1029 <p>
1030 <tt/char PointRecord (char recordNumber)/
1031 <p>
1032 This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and
1033 sector of given record in <tt/r1/. Note that the data may not be valid (if record is non-existing
1034 you will get 0,0 and if it is empty - 255, 0).
1035
1036 <sect3>NextRecord and PreviousRecord
1037 <p>
1038 <tt/char NextRecord (void)/
1039 <p>
1040 <tt/char PreviousRecord (void)/
1041 <p>
1042 These two work like <tt/PointRecord/. Names are self-explanatory.
1043
1044 <sect3>AppendRecord
1045 <p>
1046 <tt/char AppendRecord (void)/
1047 <p>
1048 This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector
1049 table. It will also set <tt/VLIRInfo.curRecord/ to its number.
1050
1051 <sect3>DeleteRecord
1052 <p>
1053 <tt/char DeleteRecord (void)/
1054 <p>
1055 This function will remove current record from the table, and move all current+1 records one place
1056 back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to
1057 commit changes.
1058
1059 <sect3>InsertRecord
1060 <p>
1061 <tt/char InsertRecord (void)/
1062 <p>
1063 This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following
1064 records in table one place forward (contents of <tt/VLIRInfo.curRecord/ after call to <tt/InsertRecord/
1065 can be found in <tt/VLIRInfo.curRecord + 1/).
1066
1067 <sect3>ReadRecord and WriteRecord
1068 <p>
1069 <tt/char ReadRecord (char *buffer, unsigned fLength)/
1070 <p>
1071 <tt/char WriteRecord (char *buffer, unsigned fLength)/
1072 <p>
1073 This function will load or save at most <tt/fLength/ bytes from currently pointed record into or from
1074 <tt/buffer/.
1075
1076 <sect1>Memory and Strings
1077 <p>
1078 Functions covered in this section are common for whole C world - copying memory parts and
1079 strings is one of the main computer tasks. GEOS also has interface to do this. These functions
1080 are replacement for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries.
1081 If you are dealing with short strings (up to 255 characters) you should use these functions
1082 instead of standard ones. E.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster.
1083 <p>
1084 However some of them have slightly different calling convention (order of arguments to be specific),
1085 so please check their syntax here before direct replacing.
1086 <p>
1087 Please note that the memory areas described here as <em/strings/ are up to 255 characters (without
1088 counting the terminating <tt/NULL/), and <em/regions/ can cover whole 64K of memory.
1089
1090 <sect2>CopyString
1091 <p>
1092 <tt/void CopyString (char *dest, char *src)/
1093 <p>
1094 This function copies string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. <tt/NULL/
1095 is also copied.
1096
1097 <sect2>CmpString
1098 <p>
1099 <tt/char CmpString (char *s1, char *s2)/
1100 <p>
1101 This function compares string <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both
1102 strings have to have the same length. It returns either <tt/true/ (non-zero) or <tt/false/ (zero).
1103
1104 <sect2>CopyFString and CmpFString
1105 <p>
1106 <tt/void CopyFString (char length, char *dest, char *src)/
1107 <p>
1108 <tt/char CmpFString (char length, char *s1, char *s2)/
1109 <p>
1110 These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide
1111 the length of copied or compared strings. The strings can also contain several <tt/NULL/
1112 characters - they are not treated as delimiters.
1113
1114 <sect2>CRC
1115 <p>
1116 <tt/unsigned CRC (char *src, unsigned length)/
1117 <p>
1118 This function calculates the CRC checksum for given memory range. I don't know if it is
1119 compatible with standard CRC routines.
1120
1121 <sect2>FillRam and ClearRam
1122 <p>
1123 <tt/void *FillRam (char *dest, char value, unsigned length)/
1124 <p>
1125 <tt/void *ClearRam (char *dest, unsigned length)/
1126 <p>
1127 Both functions are filling given memory range. <tt/ClearRam/ fills with <tt/0s/, while
1128 <tt/FillRam/ uses given <tt/value/. Be warned that these functions destroy <tt/r0, r1 and
1129 r2L/ registers. These are aliases for <tt/memset/ and <tt/bzero/, respectively.
1130
1131 <sect2>MoveData
1132 <p>
1133 <tt/void *MoveData (char *dest, char *src, unsigned length)/
1134 <p>
1135 This functions copies one memory region to another. There are checks for overlap and the
1136 non-destructive method is chosen. Be warned that this function destroys contents of
1137 <tt/r0, r1 and r2/ registers. This is also alias for <tt/memcpy/
1138
1139 <sect2>InitRam
1140 <p>
1141 <tt/void InitRam (char *table)/
1142 <p>
1143 This function allows to initialize multiple memory locations with single bytes or strings.
1144 This is done with <tt/table/ where everything is defined. See structures chapter for description of
1145 <tt/InitRam's/ command string.
1146
1147 <sect2>Stash, Fetch, Swap, and VerifyRAM
1148 <p>
1149 <tt/void StashRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1150 <p>
1151 <tt/void FetchRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1152 <p>
1153 <tt/void SwapRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1154 <p>
1155 <tt/ char VerifyRAM (char bank, unsigned length, char *reuAddress, char *cpuAddress)/
1156 <p>
1157 These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory.
1158 You can check for REU presence by taking value of <tt/ramExpSize/. You have to do it before
1159 using any of these functions.
1160
1161 <sect1>Processes and Multitasking
1162 <p>
1163 Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions
1164 called in specified intervals and you can put the main program to sleep without disturbing other
1165 tasks and making user interface unresponsive.
1166
1167 <sect2>InitProcesses
1168 <p>
1169 <tt/void InitProcesses (char number, struct process *processTab)/
1170 <p>
1171 This is the main initialization routine. After calling it processes are set up, but not
1172 enabled. The parameters for <tt/InitProcesses/ are:
1173 <itemize>
1174     <item><tt/number/ - number of processes
1175     <item><tt/processTab/ - table of <tt/struct process/, with size equal to <tt/number/
1176 </itemize>
1177 <p>
1178 Single task is described by entry in <tt/processTab/, it contains two values - <tt/pointer/ to
1179 task function and number of <tt/jiffies/ which describe the delay between calls to task. On PAL
1180 systems there are 50 jiffies per second, while on NTSC there are 60.
1181 <p>
1182 The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and
1183 if <tt/processTab/ would be too large it would overwrite existing data in GEOS space.
1184 <p>
1185 There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the
1186 maximum size of <tt/processTab/ is equal to 21.
1187 <p>
1188 See description of <tt/process/ structure for more detailed discussion on this.
1189
1190 <sect2>RestartProcess and EnableProcess
1191 <p>
1192 <tt/void RestartProcess (char processNumber)/
1193 <p>
1194 <tt/void EnableProcess (char processNumber)/
1195 <p>
1196 These two functions start the task counter. <tt/RestartProcess/ for each process should be called
1197 after <tt/InitProcesses/, because it resets all flags and counters and it starts the counters.
1198 <p>
1199 <tt/RestartProcess/ enables counters and sets their initial value to that given in <tt/processTab/.
1200 <p>
1201 <tt/EnableProcess/ forces given process to execute by simulating the timer running out of time.
1202
1203 <sect2>BlockProcess and UnBlockProcess
1204 <p>
1205 <tt/void BlockProcess (char processNumber)/
1206 <p>
1207 <tt/void UnBlockProcess (char processNumber)/
1208 <p>
1209 <tt/BlockProcess/ disables the execution of given process, but this does not disable the timers.
1210 It means that if you call <tt/UnBlockProcess/ before timer runs out, the process will be executed.
1211 <p>
1212 <tt/UnBlockProcess/ does the opposite.
1213
1214 <sect2>FreezeProcess and UnFreezeProcess
1215 <p>
1216 <tt/void FreezeProcess (char processNumber)/
1217 <p>
1218 <tt/void UnFreezeProcess (char processNumber)/
1219 <p>
1220 <tt/FreezeProcess/ disables timer for given process. <tt/UnFreezeProcess/ does the opposite.
1221 This is not equal to <tt/RestartProcess/ as timers are not reloaded with initial value.
1222
1223 <sect2>Sleep
1224 <p>
1225 <tt/void Sleep (unsigned jiffies)/
1226 <p>
1227 This function is multitasking sleep - the program is halted, but it doesn't block other functions
1228 e.g. callbacks from menus and icons.
1229 The only argument here is the number of jiffies to wait until app will wake up. It depends on
1230 video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively).
1231 If you don't want to worry about it and need only full second resolution, call standard
1232 <tt/sleep/ function from <tt/unistd.h/.
1233
1234 <sect1>System Functions
1235
1236 <sect2>FirstInit
1237 <p>
1238 <tt/void FirstInit (void)/
1239 <p>
1240 This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot
1241 up. You shouldn't use this unless you know what you are doing.
1242
1243 <sect2>InitForIO and DoneWithIO
1244 <p>
1245 <tt/void InitForIO (void)/
1246 <p>
1247 <tt/void DoneWithIO (void)/
1248 <p>
1249 These functions are called by some disk routines. You should call them only if you want to
1250 do something with IO registers or call one of Kernal ROM routines. Note that this is rather an
1251 expensive way of turning off IRQs and enabling IO.
1252
1253 <sect2>MainLoop
1254 <p>
1255 <tt/void MainLoop (void)/
1256 <p>
1257 Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current
1258 function will never be executed. When in <tt/MainLoop/ systems waits for your action - using
1259 icons, keyboard or menus to force some specific action from program. You have to define
1260 proper handlers before that.
1261
1262 <sect2>EnterDeskTop
1263 <p>
1264 <tt/void EnterDeskTop (void)/
1265 <p>
1266 This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not
1267 use it. Always use <tt/exit()/ instead. Library destructors and functions registered with
1268 <tt/atexit()/ are called.
1269
1270 <sect2>ToBASIC
1271 <p>
1272 <tt/void ToBASIC (void)/
1273 <p>
1274 This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC.
1275 I was considering whether to include it or not, but maybe someone will need it. Which is I doubt.
1276 <p>
1277 <em/WARNING:/ library destructors and functions registered with <tt/atexit()/ will not be called
1278 so it is quite unsafe way to finish your program.
1279
1280 <sect2>Panic
1281 <p>
1282 <tt/void Panic (void)/
1283 <p>
1284 This calls system's <tt/Panic/ handler - it shows dialog box with message
1285 <tscreen><verb>
1286 System error at:xxxx
1287 </verb></tscreen>
1288 where <tt/xxxx/ is last known execution address (caller). By default this is bound to <tt/BRK/
1289 instruction, but it might be usable in debugging as kind of <tt/assert/. (Note that <tt/assert/
1290 is available as a separate function and will give you more information than that).
1291 <p>
1292 System is halted after call to <tt/Panic/ which means that library destructors will not be
1293 called and some data may be lost (no wonder you're panicking).
1294
1295 <sect2>CallRoutine
1296 <p>
1297 <tt/void CallRoutine (void &ast;myFunct)/
1298 <p>
1299 This is system caller routine. You need to provide pointer to a function and it will be immediately
1300 called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function -
1301 you don't need to check if the pointer is valid.
1302
1303 <sect2>GetSerialNumber
1304 <p>
1305 <tt/unsigned GetSerialNumber (void)/
1306 <p>
1307 This function returns the serial number of system. It might be used for copy-protection.
1308 However, please remember that the Free Software is a true power and you are using it
1309 right now.
1310
1311 <sect2>GetRandom
1312 <p>
1313 <tt/char GetRandom (void)/
1314 <p>
1315 This function returns a random number. It can be also read from <tt/random/ e.g.
1316 <tscreen><verb>
1317 a=random;
1318 </verb></tscreen>
1319 but by calling this function you are sure that the results will be always different.
1320 <tt/random/ is updated once a frame (50Hz PAL) and on every call to <tt/GetRandom/.
1321 <p>
1322 Note that it is not the same as <tt/rand/ function from the standard library. <tt/GetRandom/
1323 will give you unpredictable results (if IRQs would occur between calls to it) while
1324 <tt/rand/ conforms to the standard and for given seed (<tt/srand/) it always returns with the
1325 same sequence of values.
1326
1327 <sect2>SetDevice
1328 <p>
1329 <tt/void SetDevice (char device)/
1330 <p>
1331 This function sets current device to given. It might be used together with <tt/InitForIO/,
1332 <tt/DoneWithIO/ and some Kernal routines. Unless new device is a disk drive this only sets
1333 new value in <tt/curDevice/, in other case new disk driver is loaded from REU or internal RAM.
1334
1335 <sect2>get_ostype
1336 <p>
1337 <tt/char get_ostype (void)/
1338 <p>
1339 This function returns GEOS Kernal version combined (by logical OR) with machine type. Read
1340 <tt/gsys.h/ for definitions of returned values.
1341
1342 <sect2>get_tv
1343 <p>
1344 <tt/char get_tv (void)/
1345 <p>
1346 This function returns PAL/NTSC flag combined (by logical OR) with 40/80 columns flag. This is
1347 not the best way to check if screen has 40 or 80 columns since PAL/NTSC check is always
1348 performed and it can take as long as full raster frame. If you just want to know if
1349 screen has 40 or 80 columns use expression <tt/graphMode & 0x80/ which returns <tt/0/ for
1350 40 columns and <tt/0x80/ for 80 columns. Remember that this parameter can be changed during
1351 runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test
1352 anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for
1353 definitions of returned values.
1354
1355 <sect>Library Structures
1356 <p>
1357 To simplify usage and optimize passing parameters to functions I have declared several structures
1358 which describe most common objects. Some of these structures are bound to static addresses in
1359 GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in optimized way.
1360 Please see <tt/gsym.h/ and find them. All structures are defined in <tt/gstruct.h/ and you may
1361 find also some comments there.
1362
1363 <sect1>Graphics Structures
1364
1365 <sect2>pixel
1366 <p>
1367 One simple structure describing a point on the screen.
1368
1369 <sect2>fontdesc
1370 <p>
1371 This structure describes a font in one pointsize. There is current font - <tt/struct fontdesc/
1372 bound to <tt/curFontDesc/. You can also force GEOS to use your own fonts by calling
1373 <tt/LoadCharSet/. You just need to open a VLIR font file and load one record - one pointsize -
1374 somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can
1375 pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although
1376 it has 'Load' in the name, that function loads only GEOS internal data structures, not data
1377 from disk).
1378
1379 <sect2>window
1380 <p>
1381 This widely used structure holds description of a region of the screen. It describes top-left and
1382 bottom-right corners of a window.
1383
1384 <sect2>iconpic
1385 <p>
1386 Maybe the name isn't the best - it has nothing with <tt/DoIcons/ but with bitmap functions -
1387 <tt/BitmapUp/ for example. This structure holds parameters needed to properly decode and show
1388 a bitmap on the screen. Bitmap has to be encoded - if you have some non-GEOS bitmaps simply
1389 convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/
1390 too.
1391
1392 <sect1>Icons
1393 <p>
1394 These structures describe click boxes (icons) that can be placed on screen or in a dialog box.
1395
1396 <sect2>icondef
1397 <p>
1398 This is the definition of a single click box. Please see <tt/gstruct.h/ for description of its fields.
1399
1400 <sect2>icontab
1401 <p>
1402 This is toplevel description of icons to be placed and enabled on the screen. This structure
1403 has following fields:
1404 <itemize>
1405     <item><tt/char number/ - total number of icons declared here
1406     <item><tt/struct pixel mousepos/ - after finishing <tt/DoIcons/ mouse pointer will be placed in
1407         this point allowing you to have hint for user what is default action
1408     <item><tt/struct icondef tab&lsqb;&rsqb/ - this table of size equal to <tt/icontab.number/ contains
1409         descriptions for all icons
1410 </itemize>
1411
1412 <sect1>File and Disk
1413
1414 <sect2>tr_se
1415 <p>
1416 This simple structure holds track and sector number of something. Do not expect the track to be
1417 in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K
1418 expansion is utilized as RAMDisk with layout of 4 tracks 128 sectors each. However assuming that
1419 track number equal to 0 is illegal might be wise.
1420
1421 <sect2>f_date
1422 <p>
1423 This is placeholder for file datestamp. This structure is also present in <tt/struct filehandle/.
1424 GEOS is not Y2K compliant, so if current file has in <tt/filehandle.date.year/ value less than 86
1425 you can safely assume that it is e.g. 2004 and not 1904.
1426
1427 <sect2>filehandle
1428 <p>
1429 This is main file descriptor. It is either entry in the directory (returned from file functions)
1430 or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g.
1431 by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/.
1432
1433 <sect2>fileheader
1434 <p>
1435 This structure holds fileheader description. You can load file's header into <tt/fileHeader/
1436 fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while
1437 <tt/fileheader/ is a structure).
1438 You will also need own fileheader for <tt/SaveFile/.
1439
1440 <sect1>System Structures
1441
1442 <sect2>s_date
1443 <p>
1444 This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/
1445 so I prepared this one. You can e.g. get or set current time using <tt/system_date.s_hour/ and
1446 <tt/system_date.s_minute/. Accesses to these will be optimized to simple <tt/LDA/ and <tt/STA/
1447 pair.
1448
1449 <sect2>process
1450 <p>
1451 You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number
1452 of processes is 20, and the last entry has to be equal to <tt/&lcub;NULL,NULL&rcub;/, so this table may hold
1453 only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to called
1454 function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/.
1455 The second field <tt/jiffies/ holds the amount of time between calls to that function.
1456 On PAL systems there are 50 jiffies per second, while NTSC have 60 of them.
1457
1458 <sect1>Few thing in detail...
1459 <p>
1460 GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a
1461 kind of array of unspecified length and unspecified type. Here is how it goes:
1462 <tscreen><verb>
1463 void example = &lcub;
1464     (char)3, (unsigned)3, (char)0 &rcub;;
1465 </verb></tscreen>
1466 Which will be compiled to following string of bytes:
1467 <tscreen><verb>
1468 _example:
1469         .byte 3
1470         .word 3
1471         .byte 0
1472 </verb></tscreen>
1473 As you see this way it is possible to define data of any type in any order. You must remember to
1474 cast each member to proper type.
1475
1476 <sect2>DoMenu structure
1477 <p>
1478 <tt/DoMenu/ is responsible for everything concerned with menu processing. Many, many GEOS programs
1479 are just initializing screen and menu and exit to <tt/MainLoop/. In GEOSLib it is the same as
1480 returning from <tt/main/ function without using <tt/exit(0)/.
1481 <p>
1482 Menu is described by two types of data - menu descriptors and menu items. Descriptor contains
1483 information about following menu items, and items are containing names of entries and either
1484 pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors.
1485 Note that submenu descriptor can be top-level descriptor, there's no difference in structure,
1486 just in the content.
1487 <p>
1488 Here is how single descriptor looks like:
1489 <tscreen><verb>
1490 void myMenu = &lcub;
1491         (char)top, (char)bottom,                // this is the size of the menubox
1492         (unsigned)left, (unsigned)right,        // counting all items in current descriptor
1493         (char)number_of_items | type_of_menu,   // number of following items ORed with
1494                                                 // type of this menu, it can be either
1495         // HORIZONTAL or VERTICAL if you will have also bit 6 set then menu won't be closed
1496         // after moving mouse pointer outside the menubox. You can have at most 31 items.
1497 </verb></tscreen>
1498 This is followed by <tt/number_of_items/ of following item description.
1499 <tscreen><verb>
1500         ...
1501         "menuitemname", (char)item_type, (unsigned)pointer,
1502         "nextitemname", (char)item_type, (unsigned)pointer,
1503         ...
1504         "lastitemname", (char)item_type, (unsigned)pointer &rcub;;
1505         // Note that there isn't ending <tt/NULL/ or something like that.
1506 </verb></tscreen>
1507 <tt/pointer/ is a pointer to something, what it points for depends from <tt/item_type/. This one
1508 can have following values:
1509 <p>
1510 <tt/MENU_ACTION/ - a function pointed by <tt/pointer/ will be called after clicking on menu item
1511 <p>
1512 <tt/SUB_MENU/ - <tt/pointer/ points to next menu descriptor - a submenu
1513 <p>
1514 Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function
1515 which will return in <tt/r0/ needed pointer (to function to execute or a submenu).
1516 <p>
1517 For creating nested menus (you can have at most 8 levels of submenus) you need to declare such
1518 structure for each submenu and top level menu.
1519
1520 <sect2>DoDlgBox command string
1521 <p>
1522 <tt/DoDlgBox/ is together with <tt/DoMenu/ one of the most powerful routines in GEOS. It is
1523 responsible for creating dialog boxes, that is windows which task is to interact with user.
1524 Format of the command string is following:
1525 <tscreen><verb>
1526     (window size and position)
1527     (commands and parameters)
1528     NULL
1529 </verb></tscreen>
1530 There is custom type defined for the command string: <tt/dlgBoxStr/.
1531
1532 <sect3>Size and position
1533 <p>
1534 The first element can be specified in two ways - by using default size and position or specifying
1535 own. The first case results in
1536 <tscreen><verb>
1537 const dlgBoxStr example = &lcub;
1538         DB_DEFPOS (pattern_of_shadow),
1539         ...             // commands
1540         DB_END &rcub;;
1541 </verb></tscreen>
1542 And the own size and position would be:
1543 <tscreen><verb>
1544 const dlgBoxStr example = &lcub;
1545         DB_SETPOS (pattern, top, bottom, left, right)
1546         ...             // commands
1547         DB_END &rcub;;
1548 </verb></tscreen>
1549
1550 <sect3>Commands
1551 <p>
1552 The next element of <tt/DoDlgBox/ command string are commands themselves. First six commands are
1553 default icons and the number of selected icon will be returned from window processor. The icons are
1554 <tt/OK, CANCEL, YES, NO, OPEN/, and <tt/DISK/. You can use predefined macros for use them, e.g.:
1555 <tscreen><verb>
1556         ...
1557         DB_ICON(OK, DBI_X_0, DBI_Y_0),
1558         ...
1559 </verb></tscreen>
1560 Note that the position is counted from top left corner of window, not entire screen and that the 'x'
1561 position is counted in cards (8-pixel) and not in pixels. This is true also for all following commands.
1562 <tt/DBI_X_0/ and <tt/DBI_Y_0/ are predefined (see <tt/gdlgbox.h/ for more), default positions
1563 which will make icons to appear on default window exactly where you would expect them.
1564 <p>
1565 <tt/DB_TXTSTR (x, y, text)/ will cause to show given text in the window.
1566 <p>
1567 <tt/DB_VARSTR (x, y, ptr)/ works as above, but here you are passing a pointer to a zero page location
1568 where the address of text is stored. This is useful for information windows where only text content
1569 is variable. Consider following:
1570 <tscreen><verb>
1571 char text = "foo";
1572         ...
1573         r15=(unsigned)text;             // in code just before call to DoDlgBox
1574         ...
1575         DB_VARSTR (TXT_LN_X, TXT_LN_1_Y, &amp;r15),
1576         ...
1577 </verb></tscreen>
1578 will cause to appear the word ``foo'' in the window, but you may store the pointer to any text in
1579 <tt/r15/ (in this case) before call to DoDlgBox.
1580 <p>
1581 <tt/DB_GETSTR(x, y, ptr, length)/ - will add input from keyboard feature. <tt/ptr/ works as in
1582 previous example and points to place where text is to be stored. Note that the contents of this
1583 place will be shown upon creating window. <tt/length/ is the maximum number of characters to input.
1584 <p>
1585 <tt/DB_SYSOPV(ptr)/ - this sets <tt/otherPressVec/ to given pointer. It is called on every keypress.
1586 <p>
1587 <tt/DB_GRPHSTR(ptr)/ - data for this command is the pointer for <tt/GraphicsString/ commands.
1588 <p>
1589 <tt/DB_GETFILES(x, y)/ - for standard window you should pass 4 for both x and y. This function
1590 draws file selection box and searches current drive for files. Before call to <tt/DoDlgBox/ you
1591 must load <tt/r7L/ with GEOS filetype of searched files and <tt/r10/ with class text. In <tt/r5/
1592 you have to load pointer to a <tt/char&lsqb;17&rsqb;/ where selected filename will be copied. It works
1593 like <tt/FindFTypes/ but is limited to first 16 files.
1594 <p>
1595 <tt/DB_OPVEC(ptr)/ - this sets the new pointer for button press function, if you pass
1596 <tt/RstrFrmDialogue/ here you will cause the window to close after pressing mouse button.
1597 <p>
1598 <tt/DB_USRICON(x, y, ptr)/ - places single user icon (click box) on window, <tt/ptr/ points at a
1599 <tt/struct icondef/ but fields <tt/x/ and <tt/y/ are not used here. You can have at most 8 click
1600 boxes in a window, this is internal limit of GEOS Kernal.
1601 <p>
1602 <tt/DB_USRROUT(ptr)/ - this command causes to immediately call user routine pointed by <tt/ptr/.
1603
1604 <sect2>GraphicsString command string
1605 <p>
1606 <tt/GraphicsString/ is a very powerful routine to initialize whole screen at once. There are
1607 predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. Last
1608 command have to be <tt/GSTR_END/. There is custom type defined for the command string: <tt/graphicStr/.
1609 <p>
1610 Here is an example for clearing the screen:
1611 <tscreen><verb>
1612 const graphicStr example = &lcub;
1613         MOVEPENTO(0,0),
1614         NEWPATTERN(0),
1615         RECTANGLETO(319,199)
1616         GSTR_END &rcub;;
1617 </verb></tscreen>
1618
1619 <sect2>InitRam table
1620 <p>
1621 This type of data is used to initialize one or more bytes in many places at once. The format is
1622 as following:
1623 <tscreen><verb>
1624 void example = &lcub;
1625     (unsigned)address_to_store_values_at,
1626     (char)number_of_bytes_that_follow,
1627     (char)data,(char)data (...)
1628     // more such definitions
1629     (unsigned)NULL // address of 0 ends the table
1630     &rcub;;
1631 </verb></tscreen>
1632
1633 <sect2>Intercepting system vectors
1634 <p>
1635 It is possible to intercept and hook in the GEOS Kernal using vectors. Here is a little example:
1636 <tscreen><verb>
1637 void_func oldVector;
1638
1639 void NewVectorHandler(void) &lcub;
1640         // do something and at the end call the old vector routine
1641         oldVector();
1642 &rcub;
1643
1644 void hook_into_system(void) &lcub;
1645         oldVector = mouseVector;
1646         mouseVector = NewVectorHandler;
1647 &rcub;
1648
1649 void remove_hook(void) &lcub;
1650         mouseVector = oldVector;
1651 &rcub;
1652 </verb></tscreen>
1653 <p>
1654 In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to GEOS
1655 kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/.
1656 Be warned that vectors are most likely to be changed by GEOS kernal also by other functions (like
1657 <tt/GotoFirstMenu/, <tt/DoDlgBox/ and its derivatives etc.). It depends on what kernal functions
1658 you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete
1659 list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of
1660 information contained there should be still valid for GEOS 2.0. When calling a function that restores
1661 the vector you should add a <tt/hook_into_system()/ call right after it.
1662 <p>
1663 It is critical to restore old vector values before exiting the program. If you have more than one
1664 place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to
1665 be called upon exiting with <tt/atexit(&amp;remove_hook);/ call. This way you will ensure that
1666 such destructor will be always called.
1667 <p>
1668 That little example above intercepts <tt/mouseVector/. The <tt/NewVectorHandler/ function will be
1669 called every time the mouse button changes status. Other important vectors you should know about
1670 are:
1671 <itemize>
1672         <item><tt/appMain/ - this is called from within <tt/MainLoop/ system loop
1673         <item><tt/keyVector/ - called whenever a keypress occurs
1674         <item><tt/intTopVector/ - called at the start of IRQ routine
1675         <item><tt/intBotVector/ - called at the end of IRQ routine
1676 </itemize>
1677
1678 </article>