interface/wx/textdlg.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        textdlg.h
   3 // Purpose:     interface of wxPasswordEntryDialog
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     Default text dialog style.
  11 */
  12 #define wxTextEntryDialogStyle (wxOK | wxCANCEL | wxCENTRE | wxWS_EX_VALIDATE_RECURSIVELY)
  13
  14 /// Default text dialog caption.
  15 const char wxGetTextFromUserPromptStr[] = "Input Text";
  16
  17 /// Default password dialog caption.
  18 const char wxGetPasswordFromUserPromptStr[] = "Enter Password";
  19
  20
  21 /**
  22     @class wxPasswordEntryDialog
  23
  24     This class represents a dialog that requests a one-line password string from
  25     the user.
  26
  27     It is implemented as a generic wxWidgets dialog.
  28
  29     @library{wxcore}
  30     @category{cmndlg}
  31
  32     @see @ref overview_cmndlg_password
  33 */
  34 class wxPasswordEntryDialog : public wxTextEntryDialog
  35 {
  36 public:
  37     /**
  38         Constructor.
  39
  40         Use wxTextEntryDialog::ShowModal to show the dialog.
  41
  42         @param parent
  43             Parent window.
  44         @param message
  45             Message to show on the dialog.
  46         @param caption
  47             The caption of the dialog.
  48         @param defaultValue
  49             The default value, which may be the empty string.
  50         @param style
  51             A dialog style, specifying the buttons (wxOK, wxCANCEL) and an
  52             optional wxCENTRE style. You do not need to specify the wxTE_PASSWORD style,
  53             it is always applied.
  54         @param pos
  55             Dialog position.
  56     */
  57     wxPasswordEntryDialog(wxWindow* parent, const wxString& message,
  58                           const wxString& caption = wxGetPasswordFromUserPromptStr,
  59                           const wxString& defaultValue = wxEmptyString,
  60                           long style = wxTextEntryDialogStyle,
  61                           const wxPoint& pos = wxDefaultPosition);
  62 };
  63
  64
  65
  66 /**
  67     @class wxTextEntryDialog
  68
  69     This class represents a dialog that requests a one-line text string from the user.
  70     It is implemented as a generic wxWidgets dialog.
  71
  72     @library{wxcore}
  73     @category{cmndlg}
  74
  75     @see @ref overview_cmndlg_textentry
  76 */
  77 class wxTextEntryDialog : public wxDialog
  78 {
  79 public:
  80     /**
  81         Default constructor.
  82
  83         Call Create() to really create the dialog later.
  84
  85         @since 2.9.5
  86      */
  87     wxTextEntryDialog();
  88
  89     /**
  90         Constructor.
  91
  92         Use ShowModal() to show the dialog.
  93
  94         See Create() method for parameter description.
  95     */
  96     wxTextEntryDialog(wxWindow* parent, const wxString& message,
  97                       const wxString& caption = wxGetTextFromUserPromptStr,
  98                       const wxString& value = wxEmptyString,
  99                       long style = wxTextEntryDialogStyle,
 100                       const wxPoint& pos = wxDefaultPosition);
 101
 102     /**
 103         @param parent
 104             Parent window.
 105         @param message
 106             Message to show on the dialog.
 107         @param caption
 108             The caption of the dialog.
 109         @param value
 110             The default value, which may be the empty string.
 111         @param style
 112             A dialog style, specifying the buttons (wxOK, wxCANCEL)
 113             and an optional wxCENTRE style. Additionally, wxTextCtrl styles
 114             (such as @c wxTE_PASSWORD or @c wxTE_MULTILINE) may be specified
 115             here.
 116         @param pos
 117             Dialog position.
 118
 119         @since 2.9.5
 120     */
 121     bool Create(wxWindow* parent, const wxString& message,
 122                       const wxString& caption = wxGetTextFromUserPromptStr,
 123                       const wxString& value = wxEmptyString,
 124                       long style = wxTextEntryDialogStyle,
 125                       const wxPoint& pos = wxDefaultPosition);
 126
 127     /**
 128         Destructor.
 129     */
 130     virtual ~wxTextEntryDialog();
 131
 132     /**
 133         Returns the text that the user has entered if the user has pressed OK, or the
 134         original value if the user has pressed Cancel.
 135     */
 136     wxString GetValue() const;
 137
 138     /**
 139         Associate a validator with the text control used by the dialog.
 140
 141         These methods can be used to limit the user entry to only some
 142         characters, e.g.
 143         @code
 144             wxTextEntryDialog dlg(this, ...);
 145             dlg.SetTextValidator(wxFILTER_ALPHA);
 146             if ( dlg.ShowModal() == wxID_OK )
 147             {
 148                 // We can be certain that this string contains letters only.
 149                 wxString value = dlg.GetValue();
 150             }
 151         @endcode
 152
 153         The first overload uses the provided @a validator which can be of a
 154         custom class derived from wxTextValidator while the second one creates
 155         a wxTextValidator with the specified @a style.
 156      */
 157     //@{
 158     void SetTextValidator(const wxTextValidator& validator);
 159     void SetTextValidator(wxTextValidatorStyle style = wxFILTER_NONE);
 160     //@}
 161
 162     /**
 163         Sets the default text value.
 164     */
 165     void SetValue(const wxString& value);
 166
 167     /**
 168         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
 169         otherwise.
 170
 171         Call GetValue() to retrieve the values of the string entered by the
 172         user after showing the dialog.
 173     */
 174     int ShowModal();
 175 };
 176
 177
 178
 179 // ============================================================================
 180 // Global functions/macros
 181 // ============================================================================
 182
 183 /** @addtogroup group_funcmacro_dialog */
 184 //@{
 185
 186 /**
 187     Pop up a dialog box with title set to @e caption, @c message, and a
 188     @c default_value. The user may type in text and press OK to return this
 189     text, or press Cancel to return the empty string.
 190
 191     If @c centre is @true, the message text (which may include new line
 192     characters) is centred; if @false, the message is left-justified.
 193
 194     This function is a wrapper around wxTextEntryDialog and while it is usually
 195     more convenient to use, using the dialog directly is more flexible, e.g. it
 196     allows you to specify the @c wxTE_MULTILINE to allow the user enter
 197     multiple lines of text while this function is limited to single line entry
 198     only.
 199
 200     @header{wx/textdlg.h}
 201 */
 202 wxString wxGetTextFromUser(const wxString& message,
 203                            const wxString& caption = wxGetTextFromUserPromptStr,
 204                            const wxString& default_value = wxEmptyString,
 205                            wxWindow* parent = NULL,
 206                            int x = wxDefaultCoord,
 207                            int y = wxDefaultCoord,
 208                            bool centre = true);
 209
 210 /**
 211     Similar to wxGetTextFromUser() but the text entered in the dialog is not
 212     shown on screen but replaced with stars. This is intended to be used for
 213     entering passwords as the function name implies.
 214
 215     @header{wx/textdlg.h}
 216 */
 217 wxString wxGetPasswordFromUser(const wxString& message,
 218                                const wxString& caption = wxGetPasswordFromUserPromptStr,
 219                                const wxString& default_value = wxEmptyString,
 220                                wxWindow* parent = NULL,
 221                                int x = wxDefaultCoord,
 222                                int y = wxDefaultCoord,
 223                                bool centre = true);
 224
 225 //@}
 226