Changes between Version 1 and Version 2 of GtkMenus

Timestamp:

11/03/11 22:41:55 (13 years ago)

Author:

callisto

Comment:

finished GtkMenus page

GtkMenus

@@ -3 +3 @@
 Menus are lists of commands, accessed from a drop-down or pull-down list.  Menus are typically found within a menubar, which displays the title of each menu.
 
+[[Image(menus.png)]]
+
 == Creating the Menu Bar ==
 
 The menu bar itself is created as an instance of '!MenuBar'.  The menubar is a regular Gtk widget and can be located anywhere you choose, but for the classic menu-at-the-top, place the menubar to the top of a non-expandable 'VBox' before adding it the window.  
 
-The following program shows how to construct and add the menubar to a window class.
-
-{{{
-#!cobra
-# @args -pkg:gtk-sharp-2.0 # remove initial '#'
+The following 'createMenu' definition shows how to construct and add the menubar to a window class.  (A complete example is given at the bottom of this page.)
+
+{{{
+#!cobra
+        def createMenu
+                # create the main menubar
+                mainMenu = MenuBar ()
+
+                # -- the menu construction code goes here --
+
+                # Add the menubar to the top of the window
+                box = VBox(false, 0) # make this 'false' so menubar stays compact
+                box.packStart(mainMenu, false, false, 0)
+                .add(box)
+}}}
+
+== Adding Menus to the Menu Bar ==
+
+The menubar displays instances of '!MenuItems'.  To make the headings for menus such as 'File', 'Edit', 'Help' we would write:
+{{{
+#!cobra
+                menuItem = MenuItem("_File")
+                mainMenu.append(menuItem)
+
+                menuItem = MenuItem("_Edit") # (it is convenient to reuse the 'menuItem' variable)
+                mainMenu.append(menuItem)
+
+                menuItem = MenuItem("_Help")
+                mainMenu.append(menuItem)
+}}}
+
+Notice the underscore in the title - this gets converted into a mnemonic for accessing the menu, and is shown as an underlined letter in the menu.
+
+To get an actual ''menu'' under each heading, we first create an instance of 'Menu' and attach it as the submenu for the respective menuitem:
+{{{
+#!cobra
+                menuItem = MenuItem("_File")
+                mainMenu.append(menuItem)
+                fileMenu = Menu()
+                menuItem.submenu = fileMenu
+
+                menuItem = MenuItem("_Edit")
+                mainMenu.append(menuItem)
+                editMenu = Menu()
+                menuItem.submenu = editMenu
+
+                menuItem = MenuItem("_Help")
+                mainMenu.append(menuItem)
+                helpMenu = Menu()
+                menuItem.submenu = helpMenu
+}}}
+
+If you include the above code in the 'createWidgets' method of our example program, you will see a menubar on the window with nothing in the menus.
+
+== Adding Items to Menus ==
+
+For our menus to be useful, we need to include items to launch commands or store information.  There are several categories of items we can include, but here we look at: ''simple items'' (rather like buttons), ''check boxes'', and ''radio buttons''.
+
+=== Simple Items ===
+
+A simple menu item shows as a text label.  The following code shows the three steps of creating a menu item, attaching a method to call when activated, and adding it to a menu:
+
+{{{
+#!cobra
+                # create a menu item for 'show values'
+                menuItem = MenuItem("Show values")
+                # attach method to call when menu item is selected
+                listen menuItem.activated, ref .showValues
+                # add the menu item to the editMenu
+                editMenu.append(menuItem)
+}}}
+
+=== Check Boxes ===
+
+Check boxes can be placed onto a menu, using the '!CheckMenuItem' class.  We need to store a reference to the checkbox to later retrieve its state, by accessing its 'active' attribute (see the method 'showValues' at the bottom of this page).
+
+{{{
+#!cobra
+                # create a check box item and add to the edit menu
+                _checkbox = CheckMenuItem("Select me")
+                editMenu.append(_checkbox)
+}}}
+
+=== Radio Buttons ===
+
+Radio buttons on menus are similar to regular radio buttons: the user is allowed to pick one option out of a pre-defined set.  
+
+To store the state of radio buttons we can use a variable to hold the currently selected option, and provide some methods to change that variable as different options are selected. For example, to select a language from three options:
+
+{{{
+#!cobra
+        var _language as String
+
+        def selectCobra(obj, e)
+                _language = "cobra"
+
+        def selectJava(obj, e)
+                _language = "java"
+
+        def selectPython(obj, e)
+                _language = "python"
+}}}
+
+The radio buttons can then be set up to call the respective 'selectN' method when toggled:
+{{{
+#!cobra
+                # create some radio buttons
+                _language = "cobra" # set initial option
+                radioItem1 = RadioMenuItem("Cobra") # this one selected by default
+                editMenu.append(radioItem1)
+                listen radioItem1.toggled, ref .selectCobra
+                radioItem2 = RadioMenuItem(radioItem1, "Java")
+                editMenu.append(radioItem2)
+                listen radioItem2.toggled, ref .selectJava
+                radioItem3 = RadioMenuItem(radioItem1, "Python")
+                editMenu.append(radioItem3)
+                listen radioItem3.toggled, ref .selectPython
+}}}
+
+As with standard radio buttons, radio buttons are placed into groups by including the first member of the group in the constructor of subsequent members.
+
+=== Stock Items and Accelerator Groups ===
+
+There are several standard menu items that you find in many applications: these are listed in Gtk as a set of [http://developer.gnome.org/gtk/2.24/gtk-Stock-Items.html Stock] items.  Stock items can be used on menus by creating an instance of an '!ImageMenuItem'.  Because these standard items are also usually linked with keyboard shortcuts (such as CTRL-Q to quit the application), the menu items must also be linked to an ''accelerator group''.  The following code creates an accelerator group, and then adds 'new', 'open', 'save' and 'quit' items to the file menu:
+{{{
+#!cobra
+                # create an accelerator group
+                acceleratorGroup = AccelGroup()
+                .addAccelGroup(acceleratorGroup)
+                # -- new item
+                menuItem = ImageMenuItem(Stock.new, acceleratorGroup)
+                listen menuItem.activated, ref .newAction
+                fileMenu.append(menuItem)
+                # -- open item
+                menuItem = ImageMenuItem(Stock.open, acceleratorGroup)
+                listen menuItem.activated, ref .openAction
+                fileMenu.append(menuItem)
+                # -- save item
+                menuItem = ImageMenuItem(Stock.save, acceleratorGroup)
+                listen menuItem.activated, ref .saveAction
+                fileMenu.append(menuItem)
+                # -- separator
+                fileMenu.append(SeparatorMenuItem())
+                # -- quit item
+                menuItem = ImageMenuItem(Stock.quit, acceleratorGroup)
+                listen menuItem.activated, ref .quit
+                fileMenu.append(menuItem)
+}}}
+
+
+== Submenus ==
+
+A submenu is a menu contained within another menu; a submenu is shown on the screenshot at the top of this page.  Submenus are simply menus added to an existing menu instance rather than the menubar.  We can create a submenu for the language selector as follows:
+{{{
+#!cobra
+                languageMenu = Menu()                               # instance of menu on which to build submenu
+                radioItem1 = RadioMenuItem("Cobra")
+                languageMenu.append(radioItem1)                     # attach the radio items to the submenu
+                listen radioItem1.toggled, ref .selectCobra
+                radioItem2 = RadioMenuItem(radioItem1, "Java")
+                languageMenu.append(radioItem2)
+                listen radioItem2.toggled, ref .selectJava
+                radioItem3 = RadioMenuItem(radioItem1, "Python")
+                languageMenu.append(radioItem3)
+                listen radioItem3.toggled, ref .selectPython
+                languageMenuItem = MenuItem("Language")             # create a menuitem labelled 'Language'
+                languageMenuItem.submenu = languageMenu             # and attach the languageMenu to it as a submenu
+                editMenu.append(languageMenuItem)                   # before adding to the edit menu
+}}}
+
+== Complete Example ==
+
+{{{
+#!cobra
+# @args -pkg:gtk-sharp-2.0   # remove initial '#'
 
 use Gtk
@@ -22 +194 @@
                 .createMenu
 
+        def quit(obj, e)
+                Application.quit
+
+        def newAction(obj, e)
+                print "Clicked new"
+
+        def openAction(obj, e)
+                print "Clicked open"
+        
+        def saveAction(obj, e)
+                print "Clicked save"
+
+        def aboutAction(obj, e)
+                print "Clicked about"
+
+        var _checkbox as CheckMenuItem
+
+        var _language as String
+
+        def selectCobra(obj, e)
+                _language = "cobra"
+
+        def selectJava(obj, e)
+                _language = "java"
+
+        def selectPython(obj, e)
+                _language = "python"
+
+        def showValues(obj, e)
+                print "Show values: [_checkbox.active] and language [_language]"
+
         def createMenu
                 # create the main menubar
                 mainMenu = MenuBar ()
-
-                # -- the menu construction code goes here --
+                # create an accelerator group
+                acceleratorGroup = AccelGroup()
+                .addAccelGroup(acceleratorGroup)
+
+                # -- menu 1: file menu, with three stock buttons and a separator
+                menuItem = MenuItem("_File")
+                mainMenu.append(menuItem)
+                fileMenu = Menu()
+                menuItem.submenu = fileMenu
+
+                # create an accelerator group
+                acceleratorGroup = AccelGroup()
+                .addAccelGroup(acceleratorGroup)
+                # -- new item
+                menuItem = ImageMenuItem(Stock.new, acceleratorGroup)
+                listen menuItem.activated, ref .newAction
+                fileMenu.append(menuItem)
+                # -- open item
+                menuItem = ImageMenuItem(Stock.open, acceleratorGroup)
+                listen menuItem.activated, ref .openAction
+                fileMenu.append(menuItem)
+                # -- save item
+                menuItem = ImageMenuItem(Stock.save, acceleratorGroup)
+                listen menuItem.activated, ref .saveAction
+                fileMenu.append(menuItem)
+                # -- separator
+                fileMenu.append(SeparatorMenuItem())
+                # -- quit item
+                menuItem = ImageMenuItem(Stock.quit, acceleratorGroup)
+                listen menuItem.activated, ref .quit
+                fileMenu.append(menuItem)
+                
+                # -- menu 2: edit menu, with menu item, check item, and submenu
+                menuItem = MenuItem("_Edit")
+                mainMenu.append(menuItem)
+                editMenu = Menu()
+                menuItem.submenu = editMenu
+
+                # create a menu item for 'show values'
+                menuItem = MenuItem("Show values")
+                # attach method to call when menu item is selected
+                listen menuItem.activated, ref .showValues
+                # add the menu item to the editMenu
+                editMenu.append(menuItem)
+
+                # create a check box item
+                _checkbox = CheckMenuItem("Select me")
+                editMenu.append(_checkbox)
+
+                # create some radio buttons on a submenu
+                _language = "cobra" # set initial item
+                languageMenu = Menu()
+                radioItem1 = RadioMenuItem("Cobra")
+                languageMenu.append(radioItem1)
+                listen radioItem1.toggled, ref .selectCobra
+                radioItem2 = RadioMenuItem(radioItem1, "Java")
+                languageMenu.append(radioItem2)
+                listen radioItem2.toggled, ref .selectJava
+                radioItem3 = RadioMenuItem(radioItem1, "Python")
+                languageMenu.append(radioItem3)
+                listen radioItem3.toggled, ref .selectPython
+                languageMenuItem = MenuItem("Language")
+                languageMenuItem.submenu = languageMenu
+                editMenu.append(languageMenuItem)
+
+                # -- menu 3: help menu
+                menuItem = MenuItem("_Help")
+                mainMenu.append(menuItem)
+                helpMenu = Menu()
+                menuItem.submenu = helpMenu
+
+                menuItem = ImageMenuItem(Stock.about, acceleratorGroup)
+                listen menuItem.activated, ref .aboutAction
+                helpMenu.append(menuItem)
 
                 # Add the menubar to the top of the window
@@ -32 +307 @@
                 box.packStart(mainMenu, false, false, 0)
                 .add(box)
-
-        def quit(obj, e)
-                Application.quit
 
 class MainProgram
@@ -43 +315 @@
                 Application.run
 }}}
-
-== Adding Menus to the Menu Bar ==
-
-The menubar displays instances of '!MenuItems'.  To make the headings for menus such as 'File', 'Edit', 'Help' we would write:
-{{{
-#!cobra
-                menuItem = MenuItem("_File")
-                mainMenu.append(menuItem)
-
-                menuItem = MenuItem("_Edit") # (it is convenient to reuse the 'menuItem' variable)
-                mainMenu.append(menuItem)
-
-                menuItem = MenuItem("_Help")
-                mainMenu.append(menuItem)
-}}}
-
-Notice the underscore in the title - this gets converted into a mnemonic for accessing the menu, and is shown as an underlined letter in the menu.
-
-To get a ''menu'' attached to each heading, we must create an instance of 'Menu' and attach it as the submenu for the respective menuitem:
-{{{
-#!cobra
-                menuItem = MenuItem("_File")
-                mainMenu.append(menuItem)
-                fileMenu = Menu()
-                menuItem.submenu = fileMenu
-
-                menuItem = MenuItem("_Edit")
-                mainMenu.append(menuItem)
-                editMenu = Menu()
-                menuItem.submenu = editMenu
-
-                menuItem = MenuItem("_Help")
-                mainMenu.append(menuItem)
-                helpMenu = Menu()
-                menuItem.submenu = helpMenu
-}}}
-
-If you include the above code in the 'createWidgets' method of our example program, you will see a menubar on the window with nothing in the menus.
-
-== Adding Items to Menus ==
-
-For our menus to be useful, we need to include items to launch commands or store information.  There are several categories of items we can include, but here we look at: ''simple items'' (rather like buttons), ''check boxes'', and ''radio buttons''.
-
-=== Simple Items ===
-
-A simple menu item shows as a text label.  The following code shows the three steps of creating a menu item, attaching a method to call when activated, and adding it to a menu:
-
-{{{
-#!cobra
-                # create a menu item for 'show values'
-                menuItem = MenuItem("Show values")
-                # attach method to call when menu item is selected
-                listen menuItem.activated, ref .showValues
-                # add the menu item to the editMenu
-                editMenu.append(menuItem)
-}}}
-
-=== Check Boxes ===
-
-Check boxes can be placed onto a menu, using the 'CheckMenuItem' class.  To retrieve the state of the checkbox, store its instance in a field, and access its 'active' attribute.
-
-{{{
-#!cobra
-                # create a check box item and add to the edit menu
-                _checkbox = CheckMenuItem("Select me")
-                editMenu.append(_checkbox)
-}}}
-
-=== Radio Buttons ===
-
-
-
-=== Stock Items and Accelerator Groups ===
-
-
-
-== Submenus ==
-
-
-== Complete Example ==
-