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