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