ELLIPSE (draw an ellipse) Draws an oval with radii r1 and r2 at the current cursor coordinates. To draw a circle, set r1 equal to r2. PRoc NAME The PROC instruction allows you to call any Basic procedure directly within a menu line. The called procedure must NOT include parameters, otherwise a syntax error will be indicated. This command allows you to customize the menu precisely to your own needs without having to limit yourself to the available menu commands. In order to exploit these features, you'll need to understand a little bit of theory. At the start of your procedure the following values are held in the 68000's processor registers. This holds the graphical X coordinate of the top left corner of the current menu item. Don't draw your gfxs over the part of the screen to the left of this point as this will confuse the menu redrawing process and may lead to unwanted effects. Contains the Y coordinate of your menu item. As with the X coordinate you should always limit your drawing operations to the region below this point to avoid possible errors. This register holds the current status of the menu operations. If it contains a value of 0 (false) the menu item is being drawn. In this case you will need to load Dreg(0) and Dreg(1) with the coordinates of the bottom right corner of your menu zone and return from the procedure immediately. If Dreg(0) is -1 (true) you are free to perform your gfx operations used by your procedure. After you have finished you should return the coordinates of the bottom right corner of your item in Dreg(0) and Dreg(1) as before. D3 is loaded with a value of -1 if the menu is highlighted and the first menu string is displayed, otherwise it will contain a value 0. D4 is set to TRUE when the menu branch is initially opened. Address of reserved zone This is the address of the zone created with RESERVE. It's used to allow several procedures to communicate with each other. See RESERVE for more details. The general structure of a menu procedure is: Procedure ITEM The dimensions of the menu item as displayed on the screen are set using the coordinates BX and BY. These MUST be loaded into registers D0 and D1 before leaving your procedure as they are needed to create the final menu bar. While inside your procedure you can perform most instructions including other procedures. But some instructions are absolutely forbidden! If you use these commands, you won't get an error message but your AMIGA may crash unexpectedly! * NEVER change the current screen inside a menu. * Don't set or reset a screen zone * Avoid using instructions such as WAIT, WAIT KEY, INPUT or INKEY$ * Disc operations are absolutely forbidden! * Any error trapping in your procedure will be ignored. Used with caution, the PROC command can procedure some mind-blowing effects. For a demonstration, load EXAMPLE 16.10. RESERVE (reserve a local data area for a procedure) Reserves n bytes of memory for this menu item. This area can be accessed from within your menu procedure using the address held in AREG(1). The data area you have created is common to all the strings in the current menu object. It can be used to exchange parameters between the various procedures called by a menu item. MENU CALLED (redraw a menu item continually) Automatically redraws the selected menu item 50 times a second whenever it's displayed on the screen. It's usually used in conjunction with a menu procedure to generate animated menu items which change in front of your eyes. In order to make use of this function, you first need to define a menu procedure, using the principles outlined above. Then add a call to this procedure in the required title strings using an embedded MENU CALL. When the user displays the chosen item, your procedure will be repeatedly accessed by the menuing system. Since your procedure will be called 50 times a second, it should obviously return back to the menu as quickly as possible. This will allow enough time for the rest of the menu to be successfully updated. Also note that your embedded procedure can safely animate your item using either bobs or sprites. However, as the menu items are NOT double buffered, your bobs may flicker slightly on the screen. So it may be better to use computed sprites for this purpose instead. Another approach is to draw your display with the standard graphics commands. An example of this can be seen in EXAMPLE 16.11. MENU ONCE (turns off automatic redrawing) Turns off the automatic updating system started using the MENU CALLED. Alternative menu styles ======================= Normally the titles of a menu are displayed as a horizontal line and the options are arranged below it in a vertical menu bar. If you want to create something a little unusual, you can change the format of each level of your menu using the following three instructions: MENU LINE (display a menu as a horizontal line of items) Displays the menu options at the requested level in the form of a horizontal line. This menu line starts from the left-hand corner of the first title and stretches to the bottom right corner of the last. MENU LINE level Defines the menu style of an entire level of your menu. This should only be called during your menu definitions. Normally one would only use the "level" version for this command. Setting individual items to Line and Bar can give bizarre results, but this may be useful for something! MENU TLINE (display a menu as a total line) Displays a section of the menu as a "total line" stretching from the very left of the screen to the very right. The entire line will be drawn even when the first item is in the middle of the screen. "level" is a number ranging from 1 to 8 which specifies the part of the menu to be affected. This is the standard form of the instruction, and should be called during your menu definitions as otherwise it will have no effect. You can also change the appearance of a menu after it has been writed using a second form of this command. For example, MENU BAR (display a section of the menu as a bar) This displays the selected menu items in the form of a vertical bar. The width of this bar is automatically set to the dimensions of the largest item in your menu. "level" is a number which indicates which part of the current menu definition is to be affected. As a default this option is used for levels 2 to 8 in your menu. Note that this form of the MENU BAR instruction may only be used during your programs initialization phase. (,,) is a list of parameters which allow you to change the style of your menus once they've been installed. Here's an example of Menu Bar and Menu Tline: MENU INACTIVE (turn off menu item) As its name suggests, MENU INACTIVE deactivates a series of options in your menu. Any subsequent attempts to select these items will be completely ignored. "level" allows you to deactivate an entire section of the menu and you can also deactivate individual menu options with the parameters (,,). These indicate the precise position of your item in the current menu hierarchy. Note that the menu items you've turned off with the instruction will be immediately replaced by the INACTIVE$ string you specified during your original menu definition. If this was omitted, any unavailable menu options will be shown in italics. MENU ACTIVE (activate a menu item) Simply reverses the effect of a previous MENU INACTIVE command. After you've called this instruction, the selected options will automatically redisplayed using their original title strings. Movable menus ============== Menus can be displayed at any point on the screen. Menus can be moved either explicitly by your program or directly by the user. MENU MOVABLE (activate automatic menu movement) Informs the menuing system that the menu items at "level" may be moved directly by the user - this is the default. The second form of this command allows you to set the status of each individual item in the menu. The parameters between the brackets can indicate any position in the menu hierarchy. Any menu may be repositioned by moving the mouse pointer over the FIRST item in the menu and pressing the left mouse button. A rectangular box will now appear around the selected menu item, and this may be moved to nay point on the current screen. When you release the left button the menu will be redrawn at the new position along with all the associated menu items. Note that this command does not allow you to change the arrangement of any items below this level. If you want to manipulate the individual menu options you'll need to use a separate MENU ITEM command. See EXAMPLE 16.12 for a demonstration of this system. MENU STATIC (fix a menu into place) Defines the menu at "level" to be immovable by the user. One problem with movable menu is that the amount of the memory they consume will change during the course of a program. If your menus are particularly large, or if memory is running tight, this can cause real problems as a single careless action by the user will abort your program with an "out of memory" error. With the help of the MENU STATIC command you can avoid this difficulty completely. MENU ITEM MOVABLE (move individual menu options) This command is similar to MENU MOVABLE except that it allows you to re-arrange the various options in a particular level. So all the items in a menu bar may been individually repositioned by the user. Normally it's illegal to move the items outside the current menu bar, but this can be overridden using the MENU SEPARATE command. In order for the menu items to be movable, the WHOLE menu bar must also be movable. So if you fix the MENU into place with MENU STATIC, this command will have no effect. Additionally you can't move the first item in the menu bar as this will move the entire line. Another side effect is that moving the last menu item will permanently reduce the size of your menu bar. There are two possible solutions: * Enclose your entire bar with a rectangular box like so: Menu$(1,1)=,,,"(Bar 40,100)(Loc 0,0)" Where MENU$(1,1) is the first item in your current bar. * Set the last item into place with MENU ITEM STATIC.