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