synchronize GTK2 minimum version in docs

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

diff --git a/include/wx/textentry.h b/include/wx/textentry.h
index 93ae8fbf37f27a2a07d5dc6d636298e90d342560..2ede40d714a4b3189dc0f6a038572e514147a662 100644 (file)
--- a/include/wx/textentry.h
+++ b/include/wx/textentry.h
@@ -16,6 +16,12 @@
 typedef long wxTextPos;
 
 class WXDLLIMPEXP_FWD_BASE wxArrayString;
 typedef long wxTextPos;
 
 class WXDLLIMPEXP_FWD_BASE wxArrayString;

+class WXDLLIMPEXP_FWD_CORE wxTextCompleter;
+class WXDLLIMPEXP_FWD_CORE wxTextEntryHintData;
+class WXDLLIMPEXP_FWD_CORE wxWindow;
+
+#include "wx/filefn.h"              // for wxFILE and wxDIR only
+#include "wx/gdicmn.h"              // for wxPoint

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


@@ -24,8 +30,8 @@ class WXDLLIMPEXP_FWD_BASE wxArrayString;
 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


@@ -34,8 +40,7 @@ public:
     // SetValue() generates a text change event, ChangeValue() doesn't
     virtual void SetValue(const wxString& value)
         { DoSetValue(value, SetValue_SendEvent); }
     // SetValue() generates a text change event, ChangeValue() doesn't
     virtual void SetValue(const wxString& value)
         { DoSetValue(value, SetValue_SendEvent); }

-    virtual void ChangeValue(const wxString& value)
-        { DoSetValue(value, SetValue_NoEvent); }
+    virtual void ChangeValue(const wxString& value);

 
     // writing text inserts it at the current position replacing any current
     // selection, appending always inserts it at the end and doesn't remove any
 
     // writing text inserts it at the current position replacing any current
     // selection, appending always inserts it at the end and doesn't remove any


@@ -43,9 +48,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 GetLastPosition() > 0; }
+    bool IsEmpty() const { return GetLastPosition() <= 0; }

 
 
     // editing operations
 
 
     // editing operations


@@ -103,18 +108,26 @@ public:
 
     // 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
 
     // 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
+    // file system or 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)
 
     //
     // 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;
-    }
+    bool AutoComplete(const wxArrayString& choices)
+        { return DoAutoCompleteStrings(choices); }

 
 

-    virtual bool AutoCompleteFileNames() { return false; }
+    bool AutoCompleteFileNames()
+        { return DoAutoCompleteFileNames(wxFILE); }
+
+    bool AutoCompleteDirectories()
+        { return DoAutoCompleteFileNames(wxDIR); }
+
+    // notice that we take ownership of the pointer and will delete it
+    //
+    // if the pointer is NULL auto-completion is disabled
+    bool AutoComplete(wxTextCompleter *completer)
+        { return DoAutoCompleteCustom(completer); }

 
 
     // status
 
 
     // status


@@ -129,6 +142,71 @@ 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(); }
+
+
+    // implementation only
+    // -------------------
+
+    // generate the wxEVT_COMMAND_TEXT_UPDATED event for GetEditableWindow(),
+    // like SetValue() does and return true if the event was processed
+    //
+    // NB: this is public for wxRichTextCtrl use only right now, do not call it
+    static bool SendTextUpdatedEvent(wxWindow *win);
+
+    // generate the wxEVT_COMMAND_TEXT_UPDATED event for this window
+    bool SendTextUpdatedEvent()
+    {
+        return SendTextUpdatedEvent(GetEditableWindow());
+    }
+
+
+    // generate the wxEVT_COMMAND_TEXT_UPDATED event for this window if the
+    // events are not currently disabled
+    void SendTextUpdatedEventIfAllowed()
+    {
+        if ( EventsAllowed() )
+            SendTextUpdatedEvent();
+    }
+
+    // this function is provided solely for the purpose of forwarding text
+    // change notifications state from one control to another, e.g. it can be
+    // used by a wxComboBox which derives from wxTextEntry if it delegates all
+    // of its methods to another wxTextCtrl
+    void ForwardEnableTextChangedEvents(bool enable)
+    {
+        // it's important to call the functions which update m_eventsBlock here
+        // and not just our own EnableTextChangedEvents() because our state
+        // (i.e. the result of EventsAllowed()) must change as well
+        if ( enable )
+            ResumeTextChangedEvents();
+        else
+            SuppressTextChangedEvents();
+    }
+

 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


@@ -140,6 +218,26 @@ 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;
+
+    // the derived classes should override these virtual methods to implement
+    // auto-completion, they do the same thing as their public counterparts but
+    // have different names to allow overriding just one of them without hiding
+    // the other one(s)
+    virtual bool DoAutoCompleteStrings(const wxArrayString& WXUNUSED(choices))
+        { return false; }
+    virtual bool DoAutoCompleteFileNames(int WXUNUSED(flags)) // wxFILE | wxDIR
+        { return false; }
+    virtual bool DoAutoCompleteCustom(wxTextCompleter *completer);
+

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


@@ -168,9 +266,6 @@ protected:
 
     friend class EventsSuppressor;
 
 
     friend class EventsSuppressor;
 

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

 private:
     // suppress or resume the text changed events generation: don't use these
     // functions directly, use EventsSuppressor class above instead
 private:
     // suppress or resume the text changed events generation: don't use these
     // functions directly, use EventsSuppressor class above instead


@@ -194,8 +289,19 @@ 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)) { }
 

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

     // 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;
+
+    // It needs to call our Do{Get,Set}Value() to work with the real control
+    // contents.
+    friend class wxTextEntryHintData;

 };
 
 #ifdef __WXUNIVERSAL__
 };
 
 #ifdef __WXUNIVERSAL__


@@ -206,6 +312,8 @@ private:
     };
 #elif defined(__WXGTK20__)
     #include "wx/gtk/textentry.h"
     };
 #elif defined(__WXGTK20__)
     #include "wx/gtk/textentry.h"

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

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