From a8a8b5a89ec22d87133e5ed123bb6a2f08dc03f1 Mon Sep 17 00:00:00 2001 From: "ol.sc" Date: Sun, 15 Jan 2012 00:32:23 +0000 Subject: [PATCH] Added articles (last chapterstill todo). git-svn-id: svn://svn.cc65.org/cc65/trunk@5400 b7a2c559-68d2-44c3-8de9-860c34a00d81 --- doc/geos.sgml | 620 +++++++++++++++++++++++++------------------------- 1 file changed, 309 insertions(+), 311 deletions(-) diff --git a/doc/geos.sgml b/doc/geos.sgml index 1f1ed4ddc..17d72575a 100644 --- a/doc/geos.sgml +++ b/doc/geos.sgml @@ -19,36 +19,36 @@ useful for writing GEOS applications in general. Introduction

-As we all know that the best computers in the world are c64 and c128. They have their GUI too - -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 flexible and powerful system, which +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.

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. +package and my GEOSLib you are able to create GEOS applications in no time.

-GEOSLib supports a subset of standard cc65 libraries. Whenever possible native Kernal functions +GEOSLib supports a subset of the standard cc65 libraries. Whenever possible native Kernal functions are used (e.g. - - It is safe to use these standard includes and their contents: 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 Requirements

-You will not need c64 or c128 for development. The only hardware requirement is a PC capable of -running cc65. You will however need c64 or c128 emulator and GEOS image disks (.d64) to test your +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. The software needed: - - . VICE package contains + + . The VICE package contains the c1541 program that is able to convert/unconvert GEOS files to disk images. @@ -96,7 +96,7 @@ The software needed: VICE and cc65 are portable - they run on variety of platforms - DOS, Win32 and UNIX. GEOSLib only needs cc65.

-Legal

@@ -118,28 +118,28 @@ POLAND

e-mail: What have you got and what to do with it? +What do you have and what to do with it?

This chapter describes some rules you ought to obey, and how to use GEOSLib. Usage

Apart from this file, which merely describes only standard GEOS library -functions, you should read All in all, you just need to place #include <geos.h> -on top of your source. +at the top of your source.

-As a general rule read the sources of 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 functions. Please use +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.

@@ -149,14 +149,14 @@ Screen coordinates are given in pixels unless stated differently. Notes on style

-Contrary to typical GEOS assembly program which has a main function called after loading that -setups the screen, menus, icons etc. exiting from For GEOS GUI applications the recommended program structure is to have everything initialized -in Don't hesitate to use library functions. Everything was written with size and speed in mind. In -fact many calls are just redirections to GEOS kernal which results in simple The -You might wonder why I have chosen sometimes weird order of arguments in functions. I just -wanted to avoid unnecessary pushing and popping arguments from stack because cc65 can pass single +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 -Do not try to compile in strict ANSI mode. Library uses cc65 extensions which are not available in +Do not try to compile in strict ANSI mode. The library uses cc65 extensions which are not available in ANSI.

It is possible to use dynamically loaded modules, three such modules are provided: -GEOS TGI driver, GEOS EMD driver (for VDC extended memory) and GEOS JOY driver. +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 cc65 documentation about modules and demo programs source code. +recommendations, read the cc65 documentation about modules and the demo programs source code. Library Functions

-Functions here are sorted more or less in the way they appear in header files. This way I am able -to keep functions covering similar task near each other. All function names are identical to those -from Graphics

-This section covers drawing package of GEOS along with text output routines. +This section covers the drawing package of GEOS along with text output routines. SetPattern

-This function sets current pattern to given. There are 32 different patterns in GEOS. You can +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. GraphicsString @@ -210,35 +210,35 @@ see them together in the filling box in GeoPaint. One of the more powerfull routines of GEOS. This function calls other graphic functions depending -on given command string. See structures chapter for more detailed description of the structure of it. +on the given command string. See the structures chapter for a more detailed description. Rectangle functions

-Parameters to those functions are grouped in InitDrawWindow

-This function only copies contents of Rectangle

-This draws on screen rectangle filled with current pattern. +This draws on screen a rectangle filled with the current pattern. FrameRectangle

-This one draws frame with given bit pattern (not a pattern from GEOS palette). +This one draws a frame with the given bit pattern (not a pattern from the GEOS palette). InvertRectangle

@@ -252,56 +252,56 @@ Just as the name says...

-These two functions are for copying parts of the screen to (Line Functions

-GEOS drawing package is optimized so there are different functions for drawing vertical and +The GEOS drawing package is optimized so there are different functions for drawing vertical and horizontal lines. HorizontalLine

-This function draws horizontal line using given pattern - here it is a true bit pattern, not -pattern set by InvertLine

-There is only horizontal version. +There is only a horizontal version. RecoverLine

-This function recovers only one line. It is utilized by VerticalLine

-This function draws vertical line using given pattern. Note that DrawLine

-Point Functions

-Parameters to these two functions are passed by a pointer to own DrawPoint @@ -315,7 +315,7 @@ on the screen.

-This function tests if given pixel is set and returns Character and string output @@ -326,21 +326,21 @@ This function tests if given pixel is set and returns Actually this is a part of PutChar

-This function outputs single character using current style and font to screen. +This function outputs a single character using the current style and font to the screen. PutString

-Same as PutDecimal @@ -348,9 +348,9 @@ See This function converts Font Handling @@ -358,26 +358,26 @@ justified to given pixel. See -This function returns real width (in pixels) of given character with current font. It can be used -for counting the length of string on screen, allowing for indentation or justification. +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. LoadCharSet

-This function forces GEOS to use given font instead of own. UseSystemFont

-This function forces GEOS to use built-in BSW font. +This function forces GEOS to use the built-in BSW font. Bitmap handling

-I'm not quite sure how are these functions working (except BitmapUp @@ -385,8 +385,8 @@ if something is wrong or broken. This function unpacks the bitmap and places it on the screen - just as you set it in the -BitmapClip

@@ -402,8 +402,8 @@ and the number of rows to skip from the top if it. struct iconpic *myPic)/

Similar to the previous one with some extension. Menus and Icons @@ -412,34 +412,34 @@ Here you will find information about functions related with menus and icons. Menus

-Menus are essential for GUI. GEOS can handle only one menu at a time, but each menu can call -another one, which results in submenu tree. There can be up to 8 menu levels, each one with up +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.

-Menus are initialized with DoMenu

-This function initializes GEOS menu processor and exits. See ReDoMenu

-This simply redraws the menu at lowest level. It works like calling RecoverMenu

-This function erases current menu from the screen. It doesn't change the menu level. +This function erases the current menu from the screen. It doesn't change the menu level. RecoverAllMenus

@@ -452,23 +452,23 @@ set to 0 (topmost).

-This functions causes menu processor to go back one menu level. You should use it in menu +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. GotoFirstMenu

-This one jumps back to the topmost menu. If there is only menu and submenu it works the +This one jumps back to the topmost menu. If there is only a menu and one submenu it works the same as Icon Functions

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 are still active and clicking in the place where formerly an icon was will cause +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 DoIcons @@ -476,7 +476,7 @@ There is only one, but powerful icon function. This function initializes all icons that are present on the screen at once. For more information -look at DialogBoxes

@@ -488,21 +488,21 @@ This chapter covers the most powerful GEOS user interface function - -DialogBox returns one byte. It can be the value of one of six standard icons (see -Read structures chapter for the specs of the RstrFrmDialogue

-This function called from within DialogBox event immediately closes the DialogBox and returns +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). GEOSLib extensions

-To simplify usage of DoDlgBox from C I've wrote some help functions - wrappers for DoDlgBox, +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. @@ -514,18 +514,18 @@ GEOS application.

-These function show two lines of text in standard-sized DialogBox. You can read the code of -pressed icon from return value. E.g. for DlgBoxGetString

-This function prompts user for entering a string of at most DlgBoxFileSelect @@ -534,8 +534,8 @@ to place This routine is the standard file selector. It can return At present this file selector handles only first 16 files of given type and supports only one @@ -546,13 +546,13 @@ At present this file selector handles only first 16 files of given type and supp This function is a more general one. It works very much like -Note: use it if you really need (or if you will use it in many places) as +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.

Note: the formatted text Mouse related functions

-These cover mouse - as a general pointing device, but expect user to utilize as different devices -as digital or analog joystick, mouse, lightpen or koalapad (whatever it is). +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). StartMouseMode

-This function initializes mouse vectors - ClearMouseMode @@ -587,35 +587,35 @@ but they are not cleared from the screen.

-The first function turns the mouse pointer on. It will appear on next IRQ. The second one does -the opposite - it turns off the pointer, but its position is still updated by input driver. +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. IsMseInRegion

-This function tests if mouse pointer is actually in given range of screen. See Sprites

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 text prompt. You don't have to worry about -40/80 column issues because GEOS128 has pretty good sprite emulator for VDC. +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. DrawSprite

This function initializes the sprite data. PosSprite

-This function positions the sprite on the screen. Given coordinates are screen ones - they are +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. @@ -633,7 +633,7 @@ These two functions are responsible for making the sprite visible or not.

-This function initializes sprite 1 for text prompt with given PromptOn and PromptOff @@ -642,38 +642,38 @@ range 1-48.

-The first function places text prompt in given place and enables blinking. +The first function places a text prompt in given place and enables blinking. The second one is pretty self-explanatory. GetNextChar

-This function gets next character from the keyboard queue. If the queue is empty it returns -Disk

-This chapter covers slightly low-level disk routines. You should use them with care, because +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.

-For some purposes you might consider using -All GEOS disk functions return error code in X register. In some cases this is returned by -GEOSLib function (if its type is -For passing parameters use almost always pointer to your data e.g. Buffer functions

-These functions are taking single data sector (256 bytes) to read or write on a disk. +These functions take a single data sector (256 bytes) to read or write on the disk. ReadBuff and Writebuff

@@ -681,7 +681,7 @@ These functions are taking single data sector (256 bytes) to read or write on a

-These functions read and write sector placed at GetBlock and ReadBlock

@@ -689,8 +689,8 @@ These functions read and write sector placed at -These two functions are reading a single block directly at 256 byte array placed at PutBlock, WriteBlock, VerWriteBlock @@ -702,20 +702,20 @@ enabled. Similar to previous but needed for writing the disk. Directory header

-Functions described here are operating on GetPtrCurDkNm

-This function fills given character string with the name of current disk. It is converted to C -standard - string is terminated with GetDirHead and PutDirHead

@@ -723,7 +723,7 @@ Note that passed pointer must point to an array of at least 17 bytes.

-These functions are reading and writing the directory header. You should use -This function returns the number of free blocks on current disk. It is counted using data in +This function returns the number of free blocks on the current disk. It is counted using data in ChkDskGEOS

-This functions checks SetGEOSDisk

-This function initializes disk for use with GEOS. It sets indicator in directory header and +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. @@ -753,8 +753,8 @@ using.

-This function returns the bit value from BAM (Block Allocation Map) for given sector. The bit is -set if the sector is free to use. Returned value is always zero if the sector is already allocated. +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: #define BlockInUse FindBAMBit @@ -772,12 +772,12 @@ Anyway, I feel that this function is too low-level.

-Both functions are allocating enough disk sectors to fit the number of -The difference between those two is that You need to use -Simply deallocates a block in BAM. You need to update BAM with SetNextFree

@@ -794,7 +794,7 @@ Simply deallocates a block in BAM. You need to update BAM with 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 it made usage a bit tricky. To assign a value to own struct tr_se myTrSe; @@ -804,11 +804,11 @@ struct tr_se myTrSe;

In this example -Note: you Low-level disk IO

-Functions described here are more usable in kernal or drivers code, less common in applications, +Functions described here are more usable in Kernal or drivers code, less common in applications, but who knows, maybe someone will need them. EnterTurbo, ExitTurbo, PurgeTurbo @@ -819,13 +819,13 @@ but who knows, maybe someone will need them.

-These functions are interface to GEOS TurboDos feature which makes slow Commodore drives a bit +These functions are the interface to the GEOS TurboDos feature which makes slow Commodore drives a bit more usable. -This function changes logical number of current device (in fact drives only) with given one. It is -usable for swapping drives. There's no check if given Disk Initialization

-GEOS has two functions for initialization ('logging in' as they say on CP\M) the disk. +GEOS has two functions for initialization ('logging in' as they say on CP\M) of a disk. OpenDisk

This function initializes everything for a new disk. It loads and enables TurboDos if needed. Then the disk is initialized with NewDisk

-This function is similar to DOS command I. It clears REU cache and enables TurboDos if needed. +This function is similar to the DOS command I. It clears the REU cache and enables TurboDos if needed. Files

-This section cover GEOS file interface. +This section cover the GEOS file interface. Directory handling

-Functions described here are common for SEQ and VLIR structures. +The functions described here are common for SEQ and VLIR structures. Get1stDirEntry and GetNxtDirEntry

@@ -870,34 +870,33 @@ Functions described here are common for SEQ and VLIR structures.

-These two functions are best suited for scanning whole directory for particular files. Note that -returned filehandles describes all file slots in the directory - even those with deleted files. -The return value can be obtained by casting both sides to FindFile

-This function scans whole directory for the given filename. It returns either 0 (success) or 5 -(FILE_NOT_FOUND, defined in FindFTypes

-This function scans directory and fills a table at DeleteFile

@@ -915,13 +914,13 @@ I think it is obvious...

-This function loads the file header into Common and SEQ structure

-Functions described here are common for SEQ and VLIR structures because arguments passed are -starting track and sector which may point either to start of a chain for VLIR or data for SEQ. +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. GetFile

@@ -929,12 +928,12 @@ starting track and sector which may point either to start of a chain for VLIR or

This routine loads and runs a given file ReadFile

@@ -947,70 +946,70 @@ This function reads at most -This function returns next byte from a file. Before the first call to it you must load -Returned value is valid only if there was no error. End of file is marked as SaveFile

- You have to declare a -When saving sequential files two most important fields in FreeFile

-This function deallocates all sectors contained in passed table. +This function deallocates all sectors contained in the passed table. FollowChain

-This function fills a VLIR structure

-Here are informations about VLIR files (called later as RecordFile) and functions. +Here is information about VLIR files (later called RecordFiles) and functions.

-VLIR is a file which consists of up to 127 SEQ-like files called records. Each record is like one -SEQ structure file. Records are grouped together, described by common name - VLIR file name and -own number. Each record pointed by its number is described by starting track and sector numbers. +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 ( -In GEOS there can be only one file opened at a time. Upon opening VLIR file some information -about it are copied into memory. You can retrieve records table at OpenRecordFile

-This function finds and opens given file. An error is returned if file is not found or if it is not +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 CloseRecordFile

@@ -1022,16 +1021,16 @@ This function calls -This function will check PointRecord

This function will setup internal variables (and NextRecord and PreviousRecord

@@ -1045,14 +1044,14 @@ These two work like -This function will append an empty record ( pair of 255,0 ) to current VLIR track and sector +This function will append an empty record (pair of 255,0) to the current VLIR track and sector table. It will also set DeleteRecord

-This function will remove current record from the table, and move all current+1 records one place +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 This function will insert an empty record in place of ReadRecord and WriteRecord @@ -1070,35 +1069,35 @@ can be found in -This function will load or save at most Memory and Strings

-Functions covered in this section are common for whole C world - copying memory parts and -strings is one of the main computer tasks. GEOS also has interface to do this. These functions -are replacement for those like -However some of them have slightly different calling convention (order of arguments to be specific), -so please check their syntax here before direct replacing. +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.

Please note that the memory areas described here as CopyString

-This function copies string from CmpString

-This function compares string CopyFString and CmpFString @@ -1108,14 +1107,14 @@ strings have to have the same length. It returns either These two are similar to CRC

-This function calculates the CRC checksum for given memory range. I don't know if it is +This function calculates the CRC checksum for the given memory range. I don't know if it is compatible with standard CRC routines. FillRam and ClearRam @@ -1124,27 +1123,27 @@ compatible with standard CRC routines.

-Both functions are filling given memory range. MoveData

-This functions copies one memory region to another. There are checks for overlap and the -non-destructive method is chosen. Be warned that this function destroys contents of -InitRam

This function allows to initialize multiple memory locations with single bytes or strings. -This is done with Stash, Fetch, Swap, and VerifyRAM +StashRAM, FetchRAM, SwapRAM, and VerifyRAM

@@ -1154,15 +1153,15 @@ This is done with -These functions are interface to REU - Ram Expansion Unit. I think that they are self-explanatory. -You can check for REU presence by taking value of Processes and Multitasking

-Weird? Not at all. GEOS has limited multitasking ability. You can set up a chain of functions +Weird? Not at all. GEOS has some limited multitasking ability. You can set up a chain of functions called in specified intervals and you can put the main program to sleep without disturbing other -tasks and making user interface unresponsive. +tasks and making the user interface unresponsive. InitProcesses

@@ -1172,11 +1171,11 @@ This is the main initialization routine. After calling it processes are set up, enabled. The parameters for

-Single task is described by entry in The maximum number of tasks is 20. Be warned that GEOS doesn't check if parameters are valid and @@ -1185,7 +1184,7 @@ if -See description of RestartProcess and EnableProcess

@@ -1193,12 +1192,12 @@ See description of -These two functions start the task counter. - -BlockProcess and UnBlockProcess

@@ -1206,8 +1205,8 @@ after - -This function is multitasking sleep - the program is halted, but it doesn't block other functions +This function is a multitasking sleep - the program is halted, but it doesn't block other functions e.g. callbacks from menus and icons. -The only argument here is the number of jiffies to wait until app will wake up. It depends on +The only argument here is the number of jiffies to wait until the app will wake up. It depends on the video mode (PAL or NTSC) how many jiffies there are per second (50 or 60, respectively). -If you don't want to worry about it and need only full second resolution, call standard +If you don't want to worry about it and need only full second resolution, call the standard System Functions @@ -1247,7 +1246,7 @@ up. You shouldn't use this unless you know what you are doing. These functions are called by some disk routines. You should call them only if you want to -do something with IO registers or call one of Kernal ROM routines. Note that this is rather an +do something with IO registers or call one of the Kernal ROM routines. Note that this is rather an expensive way of turning off IRQs and enabling IO. MainLoop @@ -1255,8 +1254,8 @@ expensive way of turning off IRQs and enabling IO. Returns control to the system. Any code between call to EnterDeskTop @@ -1271,32 +1270,32 @@ use it. Always use -This one is another way of finishing application - forcing GEOS to shutdown and exit to BASIC. -I was considering whether to include it or not, but maybe someone will need it. Which is I doubt. +This one is another way of terminating an application - forcing GEOS to shutdown and exit to BASIC. +I was considering whether to include it or not, but maybe someone will need it - which I doubt.

Panic

-This calls system's System error at:xxxx -where -System is halted after call to CallRoutine

-This is system caller routine. You need to provide pointer to a function and it will be immediately +This is a system caller routine. You need to provide a pointer to a function and it will be immediately called, unless the pointer is equal to -This function returns the serial number of system. It might be used for copy-protection. -However, please remember that the Free Software is a true power and you are using it -right now. +This function returns the serial number of the system. It might be used for copy-protection. +However, please remember that Free Software is a true power and you are using it right now. GetRandom

@@ -1319,38 +1317,38 @@ a=random; but by calling this function you are sure that the results will be always different. -Note that it is not the same as SetDevice

-This function sets current device to given. It might be used together with get_ostype

-This function returns GEOS Kernal version combined (by logical OR) with machine type. Read -get_tv

-This function returns PAL/NTSC flag combined (by logical OR) with 40/80 columns flag. This is -not the best way to check if screen has 40 or 80 columns since PAL/NTSC check is always -performed and it can take as long as full raster frame. If you just want to know if -screen has 40 or 80 columns use expression Library Structures

-- 2.39.5