Use /bin/echo for creation of Mac OS X PkgInfo files.
[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
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};