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;
  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     virtual wxString DoGetValue() const = 0;
 156
 157     // override this to return the associated window, it will be used for event
 158     // generation and also by generic hints implementation
 159     virtual wxWindow *GetEditableWindow() = 0;
 160
 161
 162     // class which should be used to temporarily disable text change events
 163     //
 164     // if suppress argument in ctor is false, nothing is done
 165     class EventsSuppressor
 166     {
 167     public:
 168         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
 169             : m_text(text),
 170               m_suppress(suppress)
 171         {
 172             if ( m_suppress )
 173                 m_text->SuppressTextChangedEvents();
 174         }
 175
 176         ~EventsSuppressor()
 177         {
 178             if ( m_suppress )
 179                 m_text->ResumeTextChangedEvents();
 180         }
 181
 182     private:
 183         wxTextEntryBase *m_text;
 184         bool m_suppress;
 185     };
 186
 187     friend class EventsSuppressor;
 188
 189     // return true if the events are currently not suppressed
 190     bool EventsAllowed() const { return m_eventsBlock == 0; }
 191
 192 private:
 193     // suppress or resume the text changed events generation: don't use these
 194     // functions directly, use EventsSuppressor class above instead
 195     void SuppressTextChangedEvents()
 196     {
 197         if ( !m_eventsBlock++ )
 198             EnableTextChangedEvents(false);
 199     }
 200
 201     void ResumeTextChangedEvents()
 202     {
 203         if ( !--m_eventsBlock )
 204             EnableTextChangedEvents(true);
 205     }
 206
 207
 208     // this must be overridden in the derived classes if our implementation of
 209     // SetValue() or Replace() is used to disable (and enable back) generation
 210     // of the text changed events
 211     //
 212     // initially the generation of the events is enabled
 213     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 214
 215     // if this counter is non-null, events are blocked
 216     unsigned m_eventsBlock;
 217
 218     // hint-related stuff, only allocated if/when SetHint() is used
 219     wxTextEntryHintData *m_hintData;
 220 };
 221
 222 #ifdef __WXUNIVERSAL__
 223     // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
 224     //       the GTK/MSW classes from being used in wxUniv build
 225     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 226     {
 227     };
 228 #elif defined(__WXGTK20__)
 229     #include "wx/gtk/textentry.h"
 230 #elif defined(__WXMSW__)
 231     #include "wx/msw/textentry.h"
 232 #elif defined(__WXMOTIF__)
 233     #include "wx/motif/textentry.h"
 234 #elif defined(__WXPM__)
 235     #include "wx/os2/textentry.h"
 236 #else
 237     // no platform-specific implementation of wxTextEntry yet
 238     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 239     {
 240     };
 241 #endif
 242
 243 #endif // _WX_TEXTENTRY_H_
 244