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         Sets the default text value.
 140     */
 141     void SetValue(const wxString& value);
 142
 143     /**
 144         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
 145         otherwise.
 146     */
 147     int ShowModal();
 148 };
 149
 150
 151
 152 // ============================================================================
 153 // Global functions/macros
 154 // ============================================================================
 155
 156 /** @addtogroup group_funcmacro_dialog */
 157 //@{
 158
 159 /**
 160     Pop up a dialog box with title set to @e caption, @c message, and a
 161     @c default_value. The user may type in text and press OK to return this
 162     text, or press Cancel to return the empty string.
 163
 164     If @c centre is @true, the message text (which may include new line
 165     characters) is centred; if @false, the message is left-justified.
 166
 167     This function is a wrapper around wxTextEntryDialog and while it is usually
 168     more convenient to use, using the dialog directly is more flexible, e.g. it
 169     allows you to specify the @c wxTE_MULTILINE to allow the user enter
 170     multiple lines of text while this function is limited to single line entry
 171     only.
 172
 173     @header{wx/textdlg.h}
 174 */
 175 wxString wxGetTextFromUser(const wxString& message,
 176                            const wxString& caption = wxGetTextFromUserPromptStr,
 177                            const wxString& default_value = wxEmptyString,
 178                            wxWindow* parent = NULL,
 179                            int x = wxDefaultCoord,
 180                            int y = wxDefaultCoord,
 181                            bool centre = true);
 182
 183 /**
 184     Similar to wxGetTextFromUser() but the text entered in the dialog is not
 185     shown on screen but replaced with stars. This is intended to be used for
 186     entering passwords as the function name implies.
 187
 188     @header{wx/textdlg.h}
 189 */
 190 wxString wxGetPasswordFromUser(const wxString& message,
 191                                const wxString& caption = wxGetPasswordFromUserPromptStr,
 192                                const wxString& default_value = wxEmptyString,
 193                                wxWindow* parent = NULL,
 194                                int x = wxDefaultCoord,
 195                                int y = wxDefaultCoord,
 196                                bool centre = true);
 197
 198 //@}
 199