Menus are relatively easy to create and use in wxRuby, you only need to create a Wx::MenuBar object to hold all of the menus, and a number of Wx::Menu objects.
In WxRuby, inside each Menu object, you can place any number of options. Each of these options, when selected by the user, will call a callback function defined by an ID number assigned to that particular menu option. For example, if you (the programmer) assign "Wx::ID_4" to the function "Save," when the user selects "Save" from the menu bar, the callback function will be associated with "Wx::ID_4". These ID numbers are defined by the programmer, but there are a few special ones used in this example.
-
Wx::ID_ANY - This is an ID used when you don't care what the ID is. In this example, the dummy Open and Close options use this, since they're not hooked up to anything.
-
Wx::ID_EXIT - This allows wxWidgets to do any platform-specific magic on the Exit option. This includes any icons commonly used on the platform, so it will blend in.
-
Wx::ID_ABOUT - This is a special ID for the same reason ID_EXIT is. An icon will be placed next to the menu option.
When it comes time to do something more meaningful, you're going to have to use your own ID numbers. These numbers are completely arbitrary integers, almost any numbers will do. However, you have to be careful not to clash with the pre-defined IDs of wxWidgets like the ones discussed above. There are two constants defined to tell you where the block of IDs used by wxWidgets starts and ends.
-
Wx::ID_LOWEST - This is the lowest ID used by wxWidgets. Any ID number lower than this value will not conflict with the internal IDs.
-
Wx::ID_HIGHEST - This is the highest ID used by wxWidgets. Any ID number higher than this number will not conflict with the internal IDs.
To append any menu item to a menu, call the append method on the Menu object. It takes 3 arguments at minimum. First, there's an ID as discussed above. Then, there's a string of text to be displayed. This also includes any accelerators or keyboard shortcuts. This is for easy keyboard navigation. For example, if I have a menu called "&File" (with the ampersand by the F), and an option in that menu called "E&xit", a user would only have to hit Alt-f (to bring up the file menu), then x (to select the Exit option). Finally, there's a short description. If your application has a status bar, that description will be displayed in the status bar when the mouse pointer is over that option.
In addition to menu items, you can also append separators. These are the small horizontal lines that seperate logical groups of menu items. To do this, simply call the append_seperator method to add a separator to the end of any Menu object.
Similarly, to add a Menu to the MenuBar, use the MenuBar's append method. It takes two arguments, the Menu object to add and the name of the menu (which also includes any ampersands for keyboard shortcuts).
When building menus with the append methods, remember that you're building a list from beginning to end. You must build your menus from left-most menu toward the right. When appending menu options, you must build from the top down.
Finally, to add this menu bar to your application, assign the MenuBar object to your Frame object's menu_bar attribute.
Now that you have some menus up, you should connect them to some callbacks. This is done using the evt_menu method. The evt_menu method takes 2 parameters, the ID of the menu item to watch for and the name of a method to call when it is selected. Once this last step is done, your menu is complete.
#!/usr/bin/env ruby
require 'rubygems'
require 'wx'
class AppFrame < Wx::Frame
def initialize(title)
# Call parent class' initialize function, and add int
# a few more arguments besides the title. Since this
# is a top-level frame, there is no parent widget, so
# use nil for the first argument.
super( nil, :title => title, :size => [400, 300] )
# Create the Wx::MenuBar object. This holds all the
# Wx::Menu objects to create the menu hierarchy.
menu = Wx::MenuBar.new
# Start with the File menu. Only a single thing here,
# the Exit option.
file = Wx::Menu.new
# These won't do anything, they're just there for show
file.append( Wx::ID_ANY, "&Open\tAlt-O", "Open File" )
file.append( Wx::ID_ANY, "&Close\tAlt-C", "Close File" )
# Use seperators between groups of menu options
file.append_separator
# The Exit option has a special ID, Wx::ID_EXIT, which
# will do any platform-specific magic to translate and
# put the Exit option in the correct place.
file.append( Wx::ID_EXIT, "E&xit\tAlt-X", "Quit" )
menu.append( file, "&File" )
# Create the Help menu
help = Wx::Menu.new
help.append( Wx::ID_ABOUT, "&About...\tF1", "Show about dialog" )
menu.append( help, "&Help" )
self.menu_bar = menu
# Setup our callbacks to handle menu events
evt_menu( Wx::ID_EXIT, :on_quit )
evt_menu( Wx::ID_ABOUT, :on_about )
end
# Close the window when the user clicks Quit in the File
# menu
def on_quit
close
end
# Display an "About this program" dialog
def on_about
Wx::about_box(
:name => self.title,
:version => "1.0",
:description => "Menu example"
)
end
end
class MyApp < Wx::App
def on_init
@frame = AppFrame.new("Menu test")
@frame.show
end
end
app = MyApp.new
app.main_loop