update docs after r66615

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

diff --git a/interface/wx/textentry.h b/interface/wx/textentry.h
index df1ddc9100869dd9b61066b8879a94b21a117d2d..74d7a88dc8cf99109cf832a50446026fe8a32c18 100644 (file)
--- a/interface/wx/textentry.h
+++ b/interface/wx/textentry.h
@@ -5,7 +5,7 @@
 // Created:     2009-03-01 (extracted from wx/textctrl.h)
 // RCS-ID:      $Id$
 // Copyright:   (c) 2009 Vadim Zeitlin <vadim@wxwindows.org>
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
@@ -21,6 +21,8 @@
     @category{ctrl}
 
     @see wxTextCtrl, wxComboBox
+
+    @since 2.9.0
 */
 class wxTextEntry
 {
@@ -111,7 +113,7 @@ public:
         Sets the new text control value.
 
         It also marks the control as not-modified which means that IsModified()
-        would return @false immediately after the call to SetValue().
+        would return @false immediately after the call to ChangeValue().
 
         The insertion point is set to the start of the control (i.e. position
         0) by this function.
@@ -198,6 +200,11 @@ public:
             The returned first position.
         @param to
             The returned last position.
+
+        @beginWxPerlOnly
+        In wxPerl this method takes no parameters and returns a
+        2-element list (from, to).
+        @endWxPerlOnly
     */
     virtual void GetSelection(long* from, long* to) const;
 
@@ -351,6 +358,75 @@ public:
     */
     virtual void SelectAll();
 
+    /**
+        Sets a hint shown in an empty unfocused text control.
+
+        The hints are usually used to indicate to the user what is supposed to
+        be entered into the given entry field, e.g. a common use of them is to
+        show an explanation of what can be entered in a wxSearchCtrl.
+
+        The hint is shown (usually greyed out) for an empty control until it
+        gets focus and is shown again if the control loses it and remains
+        empty. It won't be shown once the control has a non-empty value,
+        although it will be shown again if the control contents is cleared.
+        Because of this, it generally only makes sense to use hints with the
+        controls which are initially empty.
+
+        Notice that hints are known as <em>cue banners</em> under MSW or
+        <em>placeholder strings</em> under OS X.
+
+        @remarks For the platforms without native hints support (and currently
+            only the MSW port does have it and even there it is only used under
+            Windows Vista and later only), the implementation has several known
+            limitations. Notably, the hint display will not be properly updated
+            if you change wxTextEntry contents programmatically when the hint
+            is displayed using methods other than SetValue() or ChangeValue()
+            or others which use them internally (e.g. Clear()). In other words,
+            currently you should avoid calling methods such as WriteText() or
+            Replace() when using hints and the text control is empty.
+
+        @since 2.9.0
+     */
+    virtual void SetHint(const wxString& hint);
+
+    /**
+        Returns the current hint string.
+
+        See SetHint() for more information about hints.
+
+        @since 2.9.0
+     */
+    virtual wxString GetHint() const;
+
+    //@{
+    /**
+        Attempts to set the control margins. When margins are given as wxPoint,
+        x indicates the left and y the top margin. Use -1 to indicate that
+        an existing value should be used.
+
+        @return
+            @true if setting of all requested margins was successful.
+
+        @since 2.9.1
+    */
+    bool SetMargins(const wxPoint& pt);
+    bool SetMargins(wxCoord left, wxCoord top = -1);
+    //@}
+
+    /**
+        Returns the margins used by the control. The @c x field of the returned
+        point is the horizontal margin and the @c y field is the vertical one.
+
+        @remarks If given margin cannot be accurately determined, its value
+                will be set to -1. On some platforms you cannot obtain valid
+                margin values until you have called SetMargins().
+
+        @see SetMargins()
+
+        @since 2.9.1
+    */
+    wxPoint GetMargins() const;
+
     /**
         Sets the new text control value.