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