]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/text.tex
wxPython documentation updates
[wxWidgets.git] / docs / latex / wx / text.tex
... / ...
CommitLineData
1\section{\class{wxTextCtrl}}\label{wxtextctrl}
2
3A text control allows text to be displayed and edited. It may be
4single line or multi-line.
5
6\wxheading{Derived from}
7
8streambuf\\
9\helpref{wxControl}{wxcontrol}\\
10\helpref{wxWindow}{wxwindow}\\
11\helpref{wxEvtHandler}{wxevthandler}\\
12\helpref{wxObject}{wxobject}
13
14\wxheading{Include files}
15
16<wx/textctrl.h>
17
18\wxheading{Window styles}
19
20\twocolwidtha{5cm}
21\begin{twocollist}\itemsep=0pt
22\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
23the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
24either processed internally by the control or used for navigation between
25dialog controls).}
26\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
27EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the
28next control in a dialog instead. For the control created with this style,
29you can still use Ctrl-Enter to pass to the next control from the keyboard.}
30\twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
31\twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
32\twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
33\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
34\end{twocollist}
35
36See also \helpref{window styles overview}{windowstyles} and
37\helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
38
39\wxheading{Remarks}
40
41This class multiply-inherits from {\bf streambuf} where compilers allow, allowing code such as
42the following:
43
44{\small%
45\begin{verbatim}
46 wxTextCtrl *control = new wxTextCtrl(...);
47
48 ostream stream(control)
49
50 stream << 123.456 << " some text\n";
51 stream.flush();
52\end{verbatim}
53}%
54
55If your compiler does not support derivation from {\bf streambuf} and gives a compile error, define the symbol
56{\bf NO\_TEXT\_WINDOW\_STREAM} in the wxTextCtrl header file.
57
58Note that any use of C++ iostreams (including this one) deprecated and might get completely removed
59in the future.
60
61\wxheading{Event handling}
62
63The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
64wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
65automatically, when the control has the focus.
66
67To process input from a text control, use these event handler macros to direct input to member
68functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
69
70\twocolwidtha{7cm}%
71\begin{twocollist}\itemsep=0pt
72\twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
73generated when the text changes. Notice that this event will always be sent
74when the text controls contents changes - whether this is due to user input or
75comes from the program itself (for example, if SetValue() is called)}
76\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
77generated when enter is pressed in a single-line text control.}
78\end{twocollist}%
79
80%\wxheading{See also}
81%
82%\helpref{wxRichTextCtrl}{wxrichtextctrl}
83%
84\latexignore{\rtfignore{\wxheading{Members}}}
85
86\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
87
88\func{}{wxTextCtrl}{\void}
89
90Default constructor.
91
92\func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
93\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
94\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
95
96Constructor, creating and showing a text control.
97
98\wxheading{Parameters}
99
100\docparam{parent}{Parent window. Should not be NULL.}
101
102\docparam{id}{Control identifier. A value of -1 denotes a default value.}
103
104\docparam{value}{Default text value.}
105
106\docparam{pos}{Text control position.}
107
108\docparam{size}{Text control size.}
109
110\docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
111
112\docparam{validator}{Window validator.}
113
114\docparam{name}{Window name.}
115
116\wxheading{Remarks}
117
118The horizontal scrollbar ({\bf wxTE\_HSCROLL} style flag) will only be created for multi-line text controls.
119Without a horizontal scrollbar, text lines that don't fit in the control's
120size will be wrapped (but no newline character is inserted). Single line
121controls don't have a horizontal scrollbar, the text is automatically scrolled
122so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
123visible.
124
125Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
126as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
127apply.
128
129\wxheading{See also}
130
131\helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
132
133\membersection{wxTextCtrl::\destruct{wxTextCtrl}}
134
135\func{}{\destruct{wxTextCtrl}}{\void}
136
137Destructor, destroying the text control.
138
139\membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
140
141\func{void}{AppendText}{\param{const wxString\& }{ text}}
142
143Appends the text to the end of the text control.
144
145\wxheading{Parameters}
146
147\docparam{text}{Text to write to the text control.}
148
149\wxheading{Remarks}
150
151After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
152the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
153
154\wxheading{See also}
155
156\helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
157
158\membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
159
160\func{virtual bool}{CanCopy}{\void}
161
162Returns TRUE if the selection can be copied to the clipboard.
163
164\membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
165
166\func{virtual bool}{CanCut}{\void}
167
168Returns TRUE if the selection can be cut to the clipboard.
169
170\membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
171
172\func{virtual bool}{CanPaste}{\void}
173
174Returns TRUE if the contents of the clipboard can be pasted into the
175text control. On some platforms (Motif, GTK) this is an approximation
176and returns TRUE if the control is editable, FALSE otherwise.
177
178\membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
179
180\func{virtual bool}{CanRedo}{\void}
181
182Returns TRUE if there is a redo facility available and the last operation
183can be redone.
184
185\membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
186
187\func{virtual bool}{CanUndo}{\void}
188
189Returns TRUE if there is an undo facility available and the last operation
190can be undone.
191
192\membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
193
194\func{virtual void}{Clear}{\void}
195
196Clears the text in the control.
197
198\membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
199
200\func{virtual void}{Copy}{\void}
201
202Copies the selected text to the clipboard under Motif and MS Windows.
203
204\membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
205
206\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
207\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
208\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
209
210Creates the text control for two-step construction. Derived classes
211should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
212for further details.
213
214\membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
215
216\func{virtual void}{Cut}{\void}
217
218Copies the selected text to the clipboard and removes the selection.
219
220\membersection{wxTextCtrl::DiscardEdits}
221
222\func{void}{DiscardEdits}{\void}
223
224Resets the internal `modified' flag as if the current edits had been saved.
225
226\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
227
228\constfunc{virtual long}{GetInsertionPoint}{\void}
229
230Returns the insertion point. This is defined as the zero based index of the
231character position to the right of the insertion point. For example, if
232the insertion point is at the end of the text control, it is equal to
233both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
234\helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
235
236The following code snippet safely returns the character at the insertion
237point or the zero character if the point is at the end of the control.
238
239{\small%
240\begin{verbatim}
241 char GetCurrentChar(wxTextCtrl *tc) {
242 if (tc->GetInsertionPoint() == tc->GetLastPosition())
243 return '\0';
244 return tc->GetValue[tc->GetInsertionPoint()];
245 }
246\end{verbatim}
247}%
248
249\membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
250
251\constfunc{virtual long}{GetLastPosition}{\void}
252
253Returns the zero based index of the last position in the text control,
254which is equal to the number of characters in the control.
255
256\membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
257
258\constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
259
260Gets the length of the specified line, not including any trailing newline
261character(s).
262
263\wxheading{Parameters}
264
265\docparam{lineNo}{Line number (starting from zero).}
266
267\wxheading{Return value}
268
269The length of the line, or -1 if {\it lineNo} was invalid.
270
271\membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
272
273\constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
274
275Returns the contents of a given line in the text control, not including
276any trailing newline character(s).
277
278\wxheading{Parameters}
279
280\docparam{lineNo}{The line number, starting from zero.}
281
282\wxheading{Return value}
283
284The contents of the line.
285
286\membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
287
288\constfunc{int}{GetNumberOfLines}{\void}
289
290Returns the number of lines in the text control buffer.
291
292\wxheading{Remarks}
293
294Note that even empty text controls have one line (where the insertion point
295is), so GetNumberOfLines() never returns 0.
296
297For gtk\_text (multi-line) controls, the number of lines is
298calculated by actually counting newline characters in the buffer. You
299may wish to avoid using functions that work with line numbers if you are
300working with controls that contain large amounts of text.
301
302\membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
303
304\func{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
305
306Gets the current selection span. If the returned values are equal, there was
307no selection.
308
309\wxheading{Parameters}
310
311\docparam{from}{The returned first position.}
312
313\docparam{to}{The returned last position.}
314
315\pythonnote{The wxPython version of this method returns a tuple
316consisting of the from and to values.}
317
318\membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
319
320\constfunc{wxString}{GetValue}{\void}
321
322Gets the contents of the control.
323
324\membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
325
326\constfunc{bool}{IsModified}{\void}
327
328Returns TRUE if the text has been modified.
329
330\membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
331
332\func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
333
334Loads and displays the named file, if it exists.
335
336\wxheading{Parameters}
337
338\docparam{filename}{The filename of the file to load.}
339
340\wxheading{Return value}
341
342TRUE if successful, FALSE otherwise.
343
344\membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
345
346\func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
347
348Default handler for character input.
349
350\wxheading{Remarks}
351
352It is possible to intercept character
353input by overriding this member. Call this function
354to let the default behaviour take place; not calling
355it results in the character being ignored. You can
356replace the {\it keyCode} member of {\it event} to
357translate keystrokes.
358
359Note that Windows and Motif have different ways
360of implementing the default behaviour. In Windows,
361calling wxTextCtrl::OnChar immediately
362processes the character. In Motif,
363calling this function simply sets a flag
364to let default processing happen. This might affect
365the way in which you write your OnChar function
366on different platforms.
367
368\wxheading{See also}
369
370\helpref{wxKeyEvent}{wxkeyevent}
371
372\membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
373
374\func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
375
376This event handler function implements default drag and drop behaviour, which
377is to load the first dropped file into the control.
378
379\wxheading{Parameters}
380
381\docparam{event}{The drop files event.}
382
383\wxheading{Remarks}
384
385This is not yet implemented for the GTK.
386
387\wxheading{See also}
388
389\helpref{wxDropFilesEvent}{wxdropfilesevent}
390
391\membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
392
393\func{virtual void}{Paste}{\void}
394
395Pastes text from the clipboard to the text item.
396
397\membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
398
399\constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
400
401Converts given position to a zero-based column, line number pair.
402
403\wxheading{Parameters}
404
405\docparam{pos}{Position.}
406
407\docparam{x}{Receives zero based column number.}
408
409\docparam{y}{Receives zero based line number.}
410
411\wxheading{Return value}
412
413TRUE on success, FALSE on failure (most likely due to a too large position
414parameter).
415
416\wxheading{See also}
417
418\helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
419
420\pythonnote{In Python, PositionToXY() returns a tuple containing the x and
421y values, so (x,y) = PositionToXY() is equivalent to the call described
422above.}
423
424\membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
425
426\func{virtual void}{Redo}{\void}
427
428If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
429if there is no redo facility.
430
431\membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
432
433\func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
434
435Removes the text starting at the first given position up to (but not including)
436the character at the last position.
437
438\wxheading{Parameters}
439
440\docparam{from}{The first position.}
441
442\docparam{to}{The last position.}
443
444\membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
445
446\func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
447
448Replaces the text starting at the first position up to (but not including)
449the character at the last position with the given text.
450
451\wxheading{Parameters}
452
453\docparam{from}{The first position.}
454
455\docparam{to}{The last position.}
456
457\docparam{value}{The value to replace the existing text with.}
458
459\membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
460
461\func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
462
463Saves the contents of the control in a text file.
464
465\wxheading{Parameters}
466
467\docparam{filename}{The name of the file in which to save the text.}
468
469\wxheading{Return value}
470
471TRUE if the operation was successful, FALSE otherwise.
472
473\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
474
475\func{virtual void}{SetEditable}{\param{const bool}{ editable}}
476
477Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY}
478flag.
479
480\wxheading{Parameters}
481
482\docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
483
484\membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
485
486\func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
487
488Sets the insertion point at the given position.
489
490\wxheading{Parameters}
491
492\docparam{pos}{Position to set.}
493
494\membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
495
496\func{virtual void}{SetInsertionPointEnd}{\void}
497
498Sets the insertion point at the end of the text control. This is equivalent
499to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
500
501\membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
502
503\func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
504
505Selects the text starting at the first position up to (but not including) the character at the last position.
506
507\wxheading{Parameters}
508
509\docparam{from}{The first position.}
510
511\docparam{to}{The last position.}
512
513\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
514
515\func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
516
517Sets the text value.
518
519\wxheading{Parameters}
520
521\docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
522
523\membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
524
525\func{void}{ShowPosition}{\param{long}{ pos}}
526
527Makes the line containing the given position visible.
528
529\wxheading{Parameters}
530
531\docparam{pos}{The position that should be visible.}
532
533\membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
534
535\func{virtual void}{Undo}{\void}
536
537If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
538if there is no undo facility.
539
540\membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
541
542\func{void}{WriteText}{\param{const wxString\& }{ text}}
543
544Writes the text into the text control at the current insertion position.
545
546\wxheading{Parameters}
547
548\docparam{text}{Text to write to the text control.}
549
550\wxheading{Remarks}
551
552Newlines in the text string
553are the only control characters allowed, and they will cause appropriate
554line breaks. See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
555
556After the write operation, the insertion point will be at the end of the inserted text, so subsequent write operations will be appended. To append text after the user may have interacted with the control, call \helpref{wxTextCtrl::SetInsertionPointEnd}{wxtextctrlsetinsertionpointend} before writing.
557
558\membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
559
560\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
561
562Converts the given zero based column and line number to a position.
563
564\wxheading{Parameters}
565
566\docparam{x}{The column number.}
567
568\docparam{y}{The line number.}
569
570\wxheading{Return value}
571
572The position value.
573
574\membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
575
576\func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
577
578\func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
579
580\func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
581
582\func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
583
584\func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
585
586\func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
587
588Operator definitions for appending to a text control, for example:
589
590\begin{verbatim}
591 wxTextCtrl *wnd = new wxTextCtrl(my_frame);
592
593 (*wnd) << "Welcome to text control number " << 1 << ".\n";
594\end{verbatim}
595