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