Dialog functions

Dialog functions

Below are a number of convenience functions for getting input from the user or displaying messages. Note that in these functions the last three parameters are optional. However, it is recommended to pass a parent frame parameter, or (in MS Windows or Motif) the wrong window frame may be brought to the front when the dialog box is popped up.

::wxAboutBox
::wxBeginBusyCursor
::wxBell
::wxCreateFileTipProvider
::wxDirSelector
::wxFileSelector
::wxEndBusyCursor
::wxGenericAboutBox
::wxGetColourFromUser
::wxGetFontFromUser
::wxGetMultipleChoices
::wxGetNumberFromUser
::wxGetPasswordFromUser
::wxGetTextFromUser
::wxGetMultipleChoice
::wxGetSingleChoice
::wxGetSingleChoiceIndex
::wxGetSingleChoiceData
::wxIsBusy
::wxMessageBox
::wxShowTip

::wxAboutBox

void wxAboutBox(const wxAboutDialogInfo& info)

This function shows the standard about dialog containing the information specified in info. If the current platform has a native about dialog which is capable of showing all the fields in info, the native dialog is used, otherwise the function falls back to the generic wxWidgets version of the dialog, i.e. does the same thing as wxGenericAboutBox().

Here is an example of how this function may be used:

void MyFrame::ShowSimpleAboutDialog(wxCommandEvent& WXUNUSED(event))
{
    wxAboutDialogInfo info;
    info.SetName(_("My Program"));
    info.SetVersion(_("1.2.3 Beta"));
    info.SetDescription(_("This program does something great."));
    info.SetCopyright(_T("(C) 2007 Me <[email protected]>"));

    wxAboutBox(info);
}

Please see the dialogs sample for more examples of using this function and wxAboutDialogInfo for the description of the information which can be shown in the about dialog.

Include files

::wxBeginBusyCursor

void wxBeginBusyCursor(wxCursor *cursor = wxHOURGLASS_CURSOR)

Changes the cursor to the given cursor for all windows in the application. Use wxEndBusyCursor to revert the cursor back to its previous state. These two calls can be nested, and a counter ensures that only the outer calls take effect.

::wxBell

void wxBell()

Ring the system bell.

Include files

::wxCreateFileTipProvider

wxTipProvider * wxCreateFileTipProvider(const wxString& filename, size_t currentTip)

This function creates a wxTipProvider which may be used with wxShowTip.

filename

The name of the file containing the tips, one per line

currentTip

The index of the first tip to show - normally this index is remembered between the 2 program runs.

See also

Tips overview

Include files

::wxDirSelector

wxString wxDirSelector(const wxString& message = wxDirSelectorPromptStr,
const wxString& default_path = "",
long style = 0, const wxPoint& pos = wxDefaultPosition,
wxWindow *parent = NULL)

Pops up a directory selector dialog. The arguments have the same meaning as those of wxDirDialog::wxDirDialog(). The message is displayed at the top, and the default_path, if specified, is set as the initial selection.

The application must check for an empty return value (if the user pressed Cancel). For example:

const wxString& dir = wxDirSelector("Choose a folder");
if ( !dir.empty() )
{
  ...
}

Include files

::wxFileSelector

wxString wxFileSelector(const wxString& message, const wxString& default_path = "",
const wxString& default_filename = "", const wxString& default_extension = "",
const wxString& wildcard = "*.*", int flags = 0, wxWindow *parent = NULL,
int x = -1, int y = -1)

Pops up a file selector box. In Windows, this is the common file selector dialog. In X, this is a file selector box with the same functionality. The path and filename are distinct elements of a full file pathname. If path is empty, the current directory will be used. If filename is empty, no default filename will be supplied. The wildcard determines what files are displayed in the file selector, and file extension supplies a type extension for the required filename. Flags may be a combination of wxOPEN, wxSAVE, wxOVERWRITE_PROMPT or wxFILE_MUST_EXIST. Note that wxMULTIPLE can only be used with wxFileDialog and not here as this function only returns a single file name.

Both the Unix and Windows versions implement a wildcard filter. Typing a filename containing wildcards (*, ?) in the filename text item, and clicking on Ok, will result in only those files matching the pattern being displayed.

The wildcard may be a specification for multiple types of file with a description for each, such as:

 "BMP files (*.bmp)|*.bmp|GIF files (*.gif)|*.gif"

The application must check for an empty return value (the user pressed Cancel). For example:

wxString filename = wxFileSelector("Choose a file to open");
if ( !filename.empty() )
{
    // work with the file
    ...
}
//else: cancelled by user

Include files

::wxEndBusyCursor

void wxEndBusyCursor()

Changes the cursor back to the original cursor, for all windows in the application. Use with wxBeginBusyCursor.

::wxGenericAboutBox

void wxGenericAboutBox(const wxAboutDialogInfo& info)

This function does the same thing as wxAboutBox except that it always uses the generic wxWidgets version of the dialog instead of the native one. This is mainly useful if you need to customize the dialog by e.g. adding custom controls to it (customizing the native dialog is not currently supported).

See the dialogs sample for an example of about dialog customization.

See also

wxAboutDialogInfo

Include files

::wxGetColourFromUser

wxColour wxGetColourFromUser(wxWindow *parent, const wxColour& colInit, const wxString& caption = wxEmptyString)

Shows the colour selection dialog and returns the colour selected by user or invalid colour (use wxColour:IsOk to test whether a colour is valid) if the dialog was cancelled.

Parameters

parent

The parent window for the colour selection dialog

colInit

If given, this will be the colour initially selected in the dialog.

caption

If given, this will be used for the dialog caption.

Include files

::wxGetFontFromUser

wxFont wxGetFontFromUser(wxWindow *parent, const wxFont& fontInit, const wxString& caption = wxEmptyString)

Shows the font selection dialog and returns the font selected by user or invalid font (use wxFont:IsOk to test whether a font is valid) if the dialog was cancelled.

Parameters

parent

The parent window for the font selection dialog

fontInit

If given, this will be the font initially selected in the dialog.

caption

If given, this will be used for the dialog caption.

Include files

::wxGetMultipleChoices

size_t wxGetMultipleChoices(
wxArrayInt& selections,
const wxString& message,
const wxString& caption,
const wxArrayString& aChoices,
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true,
int width=150, int height=200)

size_t wxGetMultipleChoices(
wxArrayInt& selections,
const wxString& message,
const wxString& caption,
int n, const wxString& choices[],
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true,
int width=150, int height=200)

Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection listbox. The user may choose an arbitrary (including 0) number of items in the listbox whose indices will be returned in selection array. The initial contents of this array will be used to select the items when the dialog is shown.

You may pass the list of strings to choose from either using choices which is an array of n strings for the listbox or by using a single aChoices parameter of type wxArrayString.

If centre is true, the message text (which may include new line characters) is centred; if false, the message is left-justified.

Include files

::wxGetNumberFromUser

long wxGetNumberFromUser( const wxString& message, const wxString& prompt, const wxString& caption, long value, long min = 0, long max = 100, wxWindow *parent = NULL, const wxPoint& pos = wxDefaultPosition)

Shows a dialog asking the user for numeric input. The dialogs title is set to caption, it contains a (possibly) multiline message above the single line prompt and the zone for entering the number.

The number entered must be in the range min..max (both of which should be positive) and value is the initial value of it. If the user enters an invalid value or cancels the dialog, the function will return -1.

Dialog is centered on its parent unless an explicit position is given in pos.

Include files

::wxGetPasswordFromUser

wxString wxGetPasswordFromUser(const wxString& message, const wxString& caption = "Input text",
const wxString& default_value = "", wxWindow *parent = NULL,
int x = wxDefaultCoord, int y = wxDefaultCoord, bool centre = true)

Similar to wxGetTextFromUser but the text entered in the dialog is not shown on screen but replaced with stars. This is intended to be used for entering passwords as the function name implies.

Include files

::wxGetTextFromUser

wxString wxGetTextFromUser(const wxString& message, const wxString& caption = "Input text",
const wxString& default_value = "", wxWindow *parent = NULL,
int x = wxDefaultCoord, int y = wxDefaultCoord, bool centre = true)

Pop up a dialog box with title set to caption, message, and a default_value. The user may type in text and press OK to return this text, or press Cancel to return the empty string.

If centre is true, the message text (which may include new line characters) is centred; if false, the message is left-justified.

Include files

::wxGetMultipleChoice

int wxGetMultipleChoice(const wxString& message, const wxString& caption, int n, const wxString& choices[],
int nsel, int *selection, wxWindow *parent = NULL, int x = -1, int y = -1,
bool centre = true, int width=150, int height=200)

Pops up a dialog box containing a message, OK/Cancel buttons and a multiple-selection listbox. The user may choose one or more item(s) and press OK or Cancel.

The number of initially selected choices, and array of the selected indices, are passed in; this array will contain the user selections on exit, with the function returning the number of selections. selection must be as big as the number of choices, in case all are selected.

If Cancel is pressed, -1 is returned.

choices is an array of n strings for the listbox.

If centre is true, the message text (which may include new line characters) is centred; if false, the message is left-justified.

Include files

::wxGetSingleChoice

wxString wxGetSingleChoice(const wxString& message,
const wxString& caption,
const wxArrayString& aChoices,
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true,
int width=150, int height=200)

wxString wxGetSingleChoice(const wxString& message,
const wxString& caption,
int n, const wxString& choices[],
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true,
int width=150, int height=200)

Pops up a dialog box containing a message, OK/Cancel buttons and a single-selection listbox. The user may choose an item and press OK to return a string or Cancel to return the empty string. Use wxGetSingleChoiceIndex if empty string is a valid choice and if you want to be able to detect pressing Cancel reliably.

You may pass the list of strings to choose from either using choices which is an array of n strings for the listbox or by using a single aChoices parameter of type wxArrayString.

If centre is true, the message text (which may include new line characters) is centred; if false, the message is left-justified.

Include files

::wxGetSingleChoiceIndex

int wxGetSingleChoiceIndex(const wxString& message,
const wxString& caption,
const wxArrayString& aChoices,
wxWindow *parent = NULL, int x = -1, int y = -1,
bool centre = true, int width=150, int height=200)

int wxGetSingleChoiceIndex(const wxString& message,
const wxString& caption,
int n, const wxString& choices[],
wxWindow *parent = NULL, int x = -1, int y = -1,
bool centre = true, int width=150, int height=200)

As wxGetSingleChoice but returns the index representing the selected string. If the user pressed cancel, -1 is returned.

Include files

::wxGetSingleChoiceData

wxString wxGetSingleChoiceData(const wxString& message,
const wxString& caption,
const wxArrayString& aChoices,
const wxString& client_data[],
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true, int width=150, int height=200)

wxString wxGetSingleChoiceData(const wxString& message,
const wxString& caption,
int n, const wxString& choices[],
const wxString& client_data[],
wxWindow *parent = NULL,
int x = -1, int y = -1,
bool centre = true, int width=150, int height=200)

As wxGetSingleChoice but takes an array of client data pointers corresponding to the strings, and returns one of these pointers or NULL if Cancel was pressed. The client_data array must have the same number of elements as choices or aChoices!

Include files

::wxIsBusy

bool wxIsBusy()

Returns true if between two wxBeginBusyCursor and wxEndBusyCursor calls.

::wxMessageBox

int wxMessageBox(const wxString& message, const wxString& caption = "Message", int style = wxOK,
wxWindow *parent = NULL, int x = -1, int y = -1)

General purpose message dialog. style may be a bit list of the following identifiers:

wxYES_NO Puts Yes and No buttons on the message box. May be combined with wxCANCEL.

wxCANCEL Puts a Cancel button on the message box. May only be combined with wxYES_NO or wxOK.

wxOK Puts an Ok button on the message box. May be combined with wxCANCEL.

wxICON_EXCLAMATION Displays an exclamation mark symbol.

wxICON_HAND Displays an error symbol.

wxICON_ERROR Displays an error symbol - the same as wxICON_HAND.

wxICON_QUESTION Displays a question mark symbol.

wxICON_INFORMATION Displays an information symbol.

The return value is one of: wxYES, wxNO, wxCANCEL, wxOK.

For example:

  ...
  int answer = wxMessageBox("Quit program?", "Confirm",
                            wxYES_NO | wxCANCEL, main_frame);
  if (answer == wxYES)
    main_frame->Close();
  ...

message may contain newline characters, in which case the message will be split into separate lines, to cater for large messages.

Include files

::wxShowTip

bool wxShowTip(wxWindow *parent, wxTipProvider *tipProvider, bool showAtStartup = true)

This function shows a "startup tip" to the user. The return value is the state of the 'Show tips at startup' checkbox.

parent

The parent window for the modal dialog

tipProvider

wxCreateFileTipProvider

showAtStartup

Should be true if startup tips are shown, false otherwise. This is used as the initial value for "Show tips at startup" checkbox which is shown in the tips dialog.

See also

Tips overview

Include files

wxYES_NO	Puts Yes and No buttons on the message box. May be combined with wxCANCEL.
wxCANCEL	Puts a Cancel button on the message box. May only be combined with wxYES_NO or wxOK.
wxOK	Puts an Ok button on the message box. May be combined with wxCANCEL.
wxICON_EXCLAMATION	Displays an exclamation mark symbol.
wxICON_HAND	Displays an error symbol.
wxICON_ERROR	Displays an error symbol - the same as wxICON_HAND.
wxICON_QUESTION	Displays a question mark symbol.
wxICON_INFORMATION	Displays an information symbol.