include/wx/textentry.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        wx/textentry.h
   3 // Purpose:     declares wxTextEntry interface defining a simple text entry
   4 // Author:      Vadim Zeitlin
   5 // Created:     2007-09-24
   6 // RCS-ID:      $Id$
   7 // Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwindows.org>
   8 // Licence:     wxWindows licence
   9 ///////////////////////////////////////////////////////////////////////////////
  10
  11 #ifndef _WX_TEXTENTRY_H_
  12 #define _WX_TEXTENTRY_H_
  13
  14 // wxTextPos is the position in the text (currently it's hardly used anywhere
  15 // and should probably be replaced with int anyhow)
  16 typedef long wxTextPos;
  17
  18 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  19
  20 // ----------------------------------------------------------------------------
  21 // wxTextEntryBase
  22 // ----------------------------------------------------------------------------
  23
  24 class WXDLLIMPEXP_CORE wxTextEntryBase
  25 {
  26 public:
  27     wxTextEntryBase() { m_eventsBlock = 0; }
  28     virtual ~wxTextEntryBase() { }
  29
  30
  31     // accessing the value
  32     // -------------------
  33
  34     // SetValue() generates a text change event, ChangeValue() doesn't
  35     virtual void SetValue(const wxString& value)
  36         { DoSetValue(value, SetValue_SendEvent); }
  37     virtual void ChangeValue(const wxString& value)
  38         { DoSetValue(value, SetValue_NoEvent); }
  39
  40     // writing text inserts it at the current position replacing any current
  41     // selection, appending always inserts it at the end and doesn't remove any
  42     // existing text (but it will reset the selection if there is any)
  43     virtual void WriteText(const wxString& text) = 0;
  44     virtual void AppendText(const wxString& text);
  45
  46     virtual wxString GetValue() const = 0;
  47     virtual wxString GetRange(long from, long to) const;
  48     bool IsEmpty() const { return GetValue().empty(); }
  49
  50
  51     // editing operations
  52     // ------------------
  53
  54     virtual void Replace(long from, long to, const wxString& value);
  55     virtual void Remove(long from, long to) = 0;
  56     virtual void Clear() { SetValue(wxString()); }
  57     void RemoveSelection();
  58
  59
  60     // clipboard operations
  61     // --------------------
  62
  63     virtual void Copy() = 0;
  64     virtual void Cut() = 0;
  65     virtual void Paste() = 0;
  66
  67     virtual bool CanCopy() const;
  68     virtual bool CanCut() const;
  69     virtual bool CanPaste() const;
  70
  71     // undo/redo
  72     // ---------
  73
  74     virtual void Undo() = 0;
  75     virtual void Redo() = 0;
  76
  77     virtual bool CanUndo() const = 0;
  78     virtual bool CanRedo() const = 0;
  79
  80
  81     // insertion point
  82     // ---------------
  83
  84     // note that moving insertion point removes any current selection
  85     virtual void SetInsertionPoint(long pos) = 0;
  86     virtual void SetInsertionPointEnd() { SetInsertionPoint(-1); }
  87     virtual long GetInsertionPoint() const = 0;
  88     virtual long GetLastPosition() const = 0;
  89
  90
  91     // selection
  92     // ---------
  93
  94     virtual void SetSelection(long from, long to) = 0;
  95     virtual void SelectAll() { SetSelection(0, GetLastPosition()); }
  96     virtual void GetSelection(long *from, long *to) const = 0;
  97     bool HasSelection() const;
  98     virtual wxString GetStringSelection() const;
  99
 100
 101     // auto-completion
 102     // ---------------
 103
 104     // these functions allow to auto-complete the text already entered into the
 105     // control using either the given fixed list of strings, the paths from the
 106     // file system or, in the future, an arbitrary user-defined completer
 107     //
 108     // they all return true if completion was enabled or false on error (most
 109     // commonly meaning that this functionality is not available under the
 110     // current platform)
 111
 112     virtual bool AutoComplete(const wxArrayString& WXUNUSED(choices))
 113     {
 114         return false;
 115     }
 116
 117     virtual bool AutoCompleteFileNames() { return false; }
 118
 119
 120     // status
 121     // ------
 122
 123     virtual bool IsEditable() const = 0;
 124     virtual void SetEditable(bool editable) = 0;
 125
 126
 127     // set the max number of characters which may be entered in a single line
 128     // text control
 129     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 130
 131
 132 protected:
 133     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
 134     // also used to implement WriteText() in wxMSW
 135     enum
 136     {
 137         SetValue_NoEvent = 0,
 138         SetValue_SendEvent = 1,
 139         SetValue_SelectionOnly = 2
 140     };
 141
 142     virtual void DoSetValue(const wxString& value, int flags);
 143
 144     // class which should be used to temporarily disable text change events
 145     //
 146     // if suppress argument in ctor is false, nothing is done
 147     class EventsSuppressor
 148     {
 149     public:
 150         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
 151             : m_text(text),
 152               m_suppress(suppress)
 153         {
 154             if ( m_suppress )
 155                 m_text->SuppressTextChangedEvents();
 156         }
 157
 158         ~EventsSuppressor()
 159         {
 160             if ( m_suppress )
 161                 m_text->ResumeTextChangedEvents();
 162         }
 163
 164     private:
 165         wxTextEntryBase *m_text;
 166         bool m_suppress;
 167     };
 168
 169     friend class EventsSuppressor;
 170
 171     // return true if the events are currently not suppressed
 172     bool EventsAllowed() const { return m_eventsBlock == 0; }
 173
 174 private:
 175     // suppress or resume the text changed events generation: don't use these
 176     // functions directly, use EventsSuppressor class above instead
 177     void SuppressTextChangedEvents()
 178     {
 179         if ( !m_eventsBlock++ )
 180             EnableTextChangedEvents(false);
 181     }
 182
 183     void ResumeTextChangedEvents()
 184     {
 185         if ( !--m_eventsBlock )
 186             EnableTextChangedEvents(true);
 187     }
 188
 189
 190     // this must be overridden in the derived classes if our implementation of
 191     // SetValue() or Replace() is used to disable (and enable back) generation
 192     // of the text changed events
 193     //
 194     // initially the generation of the events is enabled
 195     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 196
 197     // if this counter is non-null, events are blocked
 198     unsigned m_eventsBlock;
 199 };
 200
 201 #ifdef __WXUNIVERSAL__
 202     // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
 203     //       the GTK/MSW classes from being used in wxUniv build
 204     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 205     {
 206     };
 207 #elif defined(__WXGTK20__)
 208     #include "wx/gtk/textentry.h"
 209 #elif defined(__WXMSW__)
 210     #include "wx/msw/textentry.h"
 211 #elif defined(__WXMOTIF__)
 212     #include "wx/motif/textentry.h"
 213 #elif defined(__WXPM__)
 214     #include "wx/os2/textentry.h"
 215 #else
 216     // no platform-specific implementation of wxTextEntry yet
 217     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 218     {
 219     };
 220 #endif
 221
 222 #endif // _WX_TEXTENTRY_H_
 223