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
  58
  59     // clipboard operations
  60     // --------------------
  61
  62     virtual void Copy() = 0;
  63     virtual void Cut() = 0;
  64     virtual void Paste() = 0;
  65
  66     virtual bool CanCopy() const;
  67     virtual bool CanCut() const;
  68     virtual bool CanPaste() const;
  69
  70     // undo/redo
  71     // ---------
  72
  73     virtual void Undo() = 0;
  74     virtual void Redo() = 0;
  75
  76     virtual bool CanUndo() const = 0;
  77     virtual bool CanRedo() const = 0;
  78
  79
  80     // insertion point
  81     // ---------------
  82
  83     // note that moving insertion point removes any current selection
  84     virtual void SetInsertionPoint(long pos) = 0;
  85     virtual void SetInsertionPointEnd() { SetInsertionPoint(-1); }
  86     virtual long GetInsertionPoint() const = 0;
  87     virtual long GetLastPosition() const = 0;
  88
  89
  90     // selection
  91     // ---------
  92
  93     virtual void SetSelection(long from, long to) = 0;
  94     virtual void SelectAll() { SetSelection(0, GetLastPosition()); }
  95     virtual void GetSelection(long *from, long *to) const = 0;
  96     bool HasSelection() const;
  97     virtual wxString GetStringSelection() const;
  98
  99
 100     // auto-completion
 101     // ---------------
 102
 103     // these functions allow to auto-complete the text already entered into the
 104     // control using either the given fixed list of strings, the paths from the
 105     // file system or, in the future, an arbitrary user-defined completer
 106     //
 107     // they all return true if completion was enabled or false on error (most
 108     // commonly meaning that this functionality is not available under the
 109     // current platform)
 110
 111     virtual bool AutoComplete(const wxArrayString& WXUNUSED(choices))
 112     {
 113         return false;
 114     }
 115
 116     virtual bool AutoCompleteFileNames() { return false; }
 117
 118
 119     // status
 120     // ------
 121
 122     virtual bool IsEditable() const = 0;
 123     virtual void SetEditable(bool editable) = 0;
 124
 125
 126     // set the max number of characters which may be entered in a single line
 127     // text control
 128     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 129
 130
 131 protected:
 132     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
 133     // also used to implement WriteText() in wxMSW
 134     enum
 135     {
 136         SetValue_NoEvent = 0,
 137         SetValue_SendEvent = 1,
 138         SetValue_SelectionOnly = 2
 139     };
 140
 141     virtual void DoSetValue(const wxString& value, int flags);
 142
 143     // class which should be used to temporarily disable text change events
 144     //
 145     // if suppress argument in ctor is false, nothing is done
 146     class EventsSuppressor
 147     {
 148     public:
 149         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
 150             : m_text(text),
 151               m_suppress(suppress)
 152         {
 153             if ( m_suppress )
 154                 m_text->SuppressTextChangedEvents();
 155         }
 156
 157         ~EventsSuppressor()
 158         {
 159             if ( m_suppress )
 160                 m_text->ResumeTextChangedEvents();
 161         }
 162
 163     private:
 164         wxTextEntryBase *m_text;
 165         bool m_suppress;
 166     };
 167
 168     friend class EventsSuppressor;
 169
 170     // return true if the events are currently not suppressed
 171     bool EventsAllowed() const { return m_eventsBlock == 0; }
 172
 173 private:
 174     // suppress or resume the text changed events generation: don't use these
 175     // functions directly, use EventsSuppressor class above instead
 176     void SuppressTextChangedEvents()
 177     {
 178         if ( !m_eventsBlock++ )
 179             EnableTextChangedEvents(false);
 180     }
 181
 182     void ResumeTextChangedEvents()
 183     {
 184         if ( !--m_eventsBlock )
 185             EnableTextChangedEvents(true);
 186     }
 187
 188
 189     // this must be overridden in the derived classes if our implementation of
 190     // SetValue() or Replace() is used to disable (and enable back) generation
 191     // of the text changed events
 192     //
 193     // initially the generation of the events is enabled
 194     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 195
 196     // if this counter is non-null, events are blocked
 197     unsigned m_eventsBlock;
 198 };
 199
 200 #ifdef __WXUNIVERSAL__
 201     // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
 202     //       the GTK/MSW classes from being used in wxUniv build
 203     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 204     {
 205     };
 206 #elif defined(__WXGTK20__)
 207     #include "wx/gtk/textentry.h"
 208 #elif defined(__WXMSW__)
 209     #include "wx/msw/textentry.h"
 210 #elif defined(__WXMOTIF__)
 211     #include "wx/motif/textentry.h"
 212 #else
 213     // no platform-specific implementation of wxTextEntry yet
 214     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 215     {
 216     };
 217 #endif
 218
 219 #endif // _WX_TEXTENTRY_H_
 220