## 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.

::wxCreateFileTipProvider
::wxFileSelector
::wxGetColourFromUser
::wxGetNumberFromUser
::wxGetPasswordFromUser
::wxGetTextFromUser
::wxGetMultipleChoice
::wxGetSingleChoice
::wxGetSingleChoiceIndex
::wxGetSingleChoiceData
::wxMessageBox
::wxShowTip

### ::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

<wx/tipdlg.h>

### ::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 = "",
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, wxHIDE_READONLY, wxFILE_MUST_EXIST, wxMULTIPLE or 0.

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:

    const wxString& s = wxFileSelector("Choose a file to open");
    if (s)
    {
      ...
    }

Include files

<wx/filedlg.h>

### ::wxGetColourFromUser

wxColour wxGetColourFromUser(wxWindow *parent, const wxColour& colInit)

Shows the colour selection dialog and returns the colour selected by user or invalid colour (use wxColour::Ok 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.

Include files

<wx/colordlg.h>

### ::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

<wx/textdlg.h>

### ::wxGetPasswordFromUser

wxString wxGetTextFromUser(const wxString& message, const wxString& caption = "Input text",
const wxString& default_value = "", wxWindow *parent = NULL)

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

<wx/textdlg.h>

### ::wxGetTextFromUser

wxString wxGetTextFromUser(const wxString& message, const wxString& caption = "Input text",
const wxString& default_value = "", wxWindow *parent = NULL,
int x = -1, int y = -1, 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

<wx/textdlg.h>

### ::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

<wx/choicdlg.h>

### ::wxGetSingleChoice

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.

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

<wx/choicdlg.h>

### ::wxGetSingleChoiceIndex

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

<wx/choicdlg.h>

### ::wxGetSingleChoiceData

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.

Include files

<wx/choicdlg.h>

### ::wxMessageBox

int wxMessageBox(const wxString& message, const wxString& caption = "Message", int style = wxOK | wxCENTRE,
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 be combined with wxYES_NO or wxOK.
wxOK | Puts an Ok button on the message box. May be combined with wxCANCEL.
wxCENTRE | Centres the text.
wxICON_EXCLAMATION | Displays an exclamation mark symbol.
wxICON_HAND | Displays a hand symbol.
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)
        delete main_frame;
      ...

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

Under Windows, the native MessageBox function is used unless wxCENTRE is specified in the style, in which case a generic function is used. This is because the native MessageBox function cannot centre text. The symbols are not shown when the generic function is used.

Include files

<wx/msgdlg.h>

### ::wxShowTip

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

This function shows a "startup tip" to the user.

parent

The parent window for the modal dialog

tipProvider

An object which is used to get the text of the tips. It may be created with the wxCreateFileTipProvider function.

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

<wx/tipdlg.h>