CrossPlatform GUI Programming with wxWidgets [Electronic resources] نسخه متنی

Top-Level Windows

Top-level windows are placed directly on the desktop and are not contained within other windows. They can be moved around the screen, and resized if the application permits it. There are three basic kinds of top-level window: wxFrame and wxDialog, both derived from an abstract base class called wxTopLevelWindow, and wxPopupWindow, which has less functionality and is derived directly from wxWindow. A dialog can be either modal or modeless, whereas a frame is almost always modeless. Modal means that flow through the application effectively halts until the user dismisses the dialog. This is very handy for getting a response before continuing, but it's always good to see whether an alternative user interface can be used (for example, a font control on the toolbar rather than in a properties window) to keep the interaction more fluid.

Top-level windows normally have a title bar and can have decorations for closing, minimizing, or restoring the window. A frame often has a menu bar, toolbar, and status bar, but a dialog generally does not. On Mac OS X, a frame's menu bar is not shown at the top of the frame, but at the top of the screen.

Don't confuse this usage of "top-level window" with the window returned by wxApp::GetTopWindow, by which wxWidgets or your application can get hold of the "main window," most often the first frame or dialog you create.

If needed, you can access all current top-level windows using the global variable wxTopLevelWindows, which is a wxWindowList.

wxFrame

wxFrame is a popular choice for the main application window. Chapter 7, or perhaps a splitter window (covered later in this chapter) if you need a couple of child windows.

Because some platforms do not allow direct painting on a frame, and to support keyboard navigation between child controls, you should create an intermediate wxPanel (see later).

A frame can have more than one toolbar, but it will only do sizing and positioning for one toolbar. You must implement explicit layout for multiple toolbars.

It is highly likely that you will derive a new class from wxFrame rather than using it directly, so that you can handle events such as wxEVT_CLOSE (see the following) and command events. Often you will create child windows and a menu bar within your frame constructor.

You can assign an icon to the frame to be shown by the system, such as on the taskbar or in the file manager. On Windows, it's best to use a compound icon at 16x16 and 32x32 pixels and perhaps several color depths. On Linux, the same icons as for Windows usually suffices. On Mac OS X, you'll need a variety of icons in different colors and depths. For more details on icons and icon bundles, see Chapter 10, "Programming with Images."

wxFrame has the following constructor in addition to the default constructor:

wxFrame(wxWindow* parent, wxWindowID id, const wxString& title,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxDEFAULT_FRAME_STYLE,
const wxString& name = wxT("frame"));

For example:

wxFrame* frame = new wxFrame(NULL, ID_MYFRAME,
wxT("Hello wxWidgets"), wxDefaultPosition,
wxSize(500, 300));
frame->Show(true);

Note that the frame won't be shown until Show(true) is called, to give the application the chance to do child window layout invisibly.

You don't have to pass a parent window to the new frame, but if you do, the new window will be displayed on top of the parent window if the wxFRAME_FLOAT_ON_PARENT style is specified.

To destroy a frame, do not use delete, but instead use Destroy or Close to tell wxWidgets to clean up the frame in idle time when all its events have been processed. When you call Close, you send a wxEVT_CLOSE event to the window. The default handler for this event calls Destroy. When a frame is deleted, its children are automatically deleted, as long as they are not themselves top-level windows.

When the last top-level window has been destroyed, the application exits (although you can change this behavior by calling wxApp::SetExitOnFrame Delete). Your main window's wxEVT_CLOSE handler may need to destroy other top-level windows that might be openfor example, a Find dialogotherwise the application will not close when the main window is closed.

A frame does not have the equivalent of wxDialog::ShowModal to enter an event loop and disable other top-level windows. However, you can get similar behavior by creating a wxWindowDisabler object when you require other top-level windows to be disabled. Or, you can use a wxModalEventLoop object, passing the frame pointer, calling Run to start a local event loop and calling Exit (usually from an event handler) to quit the loop.

Figure 4-3 shows the frame of a consumer application running on Windows. The frame has a title bar at the top, a menu bar, a colorful toolbar, a splitter window in the frame's client area, and a status bar at the bottom, giving help on toolbar buttons and menu items as the user drags the mouse over them.

wxFrame Styles

wxFrame can have the window styles listed in Table 4-4, in addition to those described for wxWindow.

Table 4-5 shows the extra styles that couldn't be accommodated in the regular style and that are set using wxWindow::SetExtraStyle.

wxFrame Events

wxFrame and its derived classes generate the events listed in Table 4-6, in addition to those mentioned for wxWindow.

wxFrame Member Functions

These are the major wxFrame functions. Because wxFrame derives from wxTopLevelWindow and wxWindow, please also refer also to the member functions for these classes.

CreateStatusBar creates one or more status fields at the bottom of the frame. Use SetStatusText to set the text for a particular field, and SetStatusWidths to customize the widths of the fields (see also wxStatusBar later in this chapter). For example:

frame->CreateStatusBar(2, wxST_SIZEGRIP);
int widths[3] = { 100, 100, -1 };
frame->SetStatusWidths(3, widths);
frame->SetStatusText(wxT("Ready"), 0);

CreateToolBar creates a toolbar under the menu bar and associates it with the frame. Alternatively, you can create a toolbar by using the wxToolBar constructor, but to allow it to be managed by the frame, you need to call wxFrame::SetToolBar.

GetMenuBar and SetMenuBar are accessors for the frame's wxMenuBar. There is only one menu bar per frame. You can replace an existing one with a new menu bar, and the old menu bar will be deleted.

GetTitle and SetTitle are accessors for the title that appears on the frame's title bar.

Iconize iconizes or restores the frame. You can test the frame's iconic state by calling IsIconized.

Maximize resizes the frame to fit the desktop, or restores it to the previous state if it is currently maximized. Call IsMaximized to test whether the frame is maximized.

SetIcon sets the icon displayed when the frame is minimized. It's also used for other purposes by the window manager, such as displaying the program's icon in Windows Explorer or on the taskbar. You can also use SetIcons to set an icon bundle (multiple icons with a variety of resolutions and depths).

SetShape sets a region specifying the shape of the frame on some platforms (currently Windows, Mac OS X, and GTK+, and X11 if the appropriate X11 extension is available).

ShowFullScreen hides as many decorations as possible and shows the client window at the maximum size of the display. It can also restore the frame to its former size and state. Use IsFullScreen to determine whether the frame is currently being shown full-screen.

Non-Rectangular Frames

If you want to write a more unusual-looking consumer application, such as a clock or media player, you can set a non-rectangular region for the frame, and only that region will be displayed. In Figure 4-4, the frame has no decorations (such as caption, border, or menu bar), and its paint handler is displaying a penguin bitmap. There is a region associated with the frame that acts as a mask that lets only the penguin show through.

The principles are demonstrated by the code in samples/shaped, although it uses a different image from the one shown here. When the frame is created, a bitmap is loaded, and a region is created out of it. On GTK+, setting the window shape must be delayed until the window creation event is sent, so you will need a __WXGTK__ test in your code. The following code demonstrates the required event table, frame constructor, and window creation event handler:

BEGIN_EVENT_TABLE(ShapedFrame, wxFrame)
EVT_MOTION(ShapedFrame::OnMouseMove)
EVT_PAINT(ShapedFrame::OnPaint)
#ifdef __WXGTK__
EVT_WINDOW_CREATE(ShapedFrame::OnWindowCreate)
#endif
END_EVENT_TABLE()
ShapedFrame::ShapedFrame()
: wxFrame((wxFrame *)NULL, wxID_ANY, wxEmptyString,
wxDefaultPosition, wxSize(250, 300),
| wxFRAME_SHAPED
| wxSIMPLE_BORDER
| wxFRAME_NO_TASKBAR
| wxSTAY_ON_TOP
)
{
m_hasShape = false;
m_bmp = wxBitmap(wxT("penguin.png"), wxBITMAP_TYPE_PNG);
SetSize(wxSize(m_bmp.GetWidth(), m_bmp.GetHeight()));
#ifndef __WXGTK__
// On wxGTK we can't do this yet because the window hasn't
// been created yet so we wait until the EVT_WINDOW_CREATE
// event happens. On wxMSW and wxMac the window has been created
// at this point so we go ahead and set the shape now.
SetWindowShape();
#endif
}
// Used on GTK+ only
void ShapedFrame::OnWindowCreate(wxWindowCreateEvent& WXUNUSED(evt))
{
SetWindowShape();
}

To set the shape, we create a region from the bitmap and the color to be used as the transparent color, and call SetShape.

void ShapedFrame::SetWindowShape()
{
wxRegion region(m_bmp, *wxWHITE);
m_hasShape = SetShape(region);
}

In order to allow the window to be moved around the screen, there is a mouse handler that explicitly moves the window.

void ShapedFrame::OnMouseMove(wxMouseEvent& evt)
{
wxPoint pt = evt.GetPosition();
if (evt.Dragging() && evt.LeftIsDown())
{
wxPoint pos = ClientToScreen(pt);
Move(wxPoint(pos.x - m_delta.x, pos.y - m_delta.y));
}
}

The paint handler is very simple, but of course in a real application, you will have other windows or graphics displayed inside the frame.

void ShapedFrame::OnPaint(wxPaintEvent& evt)
{
wxPaintDC dc(this);
dc.DrawBitmap(m_bmp, 0, 0, true);
}

For more details, see samples/shaped in the wxWidgets distribution.

Mini-Frames

On Windows and GTK+, you can use wxMiniFrame for frames that must have a small captionfor example, if implementing tool palettes. Figure 4-5 shows a wxMiniFrame on Windows. This class is implemented as a normal frame on Mac OS X. There are no special styles or member functions for this class.

wxMDIParentFrame

This frame class, derived from wxFrame, is part of wxWidgets' Multiple Document Interface (MDI) support, whereby a parent frame manages zero or more wxMDIChildFrame windows. How it does so depends on platform; the main visual differences are illustrated in Figure 4-6. On Windows, the child windows are clipped to the boundary of the main window. These windows can be tiled, overlapped, or maximized within the main frame so that only one shows at a time, and a Window menu (automatically added by wxWidgets) is available for controlling the child windows. The MDI style has the advantage of keeping a desktop relatively uncluttered, grouping together all the windows in the application. Also, because the main frame's menu bar is replaced by the active child frame's menu bar, the clutter of multiple menu bars is also reduced.

Under GTK+, wxWidgets emulates the MDI style using tabbed windows; only one window is shown at a time, but the user can switch between windows quickly using the tabs. On Mac OS, wxMDIParentFrame and wxMDIChildFrame windows look like normal frames, reflecting the fact that documents always open in a new window on Mac OS.

On platforms where MDI children are contained within the parent, a wxMDIParentFrame arranges its children on a wxMDIClientWindow, which can coexist with other windows in the frame. In Figure 4-6, the parent frame's size event handler sets the sizes and positions of a text control and the client window. For details, see samples/mdi in your wxWidgets distribution.

Each child frame can have its own menu bar, in addition to the parent frame's menu bar. When a child frame is activated, its menu bar is shown. When there are no child frames, the parent frame's menu bar is shown. You need to construct your child frame menu bar carefully to include the same commands as the parent's menu bar, adding others that are specific to the child. The parent frame and child frames can have their own toolbars and status bars, but they are not swapped like menu bars.

wxMDIParentFrame has the same constructor as wxFrame.

wxMDIParentFrame Styles

wxMDIParentFrame can have the window styles listed in Table 4-7, in addition to those described for wxFrame.

wxMDIParentFrame Member Functions

These are the major wxMDIParentFrame functions, in addition to those defined for wxFrame.

ActivateNext and ActivatePrevious activate the next or previous child frame.

Cascade and Tile provide two methods to arrange the child frames: overlapping and tiling them, respectively. ArrangeIcons lays out any minimized frames within the client window. These three functions only apply on Windows.

GetActiveChild provides the application with a pointer to the currently active child (if any).

GetClientWindow returns a pointer to the client window (a container for the child frames). You can provide a different client window from the default by overriding OnCreateClient and returning an instance of your own wxMDIClientWindow-derived class, but you must then use two-step parent frame construction.

wxMDIChildFrame

wxMDIChildFrame should always be created as a child of a wxMDIParentFrame window. As explained in the previous section, its appearance depends on the platform and will either be free-floating or constrained to the boundary of its parent.

Its constructor is the same as a regular frame; despite the fact that its true parent is a wxMDIClientWindow, you should pass the frame parent to the constructor.

For example:

#include "wx/mdi.h"
wxMDIParentFrame* parentFrame = new wxMDIParentFrame(
NULL, ID_MYFRAME, wxT("Hello wxWidgets"));
wxMDIChildFrame* childFrame = new wxMDIChildFrame(
parentFrame, ID_MYCHILD, wxT("Child 1"));
childFrame->Show(true);
parentFrame->Show(true);

wxMDIChildFrame Styles

wxMDIChildFrame takes the same styles as wxFrame, although depending on platform, not all of them will take effect.

wxMDIChildFrame Member Functions

These are the major wxMDIChildFrame functions. See also the base class, wxFrame.

Activate activates this frame, bringing it to the front and displaying its menu bar.

Maximize resizes the frame to fit the parent (Windows only).

Restore sets the frame to the size it was before it was maximized (Windows only).

wxDialog

A dialog is a top-level window used for presenting information, options, or selections. It can optionally have a title bar with decorations such as the close window button and minimize button, and as with wxFrame, you can assign an icon to the dialog to be shown in the taskbar or equivalent. A dialog can contain any combination of non-top level windows and controlfor example, a wxNotebook with OK and Cancel buttons underneath. As its name suggests, you use this class to initiate a dialog with a user, presenting specific information and choices, compared with the frame's usual role as the main window of an application.

There are two kinds of dialogmodal and modeless. A modal dialog blocks program flow and user input on other windows until it is dismissed (EndModal is called), whereas a modeless dialog behaves more like a frame in that program flow continues, and input in other windows is still possible. To show a modal dialog, you should use the ShowModal method, whereas to show a dialog modelessly, you simply use Show, as with frames.

Note that the modal dialog is one of the very few examples of wxWindow-derived objects that may be created on the stack and not on the heap. In other words, you can use the heap method as follows:

void AskUser()
{
MyAskDialog *dlg = new MyAskDialog(...);
if ( dlg->ShowModal() == wxID_OK )
...
//else: dialog was cancelled or some another button pressed
dlg->Destroy();
}

You can also achieve the same result by using the stack:

void AskUser()
{
MyAskDialog dlg(...);
if ( dlg.ShowModal() == wxID_OK )
...
// no need to call Destroy() here
}

Normally you will derive a new class from wxDialog rather than using it directly so that you can handle events such as wxEVT_CLOSE (see the following) and command events. Often you will create your dialog's controls within the constructor.

Just as with wxFrame, wxWidgets will resize a single child window to fill the dialog, but for more than one child, the application is responsible for sizing and positioning the controls using sizers (see Chapter 7).

When you call Show, wxWidgets calls InitDialog to send a wxInitDialog Event to the dialog, transferring data to the dialog via validators or other means.

wxDialog has the following constructor in addition to the default constructor:

wxDialog(wxWindow* parent, wxWindowID id, const wxString& title,
const wxPoint& pos = wxDefaultPosition,
const wxSize& size = wxDefaultSize,
long style = wxDEFAULT_DIALOG_STYLE,
const wxString& name = wxT("dialog"));

For example:

wxDialog* dialog = new wxDialog(NULL, ID_MYDIALOG,
wxT("Hello wxWidgets"), wxDefaultPosition,
wxSize(500, 300));
dialog->Show(true);

The dialog won't be shown until Show(true) or ShowModal is called to give the application the chance to do child window layout invisibly.

By default, a dialog created with a NULL parent window will be given the application's top-level window as parent. Use the wxDIALOG_NO_PARENT style to prevent this from happening and create an orphan dialog. This is not recommended for modal dialogs.

As with wxFrame, do not use delete to destroy a dialog, but instead use Destroy or Close to delay deletion until all the object's events have been processed. When you call Close, the default wxEVT_CLOSE handler for this function usually calls Destroy.

Note that before a modal dialog is destroyed, an event handler should have called EndModal, passing the identifier of the command that closed it (for example, wxID_OK or wxID_CANCEL). This will exit the dialog's event loop so that the dialog object can be destroyed by the code that called ShowModal. The identifier passed to EndModal will be returned by ShowModal. To clarify, the OnCancel function in the following example will be called while ShowModal is in its event loop:

// Event handler for wxID_CANCEL
void MyDialog::OnCancel(wxCommandEvent& event)
{
EndModal(wxID_CANCEL);
}
// Show a dialog
void ShowDialog()
{
// Show the dialog
MyDialog dialog;
// OnCancel or other function is called from within ShowModal
if (dialog.ShowModal() == wxID_CANCEL)
{
...
}
}

Chapter 9. Dialogs can, of course, get more complicated, such as the settings dialog shown in Figure 4-8. This one has a splitter window, a tree control to navigate between multiple panels, and a grid control acting as a property editor.

wxDialog Styles

wxDialog can have the window styles listed in Table 4-8 in addition to those described for wxWindow.

Table 4-9 describes extra styles that couldn't be accommodated in the regular style, and so are set using wxWindow::SetExtraStyle. Although wxWS_EX_BLOCK_ EVENTS is valid for all windows, we repeat it here because it is set by default.

wxDialog Events

wxDialog generates the events listed in Table 4-10, in addition to those mentioned for wxWindow.

wxDialog Member Functions

These are the major wxDialog functions. Please refer also to the member functions for wxWindow and wxTopLevelWindow, from which wxDialog is derived.

GetTitle and SetTitle are accessors for the title that appears on the dialog's title bar.

Iconize iconizes or restores the dialog. You can test the dialog's iconic state by calling IsIconized.

Maximize maximizes the dialog (makes it as large as the desktop) or restores it to the previous state. Call IsMaximized to test whether the dialog is maximized. Windows only.

SetIcon sets the icon displayed when the dialog is minimized. It's also used for other purposes by the window manager, such as displaying the program's icon in Windows Explorer or on the taskbar. You can also use SetIcons to set an icon bundle (multiple icons with a variety of resolutions and depths).

ShowModal is used when showing a modal dialog. It returns the value of the identifier passed to EndModalnormally this is the identifier of the control that the user clicked on to dismiss the dialog. By default (implemented in the dialog's wxEVT_CLOSE handler), closing the dialog sends a simulated wxID_CANCEL to the dialog. The default handler for wxID_CANCEL calls EndModal with wxID_CANCEL. Therefore, if you provide a button with the identifier wxID_CANCEL, the logic for canceling the dialog is handled for you, unless you need extra functionality.

SetLeftMenu and SetRightMenu are only available on Microsoft Smartphone, and they set the commands allocated to the left and right menu buttons. They take a command identifier, such as wxID_OK, a label, and an optional pointer to a wxMenu to show.

wxPopupWindow

Pop-up windows are not implemented on all platforms (in particular, they are missing from Mac OS X), and so we will only briefly mention them.