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