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 of the text buffer to be used by GetString and the maximum length of the input buffer. See GetString for more information. .byte COLUMNOFFSET .byte ROWOFFSET .byte R0 .byte NUMBEROFBYTES 14 Set the vector at $84A9-$84AA (otherPressVec) to close the window. Generally used with command 13. I think this makes the window close on mouse click. 15 The data for this command is the address of a GraphicsString command table. See GraphicsString for further information. .word TABLEADDR 16 The data for this command is the column offset in pixels and the row offset in pixels. This command opens a scrolling window of filenames. Locations $10 R7L and $16-$17 R10 must be set prior to calling DoDlgBox (See FindFTypes for more information). The filenames are stored at $8300-$83FF, (fileTrScTab) to a maximum of 15 filenames. Location $885C will return the index of the selected file name. If more than 6 files are found, the subwindow will have a click box for scrolling the list. .byte COLUMNOFFSET .byte ROWOFFSET 17 The data for this command is the address of the routine for button pressed. This command sets the vector at $84A9-$84AA (otherPressVec) to a user specified routine. .word VECTORADDR 18 The data for this command is the column offset in bytes, the row offset in pixels and the address of a user's 8 byte click box description, in the following format: #bytes Description 2 Address of graphic data. 2 Not used. 1 Width of box in bytes. 1 Height of box in pixels. 2 Address of routine to process this box. .word COLUMNOFFSET .byte ROWOFFSET .word CLICKBOXDATAADDR 19 The data for this command is the address of a user subroutine. This command calls the user's subroutine. .WORD USERROUTINE 1-709 Function Name: RstrFrmDialogue Purpose: Close a window. Call address: $C2BF Output: $02 R0L Command byte from window processor. $851D sysDBData: Command byte from window processor. Description: The window is erased and the memory addresses that the window processor saved are restored. Control returns to the caller of DoDlgBox. 1-710 Function Name: IsMseInRegion Purpose: Check if the mouse is in a box. Call address: $C2B3 Input requirements: $06 R2L Top margin. $07 R2H Bottom margin. $08-$09 R3 Left margin. $0A-$0B R4 Right margin. Output: A $00 - outside box, $FF - inside box. Description: This routine simply compares the present mouse location stored at locations $3A-$3C against the box's boundaries. A is set to $00 if the mouse is outside, $FF if it is inside. 1-711 Function Name: Panic Purpose: Draw a system error window, and halt system. Call address: $C2C2 Description: A window is drawn with the message 'System error near $xxxx', where xxxx is the hex address of the JSR Panic instruction. Since the system error window has no way of being closed, GEOS simply sits in its main loop forever. The BRK vector at $84AF-$84B0 (BRKVector) is initially set to this routine.