GEOS Programmer's Reference Guide written by Alexander Donald Boyce revision by Bo Zimmerman Preface This document was written after having disassembled the GEOS Kernal and completely commenting and reverse engineering it. It took a great deal of time to do this, but I did it because I enjoy computer programming and deciphering other people's programs. Because of the amount of effort involved in creating this document, I do not really wish to give it away. However, I know there are other programmers who will benefit from my hard work. Therefore I am offering this document as shareware. If you get good use out of this document, send me whatever you feel it is worth to you (or some reasonable amount, personally I find it invaluable). A few dollars would be appreciated. Here is my address: Alexander Donald Boyce 2269 Grandview Ave., Apt. 1 Cleveland Heights, Ohio 44106-3144 Thank you and happy computing!! Alex Boyce October 1986 1997 Revision notes: Wow! This document has been floating around for over 11 years! I wonder if Mr. Boyce still uses a Commodore, or has ever thought about this document written so long ago? Anyway, this revision contains many changes to reflect BSW's release of geoProgrammer, some new information, and a better organization. Those of you who know the previous version of this document will first notice that the names of all the routines and memory locations have been changed to reflect the official names that BSW gave them. This is to aid those of us using geoProgrammer for our coding. You'll find these names throughout the kernal descriptions, as well as many of the BSW logicals where appropriate. The prior version of this document was also fairly deficient in the non-kernal chapters dealing with file formats, device drivers, etc. These chapters have all been beefed up a bit. Another appendix has also been added for character set reference and another for 6502/6510/8502 assembly. Lastly, the order of all the kernal routines have been changed. This is just to cut down on page flipping and TOC referencing by putting all related routines together. Bo Zimmerman October, 1997 July, 2000 August, 2001 Table of Contents Chapter 1 GEOS Kernal Routines Defines all the GEOS kernal routines along with their input and output requirements. Chapter 2 Device Drivers Defines the format for Input and Printer Drivers. Chapter 3 File Formats Describes the format of all of GEOS's various files. Chapter 4 Directory Structure Describes the structure of a GEOS disk's directory. Chapter 5 Information Sector Format Describes the structure and the data contained in a file's information sector. Chapter 6 Memory Map Defines the memory locations used by GEOS. Appendix I GEOS Errors Defines the error numbers that can be returned by the GEOS Kernal routines. Appendix II Glossary Defines several terms used in this document. Appendix III Fill Patterns A representation of GEOS's 32 fill patterns. Appendix IV Programming Notes Information necessary for GEOS programming. Appendix V GEOS/ASCII/PETSCII Character sets Appendix VI 6502/6510/8502 Assembly language Categorical Listing -------------------------------------------------------------------------- Math routines ------------- DNegate $C172 Negate a 16 bit integer 1-001 Ddiv $C169 Unsigned 16 bit division 1-002 DMult $C166 Unsigned 16 bit by 16 bit multiply 1-003 BMult $C163 Unsigned 16 bit by 8 bit multiply 1-004 BBMult $C160 Unsigned 8 bit by 8 bit multiply 1-005 DSdiv $C16C Signed 16 bit division 1-006 Dabs $C16F 16 bit absolute value 1-007 Ddec $C175 Decrement a 16 bit integer 1-008 DShiftLeft $C15D Multiple 16 bit arithmetic shift left 1-009 DShiftRight $C262 Multiple 16 bit logical shift right 1-010 CRC $C20E Compute the checksum of a memory region 1-011 Memory manipulation ------------------- InitRam $C181 Multiple memory location initialization 1-101 MoveData $C17E Intelligent memory block move 1-102 i_MoveData $C1B7 Intelligent memory block move with inline data 1-103 FillRam $C17B Memory block fill 1-104 i_FillRam $C1B4 Memory block fill with inline data 1-105 ClearRam $C178 Fill a memory region with zeroes 1-106 CmpString $C26B String compare 1-107 CopyString $C265 String copy 1-108 CmpFString $C26E Memory block comparison 1-109 CopyFString $C268 Memory block move 1-110 StashRAM $C2C8 Stash memory into an REU 1-111 FetchRAM $C2CB Retrieve memory from an REU 1-112 SwapRAM $C2CE Swap memory with an REU memory block 1-113 VerifyRAM $C2D1 Verify (compare) memory with REU 1-114 DoRAMOp $C2D4 Perform any of the above REU commands 1-115 Text and fonts -------------- PutChar $C145 Display a character 1-201 SmallPutChar $C202 Draw a character on the screen 1-202 PutDecimal $C184 Display a 16 bit integer 1-203 PutString $C148 Display a text string 1-204 i_PutString $C1AE Display a text string with inline data 1-205 GetNextChar $C2A7 Read a character from the keyboard 1-206 GetString $C1BA Read a line of text from the user 1-207 InitTextPrompt $C1C0 Create the text cursor sprite 1-208 PromptOn $C29B Turn on the text cursor 1-209 PromptOff $C29E Turn off the text cursor 1-210 UseSystemFont $C14B Select the BSW font 1-211 LoadCharSet $C1CC Make a memory resident font the current font 1-212 GetRealSize $C1B1 Get a character's stats 1-213 GetCharWidth $C1C9 Get a character's width 1-214 Low level disk routines -------------------------- SetDevice $C2B0 Select a drive 1-301 ChangeDiskDevice $C2BC Change disk drive device number 1-302 OpenDisk $C2A1 Open a disk 1-303 NewDisk $C1E1 Initialize a drive 1-304 EnterTurbo $C214 Setup a drive with turbodos 1-305 ExitTurbo $C232 Stop turbodos in a drive 1-306 PurgeTurbo $C235 Stop and remove turbodos in a drive 1-307 GetDirHead $C247 Read track 18 sector 0 1-308 PutDirHead $C24A Write to track 18 sector 0 1-309 GetBlock $C1E4 Read a sector 1-310 PutBlock $C1E7 Write a sector 1-311 ReadBlock $C21A Read a sector with drive preset 1-312 WriteBlock $C220 Write a sector with drive preset 1-313 VerWriteBlock $C223 Verify before writing sector 1-314 GetPtrCurDkNm $C298 Compute address of disk's name 1-315 FindBAMBit $C2AD Check if a disk sector is in use 1-316 SetNextFree $C292 Find and allocate a disk block 1-317 BlkAlloc $C1FC Allocate sectors for a file 1-318 NxtBlkAlloc $C24D Allocate sectors for a file 1-319 SetGEOSDisk $C1EA Convert a disk to GEOS format 1-320 ChkDkGEOS $C1DE Check if a disk is GEOS format 1-321 CalcBlksFree $C1DB Compute number of free blocks on disk 1-322 FreeBlock $C2B9 Free a BAM bit in memory 1-323 High level disk routines ------------------------ FindFTypes $C23B Create a table of file names 1-401 FindFile $C20B Lookup a file in the directory 1-402 SaveFile $C1ED Save memory to a file 1-403 WriteFile $C1F9 Save memory to preallocated sectors 1-404 RenameFile $C259 Rename a file 1-405 DeleteFile $C238 Delete a file 1-406 FastDelFile $C244 Delete a temporary file 1-407 FreeFile $C226 Free a file's sectors 1-408 RstrAppl $C23E Load the SWAPFILE 1-409 GetFile $C208 Load a file, given a file name 1-410 LdFile $C211 Load a file, given a directory entry 1-411 LdApplic $C21D Load and run a file, given a directory entry 1-412 LdDeskAcc $C217 Load a file with memory swapping 1-413 ReadByte $C2B6 Get a byte from a file 1-414 ReadFile $C1FF Load a chain into memory, given the initial track and sector 1-415 GetFreeDirBlk $C1F6 Find a hole in the directory 1-416 SetGDirEntry $C1F0 Create a directory entry on disk 1-417 BldGDirEntry $C1F3 Create a directory entry in memory 1-418 GetFHdrInfo $C229 Get a file's load address 1-419 FollowChain $C205 Create a list of sectors used by a file 1-420 VLIR support routines --------------------- OpenRecordFile $C274 Open a VLIR file 1-501 PointRecord $C280 Goto a specific VLIR chain 1-502 PreviousRecord $C27D Move to previous VLIR chain 1-503 NextRecord $C27A Move to next VLIR chain 1-504 InsertRecord $C286 Insert a VLIR chain 1-505 AppendRecord $C289 Add a VLIR chain 1-506 DeleteRecord $C283 Remove a VLIR chain 1-507 ReadRecord $C28C Load a VLIR chain 1-508 WriteRecord $C28F Save memory to a VLIR chain 1-509 UpdateRecordFile $C295 Update a VLIR file 1-510 CloseRecordFile $C277 Close a VLIR file 1-511 Graphics -------- GraphicsString $C136 Process a graphic command table 1-601 i_GraphicsString $C1A8 Process a graphic command table with inline data 1-602 SetPattern $C139 Select a fill pattern 1-603 FrameRectangle $C127 Draw an outline in a pattern 1-604 i_FrameRectangle $C1A2 Draw a solid outline with inline data 1-605 Rectangle $C124 Fill a box with a pattern 1-606 i_Rectangle $C19F Fill a box with a pattern with inline data 1-607 RecoverRectangle $C12D Copy a box from screen 1 to screen 2 1-608 i_RecoverRectangle $C1A5 Copy a box from screen 1 to screen 2 with inline data 1-609 ImprintRectangle $C250 Copy a box from screen 2 to screen 1 1-610 i_ImprintRectangle $C253 Copy a box from screen 2 to screen 1 with inline data 1-611 InvertRectangle $C12A Reverse video a box 1-612 RecoverLine $C11E Copy a line from screen 2 to screen 1 1-613 InvertLine $C11B Reverse video a horizontal line 1-614 DrawLine $C130 Draw/Erase/Copy an arbitrary line 1-615 HorizontalLine $C118 Draw a horizontal line in a pattern 1-616 VerticalLine $C121 Draw a vertical line in a pattern 1-617 GetScanLine $C13C Compute memory address of a row on the screen 1-618 TestPoint $C13F Test the value of a pixel 1-619 DrawPoint $C133 Draw/Erase/Copy a point on the screen 1-620 BitmapUp $C1AB Draw a click box with inline data 1-621 i_BitmapUp $C1AB Draw a click box with inline data 1-622 BitmapClip $C2AA Draw a coded image 1-623 BitOtherClip $C2C5 Draw a coded image with user patches 1-624 DrawSprite $C1C6 Copy a sprite data block 1-625 PosSprite $C1CF Position a sprite 1-626 EnablSprite $C1D2 Turn on a sprite 1-627 DisablSprite $C1D5 Turn off a sprite 1-628 Controls -------- DoMenu $C151 Menu processor 1-701 DoPreviousMenu $C190 Close current menu 1-702 GotoFirstMenu $C1BD Close all menu levels 1-703 ReDoMenu $C193 Draw the current menu 1-704 RecoverMenu $C154 Erase the current menu 1-705 RecoverAllMenus $C157 Erase all menus 1-706 DoIcons $C15A Draw a table of click boxes 1-707 DoDlgBox $C256 Window processor 1-708 RstrFrmDialogue $C2BF Close a window 1-709 IsMseInRegion $C2B3 Check if mouse is inside a window 1-710 Panic $C2C2 Report system error 1-711 Miscellaneous ------------- InitForIO $C25C Open serial communication 1-801 DoneWithIO $C25F Close serial communication 1-802 FirstInit $C271 Initialize GEOS variables 1-803 MainLoop $C1C3 GEOS's main loop 1-804 InterruptMain $C100 IRQ routine 1-805 BootGEOS $C000 Reboot GEOS 1-806 StartAppl $C22F Run a program that is in memory 1-807 EnterDesktop $C22C Load and run DESKTOP 1-808 ToBasic $C241 Restart BASIC 1-809 CallRoutine $C1D8 Perform an indirect jump 1-810 DoInlineReturn $C2A4 Perform a jump through a table 1-811 StartMouseMode $C14E Initialize the mouse 1-812 MouseUp $C18A Turn on the mouse 1-813 MouseOff $C18D Turn off the mouse 1-814 ClearMouseMode $C19C Reset the mouse 1-815 Sleep $C199 Set up a time delay 1-816 GetRandom $C187 Change the random number 1-817 GetSerialNumber $C196 Who knows what this routine does??? 1-818 Processes --------- InitProcesses $C103 Initialize a table of recurring timed events 1-901 EnableProcess $C109 Force a recurring timed event to run 1-902 RestartProcess $C106 Enable a recurring timed event 1-903 FreezeProcess $C112 Stop a recurring timed event's timer 1-904 BlockProcess $C10C Prevent a recurring timed event from running 1-905 UnblockProcess $C10F Allow a recurring timed event to execute 1-906 UnfreezeProcess $C115 Start a recurring timed event's timer 1-907 Chapter 1: GEOS Kernal Routines Math routines ------------------------------------------------------------------ 1-001 Function Name: DNegate Purpose: Negates a 16 bit value. Call address: $C172 Input requirements: X The address of the 16 bit integer Output: X The address of the 16 bit result. Description: This routine is one of the GEOS math routines. X points to a 16 bit value which is negated. The value of X is not affected. 1-002 Function Name: Ddiv Purpose: Unsigned 16 bit by 16 bit division. Call address: $C169 Input requirements: Y The address of the 16 bit divisor. X The address of the 16 bit dividend. Output: X The address of the 16 bit quotient. $12-$13 R8 The 16 bit remainder. Description: This routine is one of the GEOS math routines. X and Y each have the address of a term in the division. The quotient is stored in place of the original dividend that X pointed to. The dividend is left untouched. 1-003 Function Name: DMult Purpose: Unsigned 16 bit by 16 bit multiply. Call address: $C166 Input requirements: Y The address of the 16 bit multiplier. X The address of the 16 bit multiplicand. Output: X The address of the 16 bit result. Description: This routine is one of the GEOS math routines. X and Y each have the address of a term in the multiplication. The result is stored in place of the original multiplicand that X pointed to. The multiplier pointed to by Y is untouched. 1-004 Function Name: BMult Purpose: Unsigned 8 bit by 16 bit multiply. Call address: $C163 Input requirements: Y The address of the 8 bit multiplier. X The address of the 16 bit multiplicand. Output: X The address of the 16 bit product. Description: This routine is one of the GEOS math routines. X and Y each have the address of a term in the multiplication. The result is stored in place of the original multiplicand that X pointed to. The byte following the multiplier is set to zero, then control passes to DMult. 1-005 Function Name: BBMult Purpose: Unsigned 8 bit by 8 bit multiply. Call address: $C160 Input requirements: Y The address of the multiplier. X The address of the multiplicand. Output: X The address of the 16 bit product. Description: This routine is one of the GEOS math routines. X and Y each have the address of a term in the multiplication. The result is stored in place of the original multiplicand that X pointed to. The value that Y points to is left untouched. 1-006 Function Name: DSdiv Purpose: Signed 16 bit by 16 bit division. Call address: $C16C Input requirements: Y The address of the 16 bit divisor. X The address of the 16 bit dividend. Output: X The address of the 16 bit quotient. $12-$13 R8 The 16 bit remainder. Description: This routine is one of the GEOS math routines. X and Y each have the address of a term in the division. Both terms are made positive with Dabs. Ddiv is then called; if the result of the division should be negative, DNegate is called. The quotient is stored in place of the original dividend that X pointed to. The dividend is left untouched. The remainder is always a positive integer. 1-007 Function Name: Dabs Purpose: 16 bit absolute value. Call address: $C16F Input requirements: X The address of the 16 bit integer. Output: X The address a positive 16 bit integer. Description: This routine is one of the GEOS math routines. X points to a 16 bit value which if found to be negative, DNegate is called to make it positive. 1-008 Function Name: Ddec Purpose: Decrements a 16 bit value. Call address: $C175 Input requirements: X The address of the 16 bit integer. Output: X The address of the 16 bit result. Description: This routine is one of the GEOS math routines. X points to a 16 bit value which is decremented by 1. 1-009 Function Name: DShiftLeft Purpose: 16 bit multiple arithmetic shift lefts. Call address: $C15D Input requirements: Y The shift count. X The address of the 16 bit value to be shifted. Output: X Result of shifts. Description: This routine is one of the GEOS math routines. X has the address of a 16 bit integer in zero page, which is to be shifted left by the count in Y. 1-010 Function Name: DShiftRight Purpose: 16 bit multiple logical shift rights. Call address: $C262 Input requirements: Y The shift count. X The address of the 16 bit value to be shifted. Output: X Result of shifts. Description: This routine is one of the GEOS math routines. X has the address of a 16 bit integer in zero page, which is to be shifted right by the count in Y. 1-011 Function Name: CRC Purpose: Compute a checksum for a data region. Call address: $C20E Input requirements: $02-$03 R0 Pointer to data region. $04-$05 R1 Length of region. Output: $06-$07 R2 Checksum of region. Description: This routine is called by the bootup routines to compute the checksum of GEOS BOOT. This checksum is used to create the interrupt vector address. The reason for this was to prevent piracy. This can be used to check the integrity of a memory region. This is actually more of a CRC computation then a checksum and the formula is a little too complex to explain here. Memory Manipulation Routines ------------------------------------------------------------------ 1-101 Function Name: InitRam Purpose: Uses a table to set various memory locations in a uniform manner. Call address: $C181 Input requirements: $02-$03 R0 Address of a data table. Description: This routine allows many memory locations to be specified and set in an orderly manner. The format of the data table is as follows: #bytes Description 2 Address to store values at. 1 # of values that follow. ? Values to be stored at the designated memory region. ... More definitions. 2 An address of $0000 ends the table. 1-102 Function Name: MoveData Purpose: Intelligent block move. Call address: $C17E Input requirements: $02-$03 R0 The source address. $04-$05 R1 The destination address. $06-$07 R2 The length of the region to be moved. Description: This routine will perform an intelligent, i.e. nonconflicting, block move of memory. If an attempt is made to move a block of memory to a destination that is within the block, the transfer is done from back to front so as to prevent the conflict, or 'ripple effect'. 1-103 Function Name: i_MoveData Purpose: Identical to MoveData, but with inline data. Call address: $C1B7 Description: This routine uses the inline data to set everything up before calling MoveData. For example: JSR i_MoveData .word Source address .word Destination address .word Length of transfer Control returns here upon completion. 1-104 Function Name: FillRam Purpose: Fills a memory region with a specified byte. Call address: $C17B Input requirements: $02-$03 R0 The length of the region. $04-$05 R1 The address of the region. $06 R2L The byte to fill the region with. Description: A simple loop fills memory with the specified byte. 1-105 Function Name: i_FillRam Purpose: Identical to FillRam, but with inline data. Call address: $C1B4 Description: This routine takes the inline data and sets everything up before calling FillRam. For example: JSR i_FillRam .word Length of region .word Address of region .byte Byte to fill memory with Control returns here upon completion. 1-106 Function Name: ClearRam Purpose: Fills a memory region with zeroes. Call address: $C178 Input requirements: $02-$03 R0 The length of the region. $04-$05 R1 The address of the region. Description: Memory is filled with zeroes by storing a $00 at location $06 and calling FillRam. 1-107 Function Name: CmpString Purpose: Compare two strings for equality. Call address: $C26B Input requirements: X Address of a zero page pointer. Y Address of a zero page pointer. Output: Z flag Set accordingly. Description: The X and Y registers point to zero page pointers. The two strings are compared up to a zero byte. The Z flag is set accordingly. 1-108 Function Name: CopyString Purpose: Copy a string. Call address: $C265 Input requirements: X Address of zero page source pointer. Y Address of zero page destination pointer. Description: The X and Y registers point to zero page pointers. Data is copied up to and including a zero byte. This routine is used to copy strings by setting A to zero and calling CopyFString. 1-109 Function Name: CmpFString Purpose: Compares two blocks of memory for a fixed length. Call address: $C26E Input requirements: A Byte count. X Address of zero page source pointer. Y Address of zero page destination pointer. Output: Z flag Set accordingly. Description: The X and Y registers point to zero page pointers. A has the number of bytes to be compared (1-255). If A is zero, this routine will compare up to and including a zero byte. The Z flag is set accordingly. See CmpString. 1-110 Function Name: CopyFString Purpose: Copy a block of memory. Call address: $C268 Input requirements: A Byte count. X Address of zero page source pointer. Y Address of zero page destination pointer. Description: The X and Y registers point to zero page pointers. A has the number of bytes to be transferred (1-255). If A is zero, this routine will copy up to and including a zero byte. See CopyString. 1-111 Function Name: StashRAM Purpose: Copy a block of memory into an REU from main memory Call address: $C2C8 Input requirements: $02-$03 R0 Pointer to an address in main memory $04-$05 R1 Address within the 64k REU bank addressed $06-$07 R2 Number of bytes to swap, fetch, verify, etc. $08 R3L REU 64k bank to work with Output: X Error code A REU status Description: The Y register is loaded with $90, and DoRamOp (see blow) is called. 1-112 Function Name: FetchRAM Purpose: Copies a block of memory from an REU into main memory Call address: $C2CB Input requirements: $02-$03 R0 Pointer to an address in main memory $04-$05 R1 Address within the 64k REU bank addressed $06-$07 R2 Number of bytes to fetch $08 R3L REU 64k bank to work with Output: X Error code A REU status Description: The Y register is loaded with $91, and DoRamOp (see blow) is called. 1-113 Function Name: SwapRAM Purpose: Swaps a block of main memory with an REU block Call address: $C2CE Input requirements: $02-$03 R0 Pointer to an address in main memory $04-$05 R1 Address within the 64k REU bank addressed $06-$07 R2 Number of bytes to swap $08 R3L REU 64k bank to work with Output: X Error code A REU status Description: The Y register is loaded with $92, and DoRamOp (see blow) is called. 1-114 Function Name: VerifyRAM Purpose: Verifies (compares) a block of memory to one in an REU Call address: $C2D1 Input requirements: $02-$03 R0 Pointer to an address in main memory $04-$05 R1 Address within the 64k REU bank addressed $06-$07 R2 Number of bytes verify $08 R3L REU 64k bank to work with Output: X Error code A REU status Description: The Y register is loaded with $93, and DoRamOp (see blow) is called. 1-115 Function Name: DoRamOp Purpose: Move memory to and from an REU Call address: $C2D4 Input requirements: $02-$03 R0 Pointer to an address in main memory $04-$05 R1 Address within the 64k REU bank addressed $06-$07 R2 Number of bytes to swap, fetch, verify, etc. $08 R3L REU 64k bank to work with Y REU command to execute (see below) Output: X Error code A REU status Description: The Y register contains $90 to store, $91 for a fetch, $92 for a memory swap, and $11 to verify (compare). R0 and R2 tell this routine the block of main memory to store, swap, fetch, or verify. R3L and R1 combine to form a 3-byte address within the REU to work with. Text and fonts ------------------------------------------------------------------ 1-201 Function Name: PutChar Purpose: Displays a character on the screen. Call address: $C145 Input requirements: A The character to be printed. $02-$03 R0 Pointer to extra data (Used by a few control characters, not needed otherwise). $05 R1H The row for printing (1 above the underline). $18-$19 R11 The column to start printing. $33 windowTop: The top margin (Usually 0). $34 windowBottom: The bottom margin (Usually 199). $35-$36 leftMargin: The left margin. $37-$38 rightMargin: The right margin. Preparatory routines: UseSystemFont or LoadCharSet Errors: Branches through $84AB-$84AC (StringFaultVec) if right margin is exceeded. Description: This routine displays a character in a given location in the current font and style. The style byte in location $2E (currentMode) is coded as follows: Bit Description 7 Underline 6 Boldface 5 Reversed 4 Italics 3 Outlined Either UseSystemFont or LoadCharSet must be called prior to using this routine, in order to set up the font pointers. UseSystemFont is called during GEOS's bootup procedure, as well as by the menu processor. Several control characters have special properties. Those which require a data pointer are marked with an asterisk. Control Character Table Ctrl-H Delete previous character. STA char width in realSize ($8807) first Ctrl-I Tab. Ctrl-J Move straight down a line. Ctrl-K Set text cursor to 0,0. Ctrl-L Move straight up a line. Ctrl-M Move to the beginning of the next line. Ctrl-N Turn on underlining. Ctrl-O Turn off underlining. * Ctrl-P Followed by a table suitable for GraphicsString. Ctrl-R Turn on reverse video. Ctrl-S Turn off reverse video. * Ctrl-T Followed by 2 bytes which specify the new column. * Ctrl-U Followed by a byte which specifies the new row. * Ctrl-V Followed by 3 bytes which specify the new print position. * Ctrl-W Skips the next 3 bytes. Ctrl-X Turn on Boldface. Ctrl-Y Turn on Italics. Ctrl-Z Turn on Outline. Ctrl- Turn off all effects, return to plain text. Those entries marked with an asterisk (*) should only be used from PutString because they require $02-$03 R0 to be a pointer to get extra data. As with GraphicsString, Ctrl-P must be the last command because the zero byte that terminates GraphicsString will terminate PutString. 1-202 Function Name: SmallPutChar Purpose: Draws a character. Call address: $C202 Input requirements: A The ASCII value of the character. $05 R1H Row to print on (1 above the underline). $18-$19 R11 Column to print in. $33 windowTop: The top margin (Usually 0). $34 windowBottom: The bottom margin (Usually 199). Description: This routine is not exactly the same as PutChar. This routine does not process control characters at all. It also does not check left and right margins at all. It only checks top and bottom margins so that it stays on screen. 1-203 Function Name: PutDecimal Purpose: Display an unsigned 16 bit integer. Call address: $C184 Input requirements: A Control value (See description). $02-$03 R0 The value to be displayed. Description: This routine converts the value at $02-$03 R0 to decimal ASCII and displays it using PutChar. The control value in A is defined as follows: bit 7 0 - right justify the number. 1 - left justify the number, i.e. no justify. bit 6 0 - print leading zeroes. 1 - skip leading zeroes. bits 0-5 The field width in pixels for right justification. 1-204 Function Name: PutString Purpose: Displays an entire string of text. Call address: $C148 Input requirements: $02-$03 R0 Pointer to text string. $05 R1H The row for printing (1 above the underline). $18-$19 R11 The column in which to start printing. $33 windowTop: The top margin (Usually 0). $34 windowBottom: The bottom margin (Usually 199). $35-$36 leftMargin: The left margin. $37-$38 rightMargin: The right margin. Preparatory routines: UseSystemFont or LoadCharSet Errors: Branches through $84AB-$84AC (StringFaultVec) if right margin is exceeded. Description: This routine calls PutChar to display each character in a string. The string is terminated by a zero byte. Be sure to subtract 6 from R1H for a GetString in the same place. Add 2 to underline for proper positioning. 1-205 Function Name: i_PutString Purpose: Identical to PutString, but with inline code. Call address: $C1AE Input requirements: $35-$36 leftMargin: The left margin. $37-$38 rightMargin: The right margin. Preparatory routines: UseSystemFont or LoadCharSet Errors: Branches through $84AB-$84AC (StringFaultVec) if right margin is exceeded. Description: This routine creates a pointer to the text, calls PutString, then returns to the code immediately following the text. JSR i_PutString .word The column to start printing in .byte Row for line of print (1 above the underline) .byte Text to be displayed .byte 0 Control returns here after text is printed. 1-206 Function Name: GetNextChar Purpose: Get a key from the keyboard. Call address: $C2A7 Output: A Character or $00 if there are none. Description: This routine takes a key from the keyboard buffer, if there is one. If there are no characters in the buffer, then a zero is returned. 1-207 Function Name: GetString Purpose: Input a line of text from the user. Call address: $C1BA Input requirements: $02-$03 R0 Address of text and buffer. $04 R1L Flag byte ($87D3). $05 R1H Row to print text on (1 above the underline). $06 R2L Maximum length of input. $0A-$0B R4 Vector for user routine for right margin exceeded (optional). $18-$19 R11 Column to start printing text at. $84A3-$84A4 keyVector: Address for CR entered. Output: $24-$25 string: Pointer to text buffer (from $02-$03 R0). Buffer will be modified according to the user's input. $84A3-$84A4 keyVector: Cleared to $0000. Description: This routine is rather powerful. It displays a line of text, if there was any text to display. Then the text cursor is turned on. Several of the jump vectors are used: $84AB - $84AC (StringFaultVec) is the vector for the right margin being exceeded. $84A9-$84AA (otherPressVec) is the vector for a character being typed. $84A3- $84A4 (keyVector) is the vector for CR entered. After everything is set up, control returns to the caller; however, the input is handled by the interrupt drivers. When a CR is entered, control goes through the vector at $84A3-$84A4. The flag byte at location $04 R1L is copied to $87D3 and has the following property: If bit 7 is set, then use the user's routine whose address is stored at locations $0A-$0B R4 for the right margin is exceeded routine. Add 6 to R1H for a PutString in the same place. 1-208 Function Name: InitTextPrompt Purpose: Makes a vertical bar cursor sprite. Call address: $C1C0 Input requirements: A The height of the cursor minus 1 (0-41) Output: Sprite block #41 ($8A40-$8A7E) is made into a vertical bar of a given height. Description: Given the desired height, a vertical bar is created in the sprite block. If the height is greater than 21, then the height is halved and the sprite is Y-expanded. No check is performed on the height. If a height greater than 41 is used then the memory for next few sprites will be affected. 1-209 Function Name: PromptOn Purpose: Turn on text cursor. Call address: $C29B Input requirements: $84BE-$84BF stringX: Column to place cursor in. $84C0 stringY: Row to place cursor on. Output: $84B4 alphaFlag: Bit 6 is set. Description: Turns on sprite 1 and positions it. It also sets bit 6 of location $84B4. The blink rate is set to 60, once per second. Sprite 1 is the text cursor for GEOS. 1-210 Function Name: PromptOff Purpose: Turn off text cursor. Call address: $C29E Output: $84B4 alphaFlag: Bit 6 is cleared. Preparatory routines: PromptOn Description: Sprite 1 (GEOS's text cursor) is turned off, bit 6 of location $84B4 is reset. The blink rate is set to 60 (once per second). 1-211 Function Name: UseSystemFont Purpose: Selects the Berkeley Softworks font. Call address: $C14B Output: $26 baselineOffSet: # pixels above line of print. $27-$28 curSetWidth: The number of bytes in the bit stream. $29 curHeight: The point size. $2A-$2B curIndexTable: The pointer to the table of indices into the bit stream. $2C-$2D curDataPntr: The pointer to the bit stream. Description: This routine simply copies the font header data for the BSW font to zero page for use by PutChar and PutString. 1-212 Function Name: LoadCharSet Purpose: Change the current font. Call address: $C1CC Input requirements: $02-$03 R0 Pointer to font header in memory. Output: $26 baselineOffset: # pixels above line of print. $27-$28 curSetWidth: The number of bytes in the bit stream. $29 curHeight: The point size. $2A-$2B curIndexTable: Pointer to table of bit stream indices. $2C-$2D curDataPtr: Pointer to the bit stream. Description: This routine simply copies the header block from the font to zero page. This makes the font the current font for all character output. (See PutChar, PutString and i_PutString). 1-213 Function Name: GetRealSize Purpose: Get statistics for a character. Call address: $C1B1 Input requirements: A The character. Output: A The position of the underline. Y The character's width. X The character's height. Description: Given the ASCII value of a character, this routine computes and returns the height and width, taking the style into account. The # pixels above the underline for the present font is also returned. 1-214 Function Name: GetCharWidth Purpose: Returns the width of a character. Call address: $C1C9 Input requirements: A The ASCII value of the character. Output: A The width of the character. Description: This routine simply takes the difference of the bit stream indices to get the characters width. The delete character has its width loaded from $8807. This routine is called by GetRealSize. Low level disk routines ------------------------------------------------------------------ 1-301 Function Name: SetDevice Purpose: Set current drive. Call address: $C2B0 Input requirements: A Device number of drive (8-11). Output: $BA curDevice: Set to new device number. $8489 curDrive: Set to new drive number. Description: If the drive being specified is not the current drive then ExitTurbo is called to clear the current drive. Then locations $BA and $8489 are set to the new drive number. No other locations are affected, nor is anything actually done with the drive. 1-302 Function Name: ChangeDiskDevice Purpose: Change the device number of a drive. Call address: $C2BC Input requirements: A New device number for drive. $8489 curDrive: Current drive number. Output: $BA curDevice: New device number. $8489 curDrive: New device number. $8492-$8495 turboFlags: Appropriate bytes are reset and set. Errors: See appendix I. Description: The current drive is made ready, then the new device number is sent to turbodos which will change it. This results in the drive being set as the current drive but with a new device number, and with turbodos up and running. The status bytes at $8492-$8495 are changed, the old one is reset and the new one has bits 6 and 7 set. 1-303 Function Name: OpenDisk Purpose: Opens a disk to GEOS. Call address: $C2A1 Input requirements: $8489 curDrive: Current drive number. Output: $848B isGEOS: $00/$FF Geos format or not. $841E-$8465 Appropriate buffer will have disk's name. Errors: See Appendix I. Description: The current drive is initialized by calling NewDisk. GEOS format is checked for, and the disk's name is copied into the appropriate buffer at $841E-$8465. 1-304 Function Name: NewDisk Purpose: Initializes a drive. Call address: $C1E1 Input requirements: $04 R1L Track to position the disk drive head at. $05 R1H Sector to position the disk drive head at. Errors: See Appendix Description: Makes sure that current drive has turbodos running. It also positions the head over a particular sector. 1-305 Function Name: EnterTurbo Purpose: Sets up a drive with turbodos. Call address: $C214 Input requirements: $8489 curDrive: Current drive number. Errors: See Appendix I. Description: This routine initializes the current drive, sending turbodos if necessary. It then causes the drive to run turbodos. This routine is called by several of the disk I/O routines, most notably are GetBlock and PutBlock. Upon initializing the drive, the drive's status byte is set to the appropriate value. The status bytes are stored at $8492-$8495 and have the following bit definitions: Bit 7 Turbodos is loaded. Bit 6 Turbodos is running. 1-306 Function Name: ExitTurbo Purpose: Turn off turbodos. Call address: $C232 Input requirements: $8489 curDrive: Current drive number. Description: Turbodos is terminated in the current drive. 1-307 Function Name: PurgeTurbo Purpose: Clear the drive ready status. Call address: $C235 Input requirements: $8489 curDrive: Current drive number. Output: Appropriate status byte is reset. Description: This routine terminates turbodos in the current drive, and resets the drive status byte at $8492-$8495. 1-308 Function Name: GetDirHead Purpose: Read track 18, sector 0 from the disk. Call address: $C247 Output: $04 R1L Track number. $05 R1H Sector number. $0A-$0B R4 $8200 (curDirHead), address of buffer area. $8200-$82FF curDirHead: Data from track 18 sector 0. Errors: See Appendix I. Description: This routine sets up the pointers for GetBlock, then calls it to read the sector. This is generally used to get the BAM into memory. 1-309 Function Name: PutDirHead Purpose: Write track 18 sector 0 back to disk. Call address: $C24A Input requirements: $8200-$82FF curDirHead: Data for track 18 sector 0. Output: $04 R1L $12, track number. $05 R1H $00, sector number. $0A-$0B R4 $8200, address of buffer area. Errors: See Appendix I. Description: This routine sets up the pointers for PutBlock, then calls it to write the sector. This is generally used to update the BAM on the disk. 1-310 Function Name: GetBlock Purpose: Read a given track and sector. Call address: $C1E4 Input requirements: $04 R1L Track of sector to be read. $05 R1H Sector number to be read. $0A-$0B R4 Pointer to buffer. Errors: See Appendix Description: Loads and runs turbodos if it is not already there. Then reads the desired block from the disk into the buffer. 1-311 Function Name: PutBlock Purpose: Write a given track and sector. Call address: $C1E7 Input requirements: $04 R1L Track of sector to be written. $05 R1H Sector number to be written. $0A-$0B R4 Pointer to buffer. Errors: See Appendix Description: Loads turbodos if it is not already there by calling EnterTurbo. The desired block is then written to the disk by calling WriteBlock. Finally VerWriteBlock is called to verify the sector. 1-312 Function Name: ReadBlock Purpose: Read a sector from the disk. Call address: $C21A Input requirements: $04 R1L Track to be read. $05 R1H Sector to be read. $0A-$0B R4 Pointer to buffer for data. Output: Data is read into the desired buffer. Preparatory routines: EnterTurbo, InitForIO Errors: See Appendix I. Description: This routine is called by GetBlock to read a sector. The difference between this routine and GetBlock is that GetBlock calls EnterTurbo before trying to read the sector. This routine assumes that the drive is ready with turbodos running. 1-313 Function Name: WriteBlock Purpose: Write a sector to the disk. Call address: $C220 Input requirements: $04 R1L Track number. $05 R1H Sector number. $0A-$0B R4 Pointer to data buffer. Preparatory routines: EnterTurbo, InitForIO Errors: See Appendix I. Description: This routine is to PutBlock, as ReadBlock is to GetBlock. EnterTurbo must have been called prior to using this routine. 1-314 Function Name: VerWriteBlock Purpose: Conditionally write a sector to disk. Call address: $C223 Input requirements: $04 R1L Track number. $05 R1H Sector number. $0A-$0B R4 Pointer to data buffer. Preparatory routines: EnterTurbo, InitForIO Errors: See appendix I. Description: The first thing this routine does is try to read the desired sector. If the read succeeds, nothing happens. Three attempts are made at the read. After these read attempts, the sector is written to the disk, by calling WriteBlock. If the write succeeded without any errors, then the routine restarts itself. It will make five attempts at this loop. If after five attempts, the sector can not be read reliably, an error 39 results. This routine is usually called after the sector has been written out with a call to WriteBlock. PutBlock calls this routine to verify the sector. 1-315 Function Name: GetPtrCurDkNm Purpose: Compute the address of the disk's name. Call address: $C298 Input requirements: X Address to place pointer in. $8489 curDrive: Current drive number. Output: Location in zero page pointed to by X has the address of the current drive's name. Preparatory routines: OpenDisk Description: This routine computes the address of the current drive's name by multiplying the drive number (minus 8) by 18, then the offset of $841E (DrACurDkNm) is added to that. The result of the computation is stored at the zero page address in X. 1-316 Function Name: FindBAMBit Purpose: Check if a disk sector is in use. Call address: $C2AD Input requirements: $0E R6L Track to be checked. $0F R6H Sector to be checked. $8200-$82FF curDirHead: Track 18 sector 0, BAM buffer. Output: X Index into BAM of the appropriate byte. Z flag Set if the sector is in use. $11 R7H Index to track's data in BAM. $13 R8H Bit mask for the desired sector. Preparatory routines: GetDirHead Description: This routine is used by SetNextFree to test if a sector is already in use. 1-317 Function Name: SetNextFree Purpose: Allocate a block on the disk. Call address: $C292 Input requirements: $08 R3L Track to start scanning from. $09 R3H Sector to start scanning from. $8200-$82FF curDirHead: Track 18 sector 0, BAM. $848C interleave: Skew factor (default is 8). Output: $08 R3L New track number. $09 R3H New sector number. Errors: See appendix I. Description: This routine expects that the BAM is already in memory. It scans the BAM starting at a specified location, looking for a free sector. If one is found it is returned, otherwise an error results. The sector is allocated in the BAM, and the BAM must be updated to disk afterwards in order for the sector to remain allocated. 1-318 Function Name: BlkAlloc Purpose: Allocate enough sectors for a file. Call address: $C1FC Input requirements: $06-$07 R2 Number of bytes to be saved. $0E-$0F R6 Address of buffer for track and sector list. $8200 curDirHead: Directory header information Output: Buffer is filled with a set of tracks and sectors. Errors: See Appendix Description: Given a byte count and a pointer to a buffer, this routine attempts to allocate enough sectors. This routine is called prior to saving a file. The track and sector list is not limited in length, available disk space not withstanding. The list is terminated with a track number of zero and the appropriate byte count in the sector location. Note if an error occurs during the allocation, the sectors already allocated are not freed up. Either this must be done or the disk must be validated. 1-319 Function Name: NxtBlkAlloc Purpose: Allocate enough sectors for a file. Call address: $C24D Input requirements: $06-$07 R2 Number of bytes to be saved. $08 R3L Track to start looking from. $09 R3H Sector to start looking from. $0E-$0F R6 Address of buffer for track and sector list. Output: Buffer is filled with a set of tracks and sectors. Errors: See Appendix Description: This routine is almost identical to BlkAlloc. As a matter of fact, BlkAlloc falls into this routine after setting $08- $09 to point to track 1 sector 0. This routine allows the user to specify where on the disk to start looking for free sectors, possibly speeding things up. 1-320 Function Name: SetGEOSDisk Purpose: Converts a disk to GEOS format. Call address: $C1EA Errors: See appendix Description: This routine modifies the directory header to include the GEOS format message. It also allocates a sector to be used for the border from DESKTOP. 1-321 Function Name: ChkDkGEOS Purpose: Checks if a disk is GEOS format or not. Call address: $C1DE Input requirements: $0C-$0D R5 Pointer to buffer with track 18 sector 0. Output: Z Set if non-GEOS, reset if GEOS format. A,$848B isGEOS: $00 if non-GEOS, $FF if GEOS format. Description: This routine expects that track 18 sector 0 has already been read. It compares 11 bytes, starting with the 173rd, against 'GEOS format'. It sets $848B so that the current drive is kept track of. 1-322 Function Name: CalcBlksFree Purpose: Counts the number of free blocks in the BAM that is in RAM. Call address: $C1DB Input requirements: $0C-$0D R5 Pointer to buffer with track 18 sector 0. Output: $0A-$0B R4 The number of free blocks. Preparatory routines: GetDirHead Description: This routine expects that the BAM has already been read into memory. All that it does is add up the number of free blocks in each track. 1-323 Function Name: FreeBlock Purpose: Clear the BAM bit for a given track and sector Call address: $C2B9 Input requirements: $0C-$0D R6 Track and Sector to free $8200 curDirHead: directory header Output: $8200 curDirHead: BAM bit is cleared Errors: See appendix Preparatory routines: GetDirHead Description: This routine expects that the BAM has already been read into memory. The given BAM bit is cleared. High level file routines ------------------------------------------------------------------ 1-401 Function Name: FindFTypes Purpose: Create a list of filenames. Call address: $C23B Input requirements: $0E-$0F R6 Pointer to buffer area for file names. $10 R7L GEOS file type. $11 R7H Maximum number of file names. $16-$17 R10 Pointer to class. Output: $11 R7H Number of files not found. The table is filled with filenames. Errors: See Appendix I. Description: This is a very useful routine. Given a GEOS file type, a list of files with that type is created. If the class pointer is non-zero then each file's info sector is checked for proper class. This is how GEOpaint and GEOwrite can both create Application Data files and not see each others files. The filenames are text strings with zero byte terminators. Each entry is indexed with a multiple of 17 (16 byte filename max. plus zero byte). Location $11 R7H has the number of table entries unfilled. To get the number of files actually found, this value must be subtracted from the original maximum buffer length. 1-402 Function Name: FindFile Procedure: Lookup a filename in the directory. Call address: $C20B Input requirements: $0E-$0F R6 Pointer to filename. $886E Flag byte. Output: $04 R1L Track for directory sector. $05 R1H Sector for directory sector. $0C-$0D R5 Pointer to file name entry. $8000-$80FF diskBlkBuf: Directory sector. $8400-$841D dirEntryBuf: Copy of directory entry. Errors: See Appendix Description: This is a very useful routine. Given a text string of a filename, this routine will find it in the directory. If the flag byte at $886E is $FF, then both drives 8 and 9 will be scanned if necessary. If the flag is $00, then the lookup is only to the current drive. If there is only one drive, then this flag has no effect. The directory sector is loaded into a buffer at $8000, and the track and sector are in locations $04 and $05. The particular directory entry is copied to $8400 and the pointer to the entry in the buffer is stored at $0C-$0D R5. 1-403 Function Name: SaveFile Purpose: Save memory to a file. Call address: $C1ED Input requirements: $14-$15 R9 Pointer to information sector data. $16 R10L # directory sectors to skip first. Errors: See Appendix Description: This routine will save memory to a file; each sector is verified after the write is finished. The info sector has all the necessary information. i.e. start and stop addresses, file type and structure. It must also contain the address of the filename string somewhere in memory, in the first two bytes. If the file is a VLIR file, the memory is saved to chain 0. Location $16 R10L specifies the number of directory sectors to skip for SetGDirEntry and GetFreeDirBlk. 1-404 Function Name: WriteFile Purpose: Save memory to specified sectors on the disk. Call address: $C1F9 Input requirements: $0E-$0F R6 Pointer to list of tracks and sectors to use. $10-$11 R7 Start address of memory to be saved. Preparatory routines: BlkAlloc Errors: See Appendix Description: This routine is called by SaveFile to actually save the memory. All of the sectors should have already been allocated. This routine stops saving memory when track 0 is found in the list of tracks and sectors. 1-405 Function Name: RenameFile Purpose: Rename a file. Call address: $C259 Input requirements: $02-$03 R0 Pointer to new file name. $0E-$0F R6 Pointer to old file name. Output: $04 R1L Track of directory sector. $05 R1H Sector of directory sector. $0C-$0D R5 Pointer to file name in directory entry. $8400-$841D dirEntryBuf: Copy of old directory entry. Errors: See Appendix I. Description: This routine renames a file by calling FindFile, then copying the new name into the entry. Finally, the sector is rewritten to the disk. 1-406 Function Name: DeleteFile Purpose: Delete a file from the disk. Call address: $C238 Input requirements: $02-$03 R0 Pointer to file name. Errors: See appendix I. Description: The specified file is deleted from the current drive. 1-407 Function Name: FastDelFile Purpose: Delete a temporary file. Call address: $C244 Input requirements: $08-$09 R3 Pointer to table of tracks and sectors. $0E-$0F R6 Pointer to file name. Errors: See appendix I. Description: This routine removes the file from the directory. It uses the table of tracks and sectors to free up the sectors used by the file. This routine is used to clean up a temporary file that was not completed. 1-408 Function Name: FreeFile Purpose: Deallocates all of a file's sectors. Call address: $C226 Input requirements: $8400 dirEntryBuf: Current directory entry. $14-$15 R9 Pointer to directory entry. Preparatory routines: FindFile (Pointer must be copied). Errors: See Appendix I. Description: Given the directory entry of a file, all of its sectors are returned to the free pool. The directory pointer should be pointing to the directory entry at $8400 and not the pointer returned by FindFile. This is due to memory conflicts that will arise. This routine uses $8000-$82FF for its buffer areas. 1-409 Function Name: RstrAppl Purpose: Reload the SWAPFILE. Call address: $C23E Preparatory routines: LdDeskAcc Errors: See Appendix I. Description: This routine reloads the SWAPFILE, then deletes it. The last window description is reprocessed to restore the screen and control is returned to the original program that called LdDeskAcc. 1-410 Function Name: GetFile Purpose: Load and run a file. Call address: $C208 Input requirements: $02 R0L Flag byte (See description). $06-$07 R2 Optional data pointer. $08-$09 R3 Optional data pointer. $0E-$0F R6 Pointer to filename. $10-$11 R7 Load address (optional). Output: $8100-$81FF fileHeader: Info sector for file. $8300-$83FF fileTrScTab: Table of tracks and sectors loaded. Errors: See Appendix Description: This routine loads and runs a given file. The file must be one of the following GEOS types: System File Desk Accessory Application Application Data Printer Driver Input Driver The execution address is taken from the information sector. If it is zero, the file is not executed, only loaded. VLIR files have only their first chain loaded. Desk Accessories swap out the memory that they use to the SWAPFILE. Upon completion, the SWAPFILE is reloaded. The flag byte at location $02 has two purposes. This first is if bit 0 is set and the file was an application, then it is not executed. Also if bit 0 is set, then locations $10-$11 R7 have the load address; otherwise, the load address is taken from the information sector. This bit does not apply to Desk Accessories. If either bit 6 or 7 are set, then $06-$07 R2 points to 16 bytes which are copied to $8453 (dataDiskName), and $07-$08 point to 16 bytes which are copied to $8442 (dataFileName). 1-411 Function Name: LdFile Purpose: Load a file. Call address: $C211 Input requirements: $8400 dirEntryBuf - File directory entry. $14-$15 R9 Pointer to directory entry ($8400). $886B Flag byte. $886C-$886D Load address. Output: $8100-$81FF fileHeader: Info sector for file. $8300-$83FF fileTrScTab: Table of tracks and sectors loaded. Preparatory routines: FindFile (Pointer must be copied) Errors: See Appendix Description: This routine is called by GetFile to perform the load. This routine does not try to execute the file loaded, nor is it limited to the file types that GetFile is. However, this routine can not be used to load Non-GEOS files because the info sector must be present. If bit 0 of location $886B is set, then the load address is taken from locations $886C-$886D instead of the info sector. The directory entry pointer should point to $8400 and not the pointer returned by FindFile. This is due to memory conflicts that will arise. 1-412 Function Name: LdApplic Purpose: Load and possibly run a file. Call address: $C21D $02 R0L Flag byte (See description). $06-$07 R2 Optional data pointer. $08-$09 R3 Optional data pointer. $0E-$0F R6 Pointer to filename. $10-$11 R7 Load address (optional). Output: $8100-$81FF fileHeader: Info sector for file. $8300-$83FF fileTrScTab: Table of tracks and sectors loaded. Errors: See Appendix Description: This routine is called by GetFile to load Application files. Like LdFile, this routine is not limited to any particular file type, except that it also can not load a Non-GEOS file. See GetFile for a description of the flag byte, data pointers and load address. 1-413 Function Name: LdDeskAcc Purpose: Load and run a file using the SWAPFILE. Call address: $C217 Input requirements: $14-$15 R9 Pointer to directory entry. Output: $8100-$81FF fileHeader: Info sector for file (Modified). $8300-$83FF fileTrScTab: List of tracks and sectors loaded. Preparatory routines: FindFile (Pointer must be copied). Errors: See Appendix I. Description: This routine is used to load Desk Accessories. The info sector is loaded to determine the necessary memory region. This region is saved to a file called 'SWAPFILE', whose info sector is the same as the file to be loaded. The difference is that the text field is cleared, and the file type is System file (Type 4). RstrAppl must be eventually called to reload the SWAPFILE and return to normal operation. The directory entry pointer should point to $8400, and the pointer returned by FindFile. This is due to memory conflicts that will arise. 1-414 Function Name: ReadByte Purpose: Read a byte from a file. Call address: $C2B6 Input requirements: $0C R5L Index of last byte in buffer. $0D R5H Index to next character in buffer. $0A-$0B R4 Pointer to disk buffer. Output: A Character that was read. Errors: See Appendix I. Description: The initial sector must have been read because the first two bytes in the buffer are used to find the next track and sector. Bytes are read from the buffer until there are no more, then the next sector is read from the disk. This can continue until the last character of the last sector is read. After this an error 11 (End of file) will be returned. 1-415 Function Name: ReadFile Purpose: Load memory from disk. Call address: $C1FF Input requirements: $04 R1L Initial track number. $05 R1H Initial sector number. $06-$07 R2 Byte count of load. $10-$11 R7 Load address. Output: $0C R5L Index to last sector loaded. $8300- fileTrScTab: List of tracks and sectors loaded. Preparatory routines: GetFHdrInfo Errors: See Appendix I. Description: This routine assumes that the file has been located in the directory and that the initial track and sector are known. 1-416 Function Name: GetFreeDirBlk Purpose: Find a hole in the directory, or make one. Call address: $C1F6 Output: Y Index of hole in buffer. $04 R1L Directory track number (Should be 18). $05 R1H Directory sector number. $16 R10L # directory sectors to skip first. $8000-$80FF diskBlkBuf: Buffer for directory sector. Description: This routine scans the disk's directory looking for a deleted file, by first skipping a certain number of sectors. This allows the user to find a hole in a given directory page. If one is not found in any of the available directory sectors, then a new sector is added to the directory. 1-417 Function Name: SetGDirEntry Purpose: Creates a directory entry on the disk. Call address: $C1F0 Input requirements: $14-$15 R9 fileHeader ($8100), required. $16 R10L # of directory sectors to skip first. $8100-$81FF fileHeader: Information sector for file. $8300- fileTrScTab: Track and sector list for file. Outputs: $8400-$841D dirEntryBuf: Directory entry. Directory entry is written to the disk. Preparatory routines: BlkAlloc Errors: See appendix Description: This routine is used by SaveFile and calls BldGDirEntry. Because of this, assumptions are made. The first is that the information sector is at $8100-$81FF and that $14-$15 R9 point there. The first two bytes of the information sector are the address of the filename. These are reset by this routine to $00, $FF. Another assumption made by this routine is that $8300 is a list of useable tracks and sectors; specifically, $8300-$8301 are the track and sector for the information sector and $8302-$8303 are the track and sector of the first sector of the file. 1-418 Function Name: BldGDirEntry Purpose: Create a directory entry in memory. Call address: $C1F3 Input requirements: $14-$15 R9 fileHeader ($8100), required. $8100-$81FF fileHeader: Information sector for file. $8300- fileTrScTab: Track and sector list for file. Outputs: $8400-$841D dirEntryBuf: Directory entry. Preparatory routines: BlkAlloc Errors: See appendix Description: See SetGDirEntry for a complete list of all the assumptions made by this routine. 1-419 Function Name: GetFHdrInfo Purpose: Get the load address of a file. Call address: $C229 Input requirements: $14-$15 R9 Pointer to directory entry. Output: $04 R1L Track of file's first sector. $05 R1H Sector of file's first sector. $10-$11 R7 Load address for file. $8100-$81FF fileHeader: Info sector for file. $8300-$8301 fileTrScTab: Track and sector of info sector. Errors: See Appendix I. Description: This routine loads the info sector for a file into the buffer at $8100 (fileHeader). The load address is set from $8147-$8148. This routine is called by all the load routines. 1-420 Function Name: FollowChain Purpose: Create a table of tracks and sectors. Call address: $C205 Input requirements: $04 R1L Initial track number. $05 R1H Initial sector number. $08-$09 R3 Address of table to be created. Output: Table pointed to by $08-$09 is filled with all the tracks and sectors linked to the initial sector. Errors: See Appendix Description: Given an initial track and sector, this routine traces a chain and returns a list of all the tracks and sectors encountered. This routine uses diskBlkBuf at $8000-$80FF to read the sectors. VLIR file support ------------------------------------------------------------------ 1-501 Function Name: OpenRecordFile Purpose: Opens a VLIR file. Call address: $C274 Input requirements: $02-$03 R0 Pointer to file name. Output: $04 R1L Track of VLIR sector. $05 R1H Sector of VLIR sector. $0C-$0D R5 Pointer to file's directory entry. $8100-$81FF fileHeader: File's VLIR sector. $8496 curRecord: Initial chain # (Should be 0). $8497 usedRecords: Number of chains. $8498 fileWritten: Set to $00. (VLIR file modified). $8499-$849A fileSize: File size. $886F Track of file's directory entry. $8870 Sector of file's directory entry. $8871-$8872 Pointer to directory entry. $8873 Track for VLIR sector. $8874 Sector for VLIR sector. Errors: See Appendix I. Description: This routine opens a VLIR file, and sets up all the variables associated with it. Only one VLIR file can be open at a time due to the fact that these variables are global. 1-502 Function Name: PointRecord Purpose: Get a specific VLIR chain. Call address: $C280 Input requirements: A VLIR chain number. Output: Y Track of VLIR chain. $04 R1L Track of VLIR chain. $05 R1H Sector of VLIR chain. $8496 curRecord: Set to A. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine gets the track and sector of a specific chain in the open VLIR file. It does not check to see if the chain exists (i.e. track is zero). It does check if this chain is greater than zero and less than the number of VLIR chains at $8497 (usedRecords). VLIR chains are numbered from 0 to N-1, where N is the number of chains. 1-503 Function Name: PreviousRecord Purpose: Move to previous VLIR chain. Call address: $C27D Output: Y Track of VLIR chain. $04 R1L Track of VLIR chain. $05 R1H Sector of VLIR chain. $8496 curRecord: Decremented by 1. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine gets the track and sector of the previous chain in the open VLIR file. It does not check to see if the chain exists (i.e. track is zero). It does check if this chain is greater than zero. 1-504 Function Name: NextRecord Purpose: Move to next VLIR chain. Call address: $C27A Output: Y Track of VLIR chain. $04 R1L Track of VLIR chain. $05 R1H Sector of VLIR chain. $8496 curRecord: Incremented by 1. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine gets the track and sector of the next chain in the open VLIR file. It does not check to see if the chain exists (i.e. track is zero). It does check if this chain is in range against $8497 (usedRecords). 1-505 Function Name: InsertRecord Purpose: Insert a new chain in a VLIR file. Call address: $C286 Input requirements: $8496 curRecord: Current chain number. Output: $8497 usedRecords: Incremented by 1. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: A hole is opened up in the VLIR sector starting with the current chain. The hole is filled with $00,$FF. This represents a null chain. 1-506 Function Name: AppendRecord Purpose: Append a new chain in a VLIR file. Call address: $C289 Input requirements: $8496 curRecord: Current chain number. Output: $8496 curRecord: Incremented by 1. $8497 usedRecords: Incremented by 1. Preparatory routines: OpenRecordFile Errors: See appendix I. Description: A hole is opened up in the VLIR sector immediately following the current chain. The hole is filled with $00,$FF. This represents a null chain. This hole becomes the current chain. 1-507 Function Name: DeleteRecord Purpose: Remove a VLIR chain. Call address: $C283 Input requirements: $8496 curRecord: VLIR chain number. Output: $8496 curRecord: Decremented if greater than or equal to $8497. $8497 usedRecords: Decremented by 1. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: The current VLIR chain is removed from the VLIR sector, and all the following chains are moved down one. The sectors associated with that chain are freed up. 1-508 Function Name: ReadRecord Purpose: Load a VLIR chain. Call address: $C28C Input requirements: $06-$07 R2 Maximum byte count of load. $10-$11 R7 Load address. $8496 curRecord: Current chain number. Output: $8302-$83FF fileTrScTab: Table of tracks and sectors loaded. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine loads the current chain by calling ReadFile. 1-509 Function Name: WriteRecord Purpose: Save memory to a VLIR chain. Call address: $C28F Input requirements: $06-$07 R2 Length of save. $10-$11 R7 Address of memory to be saved. $8496 curRecord: VLIR chain number. Output: $8300-$83FF fileTrScTab: Table of tracks and sectors saved to. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine saves a block of memory to a VLIR chain. If the chain already existed, then it is deleted first. If the length of the save is 0, then no save is performed. This would allow this routine to be used as a delete chain function. 1-510 Function Name: UpdateRecordFile Purpose: Update a VLIR file. Call address: $C295 Output: $8498 fileWritten: Cleared to $00. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: This routine writes the open VLIR file's VLIR sector to disk and updates the file's directory entry on disk (Time, date and file size). This operation is not performed if location $8498 is zero to start with. That location is a flag that tells whether the file has been altered or not. This routine is called by CloseRecordFile. 1-511 Function Name: CloseRecordFile Purpose: Close a VLIR file. Call address: $C277 Output: $8873 Cleared to $00. Preparatory routines: OpenRecordFile Errors: See Appendix I. Description: The VLIR sector is rewritten to the disk and the directory is updated with a new time, date and file size by calling UpdateRecordFile. Location $8873 is the track number of the VLIR sector. By clearing it, GEOS says that the file is no longer in memory. Graphics ------------------------------------------------------------------ 1-601 Function Name: GraphicsString Purpose: Process several graphics commands designated by a table. Call address: $C136 Input requirements: $02-$03 R0 Pointer to the table of commands. Description: This routine executes the graphic commands present in a table. This routine is used by PutChar (Control-P),PutString (By calling PutChar), and DoDlgBox (Command 15). The following table describes the available commands. Graphic Command Table Command #Bytes Description $00 1 Stop, end of table. $01 4 MOVEPENTO: Set column and row variables. .word COLUMN .byte ROW $02 4 LINETO: Draw a line. .word DESTCOLUMN .byte DESTROW $03 4 RECTAGLETO: Pattern fill a region. .word BOTRIGHTCOLUMN .byte BOTRIGHTROW $04 1 No operation. $05 2 NEWPATTERN: Set fill pattern. $06 4+ ESC_PUTSTRING: Set position and display text. MUST BE last command because the zero byte that ends the text also ends this command table. .word COLUMN .byte ROW .byte "Hello World!",0 $07 4 FRAME_RECTO: Draw a solid lined box. .word BOTRIGHTCOLUMN .byte BOTRIGHTROW $08 3 PEN_X_DELTA: Add an offset to column variable. .word COLUMNOFFSET $09 2 PEN_Y_DELTA: Add an offset to row variable. .byte ROWOFFSET $0A 4 Add offsets to both column and row variables. .word COLUMNOFFSET .byte ROWOFFSET Command 1 is used to set the column and row variables used by all of the other commands which require two points. The format of the commands is that all of the necessary data follows the command byte. For example, the commands to erase the entire screen would look like this: .byte $05,$00 .byte $01 .word 0 .byte 0 .byte $03 .word 320 .byte 199 .byte $00 In the case of command 6, after the column and row bytes in the command comes the text that is to be displayed. For example: .byte $06 .word 50 .byte 50 .byte 'Hello world!' .byte $00 1-602 Function Name: i_GraphicsString Purpose: Identical to GraphicsString, but with inline data. Call address: $C1A8 Description: This routine takes an inline data table, creates a pointer to it, then calls GraphicsString to process it. See i_Rectangle for an example of inline data tables. 1-603 Function Name: SetPattern Purpose: Sets the current fill pattern. Call address: $C139 Input requirements: A The pattern number (0-31). Description: This routine sets the fill pattern used by Rectangle, i_Rectangle. 1-604 Function Name: FrameRectangle Purpose: Draws the outline of a rectangular box in a given pattern. Call address: $C127 Input requirements: A The actual bit pattern for the box. $06 R2L The top margin. $07 R2H The bottom margin. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. Description: This routine draws the outline of a rectangular box in a given pattern. This routine calls HorizontalLine and VerticalLine to draw the outline. See also GetScanLine. 1-605 Function Name: i_FrameRectangle Purpose: Identical to FrameRectangle, but with inline data. Call address: $C1A2 Description: This routine draws a solid outline of a box, which is described by inline code. See i_Rectangle for an example. 1-606 Function Name: Rectangle Purpose: Fills a rectangular box with a selected design. Call address: $C124 Input requirements: $06 R2L The top margin. $07 R2H The bottom margin. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. Preparatory routines: SetPattern Description: This routine fills a rectangular box in a given design. This routine calls HorizontalLine repeatedly. See also GetScanLine. 1-607 Function Name: i_Rectangle Purpose: Identical to Rectangle, but with inline data. Call address: $C19F Preparatory routines: SetPattern Description: This routine is identical to Rectangle except that data that describes the box is part of the inline code. For example: JSR i_Rectangle .byte Top margin .byte Bottom margin .word Left margin .word Right margin Control returns here after box is filled. 1-608 Function Name: RecoverRectangle Purpose: Copies a box from screen 2 to screen 1. Call address: $C12D Input requirements: $06 R2L The top margin. $07 R2H The bottom margin. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. Description: This routine copies a box from screen 2 ($6000) to screen 1 ($A000). Location $2F is unaffected. This routine calls RecoverLine repeatedly to copy each line of the box. 1-609 Function Name: i_RecoverRectangle Purpose: Identical to RecoverRectangle, but with inline data. Call address: $C1A5 Description: This routine copies a box from screen 2 ($6000) to screen 1 ($A000). The box descriptor is inline with the calling code. See i_Rectangle for an example. 1-610 Function Name: ImprintRectangle Purpose: Copies a box from screen 2 to screen 1. Call address: $C250 Input requirements: $06 R2L The top margin. $07 R2H The bottom margin. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. Description: This routine copies a box from screen 1 ($A000) to screen 2 ($6000). Location $2F is unaffected. This routine calls RecoverLine repeatedly to copy each line of the box. 1-611 Function Name: i_ImprintRectangle Purpose: Identical to ImprintRectangle, but with inline data. Call address: $C253 Description: This routine copies a box from screen 1 ($A000) to screen 2 ($6000). The box descriptor is inline with the calling code. See i_Rectangle for an example. 1-612 Function Name: InvertRectangle Purpose: Inverts the pixels in a box. Call address: $C12A Input requirements: $06 R2L The top margin. $07 R2H The bottom margin. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. Description: This routine reverses the pixels in a given box by repeatedly calling InvertLine. See also GetScanLine. 1-613 Function Name: RecoverLine Purpose: Copies a horizontal line from screen 2 to screen 1. Call address: $C11E Input requirements: $08-$09 R3 The left margin. $0A-$0B R4 The right margin. $18 R11L The row number. Description: This routine copies a horizontal line from screen 2 ($6000) to screen 1 ($A000). Location $2F is unaffected. 1-614 Function Name: InvertLine Purpose: Inverts a horizontal line on the screen. Call address: $C11B Input requirements: $08-$09 R3 The left margin. $0A-$0B R4 The right margin. $18 R11L The row number. Description: This routine reverses the pixels on a horizontal line on the hires screen. If the pixel was on it will now be off; if it was off it will now be turned on. See also GetScanLine. 1-615 Function Name: DrawLine Purpose: Draws, erases or copies a line on the hires screen. Call address: $C130 Input requirements: N flag C Flag Operation 1 X Copy 0 1 Draw 0 0 Erase $08-$09 R3 The column for the first endpoint. $0A-$0B R4 The column for the second endpoint. $18 R11L The row for the first endpoint. $19 R11H The row for the second endpoint. Description: This is a very versatile routine. It can copy an arbitrary line from one screen to another, as well as draw or erase lines. This routine places no restrictions on the relative positions of the endpoints. This routine calls DrawPoint to plot the points. See also GetScanLine. 1-616 Function Name: HorizontalLine Purpose: Draws a horizontal line on the screen. Call address: $C118 Input requirements: A The actual bit pattern for the line. $08-$09 R3 The left margin. $0A-$0B R4 The right margin. $18 R11L The row number. Description: This routine draws a horizontal line on the hires screen in a given pattern. See also GetScanLine. 1-617 Function Name: VerticalLine Purpose: Draws a vertical line on the screen. Call address: $C121 Input requirements: A The actual bit pattern for the line. $08 R3L The top margin. $09 R3H The bottom margin. $0A-$0B R4 The right margin. Description: This routine draws a vertical line on the hires screen in a given pattern. See also GetScanLine. 1-618 Function Name: GetScanLine Purpose: Computes the address of a given row on the hires screens. Call address: $C13C Input requirements: X The row number. $2F dispBufferOn: See description. Output: $0C-$0D R5 Pointer to the row on the destination screen. $0E-$0F R6 Pointer to the row on the source screen. Description: This routine computes the address of column 0 on a given row of the hires screens. All of the graphics routines rely on this routine to get the address of the hires screens. They all take the data pointed to by $0E-$0F and store their data to both $0C-$0D R5 and $0E-$0F R6. Location $2F determines which screen is pointed to by which pointer. This is as follows: Bit 7 Bit 6 $0C-$0D $0E-$0F 0 0 $AF00 $AF00 Approximately the middle of screen 1 0 1 Screen 2 Screen 2 ST_WR_BACK 1 0 Screen 1 Screen 1 ST_WR_FORE 1 1 Screen 1 Screen 2 (Default at reset) 1-619 Function Name: TestPoint Purpose: Tests the value of a point on the hires screen. Call address: $C13F Input requirements: $08-$09 R3 The column number. $18 R11L The row number. Output: C flag is set to the value of the pixel. Description: Tests whether or not a given pixel is on or not. The carry flag is set to the value of the pixel. 1-620 Function Name: DrawPoint Purpose: Draws, erases or copies a pixel on the hires screen. Call address: $C133 Input requirements: N flag C Flag Operation 1 X Copy 0 1 Draw 0 0 Erase $08-$09 R3 The column number. $18 R11L The row number. Description: This is a very versatile routine. It can copy a point from one screen to another, as well as draw or erase it. This routine is called by DrawLine to draw lines. See also GetScanLine. 1-621 Function Name: BitmapUp Purpose: Draws a click box on the screen. Call address: $C142 Input requirements: $02-$03 R0 Pointer to the graphic data. $04 R1L Column in characters. $05 R1H The row in pixels. $06 R2L The width in bytes. $07 R2H The height in pixels. Description: This routine draws a click box on the screen. A click box is a box like Ok, Open, etc. These boxes are generally part of a window description. The graphic data is in a coded format. This format consists of a code byte followed by 1 or more data bytes. 1) Code bytes less than 128 mean that the following byte is to be repeated that many times. 2) Code bytes ranging from 128 to 219 mean that if 128 is subtracted from the code byte, then the result is the number of data bytes that follow. 3) Code bytes ranging from 220 to 225 are special. First 219 is subtracted from the code byte, the result is the number of bytes in the pattern. Following this code byte is a repetition count for the pattern. Following this are the bytes that constitute the pattern. These could include either of the previous two code types. 1-622 Function Name: i_BitmapUp Purpose: Identical to BitmapUp, but with inline data. Call address: $C1AB Description: This routine takes a click box descriptor from inline data and draws it. The inline data does NOT include the processing vector, i.e. JSR DRWCB2 .word address of graphic image .byte start column in bytes .byte start margin in pixels .byte width of box in bytes .byte height of box in pixels Control returns here after the box is drawn. 1-623 Function Name: BitmapClip Purpose: Draw a section of a coded graphic image. Call address: $C2AA Input requirements: $02-$03 R0 Pointer to graphic image data. $04 R1L Column to start on, in bytes. $05 R1H Row to start drawing the image on. $06 R2L Image width in bytes (<= actual width). $07 R2H Image height in pixels (<= actual height). $18 R11L # bytes to skip on the left side. $19 R11H # bytes on the right side. $1A-$1B R12 # rows to skip from the bottom. Description: The coding of the image is the same as that of the click boxes, see BitmapUp for more information. This routine seems to be for drawing pieces of Photo Scraps. Photo Scraps have this coded format. The parameters for this routine allow a section of the image to be drawn by specifying how many rows to skip down, as well as how many bytes to skip on the left and the right of the desired section. This is not used by GEOpaint unless GEOpaint converts its files because they are in a different format; however, Photo Scraps are in this format. 1-624 Function Name: BitOtherClip Purpose: Draw a section of a coded graphic image. Call address: $C2C5 Input requirements: $02-$03 R0 Pointer to graphic image buffer (134 bytes). $04 R1L Column to start on, in bytes. $05 R1H Row to start drawing the image on. $06 R2L Image width in bytes. (<= actual width) $07 R2H Image height in pixels (<= actual height) $18 R11L # bytes to skip on the left side. $19 R11H # bytes on the right side. $1A-$1B R12 # rows to skip from the bottom. $1C-$1D R13 Byte read and save routine vector. $1E-$1F R14 Sync routine vector. Description: This routine is identical to BitmapClip, except that before each byte is read, the first user routine is called. It should return its byte in A and save that byte to the address currently pointed to by R0 before returning. The second routine need only reload R0 with the address of the image buffer. 1-625 Function Name: DrawSprite Purpose: Copies a sprite into GEOS's storage area. Call address: $C1C6 Input requirements: $08 R3L The sprite number (0-7). $0A-$0B R4 Pointer to the sprite data. Description: This routine simply copies 63 bytes of data pointed to by $0A-$0B (R4) to the specified sprite block. GEOS uses sprite blocks 40 to 47. 1-626 Function Name: PosSprite Purpose: Sets the position of a sprite. Call address: $C1CF Input requirements: $08 R3L Sprite number (0-7). $0A-$0B R4 Sprite X position. $0C R5L Sprite Y position. Preparatory routines: DrawSprite Description: This routine copies the sprite's position to the VIC chip, relieving the user of the burden of handling the crossover in the screen from column 255 to column 256. 1-627 Function Name: EnablSprite Purpose: Turns on a sprite. Call address: $C1D2 Input requirements: $08 R3L Sprite number (0-7). Preparatory routines: DrawSprite, PosSprite Description: This routine turns the sprite on, so that it is visible. 1-628 Function Name: DisablSprite Purpose: Turns off a sprite. Call address: $C1D5 Input requirements: $08 R3L Sprite number (0-7). Preparatory routines: DrawSprite, PosSprite, EnablSprite Description: This routine turns the sprite off, so that it is no longer visible. Controls ------------------------------------------------------------------ 1-701 Function Name: DoMenu Purpose: Draws and sets everything up for pull down menus and submenus. Call address: $C151 Input requirements: A Menu option to position mouse on (0 to #options-1) $02-$03 R0 Pointer to the menu descriptor. Description: This is an EXTREMELY powerful routine. It does EVERYTHING for menu processing. Once control returns to the program that created the menu, the program can return to the GEOS main line, or do anything else. It is important to note that menus only appear on screen 1. Location $2F is saved and restored during the drawing phase. The left and right margins are also left unaltered. The following is a description of a menu descriptor: #bytes Description 1 Top margin of entire menu. 1 Bottom margin of entire menu. 2 Left margin of entire menu. 2 Right margin of entire menu. 1 Code byte: bit 7 - HORIZONTAL/VERTICAL: vertical menu. bit 6 - CONSTRAINED/UNCONSTRAINED: set secondary box descriptor to full screen; this allows the mouse to be moved outside of a menu without causing it to be closed. bits 0-4 - # entries in menu. This is followed by sets of 5 bytes; as many as there are entries. 2 Address of the text for this option. 1 Code byte which describes what to do with the address that follows: $80 - SUB_MENU: operand is the address of a submenu descriptor. $40 - DYN_SUB_MENU: call subroutine, it must return a result in $02-$03 R0 which is either 0 or the address of the next submenu. $00 - MENU_ACTION: This option is selected it will flash before the routine is executed. Control does not return to the menu processor. 2 Address of either a submenu descriptor or a routine to be executed. 1-702 Function Name: DoPreviousMenu Purpose: Backs up a menu level. Call address: $C190 Description: This routine erases the present menu, and pops back one level. 1-703 Function Name: GotoFirstMenu Purpose: Closes all menu levels. Call address: $C1BD Preparatory routines: DoMenu Description: This routine is not the same RecoverAllMenus. The menus are cleared one at a time and the previous levels are reprocessed in reverse order until all menus are closed. 1-704 Function Name: ReDoMenu Purpose: Redraws the present menu. Call address: $C193 Description: This routine redraws the current menu. 1-705 Function Name: RecoverMenu Purpose: Erases the current menu from the screen. Call address: $C154 Preparatory routines: DoMenu Description: This routine will erase the current menu. It does NOT pop up a level. It simply erases it from the screen. If the vector at $84B1 (RecoverVector) was set, then that is the routine called to erase the menu; otherwise, a blank pattern is selected with SetPattern and Rectangle is called. The default setting for $84B1 (RecoverVector) is RecoverRectangle. 1-706 Function Name: RecoverAllMenus Purpose: Erases all open menus. Call address: $C157 Preparatory routines: DoMenu Description: This routine erases all of the menus. It calls RecoverMenu repeatedly to accomplish this. It then sets the menu level counter at $84B7 (menuNumber) to $00. 1-707 Function Name: DoIcons Purpose: Draws all of the click boxes in a table. Call address: $C15A Input requirements: $02-$03 R0 Pointer to a click box table (Usually $880C). Preparatory routines: DoDlgBox (optional). Description: This routine draws all of the click boxes by calling BitmapUp repeatedly until the table is exhausted. StartMouseMode is called to set the mouse's position. Click table format: #bytes Description 1 # click boxes in table. 2 Column to place mouse in (0 will prevent placement). 1 Row to place mouse in. This is followed by sets of 8 bytes, one for each click box. 2 Address of graphic data. 1 Column position of box in characters. 1 Row position of box in pixels. 1 Width of box in bytes. 1 Height of box in pixels. 2 Address of routine to process this box. 1-708 Function Name: DoDlgBox Purpose: Process a window descriptor. Call address: $C256 Input requirements: $02-$03 R0 Pointer to window descriptor. Output: $02 R0L Window command that closed the window. $851D sysDBData: Window command that closed the window. Description: Like DoMenu, this is another very powerful routine. Given a description of the window's commands, everything gets handled. The format of the window descriptor is as follows: .byte Window type. Bit 7 Window size follows; otherwise, use standard window size rows 40 to 135, columns 72 to 263. Bits 0-4 Fill pattern for shadow. If zero, then no shadow is drawn. The following six bytes are only present if bit 7 of the window type is set. .byte Top margin. .byte Bottom margin. .word Left margin. .word Right margin. .byte Command bytes followed by whatever data is needed. All the click box descriptors are stored in a table at $880C, for GEOS to process them. This limits the number of click boxes in a window to 8. Several memory locations are saved prior to processing the window; also the stack pointer and return address are saved. After the window is drawn, control passes back to MainLoop. RstrFrmDialogue must be called to return to the caller. Therefore it is essential that some means of closing a window exists, otherwise a situation like Panic will occur (See the Panic routine for more info). The command that closes the window is the value returned to the user. i.e. if a click box closes the window then the command number that drew the click box is returned. However it is the user's routine's responsibility to set the value of location $851D if a user click box is to close the window. Command #13 is another one that can close the window. User routines do not have to close the window but they may if they so desire. The following is a list of the memory addresses stored by the window processor: $22-$38 $849B-$84C0 $86C0-$87D3 $8FF8-$8FFF $3F-$40 $D000-$D010 $D01B-$D01D $D025-$D026 $D015 $D028-$D02E Window Processor Commands 0 No data. This command ends the window descriptor. 1 The data for this command is the column offset in bytes and the row offset in pixels. Draw an 'OK' click box. .byte COLUMNBYTE .byte ROWOFFSET 2 The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Cancel' click box. .byte COLUMNBYTE .byte ROWOFFSET 3 The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Yes' click box. .byte COLUMNBYTE .byte ROWOFFSET 4 The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'No' click box. .byte COLUMNBYTE .byte ROWOFFSET 5 The data for this command is the column offset in bytes and the row offset in pixels. Draw an 'Open' click box. .byte COLUMNBYTE .byte ROWOFFSET 6 The data for this command is the column offset in bytes and the row offset in pixels. Draw a 'Disk' click box. .byte COLUMNBYTE .byte ROWOFFSET 7-10 Are undefined commands. 11 The data for this command is the column offset in pixels, the row offset in pixels, and the address of a text string. This command displays the text string at the specified offset in the window. .byte COLUMNOFFSET .byte ROWOFFSET .word POINTERTOTEXTSTRING 12 The data for this command is the column offset in pixels, the row offset in pixels and zero page address of the address of a text string. This command is similar to command 11, except for its method of addressing the string. .byte COLUMNOFFSET .byte ROWOFFSET .byte R0 13 The data for this command is the column offset in pixels, the row offset in pixels, zero page address of the address o