]>
Commit | Line | Data |
---|---|---|
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 |