]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/textentry.h
Updates to Indonesian translations by Rahmat Bambang.
[wxWidgets.git] / interface / wx / textentry.h
CommitLineData
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*/
15typedef 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*/
34class wxTextEntry
35{
36public:
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
c7001dcd
VZ
214 is at the end of the single-line text control, it is equal to
215 GetLastPosition().
2e7789a9 216
c7001dcd
VZ
217 Notice that insertion position is, in general, different from the index
218 of the character the cursor position at in the string returned by
219 GetValue(). While this is always the case for the single line controls,
220 multi-line controls can use two characters @c "\\r\\n" as line
221 separator (this is notably the case under MSW) meaning that indices in
222 the control and its string value are offset by 1 for every line.
223
224 Hence to correctly get the character at the current cursor position,
225 taking into account that there can be none if the cursor is at the end
226 of the string, you could do the following:
2e7789a9
VZ
227
228 @code
c7001dcd
VZ
229 wxString GetCurrentChar(wxTextCtrl *tc)
230 {
231 long pos = tc->GetInsertionPoint();
232 if ( pos == tc->GetLastPosition() )
233 return wxString();
234
235 return tc->GetRange(pos, pos + 1);
2e7789a9
VZ
236 }
237 @endcode
238 */
239 virtual long GetInsertionPoint() const;
240
241 /**
242 Returns the zero based index of the last position in the text control,
243 which is equal to the number of characters in the control.
244 */
245 virtual wxTextPos GetLastPosition() const;
246
247 /**
248 Returns the string containing the text starting in the positions
249 @a from and up to @a to in the control.
250
251 The positions must have been returned by another wxTextCtrl method.
252 Please note that the positions in a multiline wxTextCtrl do @b not
253 correspond to the indices in the string returned by GetValue() because
254 of the different new line representations (@c CR or @c CR LF) and so
255 this method should be used to obtain the correct results instead of
256 extracting parts of the entire value. It may also be more efficient,
257 especially if the control contains a lot of data.
258 */
259 virtual wxString GetRange(long from, long to) const;
260
261 /**
262 Gets the current selection span.
263
264 If the returned values are equal, there was no selection. Please note
265 that the indices returned may be used with the other wxTextCtrl methods
266 but don't necessarily represent the correct indices into the string
267 returned by GetValue() for multiline controls under Windows (at least,)
268 you should use GetStringSelection() to get the selected text.
269
270 @param from
271 The returned first position.
272 @param to
273 The returned last position.
1058f652
MB
274
275 @beginWxPerlOnly
276 In wxPerl this method takes no parameters and returns a
277 2-element list (from, to).
278 @endWxPerlOnly
2e7789a9
VZ
279 */
280 virtual void GetSelection(long* from, long* to) const;
281
282 /**
283 Gets the text currently selected in the control.
284
285 If there is no selection, the returned string is empty.
286 */
287 virtual wxString GetStringSelection() const;
288
289 /**
290 Gets the contents of the control.
291
292 Notice that for a multiline text control, the lines will be separated
293 by (Unix-style) @c \\n characters, even under Windows where they are
294 separated by a @c \\r\\n sequence in the native control.
295 */
296 virtual wxString GetValue() const;
297
298 /**
299 Returns @true if the controls contents may be edited by user (note that
300 it always can be changed by the program).
301
302 In other words, this functions returns @true if the control hasn't been
303 put in read-only mode by a previous call to SetEditable().
304 */
305 virtual bool IsEditable() const;
306
307 /**
308 Returns @true if the control is currently empty.
309
310 This is the same as @c GetValue().empty() but can be much more
311 efficient for the multiline controls containing big amounts of text.
312
313 @since 2.7.1
314 */
315 virtual bool IsEmpty() const;
316
317 /**
318 Pastes text from the clipboard to the text item.
319 */
320 virtual void Paste();
321
322 /**
323 If there is a redo facility and the last operation can be redone,
324 redoes the last operation.
325
326 Does nothing if there is no redo facility.
327 */
328 virtual void Redo();
329
330 /**
331 Removes the text starting at the first given position up to
332 (but not including) the character at the last position.
333
334 This function puts the current insertion point position at @a to as a
335 side effect.
336
337 @param from
338 The first position.
339 @param to
340 The last position.
341 */
342 virtual void Remove(long from, long to);
343
344 /**
345 Replaces the text starting at the first position up to
346 (but not including) the character at the last position with the given text.
347
348 This function puts the current insertion point position at @a to as a
349 side effect.
350
351 @param from
352 The first position.
353 @param to
354 The last position.
355 @param value
356 The value to replace the existing text with.
357 */
358 virtual void Replace(long from, long to, const wxString& value);
359
360 /**
361 Makes the text item editable or read-only, overriding the
362 @b wxTE_READONLY flag.
363
364 @param editable
365 If @true, the control is editable. If @false, the control is
366 read-only.
367
368 @see IsEditable()
369 */
370 virtual void SetEditable(bool editable);
371
372 /**
373 Sets the insertion point at the given position.
374
375 @param pos
376 Position to set, in the range from 0 to GetLastPosition() inclusive.
377 */
378 virtual void SetInsertionPoint(long pos);
379
380 /**
381 Sets the insertion point at the end of the text control.
382
383 This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
384 wxTextCtrl::GetLastPosition() argument.
385 */
386 virtual void SetInsertionPointEnd();
387
388 /**
389 This function sets the maximum number of characters the user can enter
390 into the control.
391
392 In other words, it allows to limit the text value length to @a len not
393 counting the terminating @c NUL character.
394
395 If @a len is 0, the previously set max length limit, if any, is discarded
396 and the user may enter as much text as the underlying native text control widget
397 supports (typically at least 32Kb).
398 If the user tries to enter more characters into the text control when it
399 already is filled up to the maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN
400 event is sent to notify the program about it (giving it the possibility
401 to show an explanatory message, for example) and the extra input is discarded.
402
403 Note that in wxGTK this function may only be used with single line text controls.
404 */
405 virtual void SetMaxLength(unsigned long len);
406
407 /**
408 Selects the text starting at the first position up to (but not
409 including) the character at the last position.
410
411 If both parameters are equal to -1 all text in the control is selected.
412
413 Notice that the insertion point will be moved to @a from by this
414 function.
415
416 @param from
417 The first position.
418 @param to
419 The last position.
420
421 @see SelectAll()
422 */
423 virtual void SetSelection(long from, long to);
424
425 /**
426 Selects all text in the control.
427
428 @see SetSelection()
429 */
430 virtual void SelectAll();
431
30496905
VZ
432 /**
433 Deselects selected text in the control.
434
435 @since 2.9.5
436 */
437 virtual void SelectNone();
438
63f7d502
VZ
439 /**
440 Sets a hint shown in an empty unfocused text control.
441
442 The hints are usually used to indicate to the user what is supposed to
443 be entered into the given entry field, e.g. a common use of them is to
444 show an explanation of what can be entered in a wxSearchCtrl.
445
446 The hint is shown (usually greyed out) for an empty control until it
447 gets focus and is shown again if the control loses it and remains
448 empty. It won't be shown once the control has a non-empty value,
449 although it will be shown again if the control contents is cleared.
450 Because of this, it generally only makes sense to use hints with the
451 controls which are initially empty.
452
453 Notice that hints are known as <em>cue banners</em> under MSW or
454 <em>placeholder strings</em> under OS X.
455
7d4cb1ef
VZ
456 @remarks For the platforms without native hints support (and currently
457 only the MSW port does have it and even there it is only used under
458 Windows Vista and later only), the implementation has several known
459 limitations. Notably, the hint display will not be properly updated
460 if you change wxTextEntry contents programmatically when the hint
461 is displayed using methods other than SetValue() or ChangeValue()
462 or others which use them internally (e.g. Clear()). In other words,
463 currently you should avoid calling methods such as WriteText() or
464 Replace() when using hints and the text control is empty.
465
7dd65e5a
VZ
466 @remarks Hints can only be used for single line text controls,
467 native multi-line text controls don't support hints under any
468 platform and hence wxWidgets doesn't provide them neither.
469
63f7d502
VZ
470 @since 2.9.0
471 */
e9321277 472 virtual bool SetHint(const wxString& hint);
63f7d502
VZ
473
474 /**
475 Returns the current hint string.
476
477 See SetHint() for more information about hints.
478
479 @since 2.9.0
480 */
481 virtual wxString GetHint() const;
482
0847e36e
JS
483 //@{
484 /**
485 Attempts to set the control margins. When margins are given as wxPoint,
486 x indicates the left and y the top margin. Use -1 to indicate that
487 an existing value should be used.
488
489 @return
490 @true if setting of all requested margins was successful.
491
492 @since 2.9.1
493 */
494 bool SetMargins(const wxPoint& pt);
495 bool SetMargins(wxCoord left, wxCoord top = -1);
496 //@}
497
498 /**
499 Returns the margins used by the control. The @c x field of the returned
500 point is the horizontal margin and the @c y field is the vertical one.
501
502 @remarks If given margin cannot be accurately determined, its value
503 will be set to -1. On some platforms you cannot obtain valid
504 margin values until you have called SetMargins().
505
506 @see SetMargins()
507
508 @since 2.9.1
509 */
510 wxPoint GetMargins() const;
511
2e7789a9
VZ
512 /**
513 Sets the new text control value.
514
515 It also marks the control as not-modified which means that IsModified()
516 would return @false immediately after the call to SetValue().
517
518 The insertion point is set to the start of the control (i.e. position
519 0) by this function.
520
521 Note that, unlike most other functions changing the controls values,
522 this function generates a @c wxEVT_COMMAND_TEXT_UPDATED event. To avoid
523 this you can use ChangeValue() instead.
524
525 @param value
526 The new value to set. It may contain newline characters if the text
527 control is multi-line.
528 */
529 virtual void SetValue(const wxString& value);
530
531 /**
532 If there is an undo facility and the last operation can be undone,
533 undoes the last operation.
534
535 Does nothing if there is no undo facility.
536 */
537 virtual void Undo();
538
539 /**
540 Writes the text into the text control at the current insertion position.
541
542 @param text
543 Text to write to the text control.
544
545 @remarks
546 Newlines in the text string are the only control characters
547 allowed, and they will cause appropriate line breaks.
548 See operator<<() and AppendText() for more convenient ways of
549 writing to the window.
550 After the write operation, the insertion point will be at the end
551 of the inserted text, so subsequent write operations will be appended.
552 To append text after the user may have interacted with the control,
553 call wxTextCtrl::SetInsertionPointEnd() before writing.
554 */
555 virtual void WriteText(const wxString& text);
556};