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 // Copyright:   (c) 2007 Vadim Zeitlin <vadim@wxwindows.org>
   7 // Licence:     wxWindows licence
   8 ///////////////////////////////////////////////////////////////////////////////
   9
  10 #ifndef _WX_TEXTENTRY_H_
  11 #define _WX_TEXTENTRY_H_
  12
  13 // wxTextPos is the position in the text (currently it's hardly used anywhere
  14 // and should probably be replaced with int anyhow)
  15 typedef long wxTextPos;
  16
  17 class WXDLLIMPEXP_FWD_BASE wxArrayString;
  18 class WXDLLIMPEXP_FWD_CORE wxTextCompleter;
  19 class WXDLLIMPEXP_FWD_CORE wxTextEntryHintData;
  20 class WXDLLIMPEXP_FWD_CORE wxWindow;
  21
  22 #include "wx/filefn.h"              // for wxFILE and wxDIR only
  23 #include "wx/gdicmn.h"              // for wxPoint
  24
  25 // ----------------------------------------------------------------------------
  26 // wxTextEntryBase
  27 // ----------------------------------------------------------------------------
  28
  29 class WXDLLIMPEXP_CORE wxTextEntryBase
  30 {
  31 public:
  32     wxTextEntryBase() { m_eventsBlock = 0; m_hintData = NULL; }
  33     virtual ~wxTextEntryBase();
  34
  35
  36     // accessing the value
  37     // -------------------
  38
  39     // SetValue() generates a text change event, ChangeValue() doesn't
  40     virtual void SetValue(const wxString& value)
  41         { DoSetValue(value, SetValue_SendEvent); }
  42     virtual void ChangeValue(const wxString& value);
  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 SelectNone()
 101         { const long pos = GetInsertionPoint(); SetSelection(pos, pos); }
 102     virtual void GetSelection(long *from, long *to) const = 0;
 103     bool HasSelection() const;
 104     virtual wxString GetStringSelection() const;
 105
 106
 107     // auto-completion
 108     // ---------------
 109
 110     // these functions allow to auto-complete the text already entered into the
 111     // control using either the given fixed list of strings, the paths from the
 112     // file system or an arbitrary user-defined completer
 113     //
 114     // they all return true if completion was enabled or false on error (most
 115     // commonly meaning that this functionality is not available under the
 116     // current platform)
 117
 118     bool AutoComplete(const wxArrayString& choices)
 119         { return DoAutoCompleteStrings(choices); }
 120
 121     bool AutoCompleteFileNames()
 122         { return DoAutoCompleteFileNames(wxFILE); }
 123
 124     bool AutoCompleteDirectories()
 125         { return DoAutoCompleteFileNames(wxDIR); }
 126
 127     // notice that we take ownership of the pointer and will delete it
 128     //
 129     // if the pointer is NULL auto-completion is disabled
 130     bool AutoComplete(wxTextCompleter *completer)
 131         { return DoAutoCompleteCustom(completer); }
 132
 133
 134     // status
 135     // ------
 136
 137     virtual bool IsEditable() const = 0;
 138     virtual void SetEditable(bool editable) = 0;
 139
 140
 141     // set the max number of characters which may be entered in a single line
 142     // text control
 143     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 144
 145
 146     // hints
 147     // -----
 148
 149     // hint is the (usually greyed out) text shown in the control as long as
 150     // it's empty and doesn't have focus, it is typically used in controls used
 151     // for searching to let the user know what is supposed to be entered there
 152
 153     virtual bool SetHint(const wxString& hint);
 154     virtual wxString GetHint() const;
 155
 156
 157     // margins
 158     // -------
 159
 160     // margins are the empty space between borders of control and the text
 161     // itself. When setting margin, use value -1 to indicate that specific
 162     // margin should not be changed.
 163
 164     bool SetMargins(const wxPoint& pt)
 165         { return DoSetMargins(pt); }
 166     bool SetMargins(wxCoord left, wxCoord top = -1)
 167         { return DoSetMargins(wxPoint(left, top)); }
 168     wxPoint GetMargins() const
 169         { return DoGetMargins(); }
 170
 171
 172     // implementation only
 173     // -------------------
 174
 175     // generate the wxEVT_TEXT event for GetEditableWindow(),
 176     // like SetValue() does and return true if the event was processed
 177     //
 178     // NB: this is public for wxRichTextCtrl use only right now, do not call it
 179     static bool SendTextUpdatedEvent(wxWindow *win);
 180
 181     // generate the wxEVT_TEXT event for this window
 182     bool SendTextUpdatedEvent()
 183     {
 184         return SendTextUpdatedEvent(GetEditableWindow());
 185     }
 186
 187
 188     // generate the wxEVT_TEXT event for this window if the
 189     // events are not currently disabled
 190     void SendTextUpdatedEventIfAllowed()
 191     {
 192         if ( EventsAllowed() )
 193             SendTextUpdatedEvent();
 194     }
 195
 196     // this function is provided solely for the purpose of forwarding text
 197     // change notifications state from one control to another, e.g. it can be
 198     // used by a wxComboBox which derives from wxTextEntry if it delegates all
 199     // of its methods to another wxTextCtrl
 200     void ForwardEnableTextChangedEvents(bool enable)
 201     {
 202         // it's important to call the functions which update m_eventsBlock here
 203         // and not just our own EnableTextChangedEvents() because our state
 204         // (i.e. the result of EventsAllowed()) must change as well
 205         if ( enable )
 206             ResumeTextChangedEvents();
 207         else
 208             SuppressTextChangedEvents();
 209     }
 210
 211 protected:
 212     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
 213     // also used to implement WriteText() in wxMSW
 214     enum
 215     {
 216         SetValue_NoEvent = 0,
 217         SetValue_SendEvent = 1,
 218         SetValue_SelectionOnly = 2
 219     };
 220
 221     virtual void DoSetValue(const wxString& value, int flags);
 222     virtual wxString DoGetValue() const = 0;
 223
 224     // override this to return the associated window, it will be used for event
 225     // generation and also by generic hints implementation
 226     virtual wxWindow *GetEditableWindow() = 0;
 227
 228     // margins functions
 229     virtual bool DoSetMargins(const wxPoint& pt);
 230     virtual wxPoint DoGetMargins() const;
 231
 232     // the derived classes should override these virtual methods to implement
 233     // auto-completion, they do the same thing as their public counterparts but
 234     // have different names to allow overriding just one of them without hiding
 235     // the other one(s)
 236     virtual bool DoAutoCompleteStrings(const wxArrayString& WXUNUSED(choices))
 237         { return false; }
 238     virtual bool DoAutoCompleteFileNames(int WXUNUSED(flags)) // wxFILE | wxDIR
 239         { return false; }
 240     virtual bool DoAutoCompleteCustom(wxTextCompleter *completer);
 241
 242
 243     // class which should be used to temporarily disable text change events
 244     //
 245     // if suppress argument in ctor is false, nothing is done
 246     class EventsSuppressor
 247     {
 248     public:
 249         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
 250             : m_text(text),
 251               m_suppress(suppress)
 252         {
 253             if ( m_suppress )
 254                 m_text->SuppressTextChangedEvents();
 255         }
 256
 257         ~EventsSuppressor()
 258         {
 259             if ( m_suppress )
 260                 m_text->ResumeTextChangedEvents();
 261         }
 262
 263     private:
 264         wxTextEntryBase *m_text;
 265         bool m_suppress;
 266     };
 267
 268     friend class EventsSuppressor;
 269
 270 private:
 271     // suppress or resume the text changed events generation: don't use these
 272     // functions directly, use EventsSuppressor class above instead
 273     void SuppressTextChangedEvents()
 274     {
 275         if ( !m_eventsBlock++ )
 276             EnableTextChangedEvents(false);
 277     }
 278
 279     void ResumeTextChangedEvents()
 280     {
 281         if ( !--m_eventsBlock )
 282             EnableTextChangedEvents(true);
 283     }
 284
 285
 286     // this must be overridden in the derived classes if our implementation of
 287     // SetValue() or Replace() is used to disable (and enable back) generation
 288     // of the text changed events
 289     //
 290     // initially the generation of the events is enabled
 291     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 292
 293     // return true if the events are currently not suppressed
 294     bool EventsAllowed() const { return m_eventsBlock == 0; }
 295
 296
 297     // if this counter is non-null, events are blocked
 298     unsigned m_eventsBlock;
 299
 300     // hint-related stuff, only allocated if/when SetHint() is used
 301     wxTextEntryHintData *m_hintData;
 302
 303     // It needs to call our Do{Get,Set}Value() to work with the real control
 304     // contents.
 305     friend class wxTextEntryHintData;
 306 };
 307
 308 #ifdef __WXUNIVERSAL__
 309     // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
 310     //       the GTK/MSW classes from being used in wxUniv build
 311     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 312     {
 313     };
 314 #elif defined(__WXGTK20__)
 315     #include "wx/gtk/textentry.h"
 316 #elif defined(__WXMAC__)
 317     #include "wx/osx/textentry.h"
 318 #elif defined(__WXMSW__)
 319     #include "wx/msw/textentry.h"
 320 #elif defined(__WXMOTIF__)
 321     #include "wx/motif/textentry.h"
 322 #elif defined(__WXPM__)
 323     #include "wx/os2/textentry.h"
 324 #else
 325     // no platform-specific implementation of wxTextEntry yet
 326     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 327     {
 328     };
 329 #endif
 330
 331 #endif // _WX_TEXTENTRY_H_
 332