Informative Dialogs

In this section, we'll look at dialogs that present information: wxMessageDialog, wxProgressDialog, wxBusyInfo, and wxShowTip.

wxMessageDialog

This dialog shows a message plus buttons that can be chosen from OK, Cancel, Yes, and No. An optional icon can be shown, such as an exclamation mark or question mark. The message text can contain newlines ("\n").

The return value of wxMessageDialog::ShowModal indicates which button the user pressed.

Figure 8-1 shows how the dialog looks under Windows, Figure 8-2 shows it under GTK+, and Figure 8-3 is the same dialog on Mac OS X.

Figure 8-1. wxMessageDialog under Windows

Figure 8-2. wxMessageDialog under GTK+

Figure 8-3. wxMessageDialog under Mac OS X

To create this dialog, pass a parent window, message, and optional caption, style, and position. Then call ShowModal to display the window, and test the returned value.

The style is a bit-list of the values shown in Table 8-1.

Table 8-1. wxMessageDialog Styles

wxOK	Shows an OK button.
wxCANCEL	Shows a Cancel button.
wxYES_NO	Shows Yes and No buttons.
wxYES_DEFAULT	Sets Yes as the default. Use with wxYES_NO.This is the default behavior for wxYES_NO.
wxNO_DEFAULT	Sets No as the default. Use with wxYES_NO.
wxICON_EXCLAMATION	Shows an exclamation mark.
wxICON_ERROR	Shows an error icon.
wxICON_HAND	Shows an error icon. The same as wxICON_ERROR.
wxICON_QUESTION	Shows a question mark.
wxICON_INFORMATION	Shows an information icon.
wxSTAY_ON_TOP	On Windows, the message box will stay on top of all other windows, even those of other applications.

wxMessageDialog Example

Here's an example of using wxMessageDialog:

 #include "wx/msgdlg.h" wxMessageDialog dialog( NULL, wxT("Message box caption"),       wxT("Message box text"),       wxNO_DEFAULT|wxYES_NO|wxCANCEL|wxICON_INFORMATION); switch ( dialog.ShowModal() ) {   case wxID_YES:       wxLogStatus(wxT("You pressed \"Yes\""));       break;   case wxID_NO:       wxLogStatus(wxT("You pressed \"No\""));       break;   case wxID_CANCEL:       wxLogStatus(wxT("You pressed \"Cancel\""));       break;   default:       wxLogError(wxT("Unexpected wxMessageDialog return code!")); } 

wxMessageBox

You can also use the convenience function wxMessageBox, which takes a message string, caption string, style, and parent window. For example:

 if (wxYES == wxMessageBox(wxT("Message box text"),     wxT("Message box caption"),     wxNO_DEFAULT|wxYES_NO|wxCANCEL|wxICON_INFORMATION,     parent)) {     return true; } 

Be aware that wxMessageBox returns values that are different from those returned by wxMessageDialog::ShowModal. wxMessageBox returns wxOK, wxCANCEL, wxYES, and wxNO, whereas wxMessageDialog::ShowModal returns wxID_OK, wxID_CANCEL, wxID_YES, and wxID_NO.

wxProgressDialog

wxProgressDialog shows a short message and a progress bar representing how long the user has to wait. It can display a Cancel button to abort the task in progress, and it can also display elapsed time, estimated total time, and remaining time. This dialog is implemented by wxWidgets on all platforms. Figure 8-4 shows wxProgressDialog under Windows.

Figure 8-4. wxProgressDialog under Windows

You can create the dialog object on the stack or dynamically. Pass the following parameters: a caption string, a message string to be displayed above the progress bar, the maximum value for the progress bar, a parent window, and a style.

The style is a bit-list of the values listed in Table 8-2.

Table 8-2. wxProgressDialog Styles

wxPD_APP_MODAL	Makes the progress dialog modal. If this style is not given, it is only "locally" modalthat is, the input to the parent window is disabled, but not to the other ones.
wxPD_AUTO_HIDE	Causes the progress dialog to disappear from the screen as soon as the maximum value of the progress meter has been reached.
wxPD_CAN_ABORT	Tells the dialog that it should have a Cancel button that the user may press. If this happens, the next call to Update will return false.
wxPD_ELAPSED_TIME	Tells the dialog that it should show the elapsed time since creating the dialog.
wxPD_ESTIMATED_TIME	Tells the dialog that it should show the estimated time.
wxPD_REMAINING_TIME	Tells the dialog that it should show the remaining time.

After dialog creation, the program flow continues, but the parent window is disabled for input. If wxPD_APP_MODAL is specified, then all other windows in the application are disabled as well. The application should call Update with a value (between zero and the maximum specified in the constructor) and, optionally, a new message to display in the dialog. If specified, the elapsed, estimated, and remaining times are all calculated automatically by the dialog.

If wxPD_AUTO_HIDE is specified, the progress dialog will be hidden (but not destroyed) as soon as the maximum value has been passed to Update. The application should destroy the dialog. You can call Resume if you need to resume an aborted progress dialog.

wxProgressDialog Example

Here's an example of using the progress dialog:

 #include "wx/progdlg.h" void MyFrame::ShowProgress() {     static const int max = 10;     wxProgressDialog dialog(wxT("Progress dialog example"),                               wxT("An informative message"),                               max,    // range                               this,   // parent                               wxPD_CAN_ABORT |                               wxPD_APP_MODAL |                               wxPD_ELAPSED_TIME |                               wxPD_ESTIMATED_TIME |                               wxPD_REMAINING_TIME);     bool cont = true;     for ( int i = 0; i <= max; i++ )     {         wxSleep(1);         if ( i == max )             cont = dialog.Update(i, wxT("That's all, folks!"));         else if ( i == max / 2 )             cont = dialog.Update(i, wxT("Only a half left (very long message)!"));         else             cont = dialog.Update(i);         if ( !cont )         {             if ( wxMessageBox(wxT("Do you really want to cancel?"),                                wxT("Progress dialog question"),                                wxYES_NO | wxICON_QUESTION) == wxYES )                 break;             dialog.Resume();         }     }     if ( !cont )         wxLogStatus(wxT("Progress dialog aborted!"));     else         wxLogStatus(wxT("Countdown from %d finished"), max); } 

wxBusyInfo

wxBusyInfo isn't actually a dialogit's derived from wxObjectbut it behaves in a similar way. It shows a window displaying a message for as long as the object exists, and it is useful for asking the user to wait while the application is working on something. On Windows, it looks like the window in Figure 8-5.

Figure 8-5. wxBusyInfo dialog under Windows

Create a wxBusyInfo object on the stack or dynamically, passing a message and a window parent.

wxBusyInfo Example

Here's an example of using wxBusyInfo, first using wxWindowDisabler to disable all windows currently open in the application.

 #include "wx/busyinfo.h" wxWindowDisabler disableAll; wxBusyInfo info(wxT("Counting, please wait..."), parent); for (int i = 0; i < 1000; i++) {     DoCalculation(); } 

wxShowTip

Many applications show a tip on startup to give you extra insights into using the application. Tips can be a good way to learn an application in small, easily digested doses, especially for users who find it tedious to read documentation.

The startup tip dialog under Windows is shown in Figure 8-6.

Figure 8-6. Tip dialog under Windows

Unlike most of the standard dialogs, startup tips are shown by calling a function: wxShowTip. Pass a parent window, a pointer to a wxTipProvider object, and optionally a boolean value specifying whether to show the Show Tips at Startup check box. The return value is the value of this check box.

You must derive a new class from wxTipProvider and override the GetTip function to return a wxString containing the tip. Fortunately, wxWidgets provides an implementation already: wxCreateFileTipProvider, which takes the name of a file of tips (one per line) and an index into the tips.

The application is responsible for deleting the wxTipProvider object when it is no longer needed.

wxShowTip Example

Here's a function that shows a startup tip using the standard tip provider:

 #include "wx/tipdlg.h" void MyFrame::ShowTip() {     static size_t s_index = (size_t)-1;     if ( s_index == (size_t)-1 )     {         // randomize...         srand(time(NULL));         // ...and pick a new tip         s_index = rand() % 5;     }     // pass a tips file and tip index     wxTipProvider *tipProvider =         wxCreateFileTipProvider(wxT("tips.txt"), s_index);     m_showAtStartup = wxShowTip(this, tipProvider, true);     delete tipProvider; }