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