Here’s the declaration for our PersonalRecordDialog. We provide run-time type information by using DECLARE_CLASS, and we add an event table with DECLARE_EVENT_TABLE.

Note that we follow wxWidgets convention by allowing both one-step and two-step construction—we provide a default constructor and Create function as well as a more verbose constructor.

We have four pieces of data to store: name (string), age (integer), sex (boolean), and voting preference (boolean). To make it easier to use a wxChoice control with the data, we’re going to use an integer to store the boolean value for sex, but the class interface can present it as boolean: true for female and false for male. Let’s add these data members and accessors to the PersonalRecordDialog class:

Now let’s add a CreateControls function to be called from Create. CreateControls adds wxStaticText controls, wxButton controls, a wxSpinCtrl, a wxTextCtrl, a wxChoice, and a wxCheckBox. Refer to Figure 9-1 earlier in the chapter to see the resulting dialog.

We’re using sizer-based layout for this dialog, which is why it looks a bit more involved than you might expect for a small number of controls. (We described sizers in Chapter 7, “Window Layout Using Sizers”—briefly, they enable you to create dialogs that look good on any platform and that easily adapt to translation and resizing.) You can use a different method if you want, such as loading the dialog from a wxWidgets resource file (XRC file).

The basic principle of sizer-based layout is to put controls into nested boxes (sizers), which can distribute space among the controls or stretch just enough to contain its controls. The sizers aren’t windows—they form a separate hierarchy, and the controls remain children of their parent, regardless of the complexity of the hierarchy of sizers. You might like to refresh your memory by looking at the schematic view of a sizer layout that we showed in Figure 7-2 in Chapter 7.

In CreateControls, we’re using a vertical box sizer (boxSizer) nested in another vertical box sizer (topSizer) to give a decent amount of space around the dialog’s controls. A horizontal box sizer is used for the wxSpinCtrl, wxChoice, and wxCheckBox, and a second horizontal box sizer (okCancelSizer) is used for the Reset, OK, Cancel, and Help buttons.

Now we have the bare controls of the dialog, but the controls and the dialog’s data are not connected. How do we make that connection?

When a dialog is first shown, wxWidgets calls InitDialog, which in turn sends a wxEVT_INIT_DIALOG event. The default handler for this event calls TransferDataToWindow on the dialog. To transfer data from the controls back to the variables, you can call TransferDataFromWindow when the user confirms his or her input. Again, wxWidgets does this for you by defining a default handler for wxID_OK command events, which calls TransferDataFromWindow before calling EndModal to dismiss the dialog.

So, you can override TransferDataToWindow and TransferDataFromWindow to transfer your data. For our dialog, the code might look like this:

However, there’s an easier way of transferring data. wxWidgets supports validators, which are objects that link data variables and their corresponding controls. Although not always applicable, the use of validators where possible will save you a lot of time and can make it unnecessary to write TransferData ToWindow and TransferDataFromWindow functions. In our PersonalRecordDialog example, we can use the following code instead of the previous two functions:

These few lines of code at the end of CreateControls replace the two overridden functions. As a bonus, the user will be prevented from accidentally entering numbers in the Name field.

Validators can perform two jobs—as well as data transfer, they can validate the data and show error messages if the data doesn’t conform to a particular specification. In this example, no actual validation of the input is done, other than for the name. wxGenericValidator is a relatively simple class, only doing data transfer. However, it works with the basic control classes. The other validator provided as standard, wxTextValidator, has more sophisticated behavior and can even intercept keystrokes to veto invalid characters. In the example, we just use the standard style wxFILTER_ALPHA, but we could also specify which characters should or should not be regarded as valid by using the validator’s SetIncludes and SetExcludes functions.

We need to dig a bit deeper into how wxWidgets handles validators in order to understand what’s going on here. As we’ve seen, the default OnOK handler calls TransferDataToWindow, but before it does so, it calls Validate, vetoing the calls to TransferDataToWindow and EndModal if validation fails. This is the default implementation of OnOK:

The default implementation of Validate iterates through all the children of the dialog (and their descendants, if you specified the extra window style wxWS_EX_VALIDATE_RECURSIVELY), calling Validate for each control’s wxValidator object. If any of these calls fails, then validation for the dialog fails, and the dialog is not dismissed. The validator is expected to show a suitable error message from within its Validate function if it fails the validation.

Similarly, TransferDataToWindow and TransferDataFromWindow will be called automatically for the validators of a dialog’s controls. A validator must do data transfer, but validation is optional.

A validator is an event handler, and the event processing mechanism will route events to the validator, if present, before passing the events on to the control. This enables validators to intercept user input—for example, to veto characters that are not permitted in a control. Such vetoing should normally be accompanied by a beep to inform the user that the key was pressed but not accepted.

Because the two provided validator classes may not be sufficient for your needs, especially if you write your own custom controls, you can derive new validator classes from wxValidator. This class should have a copy constructor and a Clone function that returns a copy of the validator object, as well as implementations for data transfer and validation. A validator will typically store a pointer to a C++ variable, and the constructor may take flags to specify modes of use. You can look at the files include/wx/valtext.h and src/common/valtext.cpp in wxWidgets to see how a validator can be implemented; see also “Writing Your Own Controls” in Chapter 12, “Advanced Window Classes.”

In this example, wxWidgets’ default processing for OK and Cancel are sufficient without any extra coding on our part, as long as we use the standard wxID_OK and wxID_CANCEL identifiers for the controls. However, for non-trivial dialogs, you probably will have to intercept and handle events from controls. In our example, we have a Reset button, which can be clicked at any time to reset the dialog back to its default values. We add an OnResetClick event handler and a suitable entry in our event table. Implementing OnResetClick turns out to be very easy; first we reset the data variables by calling the Init function we added to centralize data member initialization. Then we call TransferDataToWindow to display that data.

One of the challenges faced by the application developer is making sure that the user can’t click on controls and menus that are not currently applicable. A sure sign of sloppy programming is the appearance of messages that say, “This option is not currently available.” If an option isn’t available, then it should not look available, and clicking on the control or menu should do nothing. As time-consuming as it can be, the programmer should update the elements of the interface to reflect the context at every instant.

In our example, we must disable the Vote check box when the user’s age is less than 18 because in that case, the decision is not available to the user. Your first thought might be to add an event handler for the Age spin control and enable or disable the Vote check box according to the spin control’s value. Although this may be fine for simple user interfaces, imagine what happens when many factors are influencing the availability of controls. Even worse, there are some cases where the approach doesn’t work at all because you cannot be notified when the change occurs. An example of this situation is when you need to enable a Paste button or menu item when data becomes available on the clipboard. This event is outside your power to intercept because the data may become available from another program.

To solve these problems, wxWidgets provides an event class called wxUpdateUIEvent that it sends to all windows in idle time—that is, when the event loop has finished processing all other input. You can add EVT_UPDATE_UI event table entries to your dialog, one for each control whose state you need to maintain. Each UI update event handler evaluates the current state of the world and calls functions in the event object (not the control) to enable, disable, check, or uncheck the control. This technique puts the logic for updating each control in one place, calling the event handler even when no real event has been handled in the application. You can breathe a sigh of relief because you don’t have to remember to update the user interface after any change that might happen to be relevant!

Here’s our UI update handler for the Vote control. Note that we can’t use the m_age variable because transfer from the controls to the variables doesn’t happen until the user clicks OK.

Don’t worry unduly about efficiency considerations; plenty of spare cycles are available for processing these handlers. However, if you have a very complex application and run into performance problems, see the wxUpdateUIEvent documentation for the functions SetMode and SetUpdateInterval that can be used to decrease the time wxWidgets spends processing these events.

There are at least three kinds of help you can provide for your dialog:

You can probably think of further techniques not explicitly supported by wxWidgets. We already have some descriptive text on the dialog described here. For a more complex dialog, you could create a wxHtmlWindow instead of a wxStaticText and load an HTML file containing further details. Alternatively, a small help button could be placed next to each control to show a description when clicked.

The three main types of help supported by wxWidgets are described in the following sections.

The complete implementation of the dialog is listed in Appendix J, “Code Listings,” and can also be found in examples/chap09 on the CD-ROM.

Now that we have the dialog completely coded, we can invoke it:

Provide mnemonics in static text labels and other labeled controls by inserting ampersands in front of characters. On some platforms (notably Windows and GTK+), this will help the user navigate between controls.

Always provide a means for the user to cancel the dialog, preferably with the option of using the Escape key. If a dialog has a button with the identifier wxID_CANCEL, its handler will automatically be called when the user presses the Escape key. So, if you have a Close button, consider giving it the wxID_CANCEL identifier.

Provide a default button (often OK)—for example, by calling wxButton:: SetDefault. The command for this button will be invoked when the user presses the Enter key.

To simplify the example, the data variables that PersonalRecordDialog uses are stored in the class itself. However, a better design would be to provide a data class separate from the dialog class, with a copy constructor and assignment operator, so that you can pass a copy of the data to the dialog and retrieve the modified data from the dialog only if the user confirms any changes. This is the approach adopted for some of the standard dialogs. As an exercise, you can rewrite the PersonalRecordDialog using a PersonalRecordData class. The dialog constructor will take a PersonalRecordData reference, and there will be a GetData function so that the calling application can retrieve the data.

In general, always consider how you can separate out the UI functionality from non-UI functionality. The result will usually be code that is more compact and easier to understand and debug. Don’t be afraid to introduce new classes to make the design more elegant, and make use of copy constructors and assignment operators so that objects can easily be copied and assigned without the application having to repeat lots of low-level code.

Unless you provide an Apply button that commits your changes to the underlying data, canceling the dialog should leave the application data in the same state as it was before the dialog was opened. The use of a separate data class makes this easier to achieve because the dialog isn’t editing “live” data but rather a copy.

If your dialog looks claustrophobic or somehow odd, it may be due to a lack of space. Try adding a bigger border around the edge of the dialog by using an additional sizer (as in our PersonalRecordDialog example) and adding space between groups of controls. Use wxStaticBoxSizer and wxStaticLine to logically group or separate controls. Use wxGridSizer and wxFlexGridSizer to align controls and their labels so that they don’t appear as a random jumble. In sizer-based layouts, use expanding spacers to align a group of controls. For example, often OK, Cancel, and Help buttons are in a right-aligned group, which can be achieved by placing a spacer and the buttons in a horizontal wxBoxSizer and setting the spacer to expand horizontally (give it a positive stretch factor).

If possible and appropriate, make your dialog resizable. Traditionally, Windows dialog boxes haven’t often been resizable, but there is no reason why this should be the case, and fiddling with tiny controls on a large display can be a frustrating experience for the user. wxWidgets makes it easy to create resizable dialogs with sizers, and you should be using sizers anyway to allow for font and control size differences and changes in language. Choose carefully which elements should grow; for example, there may be a multi-line text control that is a good candidate for growing and giving the user more elbow room. Again, you can put expanding spacers to good use to preserve alignment in a resized dialog. Note that we’re not resizing controls in the sense of zooming in and out, making text bigger or smaller—we’re simply giving more or less space for items in the control. See Chapter 7 for more about sizers.

If you find that your dialog is becoming too large, split it up into a number of panels and use a wxNotebook, wxListbook, or wxChoicebook to enable selection of one page at a time. Using lots of independent dialogs is annoying to the user and clutters up your menus, whereas browsing through pages is perfectly acceptable. Scrolling panels should be avoided unless there’s a very good reason to use them. The ability to scroll controls is not supported on all platforms, and use of scrolling can be a sign that the user interface has not been adequately planned. If you have many properties to edit, consider using a property editor based on wxGrid or a third-party class (see wxPropertyGrid, which is mentioned in Appendix E, “Third-Party Tools for wxWidgets”).

Be consistent with label capitalization. Don’t be tempted to use custom colors or fonts in your dialog; this can be distracting and can look out of place in the context of the current theme and other dialogs in the application. For best results across platforms, leave control fonts and colors to wxWidgets. Instead, consider providing some impact through judicious use of wxStaticBitmap controls.

Finally, consider whether you should be creating an independent dialog box at all—a modeless solution, such as a tab in the main application window, might be better. Most of the principles of dialog design and implementation apply to modeless dialogs and panels, but there are added challenges of layout (the window has less control of its size) and synchronization (the window may no longer have exclusive use of the data it is showing).

To use XRC files in your application, you need to include wx/xrc/xmlres.h in your application code.

If you will be converting your XRC files to binary XRS files, as we will describe shortly, install the zip file system handler by placing an AddHandler call in your OnInit function:

Initialize the XRC system by adding this to your OnInit:

Load the XRC file with code like this:

This makes wxWidgets aware of the resources in the file; to create a real UI element, we need another call. For example, the following fragment creates a dialog whose resource name is dialog1:

The following code shows how to load menu bars, menus, toolbars, bitmaps, icons, and panels.

wxWidgets maintains a single wxXmlResource object that you can use, but alternatively, you can create a wxXmlResource object, load resources, and then destroy it. You can also use wxXmlResource::Set to set the current global resource object, destroying the old one.

To define event tables for windows loaded from a resource file, you can’t use integer identifiers because resources have string names. Instead, use the XRCID macro, which takes a resource name and returns an integer identifier associated with the name. XRCID is an alias for the function wxXmlResource:: GetXRCID. Here’s an example of XRCID usage:

It can be convenient to combine a number of resource files into one binary file (extension xrs). To compile XRC files into a zip file that the resource system can load, use the utility wxrc located in the utils/wxrc directory in your wxWidgets distribution:

Use wxXmlResource::Load to load a binary resource file in just the same way as with a plain XML file.

You can also compile your XRC files into C++ code that may be embedded in your application, thereby eliminating a separate resource file. Here’s the wxrc command to do this:

Compile this C++ file as normal and link it with your application. The file includes a function InitXmlResource, which you have to call, for example:

Table 9-2 lists the command-line options and arguments that wxrc accepts.

If the wxXmlResource object has been created with the wxXRC_USE_LOCALE flag (the default behavior), all displayable strings will be subject to translation, as detailed in Chapter 16, “Writing International Applications.” However, poEdit cannot scan XRC files for strings to translate as it can for C++ code, so you can create a file of such strings using wxrc with the -g option. For example:

Then you can run poEdit to scan the strings in this and other files.

There isn’t space to describe the XRC format in detail, but here is an example showing a simple dialog with sizers:

A detailed specification of the XRC format can be found in the technical note docs/tech/tn0014.txt in your wxWidgets distribution. If you use an editor to create your user interfaces, you won’t need to know about XRC’s format.

You may be wondering how a text XRC file can be used to specify binary bitmaps and icons. These resources may be specified as URLs, and wxWidgets’ virtual file system will extract them from sources such as a zip file. For example:

See Chapter 10, “Programming with Images,” and Chapter 14, “Files and Streams,” for more information on using virtual file systems to load resources such as images.

The XRC system uses a resource handler to recognize the XML specification of each type of resource. If you write your own custom control, you may want to write a resource handler so that applications can use the custom control with XRC.

As an illustration, the declaration for wxButton’s handler looks like this:

The handler implementation is quite simple. In the handler’s constructor, the XRC_ADD_STYLE macro is used to make the handler aware of specific button styles, and AddWindowStyles is called to add common window styles. In DoCreateResource, the button object is created in two steps, using XRC_MAKE_INSTANCE and then Create, extracting parameters such as the label, position, and size. Finally, CanHandle tests whether this handler can handle the node in question. It’s permissible for a single handler class to handle more than one kind of resource.

To use a handler, an application needs to include the header and register the handler, as follows:

An XRC file can specify a foreign, or “unknown” control, by specifying class="unknown" in the object definition. This can stand in for a control that is actually created in the C++ code, after the parent is loaded from XRC. When XRC loads the unknown object, a placeholder window is created. Then the application calls AttachUnknownControl to superimpose the real window onto the placeholder window, with the correct position and size. For example:

The custom control definition can look like this:

Using this technique, you can lay out interfaces in tools that don’t know about your custom controls, and you also avoid the need to write a resource handler.