68
118
Window Basics Chapter 4
You can create a menu and show it at a particular point in a window
using
wxWindow::PopupMenu
,for example:
void wxWindow::OnRightClick(wxMouseEvent& event)
{
if (!m_menu)
{
m_menu = new wxMenu;
m_menu->Append(wxID_OPEN, wxT(“&Open”));
m_menu->AppendSeparator();
m_menu->Append(wxID_EXIT, wxT(“E&xit”));
}
PopupMenu(m_menu, event.GetPosition());
}
Events are sent to the menu itself before travelling up the hierarchy of win-
dows starting from the window the popup menu was shown on.
PopupMenu
will
cause program flow to “block” at this point, resuming when the user has dis-
missed the menu. If you want, you can delete and re-create the menu every
time it needs to be shown, or you can reuse the same menu.
Where possible, use standard wxWidgets identifiers in menus, such as
wxID_OPEN
,
wxID_ABOUT
,
wxID_PRINT
,and so on. You can find a full list of these in
Chapter 3. In particular,
wxID_ABOUT
,
wxID_PREFERENCES
and
wxID_EXIT
are inter-
preted specially on Mac OS X. When used in a menu bar, these menu items are
not shown in the menus to which they are appended, but are shown instead in
the standard application menu. Thus wxWidgets adapts your menus automat-
ically to Mac OS X conventions, but beware of side effects such as a Help menu
with no menu items, or two separators together.
See
samples/menu
in the wxWidgets distribution for a test of most menu
functionality, and also see
samples/ownerdrw
for a demonstration of the use of
custom fonts and bitmaps in menu items.
wxMenu Events
There are four different kinds of event associated with
wxMenu
:
wxCommandEvent
,
wxUpdateUIEvent
,
wxMenuEvent
,and
wxContextMenuEvent
.
Table 4-45 lists the command events, whose handlers take a
wxCommandEvent
argument. Use these for processing menu commands, either
from a pop-up menu or a menu bar on a frame. These are interchangeable
with the equivalent toolbar event macros so that events generated from both
menus and toolbar buttons can be processed by the same handler.
81
Menus
119
Table 4-45
wxMenu
Command Events
EVT_MENU(id, func)
Processes a
wxEVT_COMMAND_MENU_SELECTED
event, generated by a menu item.
EVT_MENU_RANGE(id1, id2, func)
Processes a
wxEVT_COMMAND_MENU_RANGE
event, generated by a range of menu items.
Table 4-46 lists the event macros for update events—events generated by
the framework in idle time to give the application a chance to update ele-
ments of the UI—for example, enabling or disabling menu items. Although
wxUpdateUIEvent
applies to all windows, menu event handlers can use them
slightly differently than other event handlers: they can call
Check
and
SetText
as well as
Enable
.
Check
checks or unchecks the menu item, while
SetText
sets
the menu item label, which is useful if the label changes dynamically accord-
ing to some condition. For example:
BEGIN_EVENT_TABLE(MyFrame, wxFrame)
EVT_UPDATE_UI(ID_TOGGLE_TOOLBAR, MyFrame::OnUpdateToggleToolbar)
END_EVENT_TABLE()
void MyFrame::OnUpdateToggleToolbar(wxUpdateUIEvent& event)
{
event.Enable(true);
event.Check(m_showToolBar);
event.SetText(m_showToolBar ?
wxT(“Show &Toolbar (shown)”) :
wxT(“Show &Toolbar (hidden)”));
}
For more on UI update events, please see Chapter 9.
Table 4-46
wxMenu
Update Events
EVT_UPDATE_UI(id, func)
Processes a
wxEVT_UPDATE_UI
event.
The handler can call
Enable
,
Check
,and
SetText
among other functions.
EVT_UPDATE_UI_RANGE(id1, id2, func)
Processes a
wxEVT_UPDATE_UI
event for
a range of identifiers.
Table 4-47 lists the other menu-related events.
EVT_CONTEXT_MENU
handlers
take a
wxContextMenuEvent
,which is derived from
wxCommandEvent
and therefore
propagates up the parent-child window hierarchy. Use this in preference to
intercepting a right mouse button click when you want to show a context
menu, and call the event object’s
GetPosition
function to find out where to
show the menu.
The remaining macros process
wxMenuEvent
objects, and these are only
sent from a menu bar to its frame. They tell the application when a menu has
been opened and closed, and when the user has highlighted a menu item. The
83
120
Window Basics Chapter 4
default
EVT_MENU_HIGHLIGHT
handler shows a menu item’s help string in the sta-
tus bar, but you can provide your own handler to do something different.
Table 4-47 Other
wxMenu
Events
EVT_CONTEXT_MENU(func)
Processes the event generated when the
user has requested a popup menu to
appear by pressing a special key (under
Windows) or by right-clicking the
mouse. The handler takes a
wxContextMenuEvent
.
EVT_COMMAND_CONTEXT_MENU(id, func)
The same as
EVT_CONTEXT_MENU
,but it
takes a window identifier.
EVT_MENU_OPEN(func)
Handles a
wxEVT_MENU_OPEN
event, sent
when a menu is about to be opened. On
Windows, this is only sent once for each
navigation of the menu bar.
EVT_MENU_CLOSE(func)
Handles a
wxEVT_MENU_CLOSE
event, sent
when a menu has just been closed.
EVT_MENU_HIGHLIGHT(id, func)
Handles a
wxEVT_MENU_HIGHLIGHT
event,
sent when the menu item with the speci-
fied id has been highlighted.This is used
to show help prompts in a frame’s status
bar.
EVT_MENU_HIGHLIGHT_ALL(func)
Handles a
wxEVT_MENU_HIGHLIGHT
event
for any menu identifier.
wxMenu Member Functions
These are the major
wxMenu
functions.
Append
adds a menu item: specify an identifier, a label, a help string, and
the kind of item (
wxITEM_NORMAL
,
wxITEM_SEPARATOR
,
wxITEM_CHECK
or
wxITEM_
RADIO
). You can also use
AppendCheckItem
and
AppendRadioItem
to avoid specify-
ing
wxITEM_CHECK
or
wxITEM_RADIO
.For example:
// Append a normal item
menu->Append(wxID_NEW, wxT(“&New...\tCtrl+N”));
// Append a check item
menu->AppendCheckItem(ID_SHOW_STATUS, wxT(“&Show Status”));
// Append a radio item
menu->AppendRadioItem(ID_PAGE_MODE, wxT(“&Page Mode”));
Another overload of
Append
enables you to append a submenu, for example:
// Append a submenu
menu->Append(ID_SUBMENU, wxT(“&More options...”), subMenu);
86
Menus
121
Yet another overload of
Append
enables you to use a
wxMenuItem
object directly
to append an item, and this is the only way to show bitmaps on menus or to set
special fonts. For example:
// Initialization of bitmaps and font not shown
wxBitmap bmpEnabled, bmpDisabled;
wxFont fontLarge;
// Create a menu item
wxMenuItem* pItem = new wxMenuItem(menu, wxID_OPEN, wxT(“&Open…”));
// Set bitmaps and font
pItem->SetBitmaps(bmpEnabled, bmpDisabled);
pItem->SetFont(fontLarge);
// Finally append it to the menu
menu->Append(pItem);
Use
Insert
to insert a menu at a particular position. There are also the func-
tions
Prepend
,
PrependCheckItem
,
PrependRadioItem
, and
PrependSeparator
for
inserting items at the start of the menu.
AppendSeparator
adds a separator, and
InsertSeparator
inserts a separa-
tor in a given position. For example:
// Append a separator
menu->AppendSeparator();
Break
inserts a break in a menu, causing the next appended item to appear in
a new column.
Use
Check
to toggle a check or radio item on or off, passing the menu item
identifier and a boolean value. Use
IsChecked
to get the checked status.
Delete
deletes a menu item specified by identifier or by
wxMenuItem
pointer. If the item is a menu, the submenu will not be deleted. Use
Destroy
if
you want to remove and delete a submenu.
Remove
removes the menu item
from a menu without deleting the returned
wxMenuItem
object.
Use
Enable
to enable or disable a menu item, but rather than doing this
explicitly, you may want to use UI update events (see Chapter 9).
IsEnabled
returns the enabled status.
Use
FindItem
to find an item by label or identifier. Use
FindItemByPosition
to find an item by position in the menu.
GetHelpString
and
SetHelpString
are accessors for the help string associ-
ated with a menu item. When the menu is part of a menu bar,
wxFrame
shows
this string in the status bar (if available), as the user highlights each menu
item.
GetLabel
and
SetLabel
get or set the menu item label, given its identifier.
GetMenuCount
returns the number of items in the menu.
57
122
Window Basics Chapter 4
Figure 4-34 A
wxMenuBar
GetMenuItems
returns a reference to the list of menu items, a
wxMenuItemList
object.
GetTitle
and
SetTitle
are accessors for the optional title of a menu and
are only used for pop-up menus.
UpdateUI
sends UI update events to the event handler argument or to the
owning window if
NULL
is passed. This is called just before the menu is popped
up, but the application may call it at other times if required.
C
ONTROL
B
ARS
A control bar provides a convenient way to contain and arrange multiple con-
trols. There are currently three kinds of control bars:
wxMenuBar
,
wxToolBar,
and
wxStatusBar
.
wxMenuBar
can only belong to a
wxFrame
.
wxToolBar
and
wxStatusBar
are most commonly used with
wxFrame
,but they can also be children of other
windows.
wxMenuBar
A menu bar contains a series of menus accessible from the top of a frame
under the title bar. You can replace a frame’s current menu bar by calling
SetMenuBar
.To create a menu bar, use the default constructor and append
wxMenu
objects. For example:
wxMenuBar* menuBar = new wxMenuBar;
wxMenu* fileMenu = new wxMenu;
fileMenu->Append(wxID_OPEN, wxT(“&Open...”), wxT(“Opens a file”));
fileMenu->AppendSeparator();
fileMenu->Append(wxID_EXIT, wxT(“E&xit”), wxT(“Quits the program”));
menuBar->Append(fileMenu);
frame->SetMenuBar(menuBar, wxT(“&File”));
This code creates a one-menu menu bar, as shown in Figure 4-34.
83
Control Bars
123
You can append submenus to a
wxMenu
,and you can create check and
radio menu items (refer to the “Menus” section earlier in this chapter). As in
the previous example, an ampersand in a label indicates that the following
character should be used as a mnemonic (pressing that key when the menu is
shown executes the associated command).
If you provide a help string, it will be shown in the frame’s status bar (if
any) by virtue of the default
EVT_MENU_HIGHLIGHT
handler.
wxMenuBar Styles
wxMenuBar
takes the
wxMB_DOCKABLE
style, used under GTK+ to allow the menu
bar to be detached from the frame.
wxMenuBar Events
Menu bars use the events already covered in the description of
wxMenu
.
wxMenuBar Member Functions
These are the major
wxMenuBar
functions.
Append
adds a menu to the end of the menu bar, which will then own the
menu and will destroy it when the menu bar is destroyed (usually by the own-
ing frame). Pass the menu and a label.
Insert
inserts a menu at the given posi-
tion.
Enable
enables or disables the given menu item, given its identifier. Use
IsEnabled
to check its enabled status.
Check
checks or unchecks a check or radio menu item. Use
IsChecked
to
test its checked status.
EnableTop
enables or disables a whole menu, by zero-based position.
FindMenu
returns the index of a menu whose label matches the given
string, with or without mnemonic characters. It returns
wxNOT_FOUND
if there
was no match.
FindMenuItem
returns the index of a menu item given a menu name and a
menu item.
FindItem
returns the
wxMenuItem
object given a menu item identifier, and
if it is a submenu, its
wxMenu
pointer will be returned in the second argument.
GetHelpString
and
SetHelpString
are accessors for the help string for a
given menu item.
GetLabel
and
SetLabel
are accessors for a menu item’s label.
GetLabelTop
and
SetLabelTop
are accessors for a menu’s label in the menu
bar, given the zero-based menu position.
GetMenu
returns a pointer to the
wxMenu
at the given zero-based position.
GetMenuCount
returns the number of menus in the menu bar.
Refresh
redraws the menu bar.
40
124
Window Basics Chapter 4
Figure 4-35 A
wxToolBar
Remove
removes a menu and returns the
wxMenu
object, which the applica-
tion is then responsible for deleting.
Replace
replaces a menu at the given position with another one. The old
menu is returned, and the application is responsible for deleting it.
wxToolBar
A toolbar contains a number of buttons and controls. It can be horizontal or
vertical, and the buttons can be push, check, or radio buttons. The buttons can
show labels as well as bitmaps. If you use
wxFrame::CreateToolBar
to create the
toolbar, or
wxFrame::SetToolBar
to associate it with a frame, the frame will
manage the toolbar, and it will not be counted as part of the client area. If you
use it in any other way, then your code will have to manage the toolbar size
and position using sizers or some other method.
Here’s an example of creating a toolbar and associating it with a frame:
#include “wx/toolbar.h”
#include “open.xpm”
#include “save.xpm”
wxToolBar* toolBar = new wxToolBar(frame, wxID_ANY,
wxDefaultPosition, wxDefaultSize, wxTB_HORIZONTAL|wxNO_BORDER);
wxBitmap bmpOpen(open_xpm);
wxBitmap bmpSave(save_xpm);
toolBar->AddTool(wxID_OPEN, bmpOpen, wxT(“Open”));
toolBar->AddTool(wxID_SAVE, bmpSave, wxT(“Save”));
toolBar->AddSeparator();
wxComboBox* comboBox = new wxComboBox(toolBar, ID_COMBOBOX);
toolBar->AddControl(comboBox);
toolBar->Realize();
frame->SetToolBar(toolBar);
Under Windows, this will create a toolbar, as shown in Figure 4-35.
Documents you may be interested
Documents you may be interested
