X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/textdlg.h?ds=sidebyside diff --git a/interface/wx/textdlg.h b/interface/wx/textdlg.h index dc7245790d..8e65e329c4 100644 --- a/interface/wx/textdlg.h +++ b/interface/wx/textdlg.h @@ -3,81 +3,172 @@ // Purpose: interface of wxPasswordEntryDialog // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// +/** + Default text dialog style. +*/ +#define wxTextEntryDialogStyle (wxOK | wxCANCEL | wxCENTRE | wxWS_EX_VALIDATE_RECURSIVELY) + +/// Default text dialog caption. +const char wxGetTextFromUserPromptStr[] = "Input Text"; + +/// Default password dialog caption. +const char wxGetPasswordFromUserPromptStr[] = "Enter Password"; + + /** @class wxPasswordEntryDialog - @wxheader{textdlg.h} This class represents a dialog that requests a one-line password string from the user. + It is implemented as a generic wxWidgets dialog. - @library{wxbase} + @library{wxcore} @category{cmndlg} - @see @ref overview_wxpasswordentrydialogoverview "wxPassowrdEntryDialog - overview" + @see @ref overview_cmndlg_password */ class wxPasswordEntryDialog : public wxTextEntryDialog { public: + /** + Constructor. + + Use wxTextEntryDialog::ShowModal to show the dialog. + @param parent + Parent window. + @param message + Message to show on the dialog. + @param caption + The caption of the dialog. + @param defaultValue + The default value, which may be the empty string. + @param style + A dialog style, specifying the buttons (wxOK, wxCANCEL) and an + optional wxCENTRE style. You do not need to specify the wxTE_PASSWORD style, + it is always applied. + @param pos + Dialog position. + */ + wxPasswordEntryDialog(wxWindow* parent, const wxString& message, + const wxString& caption = wxGetPasswordFromUserPromptStr, + const wxString& defaultValue = wxEmptyString, + long style = wxTextEntryDialogStyle, + const wxPoint& pos = wxDefaultPosition); }; /** @class wxTextEntryDialog - @wxheader{textdlg.h} - This class represents a dialog that requests a one-line text string from the - user. + This class represents a dialog that requests a one-line text string from the user. It is implemented as a generic wxWidgets dialog. - @library{wxbase} + @library{wxcore} @category{cmndlg} - @see @ref overview_wxtextentrydialogoverview "wxTextEntryDialog overview" + @see @ref overview_cmndlg_textentry */ class wxTextEntryDialog : public wxDialog { public: /** - Constructor. Use ShowModal() to show the dialog. + Default constructor. + + Call Create() to really create the dialog later. + + @since 2.9.5 + */ + wxTextEntryDialog(); + /** + Constructor. + + Use ShowModal() to show the dialog. + + See Create() method for parameter description. + */ + wxTextEntryDialog(wxWindow* parent, const wxString& message, + const wxString& caption = wxGetTextFromUserPromptStr, + const wxString& value = wxEmptyString, + long style = wxTextEntryDialogStyle, + const wxPoint& pos = wxDefaultPosition); + + /** @param parent Parent window. @param message Message to show on the dialog. - @param defaultValue + @param caption + The caption of the dialog. + @param value The default value, which may be the empty string. @param style A dialog style, specifying the buttons (wxOK, wxCANCEL) - and an optional wxCENTRE style. Additionally, wxTextCtrl styles (such as - wxTE_PASSWORD) may be specified here. + and an optional wxCENTRE style. Additionally, wxTextCtrl styles + (such as @c wxTE_PASSWORD or @c wxTE_MULTILINE) may be specified + here. @param pos Dialog position. + + @since 2.9.5 */ - wxTextEntryDialog(wxWindow* parent, const wxString& message, - const wxString& caption = "Please enter text", - const wxString& defaultValue = "", - long style = wxOK | wxCANCEL | wxCENTRE, + bool Create(wxWindow* parent, const wxString& message, + const wxString& caption = wxGetTextFromUserPromptStr, + const wxString& value = wxEmptyString, + long style = wxTextEntryDialogStyle, const wxPoint& pos = wxDefaultPosition); /** Destructor. */ - ~wxTextEntryDialog(); + virtual ~wxTextEntryDialog(); /** Returns the text that the user has entered if the user has pressed OK, or the - original value - if the user has pressed Cancel. + original value if the user has pressed Cancel. */ wxString GetValue() const; + /** + Associate a validator with the text control used by the dialog. + + These methods can be used to limit the user entry to only some + characters, e.g. + @code + wxTextEntryDialog dlg(this, ...); + dlg.SetTextValidator(wxFILTER_ALPHA); + if ( dlg.ShowModal() == wxID_OK ) + { + // We can be certain that this string contains letters only. + wxString value = dlg.GetValue(); + } + @endcode + + The first overload uses the provided @a validator which can be of a + custom class derived from wxTextValidator while the second one creates + a wxTextValidator with the specified @a style. + */ + //@{ + void SetTextValidator(const wxTextValidator& validator); + void SetTextValidator(wxTextValidatorStyle style = wxFILTER_NONE); + //@} + + /** + This function sets the maximum number of characters the user can enter + into this dialog. + + @see wxTextEntry::SetMaxLength() + + @since 2.9.5 + */ + void SetMaxLength(unsigned long len); + /** Sets the default text value. */ @@ -86,6 +177,9 @@ public: /** Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL otherwise. + + Call GetValue() to retrieve the values of the string entered by the + user after showing the dialog. */ int ShowModal(); }; @@ -96,7 +190,7 @@ public: // Global functions/macros // ============================================================================ -/** @ingroup group_funcmacro_dialog */ +/** @addtogroup group_funcmacro_dialog */ //@{ /** @@ -107,11 +201,17 @@ public: If @c centre is @true, the message text (which may include new line characters) is centred; if @false, the message is left-justified. + This function is a wrapper around wxTextEntryDialog and while it is usually + more convenient to use, using the dialog directly is more flexible, e.g. it + allows you to specify the @c wxTE_MULTILINE to allow the user enter + multiple lines of text while this function is limited to single line entry + only. + @header{wx/textdlg.h} */ wxString wxGetTextFromUser(const wxString& message, - const wxString& caption = "Input text", - const wxString& default_value = "", + const wxString& caption = wxGetTextFromUserPromptStr, + const wxString& default_value = wxEmptyString, wxWindow* parent = NULL, int x = wxDefaultCoord, int y = wxDefaultCoord, @@ -125,8 +225,8 @@ wxString wxGetTextFromUser(const wxString& message, @header{wx/textdlg.h} */ wxString wxGetPasswordFromUser(const wxString& message, - const wxString& caption = "Input text", - const wxString& default_value = "", + const wxString& caption = wxGetPasswordFromUserPromptStr, + const wxString& default_value = wxEmptyString, wxWindow* parent = NULL, int x = wxDefaultCoord, int y = wxDefaultCoord,