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> 8This is the documentation of cc65's GEOSLib, but information contained here may be also 9useful 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> 19As we all know that the best computers in the world are the C64 and C128. They have their GUI too - 20the excellent GEOS. GEOS seems very difficult and cryptic for many people, from programmer's point 21of view. That's not true. The designers of GEOS created a flexible and powerful system, which 22is easy to use and program. 23<p> 24Coding GEOS in C? That's something new. It is possible now - with Ulrich von Bassewitz's cc65 25package and my GEOSLib you are able to create GEOS applications in no time. 26<p> 27GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions 28are used (e.g. <tt/memset/ is an alias for <tt/FillRam/), however not all are supported. E.g. 29string 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 31you write your program. If you don't need long strings simply use functions from the Kernal, 32the resulting code will be smaller. 33<p> 34<tt/dio/ - direct disk access is available, but you might have problems with devices other 35than 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. 38This implementation assumes that one character does fit in 8x8 cell, so output with 39default BSW font, which is has 9 points, might be a bit messy. There is no color support in 40GEOS 2.0 so color functions are disabled. Both 40 and 80 column modes are supported 41and automatically detected. 42<p> 43<tt/tgi/ - TGI driver for GEOS that supports both 40 and 80 column modes but mode can not be 44changed 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> 48It 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> 51For <tt/time.h/ functions <tt/clock()/ and <tt/clock_gettime()/ note that the resolution is one second. 52<p> 53Functions from the headers above are either standard C library functions or cc65-specific, in 54either case they are not GEOS specific and so they are not described here. 55<p> 56I am an assembler programmer and GEOSLib was designed in such way that cc65 could emit the best 57available code (well, the best as for machine :-). Many of the <tt/void foo (void)/ functions are 58just raw calls to the Kernal (assembled just as <tt/jsr _foo/), look in <tt/gsym.h/, where you 59can find many definitions of standard GEOS locations. Access to these addresses is optimized by 60cc65 to simple <tt/lda/ and <tt/sta/. Don't be afraid to use C syntax. 61 62<sect1>Requirements 63<p> 64You don't need a C64 or C128 for development. The only hardware requirement is a PC capable of 65running cc65. You do however need C64 or C128 emulator and GEOS disk images (.d64) to test your 66programs. 67 68The 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> 86VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only 87needs 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> 93I want to thank Uz for his cc65 package, Alexander Boyce for his excellent GEOS Programmer's 94Reference Guide and BSW for GEOS. 95<p> 96GEOSLib is covered by the same license as cc65. You can find the whole text 97among documentation. I would really appreciate if you would like to send me 98your comments, suggestions, questions, changes, bug reports etc. I will also 99appreciate if you will just give me a sign that you are using GEOSLib - not 100especially something big and important, mail me even if you are just playing 101with it. 102<p> 103You can send postcards with hellos to: 104<p> 105Maciej Witkowiak, ul. Slowackiego 6/57, 77-400 ZLOTOW 106<p> 107POLAND 108<p> 109e-mail: <tt/ytm@elysium.pl/ 110 111<sect>What do you have and what to do with it? 112<p> 113This chapter describes some rules you ought to obey, and how to use GEOSLib. 114 115<sect1>Usage 116<p> 117Apart from this file, which merely describes only standard GEOS library 118functions, you should read the <tt/grc65/ (GEOS resource compiler) documentation. 119There is information about necessary resource files (each GEOS application 120needs at least one) and the build process - what should be done and in what 121order. Please also read the cc65 documentation on how to compile C, assembler 122and link everything together. 123<p> 124All in all, you just need to place 125<tscreen><verb> 126#include <geos.h> 127</verb></tscreen> 128at the top of your source. 129<p> 130As a general rule read the sources of the example programs and read the headers. 131These are the most reliable sources of knowledge ;-). You will also find there 132many C macros representing various arguments passed to the functions. Please use 133them. You will find your sources easier to understand, and it will be easier 134to find bugs. 135<p> 136All types used in GEOSLib are <tt/unsigned/. 137<p> 138Screen coordinates are given in pixels unless stated differently. 139 140<sect1>Notes on style 141<p> 142Contrary to a typical GEOS assembly program which has a main function called after loading that 143setups the screen, menus, icons etc. exiting from the <tt/main/ function in C is equivalent to 144calling <tt/exit()/. These two are the only safe methods of terminating applications. DO NOT 145USE <tt/EnterDeskTop/! Your data may be lost as library destructors and functions registered 146with <tt/atexit/ are not called. 147<p> 148For GEOS GUI applications the recommended program structure is to have everything initialized 149in the <tt/main/ function and at the end of it a call to the <tt/MainLoop()/ function. WARNING! This 150function never returns, any code between <tt/MainLoop();/ and the end of <tt/main/ will not 151be executed. You have to call <tt/exit()/ explicitly somewhere in your code (e.g. in a menu 152handler or via DialogBox action). 153<p> 154Whenever possible use definitions from <tt/gsym.h/. The resulting code is translated by cc65 into 155series of <tt/lda/ and <tt/sta/, so you can't do it better :-). 156<p> 157Don't hesitate to use library functions. Everything was written with size and speed in mind. In 158fact many calls are just redirections to the GEOS Kernal which results in a simple <tt/jsr/. 159<p> 160The <tt/main/ function receives the standard <tt/argc/ and <tt/argv/ parameters. There are 161always either 1 or 3 parameters. The DOS application name is always set as <tt/argv[0]/. 162If present, <tt/argv[1]/ and <tt/argv[2]/ will be set to the data filename and data diskname (it only 163works if the user double-clicks on a data file associated with your application). Note that it is up 164to your application to determine which of the available (up to four) disk drives has the disk 165with given diskname inside. If this fails your program should ask to insert the proper disk into 166one of available drives. 167<p> 168You might wonder why I have chosen a sometimes weird order of arguments in functions. I just 169wanted 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> 172Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in 173ANSI. 174<p> 175It is possible to use dynamically loaded modules, three such modules are provided: 176A GEOS TGI driver, a GEOS EMD driver (for VDC extended memory) and a GEOS JOY driver. 177Just make sure that their filenames appear UPPERCASE in DeskTop. There are no more special 178recommendations, read the cc65 documentation about modules and the demo programs source code. 179 180<sect>Library Functions 181<p> 182Functions here are sorted more or less in the way they appear in the header files. This way I am able 183to keep functions covering similar tasks near each other. All function names are identical to those 184from the <tt/geosSym/ file provided with the GeoProgrammer package. Only my extensions to <tt/geosSym/ 185are covered by new names, but I tried to keep them in the naming convention. 186 187<sect1>Graphics 188<p> 189This 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> 195This function is intended for use by GEOS 128 only, and will exhibit undefined behavior on the 196C64. It will toggle between the 40 column screen mode and the 80 column screen mode. Many C128 GEOS 197programs 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> 203This function sets the current pattern to the given. There are 32 different patterns in GEOS. You can 204see them together in the filling box in GeoPaint. 205 206<sect2>GraphicsString 207<p> 208<tt/void GraphicsString (char *myGString)/ 209<p> 210One of the more powerfull routines of GEOS. This function calls other graphic functions depending 211on the given command string. See the structures chapter for a more detailed description. 212 213<sect2>Rectangle functions 214<p> 215Parameters to those functions are grouped in the <tt/struct window drawWindow/. To speed up things and 216reduce overhead this structure is bound to zero page locations, where all rectangle functions 217expect 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 219using graphics functions. In other cases you should keep your data in separate <tt/struct window/ 220and 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> 226This function only copies the contents of <tt/myWindow/ into the system area of <tt/drawWindow/. Use it 227if 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> 233This draws on screen a rectangle filled with the current pattern. 234 235<sect3>FrameRectangle 236<p> 237<tt/void FrameRectangle (char pattern)/ 238<p> 239This 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> 245Just 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> 253These two functions are for copying parts of the screen to (<tt/Imprint/) and from (<tt/Recover/) the 254backbuffer 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 256destroying the menu. 257 258<sect2>Line Functions 259<p> 260The GEOS drawing package is optimized so there are different functions for drawing vertical and 261horizontal lines. 262 263<sect3>HorizontalLine 264<p> 265<tt/void HorizontalLine (char pattern, char y, unsigned xStart, unsigned xEnd)/ 266<p> 267This function draws a horizontal line using the given pattern. Note that <tt/pattern/ is not a pattern 268number 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> 274There is only a horizontal version. 275 276<sect3>RecoverLine 277<p> 278<tt/void RecoverLine (char y, unsigned xStart, unsigned xEnd)/ 279<p> 280This function recovers a single line. It is utilized by <tt/RecoverRectangle/. See its description 281for more details. 282 283<sect3>VerticalLine 284<p> 285<tt/void VerticalLine (char pattern, char yStart, char yEnd, unsigned x)/ 286<p> 287This function draws a vertical line using the given pattern. Note that <tt/pattern/ is not a pattern 288number 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> 294The <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 297screen. If <tt/mode/ is <tt/DRAW_COPY/ then the line is copied from/to back/frontbuffer, according to 298the <tt/dispBufferOn/ setting. 299 300<sect2>Point Functions 301<p> 302The parameters to these two functions are passed by a pointer to an own <tt/struct pixel/ filled with 303proper values. 304 305<sect3>DrawPoint 306<p> 307<tt/void DrawPoint (char mode, struct pixel *myPixel)/ 308<p> 309Depending on <tt/mode/ (see <tt/DrawLine/) draws/erases/copies a single point 310on the screen. 311 312<sect3>TestPoint 313<p> 314<tt/char TestPoint (struct pixel *myPixel)/ 315<p> 316This 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> 324This 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> 330Same as <tt/PutChar/ except the fact that you can output a whole <tt/NULL/-terminated string. 331See <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> 338This function converts <tt/value/ to its decimal representation and outputs it to the screen. 339The <tt/parameter/ is the field width in pixels (range 1-31) and the mode bits. Depending on them 340the string can be filled with zeroes (the string is always 5 characters long) or not and left or right 341justified 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> 349This function returns the real width (in pixels) of the given character with the current font. It can be used 350for 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> 356This function forces GEOS to use the given font. <tt/myFont/ should be casted from a 357pointer 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> 363This function forces GEOS to use the built-in BSW font. 364 365<sect2>Bitmap handling 366<p> 367I'm not quite sure how these functions are working (except <tt/BitmapUp/) so you should 368probably look into the library sources and compare it with your knowledge. Please let me know 369if something is wrong or broken. 370 371<sect3>BitmapUp 372<p> 373<tt/void BitmapUp (struct iconpic *myPic)/ 374<p> 375This 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 377structure. 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> 383This function acts similar to <tt/BitmapUp/ but you can also define which parts of the bitmap are 384to be drawn - you give the number of columns (8-pixel) to skip on the right and left of the bitmap, 385and 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> 392Similar to the previous one with some extension. <tt/proc1/ is called before reading a byte (it 393returns in .A the next value), and <tt/proc2/ is called every time the parser reads a byte which is 394not a piece of a pattern (byte of code greater than 219). Both procedures should be written 395separately in assembler and declared as <tt/__fastcall__/ returning char. 396 397<sect1>Menus and Icons 398<p> 399Here you will find information about functions related with menus and icons. 400 401<sect2>Menus 402<p> 403Menus are essential for a GUI. GEOS can handle only one menu at a time, but each menu can call 404another one, which results in a submenu tree. There can be up to 8 menu levels, each one with up 405to 32 items. 406<p> 407Menus 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 409use <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> 415This function initializes the GEOS menu processor and exits. See <tt/DoMenu structure/ for more 416information about it. Know that many GEOS applications just initialize the screen, menu and 417exit 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> 423This simply redraws the menu at the lowest level. It works like calling <tt/DoMenu/ again with 424the same parameters. 425 426<sect3>RecoverMenu 427<p> 428<tt/void RecoverMenu (void)/ 429<p> 430This 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> 436This calls <tt/RecoverMenu/ and erases all menus from the screen. Then the menu level is 437set to 0 (topmost). 438 439<sect3>DoPreviousMenu 440<p> 441<tt/void DoPreviousMenu (void)/ 442<p> 443This functions causes the menu processor to go back one menu level. You should use it in menu 444handler code to have the screen clean. 445 446<sect3>GotoFirstMenu 447<p> 448<tt/void GotoFirstMenu (void)/ 449<p> 450This one jumps back to the topmost menu. If there is only a menu and one submenu it works the 451same as <tt/DoPreviousMenu/. 452 453<sect2>Icon Functions 454<p> 455Icons are working similar to menus except the fact that there is only one level. Icons are 456defined as a screen area filled with a bitmap, but if you would setup icons and erase the 457screen they would still be active and clicking in the place where formerly an icon was would cause 458an effect. Similarly if you would setup icons and then turn them off with <tt/ClearMouseMode/ 459the bitmap would still be on the screen but clicking on it would not cause any action. 460There is only one, but powerful icon function. 461 462<sect3>DoIcons 463<p> 464<tt/void DoIcons (struct icontab *myIconTab)/ 465<p> 466This function initializes all icons that are present on the screen at once. For more information 467look at the <tt/Icons/ chapter in this manual. 468 469<sect1>DialogBoxes 470<p> 471This 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> 479This function returns one byte. It can be the value of one of six standard icons (see <tt/gdlgbox.h/) 480or whatever the closing routine passes. Register <tt/r0L/ also contains this value. 481<p> 482Read the structures chapter for the specs of the <tt/dialogString/. 483 484<sect3>RstrFrmDialogue 485<p> 486<tt/char RstrFrmDialogue/ 487<p> 488This function is called from within DoDlgBox event. It immediately closes the DialogBox and returns 489the owner ID (or whatever caller has in the .A register). 490 491<sect2>GEOSLib extensions 492<p> 493To simplify the usage of DoDlgBox from C I wrote some helper functions - wrappers for DoDlgBox, 494with predefined data. In one word - these are standard DialogBoxes you can see in almost every 495GEOS 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> 505These function show two lines of text in a standard-sized DialogBox. You can read the code of the 506pressed icon from the return value. E.g. for <tt/DlgBoxYesNo/ it can only be <tt/YES/ or <tt/NO/. 507You 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> 513This function prompts the user to enter a string of at most <tt/strlen/ characters. It is returned 514in <tt/string/. The two given lines of text are shown above the input line. Please remember 515that there is also a <tt/CANCEL/ icon in the DialogBox and you should test if user confirmed his 516input or gave up. The <tt/string/ is also shown so you can place a default input there or remember 517to place <tt/NULL/ at start. 518 519<sect3>DlgBoxFileSelect 520<p> 521<tt/char DlgBoxFileSelect (char *class, char filetype, char *filename)/ 522<p> 523This routine is the standard file selector. It can return <tt/OPEN/, <tt/CANCEL/ or disk error 524on reading the directory or opening the disk. 525There 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 527empty (<tt/NULL/ at the start), then all files with given filetype will be shown. 528<p> 529At 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> 536This function is a more general one. It works very much like <tt/printf/ in a 537box. The only difference is the <tt/mode/ parameter which allows for placing 538default icons (see <tt/gdlgbox.h/ for list of possible <tt/MB_/ values). 539Any too wide text will be clipped to the size of the default window. If <tt/mode/ 540is invalid or equal to <tt/MB_EMPTY/ then the window will be closed 541after a click. Otherwise the user must choose an icon. 542<p> 543Note: Use it if you really need (or if you use it in many places) as 544it adds quite amount of code to your program. 545<p> 546Note: the formatted text <em/cannot exceed/ 255 bytes in length, there is no check 547for that. 548 549<sect1>Mouse, Sprites and Cursors 550<p> 551You will find here functions related to sprite and mouse drawing and handling. 552 553<sect2>Mouse related functions 554<p> 555These cover the mouse - as a general pointing device, but expect users to utilize as different devices 556as 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> 562This function initializes the mouse vectors - <tt/mouseVector/ and <tt/mouseFaultVec/, and then 563calls <tt/MouseUp/. 564 565<sect3>ClearMouseMode 566<p> 567<tt/void ClearMouseMode (void)/ 568<p> 569This function disables all mouse activities - icons and menus stop to respond to mouse events, 570but 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> 578The first function turns the mouse pointer on. It appears on the next IRQ. The second one does 579the 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> 585This function tests if the mouse pointer is actually in the given range of the screen. See <tt/gsprite.h/ for 586a description of the bits in the return values - they describe the position in detail. 587 588<sect2>Sprites 589<p> 590You are free to use any of the eight sprites, but keep in mind that sprite 0 is actually the mouse 591pointer and sprite 1 can be overwritten when using a text prompt. You don't have to worry about 59240/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> 598This function initializes the sprite data. <tt/mySprite/ is a 63-byte table with bitmap data, which 599is copied to the system sprite area (at <tt/sprpic/ - see <tt/gsym.h/). Hardware sprite registers are 600not 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> 606This function positions the sprite on the screen. The given coordinates are screen ones - they are 607converted to sprite coordinates by GEOS. Due to this you cannot use this function to position your 608sprite 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> 616These 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> 624This function initializes sprite 1 for a text prompt with given <tt/height/. This parameter can be in 625range 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> 633The first function places a text prompt in given place and enables blinking. 634The second one is pretty self-explanatory. 635 636<sect3>GetNextChar 637<p> 638<tt/char GetNextChar (void)/ 639<p> 640This 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) 642key. See <tt/gsprite.h/ for the list of them. 643 644<sect1>Disk 645<p> 646This chapter covers rather low-level disk routines. You should use them with care, because 647you may easily corrupt data on disks. Also remember that contemporary GEOS supports many various 648devices and sticking to 1541 track layout (e.g. expecting the directory on track 18) might be 649dangerous. 650<p> 651For some purposes you might consider using the <tt/dio.h/ interface to disk access. It is native. 652<p> 653All GEOS disk functions return an error code in the X register. In some cases this is returned by the 654GEOSLib function (if its type is <tt/char/), but in all cases the last error is saved in the <tt/__oserror/ 655location. If it is nonzero - an error occured. See <tt/gdisk.h/ for the list of possible errorcodes. 656You need to include <tt/errno.h/ to get <tt/__oserror/, together with the standard <tt/errno/. The 657latter gives less verbose, but still usable information and can be used with <tt/strerror/. 658Probably you will get more information using <tt/_stroserror/ in a similar way. 659<p> 660For passing parameters use almost always a pointer to your data e.g. <tt/ReadBuff (&myTrSe)/. 661 662<sect2>Buffer functions 663<p> 664These 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> 672These 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> 680These two functions read a single block directly to the 256 byte array placed at <tt/buffer/. 681The difference between them is that <tt/GetBlock/ initializes TurboDos in the drive if it was not 682enabled. <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> 692Similar to previous but needed for writing the disk. <tt/VerWriteBlock/ verifies the data after 693writing. In case of an error five tries are attempted before an error code is returned. 694 695<sect2>Directory header 696<p> 697The functions described here operate on <tt/curDirHeader/ where the current disk header is stored. 698On 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> 704This function fills the given character string with the name of current disk. It is converted to C 705standard - the string is terminated with <tt/NULL/ character instead of code 160 as in Commodore DOS. 706Note 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> 714These functions read and write the directory header. You should use <tt/GetDirHead/ before 715using any functions described below, and you should use <tt/PutDirHead/ to save the changes on the 716disk. Otherwise they will be lost. Operating area is the <tt/curDirHead/. 717 718<sect3>CalcBlksFree 719<p> 720<tt/unsigned CalcBlksFree (void)/ 721<p> 722This 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> 729This functions checks <tt/curDirHead/ for the GEOS Format identifier. It returns either true or false, 730and 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> 736This function initializes disk for use with GEOS. It sets the indicator in directory header and 737allocates a sector for the directory of border files. You don't need to initialize the disk before 738using. 739 740<sect3>FindBAMBit 741<p> 742<tt/char FindBAMBit (struct tr_se *myTrSe)/ 743<p> 744This function returns the bit value from the BAM (Block Allocation Map) for the given sector. The bit is 745set if the sector is free to use. The returned value is always zero if the sector is already allocated. 746In fact, this function could be used in a following way: 747<tscreen><verb> 748#define BlockInUse FindBAMBit 749... 750if (!BlockInUse(&myTrSe)) { 751... block not allocated ... 752} 753</verb></tscreen> 754<p> 755Anyway, 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[&rsqb, unsigned length)/ 760<p> 761<tt/char NxtBlkAlloc (struct tr_se *myTrSe, struct tr_se output[&rsqb, unsigned length)/ 762<p> 763Both functions allocate enough disk sectors to fit <tt/length/ bytes in them. You 764find the output in <tt/output/ which is a table of <tt/struct tr_se/. The last entry will have the 765track equal to 0 and sector equal to 255. The simplest way of using them is to use 766predefined space in the GEOS data space and pass <tt/fileTrScTab/, which is a predefined table. 767<p> 768The difference between those two is that <tt/NextBlkAlloc/ starts allocating from the given sector, 769and <tt/BlkAlloc/ starts from the first nonused sector. 770<p> 771You 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> 777Simply 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> 783This function finds the first free sector starting from given track and sector and allocates it. 784It might return the same argument if the given block is not allocated. I wanted it to be type 785clean, but this made the usage a bit tricky. To assign a value to your own <tt/struct tr_se/ you have to 786cast both variables to <tt/unsigned/. E.g. 787<tscreen><verb> 788struct tr_se myTrSe; 789... 790(unsigned)myTrSe=(unsigned)SetNextFree(&otherTrSe); 791</verb></tscreen> 792<p> 793In this example <tt/otherTrSe/ can be replaced by <tt/myTrSe/. 794<p> 795Note: you <em/must/ use casting to have the correct values. 796 797<sect2>Low-level disk IO 798<p> 799Functions described here are more usable in Kernal or drivers code, less common in applications, 800but 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> 810These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit 811more usable. <tt/EnterTurbo/ enables TurboDos unless it is already enabled. If not, then you will 812have to wait a bit to transfer the TurboDos code into disk drive RAM. <tt/ExitTurbo/ disables TurboDos. 813This is useful for sending some DOS commands to a drive e.g. for formatting. Note that before any 814interaction 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, 817but 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> 824This function changes the device number of the current device (in fact drives only) to the given one. It is 825usable for swapping drives. There's no check if the given <tt/newDevice/ already exist, so if you want 826to change the logical number of drive 8 to 9 and you already have a drive number 9 then GEOS will probably 827hang on disk access. Use safe, large numbers. Note that the safe IEC range is 8-30. 828 829<sect2>Disk Initialization 830<p> 831GEOS 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> 836This function initializes everything for a new disk. It loads and enables TurboDos if needed. 837Then the disk is initialized with <tt/NewDisk/. Next, <tt/GetDirHead/ initializes <tt/curDirHead/. 838Disk names are compared and if they differ then the disk cache on REU is cleared. Finally the format is 839checked 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> 845This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed. 846 847<sect1>Files 848<p> 849This section covers the GEOS file interface. 850 851<sect2>Directory handling 852<p> 853The 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> 861These two functions are best suited for scanning the whole directory for particular files. Note that 862the returned filehandles describe all file slots in the directory - even those with deleted files. 863The return value can be obtained by casting both sides to <tt/unsigned/ - as in the <tt/SetNextFree/ 864function or read directly after a call to those two functions from <tt/r5/. The current sector number 865is 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> 871This 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 874other 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> 880This function scans the directory and fills a table at <tt/buffer/ with <tt/char [17]/ 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 882header. Class matches if the given string is equal or shorter than that found in the file's header block. 883If 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 886equal to <tt/17 * fMaxNum/. This function returns the number of found files, ranging from 0 to number 887passed 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> 893This 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> 899I think it is obvious... 900 901<sect3>GetFHdrInfo 902<p> 903<tt/char GetFHdrInfo (struct filehandle *myFile)/ 904<p> 905This function loads the file header into the <tt/fileHeader/ buffer. Using after e.g. <tt/FindFile/ 906you can pass the address of <tt/dirEntryBuf/. 907 908<sect2>Common and SEQ structure 909<p> 910Functions described here are common for SEQ and VLIR structures because the arguments passed are the 911starting 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> 917This 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 919address is taken from the file header. If it is zero, then the file is only loaded. Only the first chain 920from VLIR files is loaded. If <tt/flag/ has bit 0 set then the load address is taken from <tt/loadaddr/ 921and not from the file header. In this case <tt/APPLICATION/ files will be only loaded, not executed. 922This 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/ 924thus 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> 930This 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> 937This function returns the next byte from a file. Before the first call to it you must load <tt/r5/ 938with <tt/NULL/, <tt/r4/ with the sector buffer address and <tt/r1/ with the track and sector of the 939first block of a file. 940Remember to not modify <tt/r1/, <tt/r4/ and <tt/r5/. These registers must be preserved between 941calls to <tt/ReadByte/. 942<p> 943The returned value is valid only if there was no error. The end of file is marked as <tt/BFR_OVERFLOW/ 944in <tt/__oserror/, this is set when trying to read one byte after the end of file, in this case the 945returned 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 952structure. All you need to do is to place the data in the proper place and prepare a header which will 953contain all information about a file. The <tt/skip/ parameter says how many directory pages you 954want to skip before searching for a free slot for the directory entry. In most cases you will put 955<tt/0/ there. 956<p> 957You have to declare a <tt/struct fileheader/ and fill it with proper values. There is only one 958difference - the first two bytes which are a link to a nonexistent next sector are replaced by a 959pointer to the DOS filename of the file. 960<p> 961When saving sequential files the two most important fields in <tt/struct fileheader/ are <tt/fileheader.load_address/ 962and <tt/fileheader.end_address/. 963 964<sect3>FreeFile 965<p> 966<tt/char FreeFile (struct tr_se myTable[])/ 967<p> 968This 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> 974This function fills a <tt/struct tr_se/ table at <tt/buffer/ with the sector numbers for a chain of 975sectors starting with <tt/myTrSe/. You can pass such data (<tt/buffer/) to e.g. <tt/FreeFile/. 976 977<sect2>VLIR structure 978<p> 979Here is information about VLIR files (later called RecordFiles) and functions. 980<p> 981A VLIR structure file consists of up to 127 SEQ-like files called records. Each record is like one 982SEQ structure file. Records are grouped together, described by a common name - the VLIR file name and 983an own number. Each record pointed to by its number is described by the starting track and sector numbers. 984VLIR structures allow records to be empty (<tt/tr_se/ of such record is equal to <tt/{NULL,$ff}/), 985or even non-exist (<tt/{NULL,NULL}/). Any other numbers represent the starting track and sector of 986a particular file. 987<p> 988In GEOS there can be only one file opened at a time. Upon opening a VLIR file some information 989about it is copied into memory. You can retrieve the records table at <tt/fileTrScTab/ (table of 990128 <tt/struct tr_se/) and from <tt/VLIRInfo/ (<tt/struct VLIR_info/. 991E.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> 997This function finds and opens a given file. An error is returned if the file is not found or if it is not 998in VLIR format. Information in <tt/VLIRInfo/ is initialized. VLIR track and sector table is 999loaded at <tt/fileTrScTab/ and will be valid until a call to <tt/CloseRecordFile/ so don't modify it. 1000You 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> 1006This function calls <tt/UpdateRecordFile/ and clears internal GEOS variables. 1007 1008<sect3>UpdateRecordFile 1009<p> 1010<tt/char UpdateRecordFile (void)/ 1011<p> 1012This function will check the <tt/VLIRInfo.fileWritten/ flag and if it is set, then <tt/curDirHead/ is 1013updated along with size and date stamps in the directory entry. 1014 1015<sect3>PointRecord 1016<p> 1017<tt/char PointRecord (char recordNumber)/ 1018<p> 1019This function will setup internal variables (and <tt/VLIRInfo.curRecord/) and return the track and 1020sector of the given record in <tt/r1/. Note that the data may not be valid (if the record is non-existing 1021you 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> 1029These two work like <tt/PointRecord/. Names are self-explanatory. 1030 1031<sect3>AppendRecord 1032<p> 1033<tt/char AppendRecord (void)/ 1034<p> 1035This function will append an empty record (pair of 255,0) to the current VLIR track and sector 1036table. It will also set <tt/VLIRInfo.curRecord/ to its number. 1037 1038<sect3>DeleteRecord 1039<p> 1040<tt/char DeleteRecord (void)/ 1041<p> 1042This function will remove the current record from the table, and move all current+1 records one place 1043back (in the table). Note that there's no BAM update and you must call <tt/UpdateRecordFile/ to 1044commit changes. 1045 1046<sect3>InsertRecord 1047<p> 1048<tt/char InsertRecord (void)/ 1049<p> 1050This function will insert an empty record in place of <tt/VLIRInfo.curRecord/ and move all following 1051records in the table one place forward (contents of <tt/VLIRInfo.curRecord/ after a call to <tt/InsertRecord/ 1052can 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> 1060This 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> 1065The functions covered in this section are common for the whole C world - copying memory parts and 1066strings is one of the main computer tasks. GEOS also has an interface to do this. These functions 1067are replacements for those like <tt/memset, memcpy, strcpy/ etc. from standard libraries. 1068If you are dealing with short strings (up to 255 characters) you should use these functions 1069instead of standard ones, e.g. <tt/CopyString/ instead of <tt/strcpy/. It will work faster. 1070<p> 1071However some of them have slightly different calling conventions (order of arguments to be specific), 1072so please check their syntax here before a direct replacement. 1073<p> 1074Please note that the memory areas described here as <em/strings/ are up to 255 characters (without 1075counting 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> 1081This function copies the string from <tt/src/ to <tt/dest/, until it reaches <tt/NULL/. The <tt/NULL/ 1082is also copied. 1083 1084<sect2>CmpString 1085<p> 1086<tt/char CmpString (char *s1, char *s2)/ 1087<p> 1088This function compares the strings <tt/s1/ to <tt/s2/ for equality - this is case sensitive, and both 1089strings 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> 1097These two are similar to <tt/CopyString/ and <tt/CmpString/ except the fact, that you provide 1098the length of the copied or compared strings. The strings can also contain several <tt/NULL/ 1099characters - they are not treated as delimiters. 1100 1101<sect2>CRC 1102<p> 1103<tt/unsigned CRC (char *src, unsigned length)/ 1104<p> 1105This function calculates the CRC checksum for the given memory range. I don't know if it is 1106compatible 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> 1114Both 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 1116r2L/ 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> 1122This functions copies one memory region to another. There are checks for an overlap and the 1123non-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> 1130This function allows to initialize multiple memory locations with single bytes or strings. 1131This 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> 1144These functions are the interface to a REU - Ram Expansion Unit. I think that they are self-explanatory. 1145You can check for REU presence by taking the value of <tt/ramExpSize/. You have to do it before 1146using any of these functions. 1147 1148<sect1>Processes and Multitasking 1149<p> 1150Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions 1151called in specified intervals and you can put the main program to sleep without disturbing other 1152tasks and making the user interface unresponsive. 1153 1154<sect2>InitProcesses 1155<p> 1156<tt/void InitProcesses (char number, struct process *processTab)/ 1157<p> 1158This is the main initialization routine. After calling it processes are set up, but not 1159enabled. 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> 1165A single task is described by an entry in <tt/processTab/, it contains two values - a <tt/pointer/ to 1166the task function and a number of <tt/jiffies/ which describe the delay between calls to task. On PAL 1167systems there are 50 jiffies per second, while on NTSC there are 60. 1168<p> 1169The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and 1170if <tt/processTab/ would be too large it would overwrite existing data in GEOS space. 1171<p> 1172There's one important thing - the last entry in <tt/processTab/ has to be <tt/NULL,NULL/, so the 1173maximum size of <tt/processTab/ is equal to 21. 1174<p> 1175See 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> 1183These two functions start the task counter. <tt/RestartProcess/ should be called for each process 1184after <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. 1197It 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. 1208This 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> 1214This function is a multitasking sleep - the program is halted, but it doesn't block other functions 1215e.g. callbacks from menus and icons. 1216The only argument here is the number of jiffies to wait until the app will wake up. It depends on the 1217video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). 1218If 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> 1227This function initializes some GEOS variables and mouse parameters. This is called on GEOS boot 1228up. 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> 1236These functions are called by some disk routines. You should call them only if you want to 1237do something with IO registers or call one of the Kernal ROM routines. Note that this is rather an 1238expensive way of turning off IRQs and enabling IO. 1239 1240<sect2>MainLoop 1241<p> 1242<tt/void MainLoop (void)/ 1243<p> 1244Returns control to the system. Any code between call to <tt/MainLoop/ and the end of current 1245function will never be executed. When in <tt/MainLoop/ the system waits for your action - using 1246icons, keyboard or menus to force some specific action from the program. You have to define 1247proper handlers before that. 1248 1249<sect2>EnterDeskTop 1250<p> 1251<tt/void EnterDeskTop (void)/ 1252<p> 1253This is an alias for <tt/exit(0)/ so you will never burn yourself. Anyway, you should not 1254use 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> 1261This one is another way of terminating an application - forcing GEOS to shutdown and exit to BASIC. 1262I 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 1265so it is quite unsafe way to terminate your program. 1266 1267<sect2>Panic 1268<p> 1269<tt/void Panic (void)/ 1270<p> 1271This calls system's <tt/Panic/ handler - it shows a dialog box with the message 1272<tscreen><verb> 1273System error at:xxxx 1274</verb></tscreen> 1275where <tt/xxxx/ is last known execution address (caller). By default this is bound to the <tt/BRK/ 1276instruction, but it might be usable in debugging as kind of <tt/assert/. (Note that <tt/assert/ 1277is available as a separate function and will give you more information than that). 1278<p> 1279The system is halted after a call to <tt/Panic/ which means that library destructors will not be 1280called and some data may be lost (no wonder you're panicking). 1281 1282<sect2>CallRoutine 1283<p> 1284<tt/void CallRoutine (void *myFunct)/ 1285<p> 1286This is a system caller routine. You need to provide a pointer to a function and it will be immediately 1287called, unless the pointer is equal to <tt/NULL/. This is the main functionality of this function - 1288you don't need to check if the pointer is valid. 1289 1290<sect2>GetSerialNumber 1291<p> 1292<tt/unsigned GetSerialNumber (void)/ 1293<p> 1294This function returns the serial number of the system. It might be used for copy-protection. 1295However, 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> 1301This function returns a random number. It can be also read from <tt/random/ e.g. 1302<tscreen><verb> 1303a=random; 1304</verb></tscreen> 1305but 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> 1308Note that this is not the same as the <tt/rand/ function from the standard library. <tt/GetRandom/ 1309will 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 1311same sequence of values. 1312 1313<sect2>SetDevice 1314<p> 1315<tt/void SetDevice (char device)/ 1316<p> 1317This 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 1319new 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> 1325This 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> 1332This function returns the PAL/NTSC flag combined (by logical OR) with the 40/80 columns flag. This is 1333not the best way to check if the screen has 40 or 80 columns since a PAL/NTSC check is always 1334performed and it can take as long as a full raster frame. If you just want to know if the 1335screen has 40 or 80 columns use the expression <tt/graphMode & 0x80/ which returns <tt/0/ for 133640 columns and <tt/0x80/ for 80 columns. Remember that this value can be changed during 1337runtime. It is unclear if this will work for GEOS 64 so you probably do not want to test 1338anything if not running under GEOS128. Use <tt/get_ostype/ to check it. Read <tt/gsys.h/ for 1339definitions of the returned values. 1340 1341<sect>Library Structures 1342<p> 1343To simplify usage and optimize passing parameters to functions I have declared several structures 1344which describe the most common objects. Some of these structures are bound to static addresses in 1345the GEOS data space (<tt/$8000-$8fff/), so you can use their fields directly in an optimized way. 1346Please see <tt/gsym.h/ to find them. All structures are defined in <tt/gstruct.h/ and you may 1347find also some comments there. 1348 1349<sect1>Graphics Structures 1350 1351<sect2>pixel 1352<p> 1353A simple structure describing a point on the screen. 1354 1355<sect2>fontdesc 1356<p> 1357This structure describes a font in one pointsize. There is the current font - <tt/struct fontdesc/ 1358bound 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 - 1360somewhere. At the start of this area you already have all data for <tt/fontdesc/ so you can 1361pass a pointer to the load address of that pointsize to <tt/LoadCharSet/. (Note that although 1362it has 'Load' in the name, that function loads only GEOS internal data structures, not data 1363from disk). 1364 1365<sect2>window 1366<p> 1367This widely used structure holds the description of a region of the screen. It describes the top-left and 1368bottom-right corners of a window. 1369 1370<sect2>iconpic 1371<p> 1372Maybe 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 1374a bitmap on the screen. The bitmap has to be encoded - if you have some non-GEOS bitmaps simply 1375convert them to Photo Scraps - this is the format used by all GEOS bitmap functions - <tt/DoIcons/ 1376too. 1377 1378<sect1>Icons 1379<p> 1380These structures describe click boxes (icons) that can be placed on screen or in a dialog box. 1381 1382<sect2>icondef 1383<p> 1384This 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> 1388This is the toplevel description of icons to be placed and enabled on the screen. This structure 1389has 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[&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> 1402This simple structure holds the track and sector number of something. Do not expect the track to be 1403in range 1-35, as GEOS can support many various and weird devices. For example my C128 256K 1404expansion is utilized as RAMDisk with a layout of 4 tracks of 128 sectors each. However assuming that 1405a track number equal to 0 is illegal might be wise. 1406 1407<sect2>f_date 1408<p> 1409This is a placeholder for a file datestamp. This structure is also present in <tt/struct filehandle/. 1410GEOS is not Y2K compliant, so if the current file has in <tt/filehandle.date.year/ a value less than 86 1411you can safely assume that it is e.g. 2004 and not 1904. 1412 1413<sect2>filehandle 1414<p> 1415This is the main file descriptor. It is either an entry in the directory (returned from file functions) 1416or its copy in <tt/dirEntryBuf/. This is optimized so you can safely get to the file's year e.g. 1417by testing <tt/dirEntryBuf.date.year/ - it will be compiled to simple <tt/LDA, STA/. 1418 1419<sect2>fileheader 1420<p> 1421This structure holds the fileheader description. You can load a file's header into the <tt/fileHeader/ 1422fixed area using <tt/GetFHdrInfo/. (note that <tt/fileHeader/ is a place in memory while 1423<tt/fileheader/ is a structure). 1424You will also need your own fileheader for <tt/SaveFile/. 1425 1426<sect1>System Structures 1427 1428<sect2>s_date 1429<p> 1430This structure is defined only for <tt/system_date/. It is slightly different from <tt/f_date/ 1431so 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/ 1433pair. 1434 1435<sect2>process 1436<p> 1437You should declare a table of that type to prepare data for <tt/InitProcesses/. The maximum number 1438of processes is 20, and the last entry has to be equal to <tt/{NULL,NULL}/, so this table may hold 1439only 21 entries. The first member of this structure (<tt/pointer/) holds the pointer to the called 1440function (void returning void), you will probably have to cast that pointer into <tt/unsigned int/. 1441The second field <tt/jiffies/ holds the amount of time between calls to that function. 1442On PAL systems there are 50 jiffies per second, while NTSC have 60 of them. 1443 1444<sect1>A few things in detail... 1445<p> 1446GEOSLib uses cc65 non-ANSI extensions to easily initialize data in memory. This is done with a 1447kind of array of unspecified length and unspecified type. Here is how it works: 1448<tscreen><verb> 1449void example = { 1450 (char)3, (unsigned)3, (char)0 }; 1451</verb></tscreen> 1452Which 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> 1459As you see this way it is possible to define data of any type in any order. You must remember to 1460cast 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 1465are just initializing the screen and menu and returning to <tt/MainLoop/. In GEOSLib it is the same as 1466returning from <tt/main/ function without using <tt/exit(0)/. 1467<p> 1468A menu is described by two types of data - menu descriptors and menu items. A descriptor contains 1469information about the following menu items, and items contain names of entries and either 1470pointers to functions to execute or, in case of nested menus, pointers to submenu descriptors. 1471Note that submenu descriptor can be top-level descriptor, there's no difference in structure, 1472just in the content. 1473<p> 1474Here is how a single descriptor looks like: 1475<tscreen><verb> 1476void myMenu = { 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> 1484This 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 }; 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 1494can 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> 1500Both of them can be ORed with <tt/DYN_SUB_MENU/ and then the <tt/pointer/ points to a function 1501which will return in <tt/r0/ the needed pointer (to function to execute or a submenu). 1502<p> 1503For creating nested menus (you can have at most 8 levels of submenus) you need to declare such 1504a 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 1509responsible for creating dialog boxes, that is windows which task is to interact with the user. 1510The format of the command string is following: 1511<tscreen><verb> 1512 (window size and position) 1513 (commands and parameters) 1514 NULL 1515</verb></tscreen> 1516There is a custom type defined for the command string: <tt/dlgBoxStr/. 1517 1518<sect3>Size and position 1519<p> 1520The first element can be specified in two ways - by using the default size and position or specifying 1521your own. The first case results in 1522<tscreen><verb> 1523const dlgBoxStr example = { 1524 DB_DEFPOS (pattern_of_shadow), 1525 ... // commands 1526 DB_END }; 1527</verb></tscreen> 1528And the own size and position would be: 1529<tscreen><verb> 1530const dlgBoxStr example = { 1531 DB_SETPOS (pattern, top, bottom, left, right) 1532 ... // commands 1533 DB_END }; 1534</verb></tscreen> 1535 1536<sect3>Commands 1537<p> 1538The next element of the <tt/DoDlgBox/ command string are the commands themselves. The first six commands are 1539default 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> 1546Note that the position is counted from top left corner of window, not entire screen and that the 'x' 1547position 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 1549which 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 1554where the address of the text is stored. This is useful for information windows where only the text content 1555is variable. Consider following: 1556<tscreen><verb> 1557char 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, &r15), 1562 ... 1563</verb></tscreen> 1564will 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 1568previous example and points to the location where the text is to be stored. Note that the contents of this 1569location 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 1576draws a file selection box and searches the current drive for files. Before the call to <tt/DoDlgBox/ you 1577must load <tt/r7L/ with the GEOS filetype of searched files and <tt/r10/ with the class text. In <tt/r5/ 1578you have to load a pointer to a <tt/char[17]/ where the selected filename will be copied. It works 1579like <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 1586boxes 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 1593predefined macros for all commands, names are self-explanatory, see them in <tt/ggraph.h/. The last 1594command has to be <tt/GSTR_END/. There is a custom type defined for the command string: <tt/graphicStr/. 1595<p> 1596Here is an example for clearing the screen: 1597<tscreen><verb> 1598const graphicStr example = { 1599 MOVEPENTO(0,0), 1600 NEWPATTERN(0), 1601 RECTANGLETO(319,199) 1602 GSTR_END }; 1603</verb></tscreen> 1604 1605<sect2>InitRam table 1606<p> 1607This type of data is used to initialize one or more bytes in different locations at once. The format is 1608the following: 1609<tscreen><verb> 1610void example = { 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 }; 1617</verb></tscreen> 1618 1619<sect2>Intercepting system vectors 1620<p> 1621It is possible to intercept events and hook into the GEOS Kernal using vectors. Here is a little example: 1622<tscreen><verb> 1623void_func oldVector; 1624 1625void NewVectorHandler(void) { 1626 // do something and at the end call the old vector routine 1627 oldVector(); 1628} 1629 1630void hook_into_system(void) { 1631 oldVector = mouseVector; 1632 mouseVector = NewVectorHandler; 1633} 1634 1635void remove_hook(void) { 1636 mouseVector = oldVector; 1637} 1638</verb></tscreen> 1639<p> 1640In your <tt/main/ function you should call <tt/hook_into_system()/ but <em/after/ all calls to the GEOS 1641Kernal (like <tt/DoMenu/, <tt/DoIcons/, etc.) - right before passing control to the <tt/MainLoop()/. 1642Be 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 1644you use and which vectors you altered. Unfortunately there is no exact list for GEOS 2.0, a complete 1645list for GEOS 1.x can be found in A. Boyce's Programmers' Reference Guide mentioned before. Most of the 1646information contained there should be still valid for GEOS 2.0. When calling a function that restores 1647the vector you should add a <tt/hook_into_system()/ call right after it. 1648<p> 1649It is critical to restore old vector values before exiting the program. If you have more than one 1650place where you call <tt/exit()/ then it might be worth to register <tt/remove_hook/ function to 1651be called upon exiting with <tt/atexit(&remove_hook);/ call. This way you will ensure that 1652such destructor will be always called. 1653<p> 1654That little example above intercepts <tt/mouseVector/. The <tt/NewVectorHandler/ function will be 1655called every time the mouse button changes status. Other important vectors you should know about 1656are: 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> 1665