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