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

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.

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.

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.

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.

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.

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.

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;
}