@Database "Menus" @node "Menus" @toc "Guide2Blitz:Guide2Blitz.guide/MAIN" Chapter 12 : Menus ------------------ For anyone who wishes to use their Amiga for other purposes than playing games there is a wealth of literature aimed at teaching basic programming techniques. Many who have mastered aspects of the BASIC language find themselves directed towards writing games programs rather than more serious applications. The main reason for that is the lack of direction in the literature towards developing business or educational type programs. We can, however develop a technique for writing non-games type programs which is both simple in concept and in widespread use on all computer systems. The resulting programs come under the general category of "Menu driven programs". Menus are lists of items, or options. Menu titles can be seen by pressing the right-hand mouse button. To observe the contents of a menu, point at the appropriate title with the mouse pointer and the options will appear directly beneath the menu title. These options are selected by moving the mouse pointer over the desired option and releasing the mouse button whilst it is highlighted. These menus, or MenuList objects, can contain menu titles, menu items and possible even sub-menu items. Menus are attached to windows after the window has been opened, with the SETMENU statement. Each window can have its own menus, allowing complex user interfaces to be created. This chapter will take a look at creating menu driven programs and manipulating menus in Blitz Basic 2. 12.1 Defining menus ------------------- Each list of menu options must have a menu title, which appears at the very top of the menu. MENUTITLE Mode(s): Amiga/Blitz Statement: add a menu title to a MenuList Syntax: MenuTitle MENULIST,MENU#,TITLE$ This statement is used to create the Intuition menu titles which appear when the right mouse button is held down. The MENU# parameter specifies the number of the title. The title at the left-hand edge of the menu title is given a value of (0), followed by (1) for the next title and so on. TITLE$ is the text that will appear when the right mouse button is used. Here is an example: ; *** MenuTitle example ; *** Filename - MenuTitle.bb2 ; *** Define menu title MenuTitle 0,0,"Project" ; *** Define menu option (see later) MenuItem 0,0,0,0,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,160,100,$100f,"Blitz Basic",1,2 ; *** Attach menu to window (see later) SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=0 End 12.1.1 Text menu items ---------------------- Menu items are the options which appear directly beneath a menu title. MENUITEM Mode(s): Amiga/Blitz Statement: create a text menu item Syntax: MenuItem MENULIST,FLAGS,MENU#,ITEM,TEXT$[,SHORT$] The MENUITEM statement creates a text menu item. Menu items are the options which appear directly below menu titles in Intuition menus. FLAGS is a special parameter which controls the status of an individual menu item: Table 12.1 : The FLAGS parameter FLAG Description ===================================================== 0 Standard menu item 1 Toggle-type menu item (toggled by user) 2 Toggle-type menu item (toggled by FLAG 2 items) 3 As FLAG 1 but initially "On" 4 As FLAG 2 but initially "On" The MENU# parameter is the number of the menu title under which the menu item will appear. ITEM is the option number for the menu item. Menu items with an option number of (0) appear at the top of an options list, followed by (1), and so on. TEXT$ is the option text. The optional SHORT$ parameter specifies a one character "keyboard shortcut" for the menu item. For example: ; *** MenuItem example ; *** Filename - MenuItem.bb2 ; *** Define menu title MenuTitle 0,0,"Project" ; *** Define menu options MenuItem 0,0,0,0,"Load" MenuItem 0,0,0,1,"Save" MenuItem 0,0,0,2,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,160,100,$100f,"Blitz Basic",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=2 End ; *** MenuItem example 2 ; *** Filename - MenuItem2.bb2 ; *** Define menu title MenuTitle 0,0,"Project" ; *** This option is a toggle item ; *** and has the keyboard short-cut ; *** right Amiga + T MenuItem 0,3,0,0," Toggle ","T" MenuItem 0,0,0,1,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=1 End SUBITEM Mode(s): Amiga/Blitz Statement: create a sub-menu item Syntax: SubItem MENULIST,FLAGS,MENU#,ITEM,SUB,TEXT$[,SHORT$] All menu items may have an optional list of sub-menu items attached to them. This is where the SUBITEM statement comes in. The ITEM parameter specifies the menu item to attach the sub item to. SUB is the index number for this sub item, those with number (0) appear at the top of the sub item list, followed by (1) and so on. The TEXT$ parameter is the sub item text. As with menu items, sub items may have keyboard shortcuts attached with the optional SHORT$ parameter (see the MENUITEM statement for details of the other parameters): ; *** SubItem example ; *** Filename - SubItem.bb2 ; *** Define menu title MenuTitle 0,0,"Project" ; *** Define menu option 0 MenuItem 0,0,0,0,"Load" ; *** Define menu option 0 sub-options SubItem 0,0,0,0,0,"Picture" SubItem 0,0,0,0,1,"Sample" ; *** Define menu option 1 MenuItem 0,0,0,1,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=1 End 12.1.2 Shape menu items ----------------------- Shape menu items are the graphical elements which appear directly beneath menu titles. They use pictures, instead of words, as options. SHAPEITEM Mode(s): Amiga/Blitz Statement: create a graphical menu item Syntax: ShapeItem MENULIST,FLAGS,MENU#,ITEM,SHAPE# The SHAPEITEM statement is used to create a graphical menu item. As with the MENUITEM statement, the FLAGS parameter controls the status of an individual menu item: Table 12.2 : The FLAGS parameter FLAG Description ===================================================== 0 Standard menu item 1 Toggle-type menu item (toggled by user) 2 Toggle-type menu item (toggled by FLAG 2 items) 3 As FLAG 1 but initially "On" 4 As FLAG 2 but initially "On" The MENU# parameter is the number of the menu title under which the menu item will appear. ITEM is the option number for the menu item. Menu items with an option number of (0) appear at the top of an options list, followed by (1), and so on. SHAPE# specifies the number of a previously initialised shape object to be used as the graphics. Here is an example: ; *** ShapeItem example ; *** Filename - ShapeItem.bb2 ; *** Open screen and grab its BitMap Screen 0,3 ScreensBitMap 0,0 BitMapOutput 0 ; *** Create a shape Cls 2 Boxf 30,30,60,60,5 Circlef 100,40,10,6 GetaShape 0,30,30,60,60 GetaShape 1,90,30,110,50 Cls ; *** Define menu title MenuTitle 0,0,"Shape item" ; *** Define shape options ShapeItem 0,0,0,0,0 ShapeItem 0,0,0,1,1 ; *** Open Intuition window Window 0,0,20,200,100,$100f,"Select a menu",1,2 ; *** Attach menu to window SetMenu 0 ; *** Circle item quits Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=1 End SHAPESUB Mode(s): Amiga/Blitz Statement: create a graphic sub-menu item Syntax: ShapeSub MENULIST,FLAGS,MENU#,ITEM,SUBITEM,SHAPE# SHAPESUB creates a graphical sub-menu item. The ITEM parameter specifies the menu item to attach the sub item to. SUBITEM is the index number for this sub item, those with number (0) appear at the top of the sub item list, followed by (1) and so on. The SUBTEXT$ parameter is the sub item text. As with menu items, sub items may have keyboard shortcuts attached with the optional SHORTCUT$ parameter (see the SHAPEITEM statement for details of the other parameters). SHAPE# is the number of a previously initialised shape object to be used as the graphic. For example: ; *** ShapeSub example ; *** Filename - ShapeSub.bb2 ; *** Open screen and grab its BitMap Screen 0,3 ScreensBitMap 0,0 BitMapOutput 0 ; *** Create a shape Cls 2 Boxf 30,30,60,60,5 Circlef 100,40,10,6 GetaShape 0,30,30,60,60 GetaShape 1,90,30,110,50 Cls ; *** Define menu title MenuTitle 0,0,"Shape item" ; *** Define shape option ShapeItem 0,0,0,0,0 ; *** Define shape sub-option ShapeSub 0,0,0,0,0,1 ; *** Open Intuition window Window 0,0,20,200,100,$100f,"Select a menu",1,2 ; *** Attach menu to window SetMenu 0 ; *** Circle item quits Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=0 End 12.2 Creating menus ------------------- To make a menu visible it must be attached to a window with the SETMENU statement. SETMENU Mode(s): Amiga Statement: attach a MenuList to the current window Syntax: SetMenu MENULIST This statement attaches a MenuList to the currently used window. Each window may have only one MenuList attached to it. For example: ; *** SetMenu example ; *** Filename - SetMenu.bb2 ; *** Define a menu MenuTitle 0,0,"Project" MenuItem 0,0,0,0,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=0 End 12.3 Manipulating menus ----------------------- The state, layout and colour of menus and menu options can be altered with the following MenuList commands. MENUCOLOUR Mode(s): Amiga/Blitz Statement: determine the colour of a menu item Syntax: MenuColour COLOUR The MENUCOLOUR statement is used to set the colour of the text in a menu item or sub item. Here is an example: ; *** MenuColour example ; *** Filename - MenuColour.bb2 ; *** Define menu title MenuTitle 0,0,"Project" ; *** Alter text colour MenuColour 3 MenuItem 0,0,0,0,"I want to" ; *** Alter text colour again MenuColour 5 MenuItem 0,0,0,1,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT option is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=1 End MENUGAP Mode(s): Amiga/Blitz Statement: control layout of a menu Syntax: MenuGap X_GAP,Y_GAP Executing MENUGAP before creating any menu titles, items or sub items, allows you to control the layout of the menu. The X_GAP and Y_GAP parameters specify an amount, in pixels, to be inserted to the left and right of all menu items and sub-menu items. Try the following example: ; *** MenuGap example ; *** Filename - MenuGap.bb2 ; *** Set menu gap MenuGap 60,30 ; *** Define menu title MenuTitle 0,0,"Project" MenuItem 0,0,0,0,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT optin is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=0 End SUBITEMOFF Mode(s): Amiga/Blitz Statement: control the position of sub items to menu options Syntax: SubItemOff X_OFFSET,Y_OFFSET The SUBITEMOFF statement controls the relative position of the top of a list of sub-menu items in relation to their associated menu item: ; *** SubItemOff example ; *** Filename - SubItemOff.bb2 ; *** Define menu title MenuTitle 0,0,"Project" MenuItem 0,0,0,0,"I want to" ; *** Set option offset SubItemOff 80,80 SubItem 0,0,0,0,0,"Quit" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 ; *** Repeat until QUIT optin is selected Repeat Until WaitEvent=256 AND MenuHit=0 AND ItemHit=0 End MENUSTATE Mode(s): Amiga/Blitz Statement: turn menu items on or off Syntax: MenuState MENULIST[,MENU#[,ITEM[,SUB]]],On/Off This statement is used to turn entire menus or parts of menus on or off. If the following syntax is used then a whole active menu may be turned off: MenuState MENULIST On/Off If the MENU# parameter is included then a menu may be turned on or off: MenuState MENULIST,MENU#,On/Off Menu items and sub items can also be toggled by the inclusion of the appropriate parameters. Try the following example which illustrates this: ; *** MenuState example ; *** Filename - MenuState.bb2 ; *** Define menu title MenuTitle 0,0,"Project" MenuColour 3 ; ** This item will be turned off MenuItem 0,0,0,0,"Load" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 MenuState 0,0,0,Off ; *** Wait for a mouse click Repeat Until WaitEvent=$8 End MENUCHECKED Mode(s): Amiga/Blitz Function: read status of a toggle-type menu item Syntax: s=MenuChecked(MENULIST,MENU#,ITEM[,SUBITEM]) This function reads the status of a toggle-type menu item or menu sub item. If the item is currently "checked" then MENUCHECKED wil return (-1), otherwise (0) will be returned. For example: ; *** MenuChecked example ; *** Filename - MenuChecked.bb2 ; *** Define menu title MenuTitle 0,0,"Project" MenuColour 3 MenuItem 0,1,0,0," Enable quit" MenuItem 0,0,0,1,"QUIT" ; *** Open an Intuition display Screen 0,3 Window 0,0,20,200,100,$100f,"Press right mouse",1,2 ; *** Attach menu to window SetMenu 0 Repeat ev.l=WaitEvent ; *** End if QUIT is enabled If ev=256 AND ItemHit=1 If MenuChecked(0,0,0) End ; *** QUIT option is not enabled Else WLocate 0,0 Print "Quit not enabled" EndIf EndIf Forever 12.4 A full example ------------------- Here is a full example which demonstrates one of the practical applications of menus in Blitz Basic programs. It is a very simple IFF image displayer. At present it can only load IFF files and clear them from the screen. Why not try adding the ability to save screens, or add more options, such as screen distortion and palette manipulation: ; *** Menu example ; *** Filename - MoreMenus.bb2 ; *** First menu MenuTitle 0,0,"PROJECT" MenuItem 0,0,0,0,"LOAD ","L" MenuItem 0,0,0,1,"SAVE ","S" MenuItem 0,0,0,2,"QUIT ","Q" ; *** Second menu MenuTitle 0,1,"SPECIAL" MenuItem 0,0,1,0,"CLEAR ","C" ; *** Output screen and window Screen 0,0,0,320,200,5,0,"Complete menu example",1,7 Window 0,0,0,320,200,$1900,"",1,0 ; *** Attach MenuList to window SetMenu 0 Repeat A.l=WaitEvent If A=256 ; *** "LOAD" option If MenuHit=0 AND ItemHit=0 MaxLen PATH$=160 MaxLen NAME$=64 A$=FileRequest$("Load",PATH$,NAME$) If A$<>"" LoadScreen 0,A$,0 Use Palette 0 EndIf EndIf ; *** "QUIT" option If MenuHit=0 AND ItemHit=2 Then End ; *** "CLEAR" option If MenuHit=1 AND ItemHit=0 Then WCls EndIf Forever 12.5 End-of-Chapter summary --------------------------- Menus are created through the use of MenuList objects. Each MenuList contains an entire set of menu titles, menu items and possibly sub-menu items. MENUTITLE is used to create the Intuition menu titles which appear when the right mouse button is held down. The MENUITEM statement creates a text menu item. The SHAPEITEM statement is used to create a graphical menu item. All menu items may have an optional list of sub-menu items attached to them. This is achieved with the SUBITEM and SHAPESUBITEM statements. Menus are attached to windows by the SETMENU statement. The layout of menus can be altered with MENUGAP and SUBITEMOFF. Menu status can be read and altered with the MENUSTATE and MENUCHECKED commands. Table 12.3 : Menu commands Command Function ========================================================== MENUCHECKED Read status of a toggle-type menu item MENUCOLOUR Determine the colour of a menu item MENUGAP Control layout of a menu MENUITEM Create a text menu item MENUSTATE Turn menu items on or off MENUTITLE Add a menu title to a MenuList SETMENU Attach a MenuList to the current window SHAPEITEM Create a graphical menu item SHAPESUB Create a graphic sub-menu item SUBITEM Create a sub-menu item SUBITEMOFF Control position of sub items to menu options @endnode