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