Fix html documentation warnings.

[wxWidgets.git] / interface / wx / textdlg.h

diff --git a/interface/wx/textdlg.h b/interface/wx/textdlg.h
index 9147e419e4ee51f4a5c4535885be6fcced16c07a..04d4d6411b60a51fe7ac76e1c05743060806b960 100644 (file)
--- a/interface/wx/textdlg.h
+++ b/interface/wx/textdlg.h
@@ -2,10 +2,21 @@
 // Name:        textdlg.h
 // Purpose:     interface of wxPasswordEntryDialog
 // Author:      wxWidgets team
 // Name:        textdlg.h
 // 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
 
 /**
     @class wxPasswordEntryDialog
 


@@ -14,7 +25,7 @@
 
     It is implemented as a generic wxWidgets dialog.
 
 
     It is implemented as a generic wxWidgets dialog.
 

-    @library{wxbase}
+    @library{wxcore}

     @category{cmndlg}
 
     @see @ref overview_cmndlg_password
     @category{cmndlg}
 
     @see @ref overview_cmndlg_password


@@ -31,6 +42,8 @@ public:
             Parent window.
         @param message
             Message to show on the dialog.
             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
         @param defaultValue
             The default value, which may be the empty string.
         @param style


@@ -41,9 +54,9 @@ public:
             Dialog position.
     */
     wxPasswordEntryDialog(wxWindow* parent, const wxString& message,
             Dialog position.
     */
     wxPasswordEntryDialog(wxWindow* parent, const wxString& message,

-                          const wxString& caption = "Enter password",
+                          const wxString& caption = wxGetPasswordFromUserPromptStr,

                           const wxString& defaultValue = wxEmptyString,
                           const wxString& defaultValue = wxEmptyString,

-                          long style = wxOK | wxCANCEL | wxCENTRE,
+                          long style = wxTextEntryDialogStyle,

                           const wxPoint& pos = wxDefaultPosition);
 };
 
                           const wxPoint& pos = wxDefaultPosition);
 };
 


@@ -55,7 +68,7 @@ public:
     This class represents a dialog that requests a one-line text string from the user.
     It is implemented as a generic wxWidgets dialog.
 
     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_cmndlg_textentry
     @category{cmndlg}
 
     @see @ref overview_cmndlg_textentry


@@ -64,25 +77,50 @@ class wxTextEntryDialog : public wxDialog
 {
 public:
     /**
 {
 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 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
             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.
+            (such as @c wxTE_PASSWORD or @c wxTE_MULTILINE) may be specified
+            here.

         @param pos
             Dialog position.
         @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);
 
     /**
                       const wxPoint& pos = wxDefaultPosition);
 
     /**


@@ -96,6 +134,40 @@ public:
     */
     wxString GetValue() const;
 
     */
     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.
     */
     /**
         Sets the default text value.
     */


@@ -104,6 +176,9 @@ public:
     /**
         Shows the dialog, returning wxID_OK if the user pressed OK, and wxID_CANCEL
         otherwise.
     /**
         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();
 };
     */
     int ShowModal();
 };


@@ -114,7 +189,7 @@ public:
 // Global functions/macros
 // ============================================================================
 
 // Global functions/macros
 // ============================================================================
 

-/** @ingroup group_funcmacro_dialog */
+/** @addtogroup group_funcmacro_dialog */

 //@{
 
 /**
 //@{
 
 /**


@@ -125,11 +200,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.
 
     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,
     @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,
                            wxWindow* parent = NULL,
                            int x = wxDefaultCoord,
                            int y = wxDefaultCoord,


@@ -143,8 +224,8 @@ wxString wxGetTextFromUser(const wxString& message,
     @header{wx/textdlg.h}
 */
 wxString wxGetPasswordFromUser(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,
                                wxWindow* parent = NULL,
                                int x = wxDefaultCoord,
                                int y = wxDefaultCoord,