-
Notifications
You must be signed in to change notification settings - Fork 16
Expand file tree
/
Copy pathgeos.html
More file actions
1571 lines (1220 loc) · 78.1 KB
/
geos.html
File metadata and controls
1571 lines (1220 loc) · 78.1 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<LINK REL="stylesheet" TYPE="text/css" HREF="doc.css">
<META NAME="GENERATOR" CONTENT="LinuxDoc-Tools 0.9.83">
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<TITLE>GEOSLib docs</TITLE>
</HEAD>
<BODY>
<H1>GEOSLib docs</H1>
<H2>
<A HREF="mailto:ytm@elysium.pl">Maciej Witkowiak</A></H2>
<HR>
<EM>This is the documentation of cc65's GEOSLib, but information contained here may be also
useful for writing GEOS applications in general.</EM>
<HR>
<P>
<H2><A NAME="toc1">1.</A> <A HREF="geos.html#s1">Introduction</A></H2>
<UL>
<LI><A NAME="toc1.1">1.1</A> <A HREF="geos.html#ss1.1">Requirements</A>
<LI><A NAME="toc1.2">1.2</A> <A HREF="geos.html#ss1.2">Legal</A>
</UL>
<P>
<H2><A NAME="toc2">2.</A> <A HREF="geos.html#s2">What do you have and what to do with it?</A></H2>
<UL>
<LI><A NAME="toc2.1">2.1</A> <A HREF="geos.html#ss2.1">Usage</A>
<LI><A NAME="toc2.2">2.2</A> <A HREF="geos.html#ss2.2">Notes on style</A>
</UL>
<P>
<H2><A NAME="toc3">3.</A> <A HREF="geos.html#s3">Library Functions</A></H2>
<UL>
<LI><A NAME="toc3.1">3.1</A> <A HREF="geos.html#ss3.1">Graphics</A>
<LI><A NAME="toc3.2">3.2</A> <A HREF="geos.html#ss3.2">Menus and Icons</A>
<LI><A NAME="toc3.3">3.3</A> <A HREF="geos.html#ss3.3">DialogBoxes</A>
<LI><A NAME="toc3.4">3.4</A> <A HREF="geos.html#ss3.4">Mouse, Sprites and Cursors</A>
<LI><A NAME="toc3.5">3.5</A> <A HREF="geos.html#ss3.5">Disk</A>
<LI><A NAME="toc3.6">3.6</A> <A HREF="geos.html#ss3.6">Files</A>
<LI><A NAME="toc3.7">3.7</A> <A HREF="geos.html#ss3.7">Memory and Strings</A>
<LI><A NAME="toc3.8">3.8</A> <A HREF="geos.html#ss3.8">Processes and Multitasking</A>
<LI><A NAME="toc3.9">3.9</A> <A HREF="geos.html#ss3.9">System Functions</A>
</UL>
<P>
<H2><A NAME="toc4">4.</A> <A HREF="geos.html#s4">Library Structures</A></H2>
<UL>
<LI><A NAME="toc4.1">4.1</A> <A HREF="geos.html#ss4.1">Graphics Structures</A>
<LI><A NAME="toc4.2">4.2</A> <A HREF="geos.html#ss4.2">Icons</A>
<LI><A NAME="toc4.3">4.3</A> <A HREF="geos.html#ss4.3">File and Disk</A>
<LI><A NAME="toc4.4">4.4</A> <A HREF="geos.html#ss4.4">System Structures</A>
<LI><A NAME="toc4.5">4.5</A> <A HREF="geos.html#ss4.5">A few things in detail...</A>
</UL>
<HR>
<H2><A NAME="s1">1.</A> <A HREF="#toc1">Introduction</A></H2>
<P>As we all know that the best computers in the world are the C64 and C128. They have their GUI too -
the excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point
of view. That's not true. The designers of GEOS created a flexible and powerful system, which
is easy to use and program.</P>
<P>Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65
package and my GEOSLib you are able to create GEOS applications in no time.</P>
<P>GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions
are used (e.g. <CODE>memset</CODE> is an alias for <CODE>FillRam</CODE>), however not all are supported. E.g.
string functions like <CODE>strcmp</CODE>, <CODE>strcpy</CODE> are doubled with native <CODE>CmpString</CODE>,
<CODE>CopyString</CODE> because the latter can handle only 256 byte strings. Keep this in mind when
you write your program. If you don't need long strings simply use functions from the Kernal,
the resulting code will be smaller.</P>
<P><CODE>dio</CODE> - direct disk access is available, but you might have problems with devices other
than 1541, 1571 or 1581. RAM drives emulating these should work.</P>
<P><CODE>conio</CODE> - simple console input-output is available for command line applications.
This implementation assumes that one character does fit in 8x8 cell, so output with
default BSW font, which is has 9 points, might be a bit messy. There is no color support in
GEOS 2.0 so color functions are disabled. Both 40 and 80 column modes are supported
and automatically detected.</P>
<P><CODE>tgi</CODE> - TGI driver for GEOS that supports both 40 and 80 column modes but mode can not be
changed between <CODE>tgi_init</CODE> and <CODE>tgi_done</CODE>.</P>
<P><CODE>joy</CODE> - JOY driver for GEOS that supports only joystick, not current pointing device.</P>
<P>It is safe to use these standard includes and their contents:
<CODE>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</CODE></P>
<P>For <CODE>time.h</CODE> functions <CODE>clock()</CODE> and <CODE>clock_gettime()</CODE> note that the resolution is one second.</P>
<P>Functions from the headers above are either standard C library functions or cc65-specific, in
either case they are not GEOS specific and so they are not described here.</P>
<P>I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best
available code (well, the best as for machine :-). Many of the <CODE>void foo (void)</CODE> functions are
just raw calls to the Kernal (assembled just as <CODE>jsr _foo</CODE>), look in <CODE>gsym.h</CODE>, where you
can find many definitions of standard GEOS locations. Access to these addresses is optimized by
cc65 to simple <CODE>lda</CODE> and <CODE>sta</CODE>. Don't be afraid to use C syntax.</P>
<H2><A NAME="ss1.1">1.1</A> <A HREF="#toc1.1">Requirements</A>
</H2>
<P>You don't need a C64 or C128 for development. The only hardware requirement is a PC capable of
running cc65. You do however need C64 or C128 emulator and GEOS disk images (.d64) to test your
programs.</P>
<P>The software needed:
<UL>
<LI><EM>cc65</EM> Excellent package containing a C crosscompiler, a crossassembler and a linker, you
can get it from:
<A HREF="https://cc65.github.io/">https://cc65.github.io/</A>.</LI>
<LI><EM>VICE</EM> This is a portable C64, C128 and few other Commodore computers emulator, you
can obtain it from:
<A HREF="http://vice-emu.sourceforge.net/">http://vice-emu.sourceforge.net/</A>.
The VICE package contains the <EM>c1541</EM> program that is able
to convert/unconvert GEOS files to disk images.</LI>
<LI><EM>The Star Commander</EM> This tool is only for DOS. You will need it for transferring
object files from a PC to a 1541. There's also one important ability of this
tool - it automatically un-converts .cvt files into GEOS native format on
disk image files. Check out:
<A HREF="http://sta.c64.org/sc.html">http://sta.c64.org/sc.html</A>.</LI>
<LI><EM>opencbm</EM> A package that allows for communication directly with a 1541 and
other Commodore IEC bus drives. It can be a replacement for Star Commander if
you only want to transfer files to a disk and unconvert using GEOS program for
this purpose. Check out:
<A HREF="https://spiro.trikaliotis.net/opencbm">https://spiro.trikaliotis.net/opencbm</A>.</LI>
</UL>
</P>
<P>VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only
needs cc65.</P>
<P><EM>Update:</EM> starting from v2.5.0 GEOSLib is a part of the cc65 package as its GEOS support library.</P>
<H2><A NAME="ss1.2">1.2</A> <A HREF="#toc1.2">Legal</A>
</H2>
<P>I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's
Reference Guide and BSW for GEOS.</P>
<P>GEOSLib is covered by the same license as cc65. You can find the whole text
among documentation. I would really appreciate if you would like to send me
your comments, suggestions, questions, changes, bug reports etc. I will also
appreciate if you will just give me a sign that you are using GEOSLib - not
especially something big and important, mail me even if you are just playing
with it.</P>
<P>You can send postcards with hellos to:</P>
<P>Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW</P>
<P>POLAND</P>
<P>e-mail: <CODE>ytm@elysium.pl</CODE></P>
<H2><A NAME="s2">2.</A> <A HREF="#toc2">What do you have and what to do with it?</A></H2>
<P>This chapter describes some rules you ought to obey, and how to use GEOSLib.</P>
<H2><A NAME="ss2.1">2.1</A> <A HREF="#toc2.1">Usage</A>
</H2>
<P>Apart from this file, which merely describes only standard GEOS library
functions, you should read the <CODE>grc65</CODE> (GEOS resource compiler) documentation.
There is information about necessary resource files (each GEOS application
needs at least one) and the build process - what should be done and in what
order. Please also read the cc65 documentation on how to compile C, assembler
and link everything together.</P>
<P>All in all, you just need to place
<BLOCKQUOTE><CODE>
<PRE>
#include <geos.h>
</PRE>
</CODE></BLOCKQUOTE>
at the top of your source.</P>
<P>As a general rule read the sources of the example programs and read the headers.
These are the most reliable sources of knowledge ;-). You will also find there
many C macros representing various arguments passed to the functions. Please use
them. You will find your sources easier to understand, and it will be easier
to find bugs.</P>
<P>All types used in GEOSLib are <CODE>unsigned</CODE>.</P>
<P>Screen coordinates are given in pixels unless stated differently.</P>
<H2><A NAME="ss2.2">2.2</A> <A HREF="#toc2.2">Notes on style</A>
</H2>
<P>Contrary to a typical GEOS assembly program which has a main function called after loading that
setups the screen, menus, icons etc. exiting from the <CODE>main</CODE> function in C is equivalent to
calling <CODE>exit()</CODE>. These two are the only safe methods of terminating applications. DO NOT
USE <CODE>EnterDeskTop</CODE>! Your data may be lost as library destructors and functions registered
with <CODE>atexit</CODE> are not called.</P>
<P>For GEOS GUI applications the recommended program structure is to have everything initialized
in the <CODE>main</CODE> function and at the end of it a call to the <CODE>MainLoop()</CODE> function. WARNING! This
function never returns, any code between <CODE>MainLoop();</CODE> and the end of <CODE>main</CODE> will not
be executed. You have to call <CODE>exit()</CODE> explicitly somewhere in your code (e.g. in a menu
handler or via DialogBox action).</P>
<P>Whenever possible use definitions from <CODE>gsym.h</CODE>. The resulting code is translated by cc65 into
series of <CODE>lda</CODE> and <CODE>sta</CODE>, so you can't do it better :-).</P>
<P>Don't hesitate to use library functions. Everything was written with size and speed in mind. In
fact many calls are just redirections to the GEOS Kernal which results in a simple <CODE>jsr</CODE>.</P>
<P>The <CODE>main</CODE> function receives the standard <CODE>argc</CODE> and <CODE>argv</CODE> parameters. There are
always either 1 or 3 parameters. The DOS application name is always set as <CODE>argv[0]</CODE>.
If present, <CODE>argv[1]</CODE> and <CODE>argv[2]</CODE> will be set to the data filename and data diskname (it only
works if the user double-clicks on a data file associated with your application). Note that it is up
to your application to determine which of the available (up to four) disk drives has the disk
with given diskname inside. If this fails your program should ask to insert the proper disk into
one of available drives.</P>
<P>You might wonder why I have chosen a sometimes weird order of arguments in functions. I just
wanted to avoid unnecessary pushing and popping of arguments from the stack because cc65 can pass a single
<CODE>unsigned int</CODE> through CPU registers.</P>
<P>Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in
ANSI.</P>
<P>It is possible to use dynamically loaded modules, three such modules are provided:
A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver.
Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special
recommendations, read the cc65 documentation about modules and the demo programs source code.</P>
<H2><A NAME="s3">3.</A> <A HREF="#toc3">Library Functions</A></H2>
<P>Functions here are sorted more or less in the way they appear in the header files. This way I am able
to keep functions covering similar tasks near each other. All function names are identical to those
from the <CODE>geosSym</CODE> file provided with the GeoProgrammer package. Only my extensions to <CODE>geosSym</CODE>
are covered by new names, but I tried to keep them in the naming convention.</P>
<H2><A NAME="ss3.1">3.1</A> <A HREF="#toc3.1">Graphics</A>
</H2>
<P>This section covers the drawing package of GEOS along with text output routines.</P>
<H3>SetNewMode</H3>
<P><CODE>void SetNewMode (void)</CODE></P>
<P>This function is intended for use by GEOS 128 only, and will exhibit undefined behavior on the
C64. It will toggle between the 40 column screen mode and the 80 column screen mode. Many C128 GEOS
programs implement a "Switch 40/80" submenu option under the <CODE>geos</CODE> menu.</P>
<H3>SetPattern</H3>
<P><CODE>void SetPattern (char pattern)</CODE></P>
<P>This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can
see them together in the filling box in GeoPaint.</P>
<H3>GraphicsString</H3>
<P><CODE>void GraphicsString (const void *myGString)</CODE></P>
<P>One of the more powerful routines of GEOS. This function calls other graphic functions depending
on the given command string. See the structures chapter for a more detailed description.</P>
<H3>Rectangle functions</H3>
<P>Parameters to those functions are grouped in the <CODE>struct window drawWindow</CODE>. To speed up things and
reduce overhead this structure is bound to zero page locations, where all rectangle functions
expect their parameters. You can modify the data directly (e.g. <CODE>drawWindow.top=10</CODE>) or via the
<CODE>InitDrawWindow</CODE> function. Contents of <CODE>drawWindow</CODE> are guaranteed not to change when only
using graphics functions. In other cases you should keep your data in separate <CODE>struct window</CODE>
and use <CODE>InitDrawWindow</CODE> before the first call to one of the rectangle functions.</P>
<H3>InitDrawWindow</H3>
<P><CODE>void InitDrawWindow (struct window *myWindow)</CODE></P>
<P>This function only copies the contents of <CODE>myWindow</CODE> into the system area of <CODE>drawWindow</CODE>. Use it
if for some reason you have to keep your window data out of the zero page space.</P>
<H3>Rectangle</H3>
<P><CODE>void Rectangle (void)</CODE></P>
<P>This draws on screen a rectangle filled with the current pattern.</P>
<H3>FrameRectangle</H3>
<P><CODE>void FrameRectangle (char pattern)</CODE></P>
<P>This one draws a frame with the given bit pattern (not a pattern from the GEOS palette).</P>
<H3>InvertRectangle</H3>
<P><CODE>void InvertRectangle (void)</CODE></P>
<P>Just as the name says...</P>
<H3>ImprintRectangle and RecoverRectangle</H3>
<P><CODE>void ImprintRectangle (void)</CODE></P>
<P><CODE>void RecoverRectangle (void)</CODE></P>
<P>These two functions are for copying parts of the screen to (<CODE>Imprint</CODE>) and from (<CODE>Recover</CODE>) the
backbuffer of the screen. For example when drawing a new menu box GEOS first uses
<CODE>ImprintRectangle</CODE> to save the area under the box, and restores it by <CODE>RecoverRectangle</CODE> upon
destroying the menu.</P>
<H3>Line Functions</H3>
<P>The GEOS drawing package is optimized so there are different functions for drawing vertical and
horizontal lines.</P>
<H3>HorizontalLine</H3>
<P><CODE>void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)</CODE></P>
<P>This function draws a horizontal line using the given pattern. Note that <CODE>pattern</CODE> is not a pattern
number as set in <CODE>SetPattern</CODE> but a true bit pattern.</P>
<H3>InvertLine</H3>
<P><CODE>void InvertLine (char y, unsigned xStart, unsigned xEnd)</CODE></P>
<P>There is only a horizontal version.</P>
<H3>RecoverLine</H3>
<P><CODE>void RecoverLine (char y, unsigned xStart, unsigned xEnd)</CODE></P>
<P>This function recovers a single line. It is utilized by <CODE>RecoverRectangle</CODE>. See its description
for more details.</P>
<H3>VerticalLine</H3>
<P><CODE>void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)</CODE></P>
<P>This function draws a vertical line using the given pattern. Note that <CODE>pattern</CODE> is not a pattern
number as set in <CODE>SetPattern</CODE> but a true bit pattern.</P>
<H3>DrawLine</H3>
<P><CODE>void DrawLine (char mode, struct window *myWindow)</CODE></P>
<P>The <CODE>top</CODE> parameters of <CODE>struct window</CODE> describe the starting point of the line, while
<CODE>bottom</CODE> ones are for the ending point. If <CODE>mode</CODE> is <CODE>DRAW_DRAW</CODE> then the current pattern from
<CODE>SetPattern</CODE> is used for drawing. If <CODE>mode</CODE> is <CODE>DRAW_ERASE</CODE> then the line is erased from the
screen. If <CODE>mode</CODE> is <CODE>DRAW_COPY</CODE> then the line is copied from/to back/frontbuffer, according to
the <CODE>dispBufferOn</CODE> setting.</P>
<H3>Point Functions</H3>
<P>The parameters to these two functions are passed by a pointer to an own <CODE>struct pixel</CODE> filled with
proper values.</P>
<H3>DrawPoint</H3>
<P><CODE>void DrawPoint (char mode, struct pixel *myPixel)</CODE></P>
<P>Depending on <CODE>mode</CODE> (see <CODE>DrawLine</CODE>) draws/erases/copies a single point
on the screen.</P>
<H3>TestPoint</H3>
<P><CODE>char TestPoint (struct pixel *myPixel)</CODE></P>
<P>This function tests if the given pixel is set and returns <CODE>true</CODE> (non-zero) or <CODE>false</CODE> (zero).</P>
<H3>Character and string output</H3>
<H3>PutChar</H3>
<P><CODE>void PutChar (char character, char y, unsigned x)</CODE></P>
<P>This function outputs a single character using the current style and font to the screen.</P>
<H3>PutString</H3>
<P><CODE>void PutString (char *myString, char y, unsigned x)</CODE></P>
<P>Same as <CODE>PutChar</CODE> except the fact that you can output a whole <CODE>NULL</CODE>-terminated string.
See <CODE>ggraph.h</CODE> for the list of tokens that you can also place in the string - like <CODE>CBOLDON</CODE> or
<CODE>COUTLINEON</CODE>.</P>
<H3>PutDecimal</H3>
<P><CODE>void PutDecimal (char parameter, unsigned value, char y, unsigned x)</CODE></P>
<P>This function converts <CODE>value</CODE> to its decimal representation and outputs it to the screen.
The <CODE>parameter</CODE> is the field width in pixels (range 1-31) and the mode bits. Depending on them
the string can be filled with zeroes (the string is always 5 characters long) or not and left or right
justified to the given pixel. See <CODE>ggraph.h</CODE> for predefined values for <CODE>parameter</CODE>.</P>
<H3>Font Handling</H3>
<H3>GetCharWidth</H3>
<P><CODE>char GetCharWidth (char character)</CODE></P>
<P>This function returns the real width (in pixels) of the given character with the current font. It can be used
for counting the length of a string on the screen, allowing for indentation or justification.</P>
<H3>LoadCharSet</H3>
<P><CODE>void LoadCharSet (struct fontdesc *myFont)</CODE></P>
<P>This function forces GEOS to use the given font. <CODE>myFont</CODE> should be casted from a
pointer to the start of the area where a record from a font file (VLIR structure) was loaded.</P>
<H3>UseSystemFont</H3>
<P><CODE>void UseSystemFont (void)</CODE></P>
<P>This function forces GEOS to use the built-in BSW font.</P>
<H3>Bitmap handling</H3>
<P>I'm not quite sure how these functions are working (except <CODE>BitmapUp</CODE>) so you should
probably look into the library sources and compare it with your knowledge. Please let me know
if something is wrong or broken.</P>
<H3>BitmapUp</H3>
<P><CODE>void BitmapUp (struct iconpic *myPic)</CODE></P>
<P>This function unpacks the bitmap and places it on the screen - just as you set it in the
<CODE>struct iconpic</CODE> pointer which you pass. See <CODE>gstruct.h</CODE> for a description of this
structure. Note that you can only use packed GEOS bitmaps - a simple Photo Scrap is in this format.</P>
<H3>BitmapClip</H3>
<P><CODE>void BitmapClip (char skipLeft, char skipRight, unsigned skipTop, struct iconpic *myPic)</CODE></P>
<P>This function acts similar to <CODE>BitmapUp</CODE> but you can also define which parts of the bitmap are
to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap,
and the number of rows to skip from the top if it.</P>
<H3>BitOtherClip</H3>
<P><CODE>void BitOtherClip (void *proc1, void *proc2, char skipLeft, char skip Right, unsigned skipTop,
struct iconpic *myPic)</CODE></P>
<P>Similar to the previous one with some extension. <CODE>proc1</CODE> is called before reading a byte (it
returns in .A the next value), and <CODE>proc2</CODE> is called every time the parser reads a byte which is
not a piece of a pattern (byte of code greater than 219). Both procedures should be written
separately in assembler and declared as <CODE>__fastcall__</CODE> returning char.</P>
<H2><A NAME="ss3.2">3.2</A> <A HREF="#toc3.2">Menus and Icons</A>
</H2>
<P>Here you will find information about functions related with menus and icons.</P>
<H3>Menus</H3>
<P>Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call
another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up
to 32 items.</P>
<P>Menus are initialized with <CODE>DoMenu</CODE> and then the Kernal takes care of everything. Your code
(called from an event handler) should be a function without parameters, returning void. You should
use <CODE>DoPreviousMenu</CODE> or <CODE>GotoFirstMenu</CODE> at least once in its code to have the screen clean.</P>
<H3>DoMenu</H3>
<P><CODE>void DoMenu (struct menu *myMenu)</CODE></P>
<P>This function initializes the GEOS menu processor and exits. See <CODE>DoMenu structure</CODE> for more
information about it. Know that many GEOS applications just initialize the screen, menu and
exit to the main Kernal loop, this proves the power of <CODE>DoMenu</CODE>.</P>
<H3>ReDoMenu</H3>
<P><CODE>void ReDoMenu (void)</CODE></P>
<P>This simply redraws the menu at the lowest level. It works like calling <CODE>DoMenu</CODE> again with
the same parameters.</P>
<H3>RecoverMenu</H3>
<P><CODE>void RecoverMenu (void)</CODE></P>
<P>This function erases the current menu from the screen. It doesn't change the menu level.</P>
<H3>RecoverAllMenus</H3>
<P><CODE>void RecoverAllMenus (void)</CODE></P>
<P>This calls <CODE>RecoverMenu</CODE> and erases all menus from the screen. Then the menu level is
set to 0 (topmost).</P>
<H3>DoPreviousMenu</H3>
<P><CODE>void DoPreviousMenu (void)</CODE></P>
<P>This functions causes the menu processor to go back one menu level. You should use it in menu
handler code to have the screen clean.</P>
<H3>GotoFirstMenu</H3>
<P><CODE>void GotoFirstMenu (void)</CODE></P>
<P>This one jumps back to the topmost menu. If there is only a menu and one submenu it works the
same as <CODE>DoPreviousMenu</CODE>.</P>
<H3>Icon Functions</H3>
<P>Icons are working similar to menus except the fact that there is only one level. Icons are
defined as a screen area filled with a bitmap, but if you would setup icons and erase the
screen they would still be active and clicking in the place where formerly an icon was would cause
an effect. Similarly if you would setup icons and then turn them off with <CODE>ClearMouseMode</CODE>
the bitmap would still be on the screen but clicking on it would not cause any action.
There is only one, but powerful icon function.</P>
<H3>DoIcons</H3>
<P><CODE>void DoIcons (struct icontab *myIconTab)</CODE></P>
<P>This function initializes all icons that are present on the screen at once. For more information
look at the <CODE>Icons</CODE> chapter in this manual.</P>
<H2><A NAME="ss3.3">3.3</A> <A HREF="#toc3.3">DialogBoxes</A>
</H2>
<P>This chapter covers the most powerful GEOS user interface function - <CODE>DoDlgBox</CODE>.</P>
<H3>GEOS standard</H3>
<H3>DoDlgBox</H3>
<P><CODE>char DoDlgBox (char *dialogString)</CODE></P>
<P>This function returns one byte. It can be the value of one of six standard icons (see <CODE>gdlgbox.h</CODE>)
or whatever the closing routine passes. Register <CODE>r0L</CODE> also contains this value.</P>
<P>Read the structures chapter for the specs of the <CODE>dialogString</CODE>.</P>
<H3>RstrFrmDialogue</H3>
<P><CODE>char RstrFrmDialogue</CODE></P>
<P>This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns
the owner ID (or whatever caller has in the .A register).</P>
<H3>GEOSLib extensions</H3>
<P>To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox,
with predefined data. In one word - these are standard DialogBoxes you can see in almost every
GEOS application.</P>
<H3>DlgBoxYesNo, DlgBoxOkCancel, DlgBoxOk</H3>
<P><CODE>char DlgBoxYesNo (char *line1, char *line2)</CODE></P>
<P><CODE>char DlgBoxOkCancel (char *line1, char *line2)</CODE></P>
<P><CODE>void DlgBoxOk (char *line1, char *line2)</CODE></P>
<P>These function show two lines of text in a standard-sized DialogBox. You can read the code of the
pressed icon from the return value. E.g. for <CODE>DlgBoxYesNo</CODE> it can only be <CODE>YES</CODE> or <CODE>NO</CODE>.
You can pass an empty string or NULL to get a blank line.</P>
<H3>DlgBoxGetString</H3>
<P><CODE>char DlgBoxGetString (char *string, char strlen, char *line1, char *line2)</CODE></P>
<P>This function prompts the user to enter a string of at most <CODE>strlen</CODE> characters. It is returned
in <CODE>string</CODE>. The two given lines of text are shown above the input line. Please remember
that there is also a <CODE>CANCEL</CODE> icon in the DialogBox and you should test if user confirmed his
input or gave up. The <CODE>string</CODE> is also shown so you can place a default input there or remember
to place <CODE>NULL</CODE> at start.</P>
<H3>DlgBoxFileSelect</H3>
<P><CODE>char DlgBoxFileSelect (char *class, char filetype, char *filename)</CODE></P>
<P>This routine is the standard file selector. It can return <CODE>OPEN</CODE>, <CODE>CANCEL</CODE> or disk error
on reading the directory or opening the disk.
There is also a <CODE>DISK</CODE> icon shown, but it is handled internally. You pass as input parameters
<CODE>filetype</CODE> and a pointer to a string containing the first part of a file's class. If this string is
empty (<CODE>NULL</CODE> at the start), then all files with given filetype will be shown.</P>
<P>At present this file selector handles only first 16 files of given type and supports only one
(current) drive.</P>
<H3>MessageBox</H3>
<P><CODE>char MessageBox (char mode, const char *format, ...)</CODE></P>
<P>This function is a more general one. It works very much like <CODE>printf</CODE> in a
box. The only difference is the <CODE>mode</CODE> parameter which allows for placing
default icons (see <CODE>gdlgbox.h</CODE> for list of possible <CODE>MB_</CODE> values).
Any too wide text will be clipped to the size of the default window. If <CODE>mode</CODE>
is invalid or equal to <CODE>MB_EMPTY</CODE> then the window will be closed
after a click. Otherwise the user must choose an icon.</P>
<P>Note: Use it if you really need (or if you use it in many places) as
it adds quite amount of code to your program.</P>
<P>Note: the formatted text <EM>cannot exceed</EM> 255 bytes in length, there is no check
for that.</P>
<H2><A NAME="ss3.4">3.4</A> <A HREF="#toc3.4">Mouse, Sprites and Cursors</A>
</H2>
<P>You will find here functions related to sprite and mouse drawing and handling.</P>
<H3>Mouse related functions</H3>
<P>These cover the mouse - as a general pointing device, but expect users to utilize as different devices
as a digital or analog joystick, a mouse, a lightpen or a koalapad (whatever it is).</P>
<H3>StartMouseMode</H3>
<P><CODE>void StartMouseMode (void)</CODE></P>
<P>This function initializes the mouse vectors - <CODE>mouseVector</CODE> and <CODE>mouseFaultVec</CODE>, and then
calls <CODE>MouseUp</CODE>.</P>
<H3>ClearMouseMode</H3>
<P><CODE>void ClearMouseMode (void)</CODE></P>
<P>This function disables all mouse activities - icons and menus stop to respond to mouse events,
but they are not cleared from the screen.</P>
<H3>MouseUp and MouseOff</H3>
<P><CODE>void MouseUp (void)</CODE></P>
<P><CODE>void MouseOff (void)</CODE></P>
<P>The first function turns the mouse pointer on. It appears on the next IRQ. The second one does
the opposite - it turns off the pointer, but its position is still updated by the input driver.</P>
<H3>IsMseInRegion</H3>
<P><CODE>char IsMseInRegion (struct window *myWindow)</CODE></P>
<P>This function tests if the mouse pointer is actually in the given range of the screen. See <CODE>gsprite.h</CODE> for
a description of the bits in the return values - they describe the position in detail.</P>
<H3>Sprites</H3>
<P>You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse
pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about
40/80 column issues because GEOS128 has a pretty good sprite emulator for the VDC.</P>
<H3>DrawSprite</H3>
<P><CODE>void DrawSprite (char sprite, char *mySprite)</CODE></P>
<P>This function initializes the sprite data. <CODE>mySprite</CODE> is a 63-byte table with bitmap data, which
is copied to the system sprite area (at <CODE>sprpic</CODE> - see <CODE>gsym.h</CODE>). Hardware sprite registers are
not initialized and the sprite is not yet visible.</P>
<H3>PosSprite</H3>
<P><CODE>void PosSprite (char sprite, struct pixel *myPixel)</CODE></P>
<P>This function positions the sprite on the screen. The given coordinates are screen ones - they are
converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your
sprite off the left or top to the screen.</P>
<H3>EnablSprite and DisablSprite</H3>
<P><CODE>void EnablSprite (char sprite)</CODE></P>
<P><CODE>void DisablSprite (char sprite)</CODE></P>
<P>These two functions are responsible for making the sprite visible or not.</P>
<H3>Cursors and Console</H3>
<H3>InitTextPrompt</H3>
<P><CODE>void InitTextPrompt (char height)</CODE></P>
<P>This function initializes sprite 1 for a text prompt with given <CODE>height</CODE>. This parameter can be in
range 1-48.</P>
<H3>PromptOn and PromptOff</H3>
<P><CODE>void PromptOn (struct pixel *myPixel)</CODE></P>
<P><CODE>void PromptOff (void)</CODE></P>
<P>The first function places a text prompt in given place and enables blinking.
The second one is pretty self-explanatory.</P>
<H3>GetNextChar</H3>
<P><CODE>char GetNextChar (void)</CODE></P>
<P>This function gets the next character from the keyboard queue. If the queue is empty it returns
<CODE>NULL</CODE>, otherwise you receive the true ASCII code of a character or the value of a special (function)
key. See <CODE>gsprite.h</CODE> for the list of them.</P>
<H2><A NAME="ss3.5">3.5</A> <A HREF="#toc3.5">Disk</A>
</H2>
<P>This chapter covers rather low-level disk routines. You should use them with care, because
you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various
devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be
dangerous.</P>
<P>For some purposes you might consider using the <CODE>dio.h</CODE> interface to disk access. It is native.</P>
<P>All GEOS disk functions return an error code in the X register. In some cases this is returned by the
GEOSLib function (if its type is <CODE>char</CODE>), but in all cases the last error is saved in the <CODE>__oserror</CODE>
location. If it is nonzero - an error occurred. See <CODE>gdisk.h</CODE> for the list of possible errorcodes.
You need to include <CODE>errno.h</CODE> to get <CODE>__oserror</CODE>, together with the standard <CODE>errno</CODE>. The
latter gives less verbose, but still usable information and can be used with <CODE>strerror</CODE>.
Probably you will get more information using <CODE>_stroserror</CODE> in a similar way.</P>
<P>For passing parameters use almost always a pointer to your data e.g. <CODE>ReadBuff (&myTrSe)</CODE>.</P>
<H3>Buffer functions</H3>
<P>These functions take a single data sector (256 bytes) to read or write on the disk.</P>
<H3>ReadBuff and Writebuff</H3>
<P><CODE>char ReadBuff (struct tr_se *myTrSe)</CODE></P>
<P><CODE>char WriteBuff (struct tr_se *myTrSe)</CODE></P>
<P>These functions read and write a sector placed at <CODE>diskBlkBuf</CODE>.</P>
<H3>GetBlock and ReadBlock</H3>
<P><CODE>char GetBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char ReadBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P>These two functions read a single block directly to the 256 byte array placed at <CODE>buffer</CODE>.
The difference between them is that <CODE>GetBlock</CODE> initializes TurboDos in the drive if it was not
enabled. <CODE>ReadBlock</CODE> assumes that it is already enabled thus being slightly faster.</P>
<H3>PutBlock, WriteBlock, VerWriteBlock</H3>
<P><CODE>char PutBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char WriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P><CODE>char VerWriteBlock (struct tr_se *myTrSe, char *buffer)</CODE></P>
<P>Similar to previous but needed for writing the disk. <CODE>VerWriteBlock</CODE> verifies the data after
writing. In case of an error five tries are attempted before an error code is returned.</P>
<H3>Directory header</H3>
<P>The functions described here operate on <CODE>curDirHeader</CODE> where the current disk header is stored.
On larger (than 1541) capacity drives the second part of the directory header is in <CODE>dir2Head</CODE>.</P>
<H3>GetPtrCurDkNm</H3>
<P><CODE>void GetPtrCurDkNm (char *diskName)</CODE></P>
<P>This function fills the given character string with the name of current disk. It is converted to C
standard - the string is terminated with <CODE>NULL</CODE> character instead of code 160 as in Commodore DOS.
Note that the passed pointer must point to an array of at least 17 bytes.</P>
<H3>GetDirHead and PutDirHead</H3>
<P><CODE>char GetDirHead (void)</CODE></P>
<P><CODE>char PutDirHead (void)</CODE></P>
<P>These functions read and write the directory header. You should use <CODE>GetDirHead</CODE> before
using any functions described below, and you should use <CODE>PutDirHead</CODE> to save the changes on the
disk. Otherwise they will be lost. Operating area is the <CODE>curDirHead</CODE>.</P>
<H3>CalcBlksFree</H3>
<P><CODE>unsigned CalcBlksFree (void)</CODE></P>
<P>This function returns the number of free blocks on the current disk. It is counted using data in
<CODE>curDirHead</CODE> so you must initialize the disk before calling it.</P>
<H3>ChkDkGEOS</H3>
<P><CODE>char ChkDkGEOS (void)</CODE></P>
<P>This functions checks <CODE>curDirHead</CODE> for the GEOS Format identifier. It returns either true or false,
and also sets <CODE>isGEOS</CODE> properly. You must initialize the disk before using this.</P>
<H3>SetGEOSDisk</H3>
<P><CODE>char SetGEOSDisk (void)</CODE></P>
<P>This function initializes disk for use with GEOS. It sets the indicator in directory header and
allocates a sector for the directory of border files. You don't need to initialize the disk before
using.</P>
<H3>FindBAMBit</H3>
<P><CODE>char FindBAMBit (struct tr_se *myTrSe)</CODE></P>
<P>This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is
set if the sector is free to use. The returned value is always zero if the sector is already allocated.
In fact, this function could be used in a following way:
<BLOCKQUOTE><CODE>
<PRE>
#define BlockInUse FindBAMBit
...
if (!BlockInUse(&myTrSe)) {
... block not allocated ...
}
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>Anyway, I feel that this function is too low-level.</P>
<H3>BlkAlloc and NxtBlkAlloc</H3>
<P><CODE>char BlkAlloc (struct tr_se output[], unsigned length)</CODE></P>
<P><CODE>char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[], unsigned length)</CODE></P>
<P>Both functions allocate enough disk sectors to fit <CODE>length</CODE> bytes in them. You
find the output in <CODE>output</CODE> which is a table of <CODE>struct tr_se</CODE>. The last entry will have the
track equal to 0 and sector equal to 255. The simplest way of using them is to use
predefined space in the GEOS data space and pass <CODE>fileTrScTab</CODE>, which is a predefined table.</P>
<P>The difference between those two is that <CODE>NextBlkAlloc</CODE> starts allocating from the given sector,
and <CODE>BlkAlloc</CODE> starts from the first nonused sector.</P>
<P>You need to use <CODE>PutDirHead</CODE> later to save any changes in BAM.</P>
<H3>FreeBlock</H3>
<P><CODE>char FreeBlock (struct tr_se *myTrSe)</CODE></P>
<P>Simply deallocates a block in the BAM. You need to update the BAM with <CODE>PutDirHead</CODE>.</P>
<H3>SetNextFree</H3>
<P><CODE>struct tr_se SetNextFree (struct tr_se *myTrSe)</CODE></P>
<P>This function finds the first free sector starting from given track and sector and allocates it.
It might return the same argument if the given block is not allocated. I wanted it to be type
clean, but this made the usage a bit tricky. To assign a value to your own <CODE>struct tr_se</CODE> you have to
cast both variables to <CODE>unsigned</CODE>. E.g.
<BLOCKQUOTE><CODE>
<PRE>
struct tr_se myTrSe;
...
(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe);
</PRE>
</CODE></BLOCKQUOTE>
</P>
<P>In this example <CODE>otherTrSe</CODE> can be replaced by <CODE>myTrSe</CODE>.</P>
<P>Note: you <EM>must</EM> use casting to have the correct values.</P>
<H3>Low-level disk IO</H3>
<P>Functions described here are more usable in Kernal or drivers code, less common in applications,
but who knows, maybe someone will need them.</P>
<H3>EnterTurbo, ExitTurbo, PurgeTurbo</H3>
<P><CODE>void EnterTurbo (void)</CODE></P>
<P><CODE>void ExitTurbo (void)</CODE></P>
<P><CODE>void PurgeTurbo (void)</CODE></P>
<P>These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit
more usable. <CODE>EnterTurbo</CODE> enables TurboDos unless it is already enabled. If not, then you will
have to wait a bit to transfer the TurboDos code into disk drive RAM. <CODE>ExitTurbo</CODE> disables TurboDos.
This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any
interaction with the Kernal in ROM you have to call <CODE>InitForIO</CODE>. You don't have to worry about speed.
<CODE>EnterTurbo</CODE> will only enable TurboDos (no code transfer) if TurboDos was disabled with
<CODE>ExitTurbo</CODE>. <CODE>PurgeTurbo</CODE> acts differently from <CODE>ExitTurbo</CODE> - it not only disables TurboDos,
but also removes it from drive RAM (not quite true, but it works like that). After using
<CODE>PurgeTurbo</CODE> the next call to <CODE>EnterTurbo</CODE> will reload drive RAM.</P>
<H3>ChangeDiskDevice</H3>
<P><CODE>char ChangeDiskDevice (char newDevice)</CODE></P>
<P>This function changes the device number of the current device (in fact drives only) to the given one. It is
usable for swapping drives. There's no check if the given <CODE>newDevice</CODE> already exist, so if you want
to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably
hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30.</P>
<H3>Disk Initialization</H3>
<P>GEOS has two functions for initialization ('logging in' as they say on CP/M) of a disk.</P>
<H3>OpenDisk</H3>
<P><CODE>char OpenDisk (void)</CODE></P>
<P>This function initializes everything for a new disk. It loads and enables TurboDos if needed.
Then the disk is initialized with <CODE>NewDisk</CODE>. Next, <CODE>GetDirHead</CODE> initializes <CODE>curDirHead</CODE>.
Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is
checked with <CODE>ChkDkGEOS</CODE> and the disk name is updated in the internal tables.</P>
<H3>NewDisk</H3>
<P><CODE>char NewDisk (void)</CODE></P>
<P>This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed.</P>
<H2><A NAME="ss3.6">3.6</A> <A HREF="#toc3.6">Files</A>
</H2>
<P>This section covers the GEOS file interface.</P>
<H3>Directory handling</H3>
<P>The functions described here are common for SEQ and VLIR structures.</P>
<H3>Get1stDirEntry and GetNxtDirEntry</H3>
<P><CODE>struct filehandle *Get1stDirEntry (void)</CODE></P>
<P><CODE>struct filehandle *GetNxtDirEntry (void)</CODE></P>
<P>Those two functions are best suited for scanning the whole directory for particular files. Note that
the returned filehandles describe all file slots in the directory -- even those with deleted files.
The return value is <CODE>NULL</CODE> if there are no more slots, or if there was a disk error. The
<CODE>_oserror</CODE> variable is non-zero if it was a disk error (see <CODE>geos/gdisk.h</CODE>). The current
directory track and sector numbers are in <CODE>r1L</CODE> and <CODE>r1H</CODE>. The sector data itself is in
<CODE>diskBlkBuf</CODE>.</P>
<H3>FindFile</H3>
<P><CODE>char FindFile (char *fName)</CODE></P>
<P>This function scans the whole directory for the given filename. It returns either 0 (success), 5
(FILE_NOT_FOUND, defined in <CODE>geos/gdisk.h</CODE>), or any other fatal disk read error. After a successful
<CODE>FindFile()</CODE>, you will have <CODE>struct filehandle</CODE> at <CODE>dirEntryBuf</CODE> filled with the file's data, and
other registers set as described in <CODE>GetNxtDirEntry()</CODE>.</P>
<H3>FindFTypes</H3>
<P><CODE>char FindFTypes (char *buffer, char fType, char fMaxNum, char *classTxt)</CODE></P>
<P>This function scans the directory and fills a table at <CODE>buffer</CODE> with <CODE>char [17]</CODE> entries.
<CODE>fType</CODE> is the GEOS type of the searched files and <CODE>classTxt</CODE> is a string for the Class field in the file
header. Class matches if the given string is equal or shorter than that found in the file's header block.
If you want just to find all files with the given GEOS type you should pass an empty string or <CODE>NULL</CODE> as
<CODE>classTxt</CODE>. Be warned that for searching <CODE>NON_GEOS</CODE> files you must pass <CODE>NULL</CODE> as <CODE>classTxt</CODE>.
<CODE>fMaxNum</CODE> is the maximal number of files to find, thus the <CODE>buffer</CODE> must provide an area of size
equal to <CODE>17 * fMaxNum</CODE>. This function returns the number of found files, ranging from 0 to number
passed as <CODE>fMaxNum</CODE>. The return value can be also restored from <CODE>r7H</CODE>.</P>
<H3>DeleteFile</H3>
<P><CODE>char DeleteFile (char *fName)</CODE></P>
<P>This function deletes a file by its name. It works for SEQ and VLIR files.</P>
<H3>RenameFile</H3>
<P><CODE>char RenameFile (char *oldName, char *newName)</CODE></P>
<P>I think it is obvious...</P>
<H3>GetFHdrInfo</H3>
<P><CODE>char GetFHdrInfo (struct filehandle *myFile)</CODE></P>
<P>This function loads the file header into the <CODE>fileHeader</CODE> buffer. Using after e.g. <CODE>FindFile</CODE>
you can pass the address of <CODE>dirEntryBuf</CODE>.</P>
<H3>Common and SEQ structure</H3>
<P>Functions described here are common for SEQ and VLIR structures because the arguments passed are the
starting track and sector which may point either to the start of a chain for VLIR or the data for SEQ.</P>
<H3>GetFile</H3>
<P><CODE>char __fastcall__ GetFile(char flag, const char *fname, const char *loadaddr, const char *datadname, const char *datafname)</CODE></P>
<P>This routine loads and runs a given file <CODE>fname</CODE>. The file must be one of following types:
<CODE>SYSTEM, DESK_ACC, APPLICATION, APPL_DATA, PRINTER,</CODE> or <CODE>INPUT_DEVICE</CODE>. The execution
address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain
from VLIR files is loaded. If <CODE>flag</CODE> has bit 0 set then the load address is taken from <CODE>loadaddr</CODE>
and not from the file header. In this case <CODE>APPLICATION</CODE> files will be only loaded, not executed.
This does not apply to <CODE>DESK_ACC</CODE>. If either bit 6 or 7 of <CODE>flag</CODE> are set, then 16 bytes from
<CODE>datadname</CODE> are copied to <CODE>dataDiskName</CODE> and 16 bytes from <CODE>datafname</CODE> go to <CODE>dataFileName</CODE>
thus becoming parameters for the new application. Pass <CODE>NULL</CODE> for any unused parameter.</P>
<H3>ReadFile</H3>
<P><CODE>char ReadFile (struct tr_se *myTrSe, char *buffer, unsigned fLength)</CODE></P>
<P>This function reads at most <CODE>fLength</CODE> bytes into <CODE>buffer</CODE> from chained sectors starting at
<CODE>myTrSe</CODE>.</P>
<H3>ReadByte</H3>
<P><CODE>char ReadByte (void)</CODE></P>
<P>This function returns the next byte from a file. Before the first call to it you must load <CODE>r5</CODE>
with <CODE>NULL</CODE>, <CODE>r4</CODE> with the sector buffer address and <CODE>r1</CODE> with the track and sector of the
first block of a file.
Remember to not modify <CODE>r1</CODE>, <CODE>r4</CODE> and <CODE>r5</CODE>. These registers must be preserved between
calls to <CODE>ReadByte</CODE>.</P>
<P>The returned value is valid only if there was no error. The end of file is marked as <CODE>BFR_OVERFLOW</CODE>
in <CODE>__oserror</CODE>, this is set when trying to read one byte after the end of file, in this case the
returned value is invalid.</P>
<H3>SaveFile</H3>
<P><CODE>char SaveFile (char skip, struct fileheader *myHeader)</CODE></P>
<P><CODE>SaveFile</CODE> will take care of everything needed to create a GEOS file, no matter if VLIR of SEQ
structure. All you need to do is to place the data in the proper place and prepare a header which will
contain all information about a file. The <CODE>skip</CODE> parameter says how many directory pages you
want to skip before searching for a free slot for the directory entry. In most cases you will put
<CODE>0</CODE> there.</P>
<P>You have to declare a <CODE>struct fileheader</CODE> and fill it with proper values. There is only one
difference - the first two bytes which are a link to a nonexistent next sector are replaced by a
pointer to the DOS filename of the file.</P>
<P>When saving sequential files the two most important fields in <CODE>struct fileheader</CODE> are <CODE>fileheader.load_address</CODE>
and <CODE>fileheader.end_address</CODE>.</P>
<H3>FreeFile</H3>
<P><CODE>char FreeFile (struct tr_se myTable[])</CODE></P>
<P>This function deallocates all sectors contained in the passed table.</P>
<H3>FollowChain</H3>
<P><CODE>char FollowChain(struct tr_se *myTrSe, char *buffer)</CODE></P>
<P>This function fills a <CODE>struct tr_se</CODE> table at <CODE>buffer</CODE> with the sector numbers for a chain of
sectors starting with <CODE>myTrSe</CODE>. You can pass such data (<CODE>buffer</CODE>) to e.g. <CODE>FreeFile</CODE>.</P>
<H3>VLIR structure</H3>
<P>Here is information about VLIR files (later called RecordFiles) and functions.</P>
<P>A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one
SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and
an own number. Each record pointed to by its number is described by the starting track and sector numbers.
VLIR structures allow records to be empty (<CODE>tr_se</CODE> of such record is equal to <CODE>{NULL,$ff}</CODE>),
or even non-exist (<CODE>{NULL,NULL}</CODE>). Any other numbers represent the starting track and sector of
a particular file.</P>
<P>In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information
about it is copied into memory. You can retrieve the records table at <CODE>fileTrScTab</CODE> (table of
128 <CODE>struct tr_se</CODE>) and from <CODE>VLIRInfo</CODE> (<CODE>struct VLIR_info</CODE>).
E.g. the size of whole VLIR file can be retrieved by reading <CODE>VLIRInfo.fileSize</CODE>.</P>
<H3>OpenRecordFile</H3>
<P><CODE>char OpenRecordFile (char *fName)</CODE></P>
<P>This function finds and opens a given file. An error is returned if the file is not found or if it is not
in VLIR format. Information in <CODE>VLIRInfo</CODE> is initialized. VLIR track and sector table is
loaded at <CODE>fileTrScTab</CODE> and will be valid until a call to <CODE>CloseRecordFile</CODE> so don't modify it.
You should call <CODE>PointRecord</CODE> before trying to do something with the file.</P>
<H3>CloseRecordFile</H3>
<P><CODE>char CloseRecordFile (void)</CODE></P>
<P>This function calls <CODE>UpdateRecordFile</CODE> and clears internal GEOS variables.</P>
<H3>UpdateRecordFile</H3>
<P><CODE>char UpdateRecordFile (void)</CODE></P>
<P>This function will check the <CODE>VLIRInfo.fileWritten</CODE> flag and if it is set, then <CODE>curDirHead</CODE> is
updated along with size and date stamps in the directory entry.</P>
<H3>PointRecord</H3>
<P><CODE>char PointRecord (char recordNumber)</CODE></P>
<P>This function will setup internal variables (and <CODE>VLIRInfo.curRecord</CODE>) and return the track and
sector of the given record in <CODE>r1</CODE>. Note that the data may not be valid (if the record is non-existing
you will get 0,0 and if it is empty - 255,0).</P>
<H3>NextRecord and PreviousRecord</H3>
<P><CODE>char NextRecord (void)</CODE></P>
<P><CODE>char PreviousRecord (void)</CODE></P>
<P>These two work like <CODE>PointRecord</CODE>. Names are self-explanatory.</P>
<H3>AppendRecord</H3>
<P><CODE>char AppendRecord (void)</CODE></P>
<P>This function will append an empty record (pair of 255,0) to the current VLIR track and sector
table. It will also set <CODE>VLIRInfo.curRecord</CODE> to its number.</P>
<H3>DeleteRecord</H3>
<P><CODE>char DeleteRecord (void)</CODE></P>
<P>This function will remove the current record from the table, and move all current+1 records one place
back (in the table). Note that there's no BAM update and you must call <CODE>UpdateRecordFile</CODE> to
commit changes.</P>
<H3>InsertRecord</H3>
<P><CODE>char InsertRecord (void)</CODE></P>
<P>This function will insert an empty record in place of <CODE>VLIRInfo.curRecord</CODE> and move all following
records in the table one place forward (contents of <CODE>VLIRInfo.curRecord</CODE> after a call to <CODE>InsertRecord</CODE>
can be found in <CODE>VLIRInfo.curRecord + 1</CODE>).</P>
<H3>ReadRecord and WriteRecord</H3>
<P><CODE>char ReadRecord (char *buffer, unsigned fLength)</CODE></P>
<P><CODE>char WriteRecord (char *buffer, unsigned fLength)</CODE></P>
<P>This function will load or save at most <CODE>fLength</CODE> bytes from the currently pointed record into or from
<CODE>buffer</CODE>.</P>
<H2><A NAME="ss3.7">3.7</A> <A HREF="#toc3.7">Memory and Strings</A>
</H2>
<P>The functions covered in this section are common for the whole C world - copying memory parts and
strings is one of the main computer tasks. GEOS also has an interface to do this. These functions
are replacements for those like <CODE>memset, memcpy, strcpy</CODE> etc. from standard libraries.
If you are dealing with short strings (up to 255 characters) you should use these functions
instead of standard ones, e.g. <CODE>CopyString</CODE> instead of <CODE>strcpy</CODE>. It will work faster.</P>
<P>However some of them have slightly different calling conventions (order of arguments to be specific),
so please check their syntax here before a direct replacement.</P>
<P>Please note that the memory areas described here as <EM>strings</EM> are up to 255 characters (without
counting the terminating <CODE>NULL</CODE>), and <EM>regions</EM> can cover the whole 64K of memory.</P>
<H3>CopyString</H3>
<P><CODE>void CopyString (char *dest, char *src)</CODE></P>
<P>This function copies the string from <CODE>src</CODE> to <CODE>dest</CODE>, until it reaches <CODE>NULL</CODE>. The <CODE>NULL</CODE>
is also copied.</P>
<H3>CmpString</H3>