Choice and Selection Dialogs

In this section, we look at dialogs for getting choices and selections from the user: wxColourDialog, wxFontDialog, wxSingleChoiceDialog, and wxMultiChoiceDialog.

wxColourDialog

This dialog allows the user to pick from a standard set or a full range of colors.

Under Windows, the native color selector dialog is used. This dialog contains three main regions: at the top left, a palette of 48 commonly used colors is shown. Below this, there is a palette of 16 custom colors, which can be set by the application. Additionally, the user may add to the custom color palette by expanding the dialog box and choosing a precise color from the color selector panel on the right. Figure 8-14 shows the color selector under Windows in full selection mode.

Figure 8-14. wxColourDialog under Windows

The generic color dialog, shown in Figure 8-15 under GTK+ 1 and X11, shows palettes of 48 standard and 16 custom colors, with the area on the right containing three sliders for the user to select a color from red, green, and blue components. This color may be added to the custom color palette, and it will replace either the currently selected custom color or the first one in the palette if none is selected. The RGB color sliders are not optional in the generic color selector. The generic color selector is also available under Windows and other platforms; use the name wxGenericColourDialog.

Figure 8-15. Generic wxColourDialog under X11

Figure 8-16 shows the native color dialog under GTK+.

Figure 8-16. wxColourDialog under GTK+

Figure 8-17 shows Mac OS X's color dialog, which offers yet another way of getting a color from the user.

Figure 8-17. wxColourDialog under Mac OS X

To use this dialog, create a wxColourDialog object (dynamically allocated or on the stack) and pass it a parent window and a pointer to a wxColourData object. The information in wxColourData will be copied to the dialog to set some defaults. Call ShowModal to enter the modal loop, and when control is returned to your code, you can retrieve the user-modified data by calling GetColourData.

wxColourData Functions

wxColourData has the following functions.

SetChooseFull specifies that the color dialog should show the full selection of colors; otherwise only a subset will be shown. This currently works only under Windows. GetChooseFull retrieves the value of this boolean.

SetColour sets the default color to show in the color selector, and GetColour retrieves the color that the user has chosen.

SetCustomColour takes a zero-based index (maximum 15) and a wxColour object and sets one of the 16 custom colors. Use GetCustomColour to retrieve the custom colors, which may have changed if the user has added to the custom colors from within the color selector.

wxColourDialog Example

Here is an example of using wxColourDialog. The code sets various parameters of a wxColourData object, including a gray scale for the custom colors. If the user did not cancel the dialog, the application retrieves the selected color and uses it to set the background of a window.

 #include "wx/colordlg.h" wxColourData data; data.SetChooseFull(true); for (int i = 0; i < 16; i++) {     wxColour color(i*16, i*16, i*16);     data.SetCustomColour(i, color); } wxColourDialog dialog(this, &data); if (dialog.ShowModal() == wxID_OK) {     wxColourData retData = dialog.GetColourData();     wxColour col = retData.GetColour();     myWindow->SetBackgroundColour(col);     myWindow->Refresh(); } 

wxFontDialog

wxFontDialog allows the user to provide font and, on some platforms, font color selections.

Under Windows, the native font selector standard dialog is used. This presents a dialog box with controls for font name, point size, style, weight, underlining, strikeout, and text foreground color. A sample of the font is shown on a white area of the dialog box. Note that in the translation from full Windows fonts to wxWidgets font conventions, strikeout is ignored, and a font family (such as Swiss or Modern) is deduced from the actual font name (such as Arial or Courier). Under GTK+, the GTK+ standard font selector is used, which does not allow color selection.

Figure 8-18 shows how the font dialog looks under Windows.

Figure 8-18. wxFontDialog under Windows

Figure 8-19 shows the native font dialog under GTK+.

Figure 8-19. wxFontDialog under GTK+

Under platforms other than Windows and GTK+, the font selector is simpler: see Figure 8-20 for a view of the generic dialog on Mac OS X. Controls for font family, point size, style, weight, underlining, and text foreground color are provided, and a sample is shown upon a white background. The generic font selector is available on all platforms; use the name wxGenericFontDialog.

Figure 8-20. Generic wxFontDialog under Mac OS X

To use wxFontDialog, create an object dynamically or on the stack and pass a parent window and a wxFontData object. Call ShowModal and test for a wxID_OK return value. Then retrieve the wxFontData from the dialog and call GetChosenFont and GetChosenColour as required.

wxFontData Functions

wxFontData has the following functions.

EnableEffects enables controls for manipulating color and underline properties under Windows or on the generic dialog (no effect on GTK+). GetEnableEffects returns the current boolean value of this setting. Note that even if effects are disabled, the font color will be preserved.

SetAllowSymbols allows the selection of symbol fonts (Windows only), and GetAllowSymbols returns the current boolean value of this setting.

SetColour sets the default font color, and GetColour retrieves the font color selected by the user.

SetInitialFont sets the default font that will be selected when the dialog is first opened. GetChosenFont retrieves the wxFont selected by the user.

SetShowHelp can be called to indicate that the help button should be displayed (under Windows only). Use GetShowHelp to return the value of this setting.

Call SetRange with the minimum and maximum point size that the user can select; the default (0, 0) indicates that any point size can be selected. This has an effect on Windows only.

Font Selector Example

In this fragment, the application uses the returned font and color for drawing text on a window.

 #include "wx/fontdlg.h" wxFontData data; data.SetInitialFont(m_font); data.SetColour(m_textColor); wxFontDialog dialog(this, &data); if (dialog.ShowModal() == wxID_OK) {     wxFontData retData = dialog.GetFontData();     m_font = retData.GetChosenFont();     m_textColor = retData.GetColour();     // Update the window to reflect the new font and color     myWindow->Refresh(); } 

wxSingleChoiceDialog

wxSingleChoiceDialog presents the user with a list of strings and allows the user to select one. It looks like the dialog in Figure 8-21.

Figure 8-21. wxSingleChoiceDialog under Windows

Pass to the dialog constructor the parent window, a message to show on the dialog, the dialog caption, and a wxArrayString for the strings to appear in the list. You can also pass an array size and a C array of strings (wxChar**) instead of passing a wxArrayString.

You can use SetSelection to set the default selection before showing the dialog; after the dialog has been dismissed, query the user's choice with GetSelection (to return the index) or GetStringSelection (to return the string).

You also can pass an array of char* client data to the dialog's constructor; when the dialog is dismissed, GetSelectionClientData will return the char* client data corresponding to the user selection.

wxSingleChoiceDialog Example

Here's some code to show how wxSingleChoiceDialog is used.

 #include "wx/choicdlg.h" const wxArrayString choices; choices.Add(wxT("One")); choices.Add(wxT("Two")); choices.Add(wxT("Three")); choices.Add(wxT("Four")); choices.Add(wxT("Five")); wxSingleChoiceDialog dialog(this,                             wxT("This is a small sample\nA single-choice convenience dialog"),                             wxT("Please select a value"),                             choices); dialog.SetSelection(2); if (dialog.ShowModal() == wxID_OK)     wxMessageBox(dialog.GetStringSelection(), wxT("Got string")); 

wxMultiChoiceDialog

wxMultiChoiceDialog is similar to wxSingleChoiceDialog, presenting the user with a list of strings, but it allows the user to select zero or more. This dialog is illustrated in Figure 8-22.

Figure 8-22. wxMultiChoiceDialog under Windows

Pass to the dialog constructor the parent window, a message to show on the dialog, the dialog caption, and a wxArrayString array of strings. As with wxSingleChoiceDialog, you may pass an array size and wxChar** array instead of the wxArrayString argument. Unlike wxSingleChoiceDialog, no client data may be passed to the constructor.

To set the default selections, call SetSelections passing a wxArrayInt where each element specifies an index in the passed array of strings. Query the user's choice with GetSelections to return a wxArrayInt of indices specifying the user's selections.

wxMultiChoiceDialog Example

Here's how you use a wxMultiChoiceDialog.

 #include "wx/choicdlg.h" const wxArrayString choices; choices.Add(wxT("One")); choices.Add(wxT("Two")); choices.Add(wxT("Three")); choices.Add(wxT("Four")); choices.Add(wxT("Five")); wxMultiChoiceDialog dialog(this,                             wxT("A multi-choice convenience dialog"),                             wxT("Please select several values"),                             choices); if (dialog.ShowModal() == wxID_OK) {     wxArrayInt selections = dialog.GetSelections();     wxString msg;     msg.Printf(wxT("You selected %u items:\n"),         selections.GetCount());     for ( size_t n = 0; n < selections.GetCount(); n++ )     {         msg += wxString::Format(wxT("\t%d: %d (%s)\n"),                               n, selections[n],                               choices[selections[n]].c_str());     }     wxMessageBox(msg, wxT("Got selections")); }