The MaxGUI Beginner Tutorial Series - Tutorial 14:  Menus and Popup Menus
(c) Assari Jan 07 2005

Menus are another common GUI gadget. In this tutorial we are going to cover menus. Lets get started as usual with a very simple exmaple.

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local FileMenu:TGadget=CreateMenu("File",0,WindowMenu(MyWindow))
UpdateWindowMenu
MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
   End Select
Forever


We can see our File menu appearing on the menubar but we cannot do anything with it yet.

   



The requirement to create a menu and use it in our window is a bit more onerous that other gadgets we have seen previously. At the very least, we need to specify the following:-
In our example above, clicking the Menu actually does not do anything. Let's do something more exciting.

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local FileMenu:TGadget=CreateMenu("&File",0,WindowMenu(MyWindow))
CreateMenu "Exit",101,FileMenu

UpdateWindowMenu
MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     End Select
   End Select
Forever


Running the above program will get us a File Menu with an Exit sub-menu, clicking it activate the Notify message and then ends the program.

   


Notice how we create the Exit menu which has the FileMenu gadget as its parent. A unique identifier 101 was used for this Menu Item. Any unique id will work as well. Never forget to call the UpdateWindowMenu function.

    Local FileMenu:TGadget=CreateMenu("&File",0,WindowMenu(MyWindow))
CreateMenu "Exit",101,FileMenu

UpdateWindowMenu
MyWindow

When the user clicks the menu item, a MenuAction event is generated, we then need to check which menu item has been clicked by checking against the unique identifier specified earlier in the CreateMenu function.

      Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     End Select

Let us see how we can cope with more menu items.

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local FileMenu:TGadget=CreateMenu("File",0,WindowMenu(MyWindow))
CreateMenu "Open",102,FileMenu
CreateMenu "Exit",101,FileMenu

Local HelpMenu:TGadget=CreateMenu("Help",0,WindowMenu(MyWindow))
CreateMenu "About",123456,HelpMenu

UpdateWindowMenu MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     Case 102
       Notify "You Have Just Clicked OPEN"
     Case 123456
       Notify "A very simple Menu Example~n(c) Assari  2006"

     End Select
   End Select
Forever


Run the program and click on Help About and you would see the Notify message as we have defined above in our program.

   


The first line below creates the File Menu and then we create the 2 sub-menu items Open and Exit
    Local FileMenu:TGadget=CreateMenu("File",0,WindowMenu(MyWindow))
CreateMenu "Open",102,FileMenu
CreateMenu "Exit",101,FileMenu

Next we create the Help Menu and the About sub-menu item
    Local HelpMenu:TGadget=CreateMenu("Help",0,WindowMenu(MyWindow))
CreateMenu "About",123456,HelpMenu

We then use the Select/Case statement on the EventData() function which actually returns the unique identifer which we have defined in the respective CreateMenu function above

      Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     Case 102
       Notify "You Have Just Clicked OPEN"
     Case 123456
       Notify "A very simple Menu Example~n(c) Assari  2006"

     End Select

So there you go, building more menu is just an extension of the above method.

The syntax for using the CreateMenu function is as follows:-

Function CreateMenu:TGadget( text$,tag,parent:TGadget,hotKey=0,modifier=0 )

Let us now take a look at the hotkey parameter. This parameter allows you to attach a "hotkey" to the menu ie pressing the assigned key will cause the menu item to be triggered.

In the example below, we are now attaching the F4 ket to our File Exit menu item. Note the use of the constant KEY_F4 in the CreateMenu function below

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local FileMenu:TGadget=CreateMenu("&File",0,WindowMenu(MyWindow))
CreateMenu "Exit",101,FileMenu,KEY_F4

UpdateWindowMenu
MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     End Select
   End Select
Forever


Now run the above program and then press the F4 key. You will see the Notify message coming out just as if you have clicked on the File Exit menu item.

The next parameter we want to look at is the modifier parameter. What the modifier does is allow us to use the CTRL or ALT keys in conjuction with our assigned key ie CTRL-F4 to exit instead of just using the F4 key.

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local FileMenu:TGadget=CreateMenu("&File",0,WindowMenu(MyWindow))
CreateMenu "Exit",101,FileMenu,KEY_F4,  MODIFIER_COMMAND

UpdateWindowMenu
MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End
  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     End Select
   End Select
Forever


Now run the above program and then press the CTRL-F4 key. You will see the Notify message coming out just as if you have clicked on the File Exit menu item.

A list of keys and modifiers can be found in the helpfiles.

POP UP MENU

MaxGUI also allows the creation of a pop menu when the user clicks the right-mouse button. Let us see how to do this

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local MyPanel:TGadget=CreatePanel(0,0,300,200,MyWindow,PANEL_ACTIVE)
Local FileMenu:TGadget=CreateMenu("File",0,WindowMenu(MyWindow))
CreateMenu "Open",102,FileMenu
CreateMenu "Exit",101,FileMenu

UpdateWindowMenu MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End

  Case EVENT_MOUSEDOWN
   If EventSource()=MyPanel And EventData()=2 Then
      PopupWindowMenu MyWindow,FileMenu
   EndIf

  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     Case 102
       Notify "You Have Just Clicked OPEN"


     End Select
   End Select
Forever


Right-clicking on the panel now causes the File menu to pop up at our mouse location.

   


First we need to have gadgets which can handle mouse events. In this example we are going to use the panel gadget. We just need to remember to create the panel gadget with the PANEL_ACTIVE style so that mouse events can be captured.

    Local MyPanel:TGadget=CreatePanel(0,0,300,200,MyWindow,PANEL_ACTIVE)

Then we need to catch the mouse event usent the WaitEvent() and Select/Case statements. We then need to check that the mouse event came from our panel (EventSource()=MyPanel) and also that the right mouse button has been clicked (EventData()=2). Once both of these have been satisfied, we can then call the PopupWindowMenu function.

      Case EVENT_MOUSEDOWN
   If EventSource()=MyPanel And EventData()=2 Then
      PopupWindowMenu MyWindow,FileMenu
   EndIf

DisableMenu

There are several functions that can be used to manipulate menu items. We will not cover all of them here. One function we will cover is DisableMenu which as the name suggests disables a menu item. Let us see how that works

    SuperStrict

Local MyWindow:TGadget=CreateWindow("Menu Example", 200,200,320,240)
Local MyPanel:TGadget=CreatePanel(0,0,300,200,MyWindow,PANEL_ACTIVE)
Local FileMenu:TGadget=CreateMenu("File",0,WindowMenu(MyWindow))

Local
ExitMenu:TGadget=CreateMenu("Exit",101,FileMenu)
CreateMenu "Toggle Exit Menu",103,FileMenu
CreateMenu "Open",102,FileMenu

UpdateWindowMenu MyWindow

Repeat
  WaitEvent()
  Select EventID()
  Case EVENT_WINDOWCLOSE
     End

  Case EVENT_MOUSEDOWN
   If EventSource()=MyPanel And EventData()=2 Then
      PopupWindowMenu MyWindow,FileMenu
   EndIf

  Case EVENT_MENUACTION
   Select EventData()
     Case 101
       Notify "You Have Just Clicked Exit"
       End
     Case 102
       Notify "You Have Just Clicked OPEN"
     Case 103
       If MenuEnabled(ExitMenu)=1
          DisableMenu ExitMenu
       Else
          EnableMenu ExitMenu
       EndIf
       UpdateWindowMenu MyWindow


     End Select
   End Select
Forever


From the screenshots below we can see our menu being disabled after we have clicked on the toggle menu item.  The disabled menu item has been greyed out.

   


The first thing we need to do is to have a name for the menu-item that we want to disable. For the other menu-items we have seen that this was not necessary

    Local ExitMenu:TGadget=CreateMenu("Exit",101,FileMenu)

When the Toggle Exit Menu  was clicked, the menu action event will return the 103 identifier. We then check for the state of the menu item via the MenuEnabled function. Based on this we either enable or disable our menu item via the DisableMenu and EnableMenu function.

         Case 103
       If MenuEnabled(ExitMenu)=1
          DisableMenu ExitMenu
       Else
          EnableMenu ExitMenu
       EndIf
       UpdateWindowMenu MyWindow



Note that the UpdateWindowMenu function must always be called after we make changes to our menu

Summary

Menus are fairly simple gadgets and as we can see from above are fairly simple to use as well.

To recap what we have learnt so far
So thats ends our tutorial for now. Back to Tutorial Index.