interface/wx/textdlg.h

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