]>
Commit | Line | Data |
---|---|---|
1 | ///////////////////////////////////////////////////////////////////////////// | |
2 | // Name: wx/textentry.h | |
3 | // Purpose: interface of wxTextEntry | |
4 | // Author: Vadim Zeitlin | |
5 | // Created: 2009-03-01 (extracted from wx/textctrl.h) | |
6 | // RCS-ID: $Id$ | |
7 | // Copyright: (c) 2009 Vadim Zeitlin <vadim@wxwindows.org> | |
8 | // Licence: wxWindows licence | |
9 | ///////////////////////////////////////////////////////////////////////////// | |
10 | ||
11 | /** | |
12 | @class wxTextEntry | |
13 | ||
14 | Common base class for single line text entry fields. | |
15 | ||
16 | This class is not a control itself, as it doesn't derive from wxWindow. | |
17 | Instead it is used as a base class by other controls, notably wxTextCtrl | |
18 | and wxComboBox and gathers the methods common to both of them. | |
19 | ||
20 | @library{wxcore} | |
21 | @category{ctrl} | |
22 | ||
23 | @see wxTextCtrl, wxComboBox | |
24 | ||
25 | @since 2.9.0 | |
26 | */ | |
27 | class wxTextEntry | |
28 | { | |
29 | public: | |
30 | /** | |
31 | Appends the text to the end of the text control. | |
32 | ||
33 | @param text | |
34 | Text to write to the text control. | |
35 | ||
36 | @remarks | |
37 | After the text is appended, the insertion point will be at the | |
38 | end of the text control. If this behaviour is not desired, the | |
39 | programmer should use GetInsertionPoint() and SetInsertionPoint(). | |
40 | ||
41 | @see WriteText() | |
42 | */ | |
43 | virtual void AppendText(const wxString& text); | |
44 | ||
45 | /** | |
46 | Call this function to enable auto-completion of the text typed in a | |
47 | single-line text control using the given @a choices. | |
48 | ||
49 | Notice that currently this function is only implemented in wxGTK2 and | |
50 | wxMSW ports and does nothing under the other platforms. | |
51 | ||
52 | @since 2.9.0 | |
53 | ||
54 | @return | |
55 | @true if the auto-completion was enabled or @false if the operation | |
56 | failed, typically because auto-completion is not supported by the | |
57 | current platform. | |
58 | ||
59 | @see AutoCompleteFileNames() | |
60 | */ | |
61 | virtual bool AutoComplete(const wxArrayString& choices); | |
62 | ||
63 | /** | |
64 | Call this function to enable auto-completion of the text typed in a | |
65 | single-line text control using all valid file system paths. | |
66 | ||
67 | Notice that currently this function is only implemented in wxGTK2 port | |
68 | and does nothing under the other platforms. | |
69 | ||
70 | @since 2.9.0 | |
71 | ||
72 | @return | |
73 | @true if the auto-completion was enabled or @false if the operation | |
74 | failed, typically because auto-completion is not supported by the | |
75 | current platform. | |
76 | ||
77 | @see AutoComplete() | |
78 | */ | |
79 | virtual bool AutoCompleteFileNames(); | |
80 | ||
81 | /** | |
82 | Returns @true if the selection can be copied to the clipboard. | |
83 | */ | |
84 | virtual bool CanCopy() const; | |
85 | ||
86 | /** | |
87 | Returns @true if the selection can be cut to the clipboard. | |
88 | */ | |
89 | virtual bool CanCut() const; | |
90 | ||
91 | /** | |
92 | Returns @true if the contents of the clipboard can be pasted into the | |
93 | text control. | |
94 | ||
95 | On some platforms (Motif, GTK) this is an approximation and returns | |
96 | @true if the control is editable, @false otherwise. | |
97 | */ | |
98 | virtual bool CanPaste() const; | |
99 | ||
100 | /** | |
101 | Returns @true if there is a redo facility available and the last | |
102 | operation can be redone. | |
103 | */ | |
104 | virtual bool CanRedo() const; | |
105 | ||
106 | /** | |
107 | Returns @true if there is an undo facility available and the last | |
108 | operation can be undone. | |
109 | */ | |
110 | virtual bool CanUndo() const; | |
111 | ||
112 | /** | |
113 | Sets the new text control value. | |
114 | ||
115 | It also marks the control as not-modified which means that IsModified() | |
116 | would return @false immediately after the call to ChangeValue(). | |
117 | ||
118 | The insertion point is set to the start of the control (i.e. position | |
119 | 0) by this function. | |
120 | ||
121 | This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED | |
122 | event but otherwise is identical to SetValue(). | |
123 | ||
124 | See @ref overview_events_prog for more information. | |
125 | ||
126 | @since 2.7.1 | |
127 | ||
128 | @param value | |
129 | The new value to set. It may contain newline characters if the text | |
130 | control is multi-line. | |
131 | */ | |
132 | virtual void ChangeValue(const wxString& value); | |
133 | ||
134 | /** | |
135 | Clears the text in the control. | |
136 | ||
137 | Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED | |
138 | event, i.e. its effect is identical to calling @c SetValue(""). | |
139 | */ | |
140 | virtual void Clear(); | |
141 | ||
142 | /** | |
143 | Copies the selected text to the clipboard. | |
144 | */ | |
145 | virtual void Copy(); | |
146 | ||
147 | /** | |
148 | Returns the insertion point, or cursor, position. | |
149 | ||
150 | This is defined as the zero based index of the character position to | |
151 | the right of the insertion point. For example, if the insertion point | |
152 | is at the end of the single-line text control, it is equal to both | |
153 | GetLastPosition() and @c "GetValue().Length()" (but notice that the latter | |
154 | equality is not necessarily true for multiline edit controls which may | |
155 | use multiple new line characters). | |
156 | ||
157 | The following code snippet safely returns the character at the insertion | |
158 | point or the zero character if the point is at the end of the control. | |
159 | ||
160 | @code | |
161 | char GetCurrentChar(wxTextCtrl *tc) { | |
162 | if (tc->GetInsertionPoint() == tc->GetLastPosition()) | |
163 | return '\0'; | |
164 | return tc->GetValue[tc->GetInsertionPoint()]; | |
165 | } | |
166 | @endcode | |
167 | */ | |
168 | virtual long GetInsertionPoint() const; | |
169 | ||
170 | /** | |
171 | Returns the zero based index of the last position in the text control, | |
172 | which is equal to the number of characters in the control. | |
173 | */ | |
174 | virtual wxTextPos GetLastPosition() const; | |
175 | ||
176 | /** | |
177 | Returns the string containing the text starting in the positions | |
178 | @a from and up to @a to in the control. | |
179 | ||
180 | The positions must have been returned by another wxTextCtrl method. | |
181 | Please note that the positions in a multiline wxTextCtrl do @b not | |
182 | correspond to the indices in the string returned by GetValue() because | |
183 | of the different new line representations (@c CR or @c CR LF) and so | |
184 | this method should be used to obtain the correct results instead of | |
185 | extracting parts of the entire value. It may also be more efficient, | |
186 | especially if the control contains a lot of data. | |
187 | */ | |
188 | virtual wxString GetRange(long from, long to) const; | |
189 | ||
190 | /** | |
191 | Gets the current selection span. | |
192 | ||
193 | If the returned values are equal, there was no selection. Please note | |
194 | that the indices returned may be used with the other wxTextCtrl methods | |
195 | but don't necessarily represent the correct indices into the string | |
196 | returned by GetValue() for multiline controls under Windows (at least,) | |
197 | you should use GetStringSelection() to get the selected text. | |
198 | ||
199 | @param from | |
200 | The returned first position. | |
201 | @param to | |
202 | The returned last position. | |
203 | ||
204 | @beginWxPerlOnly | |
205 | In wxPerl this method takes no parameters and returns a | |
206 | 2-element list (from, to). | |
207 | @endWxPerlOnly | |
208 | */ | |
209 | virtual void GetSelection(long* from, long* to) const; | |
210 | ||
211 | /** | |
212 | Gets the text currently selected in the control. | |
213 | ||
214 | If there is no selection, the returned string is empty. | |
215 | */ | |
216 | virtual wxString GetStringSelection() const; | |
217 | ||
218 | /** | |
219 | Gets the contents of the control. | |
220 | ||
221 | Notice that for a multiline text control, the lines will be separated | |
222 | by (Unix-style) @c \\n characters, even under Windows where they are | |
223 | separated by a @c \\r\\n sequence in the native control. | |
224 | */ | |
225 | virtual wxString GetValue() const; | |
226 | ||
227 | /** | |
228 | Returns @true if the controls contents may be edited by user (note that | |
229 | it always can be changed by the program). | |
230 | ||
231 | In other words, this functions returns @true if the control hasn't been | |
232 | put in read-only mode by a previous call to SetEditable(). | |
233 | */ | |
234 | virtual bool IsEditable() const; | |
235 | ||
236 | /** | |
237 | Returns @true if the control is currently empty. | |
238 | ||
239 | This is the same as @c GetValue().empty() but can be much more | |
240 | efficient for the multiline controls containing big amounts of text. | |
241 | ||
242 | @since 2.7.1 | |
243 | */ | |
244 | virtual bool IsEmpty() const; | |
245 | ||
246 | /** | |
247 | Pastes text from the clipboard to the text item. | |
248 | */ | |
249 | virtual void Paste(); | |
250 | ||
251 | /** | |
252 | If there is a redo facility and the last operation can be redone, | |
253 | redoes the last operation. | |
254 | ||
255 | Does nothing if there is no redo facility. | |
256 | */ | |
257 | virtual void Redo(); | |
258 | ||
259 | /** | |
260 | Removes the text starting at the first given position up to | |
261 | (but not including) the character at the last position. | |
262 | ||
263 | This function puts the current insertion point position at @a to as a | |
264 | side effect. | |
265 | ||
266 | @param from | |
267 | The first position. | |
268 | @param to | |
269 | The last position. | |
270 | */ | |
271 | virtual void Remove(long from, long to); | |
272 | ||
273 | /** | |
274 | Replaces the text starting at the first position up to | |
275 | (but not including) the character at the last position with the given text. | |
276 | ||
277 | This function puts the current insertion point position at @a to as a | |
278 | side effect. | |
279 | ||
280 | @param from | |
281 | The first position. | |
282 | @param to | |
283 | The last position. | |
284 | @param value | |
285 | The value to replace the existing text with. | |
286 | */ | |
287 | virtual void Replace(long from, long to, const wxString& value); | |
288 | ||
289 | /** | |
290 | Makes the text item editable or read-only, overriding the | |
291 | @b wxTE_READONLY flag. | |
292 | ||
293 | @param editable | |
294 | If @true, the control is editable. If @false, the control is | |
295 | read-only. | |
296 | ||
297 | @see IsEditable() | |
298 | */ | |
299 | virtual void SetEditable(bool editable); | |
300 | ||
301 | /** | |
302 | Sets the insertion point at the given position. | |
303 | ||
304 | @param pos | |
305 | Position to set, in the range from 0 to GetLastPosition() inclusive. | |
306 | */ | |
307 | virtual void SetInsertionPoint(long pos); | |
308 | ||
309 | /** | |
310 | Sets the insertion point at the end of the text control. | |
311 | ||
312 | This is equivalent to calling wxTextCtrl::SetInsertionPoint() with | |
313 | wxTextCtrl::GetLastPosition() argument. | |
314 | */ | |
315 | virtual void SetInsertionPointEnd(); | |
316 | ||
317 | /** | |
318 | This function sets the maximum number of characters the user can enter | |
319 | into the control. | |
320 | ||
321 | In other words, it allows to limit the text value length to @a len not | |
322 | counting the terminating @c NUL character. | |
323 | ||
324 | If @a len is 0, the previously set max length limit, if any, is discarded | |
325 | and the user may enter as much text as the underlying native text control widget | |
326 | supports (typically at least 32Kb). | |
327 | If the user tries to enter more characters into the text control when it | |
328 | already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN | |
329 | event is sent to notify the program about it (giving it the possibility | |
330 | to show an explanatory message, for example) and the extra input is discarded. | |
331 | ||
332 | Note that in wxGTK this function may only be used with single line text controls. | |
333 | */ | |
334 | virtual void SetMaxLength(unsigned long len); | |
335 | ||
336 | /** | |
337 | Selects the text starting at the first position up to (but not | |
338 | including) the character at the last position. | |
339 | ||
340 | If both parameters are equal to -1 all text in the control is selected. | |
341 | ||
342 | Notice that the insertion point will be moved to @a from by this | |
343 | function. | |
344 | ||
345 | @param from | |
346 | The first position. | |
347 | @param to | |
348 | The last position. | |
349 | ||
350 | @see SelectAll() | |
351 | */ | |
352 | virtual void SetSelection(long from, long to); | |
353 | ||
354 | /** | |
355 | Selects all text in the control. | |
356 | ||
357 | @see SetSelection() | |
358 | */ | |
359 | virtual void SelectAll(); | |
360 | ||
361 | /** | |
362 | Sets a hint shown in an empty unfocused text control. | |
363 | ||
364 | The hints are usually used to indicate to the user what is supposed to | |
365 | be entered into the given entry field, e.g. a common use of them is to | |
366 | show an explanation of what can be entered in a wxSearchCtrl. | |
367 | ||
368 | The hint is shown (usually greyed out) for an empty control until it | |
369 | gets focus and is shown again if the control loses it and remains | |
370 | empty. It won't be shown once the control has a non-empty value, | |
371 | although it will be shown again if the control contents is cleared. | |
372 | Because of this, it generally only makes sense to use hints with the | |
373 | controls which are initially empty. | |
374 | ||
375 | Notice that hints are known as <em>cue banners</em> under MSW or | |
376 | <em>placeholder strings</em> under OS X. | |
377 | ||
378 | @since 2.9.0 | |
379 | */ | |
380 | virtual void SetHint(const wxString& hint); | |
381 | ||
382 | /** | |
383 | Returns the current hint string. | |
384 | ||
385 | See SetHint() for more information about hints. | |
386 | ||
387 | @since 2.9.0 | |
388 | */ | |
389 | virtual wxString GetHint() const; | |
390 | ||
391 | //@{ | |
392 | /** | |
393 | Attempts to set the control margins. When margins are given as wxPoint, | |
394 | x indicates the left and y the top margin. Use -1 to indicate that | |
395 | an existing value should be used. | |
396 | ||
397 | @return | |
398 | @true if setting of all requested margins was successful. | |
399 | ||
400 | @since 2.9.1 | |
401 | */ | |
402 | bool SetMargins(const wxPoint& pt); | |
403 | bool SetMargins(wxCoord left, wxCoord top = -1); | |
404 | //@} | |
405 | ||
406 | /** | |
407 | Returns the margins used by the control. The @c x field of the returned | |
408 | point is the horizontal margin and the @c y field is the vertical one. | |
409 | ||
410 | @remarks If given margin cannot be accurately determined, its value | |
411 | will be set to -1. On some platforms you cannot obtain valid | |
412 | margin values until you have called SetMargins(). | |
413 | ||
414 | @see SetMargins() | |
415 | ||
416 | @since 2.9.1 | |
417 | */ | |
418 | wxPoint GetMargins() const; | |
419 | ||
420 | /** | |
421 | Sets the new text control value. | |
422 | ||
423 | It also marks the control as not-modified which means that IsModified() | |
424 | would return @false immediately after the call to SetValue(). | |
425 | ||
426 | The insertion point is set to the start of the control (i.e. position | |
427 | 0) by this function. | |
428 | ||
429 | Note that, unlike most other functions changing the controls values, | |
430 | this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid | |
431 | this you can use ChangeValue() instead. | |
432 | ||
433 | @param value | |
434 | The new value to set. It may contain newline characters if the text | |
435 | control is multi-line. | |
436 | */ | |
437 | virtual void SetValue(const wxString& value); | |
438 | ||
439 | /** | |
440 | If there is an undo facility and the last operation can be undone, | |
441 | undoes the last operation. | |
442 | ||
443 | Does nothing if there is no undo facility. | |
444 | */ | |
445 | virtual void Undo(); | |
446 | ||
447 | /** | |
448 | Writes the text into the text control at the current insertion position. | |
449 | ||
450 | @param text | |
451 | Text to write to the text control. | |
452 | ||
453 | @remarks | |
454 | Newlines in the text string are the only control characters | |
455 | allowed, and they will cause appropriate line breaks. | |
456 | See operator<<() and AppendText() for more convenient ways of | |
457 | writing to the window. | |
458 | After the write operation, the insertion point will be at the end | |
459 | of the inserted text, so subsequent write operations will be appended. | |
460 | To append text after the user may have interacted with the control, | |
461 | call wxTextCtrl::SetInsertionPointEnd() before writing. | |
462 | */ | |
463 | virtual void WriteText(const wxString& text); | |
464 | }; |