Clarify documentation for wxPropertyGridEvent::GetProperty()

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

diff --git a/include/wx/textentry.h b/include/wx/textentry.h
index 3050074282ff5956915399bbd65d3930b2cc8c2b..f773635ea111d2e388aab192767c4c4670d0d120 100644 (file)
--- a/include/wx/textentry.h
+++ b/include/wx/textentry.h
@@ -15,6 +15,12 @@
 // and should probably be replaced with int anyhow)
 typedef long wxTextPos;
 
 // and should probably be replaced with int anyhow)
 typedef long wxTextPos;
 

+class WXDLLIMPEXP_FWD_BASE wxArrayString;
+class WXDLLIMPEXP_FWD_CORE wxTextEntryHintData;
+class WXDLLIMPEXP_FWD_CORE wxWindow;
+
+#include "wx/gdicmn.h"              // for wxPoint
+

 // ----------------------------------------------------------------------------
 // wxTextEntryBase
 // ----------------------------------------------------------------------------
 // ----------------------------------------------------------------------------
 // wxTextEntryBase
 // ----------------------------------------------------------------------------


@@ -22,8 +28,8 @@ typedef long wxTextPos;
 class WXDLLIMPEXP_CORE wxTextEntryBase
 {
 public:
 class WXDLLIMPEXP_CORE wxTextEntryBase
 {
 public:

-    wxTextEntryBase() { m_eventsBlock = 0; }
-    virtual ~wxTextEntryBase() { }
+    wxTextEntryBase() { m_eventsBlock = 0; m_hintData = NULL; }
+    virtual ~wxTextEntryBase();

 
 
     // accessing the value
 
 
     // accessing the value


@@ -41,9 +47,9 @@ public:
     virtual void WriteText(const wxString& text) = 0;
     virtual void AppendText(const wxString& text);
 
     virtual void WriteText(const wxString& text) = 0;
     virtual void AppendText(const wxString& text);
 

-    virtual wxString GetValue() const = 0;
+    virtual wxString GetValue() const;

     virtual wxString GetRange(long from, long to) const;
     virtual wxString GetRange(long from, long to) const;

-    bool IsEmpty() const { return GetValue().empty(); }
+    bool IsEmpty() const { return GetLastPosition() <= 0; }

 
 
     // editing operations
 
 
     // editing operations


@@ -52,6 +58,7 @@ public:
     virtual void Replace(long from, long to, const wxString& value);
     virtual void Remove(long from, long to) = 0;
     virtual void Clear() { SetValue(wxString()); }
     virtual void Replace(long from, long to, const wxString& value);
     virtual void Remove(long from, long to) = 0;
     virtual void Clear() { SetValue(wxString()); }

+    void RemoveSelection();

 
 
     // clipboard operations
 
 
     // clipboard operations


@@ -89,14 +96,34 @@ public:
     // ---------
 
     virtual void SetSelection(long from, long to) = 0;
     // ---------
 
     virtual void SetSelection(long from, long to) = 0;

-    virtual void SelectAll() { SetSelection(0, GetLastPosition()); }
+    virtual void SelectAll() { SetSelection(-1, -1); }

     virtual void GetSelection(long *from, long *to) const = 0;
     bool HasSelection() const;
     virtual wxString GetStringSelection() const;
 
 
     virtual void GetSelection(long *from, long *to) const = 0;
     bool HasSelection() const;
     virtual wxString GetStringSelection() const;
 
 

+    // auto-completion
+    // ---------------
+
+    // these functions allow to auto-complete the text already entered into the
+    // control using either the given fixed list of strings, the paths from the
+    // file system or, in the future, an arbitrary user-defined completer
+    //
+    // they all return true if completion was enabled or false on error (most
+    // commonly meaning that this functionality is not available under the
+    // current platform)
+
+    virtual bool AutoComplete(const wxArrayString& WXUNUSED(choices))
+    {
+        return false;
+    }
+
+    virtual bool AutoCompleteFileNames() { return false; }
+
+

     // status
     // ------
     // status
     // ------

+

     virtual bool IsEditable() const = 0;
     virtual void SetEditable(bool editable) = 0;
 
     virtual bool IsEditable() const = 0;
     virtual void SetEditable(bool editable) = 0;
 


@@ -106,6 +133,31 @@ public:
     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 
 
     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 
 

+    // hints
+    // -----
+
+    // hint is the (usually greyed out) text shown in the control as long as
+    // it's empty and doesn't have focus, it is typically used in controls used
+    // for searching to let the user know what is supposed to be entered there
+
+    virtual bool SetHint(const wxString& hint);
+    virtual wxString GetHint() const;
+
+
+    // margins
+    // -------
+
+    // margins are the empty space between borders of control and the text
+    // itself. When setting margin, use value -1 to indicate that specific
+    // margin should not be changed.
+
+    bool SetMargins(const wxPoint& pt)
+        { return DoSetMargins(pt); }
+    bool SetMargins(wxCoord left, wxCoord top = -1)
+        { return DoSetMargins(wxPoint(left, top)); }
+    wxPoint GetMargins() const
+        { return DoGetMargins(); }
+

 protected:
     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
     // also used to implement WriteText() in wxMSW
 protected:
     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
     // also used to implement WriteText() in wxMSW


@@ -117,6 +169,16 @@ protected:
     };
 
     virtual void DoSetValue(const wxString& value, int flags);
     };
 
     virtual void DoSetValue(const wxString& value, int flags);

+    virtual wxString DoGetValue() const = 0;
+
+    // override this to return the associated window, it will be used for event
+    // generation and also by generic hints implementation
+    virtual wxWindow *GetEditableWindow() = 0;
+
+    // margins functions
+    virtual bool DoSetMargins(const wxPoint& pt);
+    virtual wxPoint DoGetMargins() const;
+

 
     // class which should be used to temporarily disable text change events
     //
 
     // class which should be used to temporarily disable text change events
     //


@@ -125,13 +187,11 @@ protected:
     {
     public:
         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
     {
     public:
         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)

+            : m_text(text),
+              m_suppress(suppress)

         {
         {

-            m_suppress = suppress;

             if ( m_suppress )
             if ( m_suppress )

-            {
-                m_text = text;

                 m_text->SuppressTextChangedEvents();
                 m_text->SuppressTextChangedEvents();

-            }

         }
 
         ~EventsSuppressor()
         }
 
         ~EventsSuppressor()


@@ -145,6 +205,8 @@ protected:
         bool m_suppress;
     };
 
         bool m_suppress;
     };
 

+    friend class EventsSuppressor;
+

     // return true if the events are currently not suppressed
     bool EventsAllowed() const { return m_eventsBlock == 0; }
 
     // return true if the events are currently not suppressed
     bool EventsAllowed() const { return m_eventsBlock == 0; }
 


@@ -171,17 +233,29 @@ private:
     // initially the generation of the events is enabled
     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 
     // initially the generation of the events is enabled
     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 

-
-    friend class EventsSuppressor;
-

     // if this counter is non-null, events are blocked
     unsigned m_eventsBlock;
     // if this counter is non-null, events are blocked
     unsigned m_eventsBlock;

+
+    // hint-related stuff, only allocated if/when SetHint() is used
+    wxTextEntryHintData *m_hintData;

 };
 
 };
 

-#ifdef __WXGTK20__
+#ifdef __WXUNIVERSAL__
+    // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
+    //       the GTK/MSW classes from being used in wxUniv build
+    class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
+    {
+    };
+#elif defined(__WXGTK20__)

     #include "wx/gtk/textentry.h"
     #include "wx/gtk/textentry.h"

+#elif defined(__WXMAC__)
+    #include "wx/osx/textentry.h"

 #elif defined(__WXMSW__)
     #include "wx/msw/textentry.h"
 #elif defined(__WXMSW__)
     #include "wx/msw/textentry.h"

+#elif defined(__WXMOTIF__)
+    #include "wx/motif/textentry.h"
+#elif defined(__WXPM__)
+    #include "wx/os2/textentry.h"

 #else
     // no platform-specific implementation of wxTextEntry yet
     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 #else
     // no platform-specific implementation of wxTextEntry yet
     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase