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     virtual bool AutoComplete(const wxArrayString& WXUNUSED(choices))
 116     {
 117         return false;
 118     }
 119
 120     virtual bool AutoCompleteFileNames() { return false; }
 121
 122
 123     // status
 124     // ------
 125
 126     virtual bool IsEditable() const = 0;
 127     virtual void SetEditable(bool editable) = 0;
 128
 129
 130     // set the max number of characters which may be entered in a single line
 131     // text control
 132     virtual void SetMaxLength(unsigned long WXUNUSED(len)) { }
 133
 134
 135     // hints
 136     // -----
 137
 138     // hint is the (usually greyed out) text shown in the control as long as
 139     // it's empty and doesn't have focus, it is typically used in controls used
 140     // for searching to let the user know what is supposed to be entered there
 141
 142     virtual bool SetHint(const wxString& hint);
 143     virtual wxString GetHint() const;
 144
 145
 146     // margins
 147     // -------
 148
 149     // margins are the empty space between borders of control and the text
 150     // itself. When setting margin, use value -1 to indicate that specific
 151     // margin should not be changed.
 152
 153     bool SetMargins(const wxPoint& pt)
 154         { return DoSetMargins(pt); }
 155     bool SetMargins(wxCoord left, wxCoord top = -1)
 156         { return DoSetMargins(wxPoint(left, top)); }
 157     wxPoint GetMargins() const
 158         { return DoGetMargins(); }
 159
 160
 161     // implementation only
 162     // -------------------
 163
 164     // generate the wxEVT_COMMAND_TEXT_UPDATED event for GetEditableWindow(),
 165     // like SetValue() does and return true if the event was processed
 166     //
 167     // NB: this is public for wxRichTextCtrl use only right now, do not call it
 168     static bool SendTextUpdatedEvent(wxWindow *win);
 169
 170     // generate the wxEVT_COMMAND_TEXT_UPDATED event for this window
 171     bool SendTextUpdatedEvent()
 172     {
 173         return SendTextUpdatedEvent(GetEditableWindow());
 174     }
 175
 176
 177     // generate the wxEVT_COMMAND_TEXT_UPDATED event for this window if the
 178     // events are not currently disabled
 179     void SendTextUpdatedEventIfAllowed()
 180     {
 181         if ( EventsAllowed() )
 182             SendTextUpdatedEvent();
 183     }
 184
 185     // this function is provided solely for the purpose of forwarding text
 186     // change notifications state from one control to another, e.g. it can be
 187     // used by a wxComboBox which derives from wxTextEntry if it delegates all
 188     // of its methods to another wxTextCtrl
 189     void ForwardEnableTextChangedEvents(bool enable)
 190     {
 191         // it's important to call the functions which update m_eventsBlock here
 192         // and not just our own EnableTextChangedEvents() because our state
 193         // (i.e. the result of EventsAllowed()) must change as well
 194         if ( enable )
 195             ResumeTextChangedEvents();
 196         else
 197             SuppressTextChangedEvents();
 198     }
 199
 200 protected:
 201     // flags for DoSetValue(): common part of SetValue() and ChangeValue() and
 202     // also used to implement WriteText() in wxMSW
 203     enum
 204     {
 205         SetValue_NoEvent = 0,
 206         SetValue_SendEvent = 1,
 207         SetValue_SelectionOnly = 2
 208     };
 209
 210     virtual void DoSetValue(const wxString& value, int flags);
 211     virtual wxString DoGetValue() const = 0;
 212
 213     // override this to return the associated window, it will be used for event
 214     // generation and also by generic hints implementation
 215     virtual wxWindow *GetEditableWindow() = 0;
 216
 217     // margins functions
 218     virtual bool DoSetMargins(const wxPoint& pt);
 219     virtual wxPoint DoGetMargins() const;
 220
 221
 222     // class which should be used to temporarily disable text change events
 223     //
 224     // if suppress argument in ctor is false, nothing is done
 225     class EventsSuppressor
 226     {
 227     public:
 228         EventsSuppressor(wxTextEntryBase *text, bool suppress = true)
 229             : m_text(text),
 230               m_suppress(suppress)
 231         {
 232             if ( m_suppress )
 233                 m_text->SuppressTextChangedEvents();
 234         }
 235
 236         ~EventsSuppressor()
 237         {
 238             if ( m_suppress )
 239                 m_text->ResumeTextChangedEvents();
 240         }
 241
 242     private:
 243         wxTextEntryBase *m_text;
 244         bool m_suppress;
 245     };
 246
 247     friend class EventsSuppressor;
 248
 249 private:
 250     // suppress or resume the text changed events generation: don't use these
 251     // functions directly, use EventsSuppressor class above instead
 252     void SuppressTextChangedEvents()
 253     {
 254         if ( !m_eventsBlock++ )
 255             EnableTextChangedEvents(false);
 256     }
 257
 258     void ResumeTextChangedEvents()
 259     {
 260         if ( !--m_eventsBlock )
 261             EnableTextChangedEvents(true);
 262     }
 263
 264
 265     // this must be overridden in the derived classes if our implementation of
 266     // SetValue() or Replace() is used to disable (and enable back) generation
 267     // of the text changed events
 268     //
 269     // initially the generation of the events is enabled
 270     virtual void EnableTextChangedEvents(bool WXUNUSED(enable)) { }
 271
 272     // return true if the events are currently not suppressed
 273     bool EventsAllowed() const { return m_eventsBlock == 0; }
 274
 275
 276     // if this counter is non-null, events are blocked
 277     unsigned m_eventsBlock;
 278
 279     // hint-related stuff, only allocated if/when SetHint() is used
 280     wxTextEntryHintData *m_hintData;
 281
 282     // It needs to call our Do{Get,Set}Value() to work with the real control
 283     // contents.
 284     friend class wxTextEntryHintData;
 285 };
 286
 287 #ifdef __WXUNIVERSAL__
 288     // TODO: we need to use wxTextEntryDelegate here, but for now just prevent
 289     //       the GTK/MSW classes from being used in wxUniv build
 290     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 291     {
 292     };
 293 #elif defined(__WXGTK20__)
 294     #include "wx/gtk/textentry.h"
 295 #elif defined(__WXMAC__)
 296     #include "wx/osx/textentry.h"
 297 #elif defined(__WXMSW__)
 298     #include "wx/msw/textentry.h"
 299 #elif defined(__WXMOTIF__)
 300     #include "wx/motif/textentry.h"
 301 #elif defined(__WXPM__)
 302     #include "wx/os2/textentry.h"
 303 #else
 304     // no platform-specific implementation of wxTextEntry yet
 305     class WXDLLIMPEXP_CORE wxTextEntry : public wxTextEntryBase
 306     {
 307     };
 308 #endif
 309
 310 #endif // _WX_TEXTENTRY_H_
 311