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         This function sets the maximum number of characters the user can enter
 164         into this dialog.
 165
 166         @see wxTextEntry::SetMaxLength()
 167
 168         @since 2.9.5
 169     */
 170     void SetMaxLength(unsigned long len);
 171
 172     /**
 173         Sets the default text value.
 174     */
 175     void SetValue(const wxString& value);
 176
 177     /**
 178         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
 179         otherwise.
 180
 181         Call GetValue() to retrieve the values of the string entered by the
 182         user after showing the dialog.
 183     */
 184     int ShowModal();
 185 };
 186
 187
 188
 189 // ============================================================================
 190 // Global functions/macros
 191 // ============================================================================
 192
 193 /** @addtogroup group_funcmacro_dialog */
 194 //@{
 195
 196 /**
 197     Pop up a dialog box with title set to @e caption, @c message, and a
 198     @c default_value. The user may type in text and press OK to return this
 199     text, or press Cancel to return the empty string.
 200
 201     If @c centre is @true, the message text (which may include new line
 202     characters) is centred; if @false, the message is left-justified.
 203
 204     This function is a wrapper around wxTextEntryDialog and while it is usually
 205     more convenient to use, using the dialog directly is more flexible, e.g. it
 206     allows you to specify the @c wxTE_MULTILINE to allow the user enter
 207     multiple lines of text while this function is limited to single line entry
 208     only.
 209
 210     @header{wx/textdlg.h}
 211 */
 212 wxString wxGetTextFromUser(const wxString& message,
 213                            const wxString& caption = wxGetTextFromUserPromptStr,
 214                            const wxString& default_value = wxEmptyString,
 215                            wxWindow* parent = NULL,
 216                            int x = wxDefaultCoord,
 217                            int y = wxDefaultCoord,
 218                            bool centre = true);
 219
 220 /**
 221     Similar to wxGetTextFromUser() but the text entered in the dialog is not
 222     shown on screen but replaced with stars. This is intended to be used for
 223     entering passwords as the function name implies.
 224
 225     @header{wx/textdlg.h}
 226 */
 227 wxString wxGetPasswordFromUser(const wxString& message,
 228                                const wxString& caption = wxGetPasswordFromUserPromptStr,
 229                                const wxString& default_value = wxEmptyString,
 230                                wxWindow* parent = NULL,
 231                                int x = wxDefaultCoord,
 232                                int y = wxDefaultCoord,
 233                                bool centre = true);
 234
 235 //@}
 236