]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/text.tex
Underscore escaping fix from Angel Vidal Veiga
[wxWidgets.git] / docs / latex / wx / text.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextAttr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3\section{\class{wxTextAttr}}\label{wxtextattr}
4
5wxTextAttr represents the character and paragraph attributes, or style, for a range of text in a\rtfsp
6\helpref{wxTextCtrl}{wxtextctrl}.
7
8When setting up a wxTextAttr object, pass a bitlist mask to SetFlags to indicate
9which style elements should be changed. As a convenience, when you call a
10setter such as SetFont, the relevant bit will be set.
11
12\wxheading{Derived from}
13
14No base class
15
16\wxheading{Include files}
17
18<wx/textctrl.h>
19
20\wxheading{Typedefs}
21
22\texttt{wxTextPos} is the type containing the index of a position in a text
23control. \texttt{wxTextCoord} contains the index of a column or a row in the
24control.
25
26Note that although both of these types should probably have been unsigned, due
27to backwards compatibility reasons, are defined as \texttt{long} currently.
28Their use (instead of plain \texttt{long}) is still encouraged as it makes the
29code more readable.
30
31\wxheading{Constants}
32
33The following values can be passed to SetAlignment to determine
34paragraph alignment.
35
36{\small
37\begin{verbatim}
38enum wxTextAttrAlignment
39{
40 wxTEXT_ALIGNMENT_DEFAULT,
41 wxTEXT_ALIGNMENT_LEFT,
42 wxTEXT_ALIGNMENT_CENTRE,
43 wxTEXT_ALIGNMENT_CENTER = wxTEXT_ALIGNMENT_CENTRE,
44 wxTEXT_ALIGNMENT_RIGHT,
45 wxTEXT_ALIGNMENT_JUSTIFIED
46};
47\end{verbatim}
48}
49
50These values are passed in a bitlist to SetFlags to determine
51what attributes will be considered when setting the attributes
52for a text control.
53
54{\small
55\begin{verbatim}
56#define wxTEXT_ATTR_TEXT_COLOUR 0x0001
57#define wxTEXT_ATTR_BACKGROUND_COLOUR 0x0002
58#define wxTEXT_ATTR_FONT_FACE 0x0004
59#define wxTEXT_ATTR_FONT_SIZE 0x0008
60#define wxTEXT_ATTR_FONT_WEIGHT 0x0010
61#define wxTEXT_ATTR_FONT_ITALIC 0x0020
62#define wxTEXT_ATTR_FONT_UNDERLINE 0x0040
63#define wxTEXT_ATTR_FONT \
64 wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT \
65| wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE
66#define wxTEXT_ATTR_ALIGNMENT 0x0080
67#define wxTEXT_ATTR_LEFT_INDENT 0x0100
68#define wxTEXT_ATTR_RIGHT_INDENT 0x0200
69#define wxTEXT_ATTR_TABS 0x0400
70\end{verbatim}
71}
72
73The values below are the possible return codes of the
74\helpref{HitTest}{wxtextctrlhittest} method:
75{\small
76\begin{verbatim}
77// the point asked is ...
78enum wxTextCtrlHitTestResult
79{
80 wxTE_HT_UNKNOWN = -2, // this means HitTest() is simply not implemented
81 wxTE_HT_BEFORE, // either to the left or upper
82 wxTE_HT_ON_TEXT, // directly on
83 wxTE_HT_BELOW, // below [the last line]
84 wxTE_HT_BEYOND // after [the end of line]
85};
86// ... the character returned
87\end{verbatim}
88}
89
90
91\latexignore{\rtfignore{\wxheading{Members}}}
92
93
94\membersection{wxTextAttr::wxTextAttr}\label{wxtextattrctor}
95
96\func{}{wxTextAttr}{\void}
97
98\func{}{wxTextAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour},
99 \param{const wxFont\& }{font = wxNullFont}, \param{wxTextAttrAlignment }{alignment = wxTEXT\_ALIGNMENT\_DEFAULT}}
100
101The constructors initialize one or more of the text foreground colour, background
102colour, font, and alignment. The values not initialized in the constructor can be set
103later, otherwise \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle} will use
104the default values for them.
105
106
107\membersection{wxTextAttr::GetAlignment}\label{wxtextattrgetalignment}
108
109\constfunc{wxTextAttrAlignment}{GetAlignment}{\void}
110
111Returns the paragraph alignment.
112
113
114\membersection{wxTextAttr::GetBackgroundColour}\label{wxtextattrgetbackgroundcolour}
115
116\constfunc{const wxColour\&}{GetBackgroundColour}{\void}
117
118Return the background colour specified by this attribute.
119
120
121\membersection{wxTextAttr::GetFont}\label{wxtextattrgetfont}
122
123\constfunc{const wxFont\&}{GetFont}{\void}
124
125Return the text font specified by this attribute.
126
127
128\membersection{wxTextAttr::GetLeftIndent}\label{wxtextattrgetleftindent}
129
130\constfunc{int}{GetLeftIndent}{\void}
131
132Returns the left indent in tenths of a millimetre.
133
134
135\membersection{wxTextAttr::GetLeftSubIndent}\label{wxtextattrgetleftsubindent}
136
137\constfunc{int}{GetLeftSubIndent}{\void}
138
139Returns the left sub indent for all lines but the first line in a paragraph in
140tenths of a millimetre.
141
142
143\membersection{wxTextAttr::GetRightIndent}\label{wxtextattrgetrightindent}
144
145\constfunc{int}{GetRightIndent}{\void}
146
147Returns the right indent in tenths of a millimetre.
148
149
150\membersection{wxTextAttr::GetTabs}\label{wxtextattrgettabs}
151
152\constfunc{const wxArrayInt\&}{GetTabs}{\void}
153
154Returns the array of integers representing the tab stops. Each
155array element specifies the tab stop in tenths of a millimetre.
156
157
158\membersection{wxTextAttr::GetTextColour}\label{wxtextattrgettextcolour}
159
160\constfunc{const wxColour\&}{GetTextColour}{\void}
161
162Return the text colour specified by this attribute.
163
164
165\membersection{wxTextAttr::HasBackgroundColour}\label{wxtextattrhasbackgroundcolour}
166
167\constfunc{bool}{HasBackgroundColour}{\void}
168
169Returns {\tt true} if this style specifies the background colour to use.
170
171
172\membersection{wxTextAttr::HasFont}\label{wxtextattrhasfont}
173
174\constfunc{bool}{HasFont}{\void}
175
176Returns {\tt true} if this style specifies the font to use.
177
178
179\membersection{wxTextAttr::HasTextColour}\label{wxtextattrhastextcolour}
180
181\constfunc{bool}{HasTextColour}{\void}
182
183Returns {\tt true} if this style specifies the foreground colour to use.
184
185
186\membersection{wxTextAttr::GetFlags}\label{wxtextattrgetflags}
187
188\func{long}{GetFlags}{\void}
189
190Returns a bitlist indicating which attributes will be set.
191
192
193\membersection{wxTextAttr::IsDefault}\label{wxtextattrisdefault}
194
195\constfunc{bool}{IsDefault}{\void}
196
197Returns {\tt true} if this style specifies any non-default attributes.
198
199
200\membersection{wxTextAttr::Merge}\label{wxtextattrmerge}
201
202\func{void}{Merge}{\param{const wxTextAttr\&}{ overlay}}
203
204Copies all defined/valid properties from \arg{overlay} to current object.
205
206\func{static wxTextAttr}{Merge}{\param{const wxTextAttr\&}{ base}, \param{const wxTextAttr\&}{ overlay}}
207
208Creates a new {\tt wxTextAttr} which is a merge of \arg{base} and
209\arg{overlay}. Properties defined in \arg{overlay} take precedence over those
210in \arg{base}. Properties undefined/invalid in both are undefined in the
211result.
212
213
214\membersection{wxTextAttr::SetAlignment}\label{wxtextattrsetalignment}
215
216\func{void}{SetAlignment}{\param{wxTextAttrAlignment}{ alignment}}
217
218Sets the paragraph alignment.
219
220
221\membersection{wxTextAttr::SetBackgroundColour}\label{wxtextattrsetbackgroundcolour}
222
223\func{void}{SetBackgroundColour}{\param{const wxColour\& }{colour}}
224
225Sets the background colour.
226
227
228\membersection{wxTextAttr::SetFlags}\label{wxtextattrsetflags}
229
230\func{void}{SetFlags}{\param{long}{ flags}}
231
232Pass a bitlist indicating which attributes will be set.
233
234
235\membersection{wxTextAttr::SetFont}\label{wxtextattrsetfont}
236
237\func{void}{SetFont}{\param{const wxFont\&}{ font}}
238
239Sets the text font.
240
241
242\membersection{wxTextAttr::SetLeftIndent}\label{wxtextattrsetleftindent}
243
244\func{void}{SetLeftIndent}{\param{int }{indent}, \param{int }{subIndent = 0}}
245
246Sets the left indent in tenths of a millimetre.
247subIndent sets the indent for all lines but the first line in a paragraph
248relative to the first line.
249
250
251\membersection{wxTextAttr::SetRightIndent}\label{wxtextattrsetrightindent}
252
253\func{void}{SetRightIndent}{\param{int }{indent}}
254
255Sets the right indent in tenths of a millimetre.
256
257
258\membersection{wxTextAttr::SetTabs}\label{wxtextattrsettabs}
259
260\func{void}{SetTabs}{\param{const wxArrayInt\&}{ tabs}}
261
262Sets the array of integers representing the tab stops. Each
263array element specifies the tab stop in tenths of a millimetre.
264
265
266\membersection{wxTextAttr::SetTextColour}\label{wxtextattrsettextcolour}
267
268\func{void}{SetTextColour}{\param{const wxColour\& }{colour}}
269
270Sets the text colour.
271
272
273%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
274
275\section{\class{wxTextCtrl}}\label{wxtextctrl}
276
277A text control allows text to be displayed and edited. It may be
278single line or multi-line.
279
280\wxheading{Derived from}
281
282streambuf\\
283\helpref{wxControl}{wxcontrol}\\
284\helpref{wxWindow}{wxwindow}\\
285\helpref{wxEvtHandler}{wxevthandler}\\
286\helpref{wxObject}{wxobject}
287
288\wxheading{Include files}
289
290<wx/textctrl.h>
291
292\wxheading{Window styles}
293
294\twocolwidtha{5cm}
295\begin{twocollist}\itemsep=0pt
296\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
297the event wxEVT\_COMMAND\_TEXT\_ENTER (otherwise pressing Enter key
298is either processed internally by the control or used for navigation between
299dialog controls).}
300\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receive
301wxEVT\_CHAR events for TAB pressed - normally, TAB is used for passing to the
302next control in a dialog instead. For the control created with this style,
303you can still use Ctrl-Enter to pass to the next control from the keyboard.}
304\twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
305\twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
306\twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
307\twocolitem{\windowstyle{wxTE\_RICH}}{Use rich text control under Win32, this
308allows to have more than 64KB of text in the control even under Win9x. This
309style is ignored under other platforms.}
310\twocolitem{\windowstyle{wxTE\_RICH2}}{Use rich text control version 2.0 or 3.0
311under Win32, this style is ignored under other platforms}
312\twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the
313wxTextUrlEvents when mouse events occur over them. This style is only supported
314for wxTE\_RICH Win32 and multi-line wxGTK2 text controls.}
315\twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control
316doesn't show the selection when it doesn't have focus - use this style to force
317it to always show it. It doesn't do anything under other platforms.}
318\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created and
319used, so that text won't be wrapped. No effect under wxGTK1.}
320\twocolitem{\windowstyle{wxTE\_LEFT}}{The text in the control will be left-justified (default).}
321\twocolitem{\windowstyle{wxTE\_CENTRE}}{The text in the control will be centered (currently wxMSW and wxGTK2 only).}
322\twocolitem{\windowstyle{wxTE\_RIGHT}}{The text in the control will be right-justified (currently wxMSW and wxGTK2 only).}
323\twocolitem{\windowstyle{wxTE\_DONTWRAP}}{Same as {\tt wxHSCROLL} style: don't wrap at all, show horizontal scrollbar instead.}
324\twocolitem{\windowstyle{wxTE\_CHARWRAP}}{Wrap the lines too long to be shown entirely at any position (wxUniv and wxGTK2 only).}
325\twocolitem{\windowstyle{wxTE\_WORDWRAP}}{Wrap the lines too long to be shown entirely at word boundaries (wxUniv and wxGTK2 only).}
326\twocolitem{\windowstyle{wxTE\_BESTWRAP}}{Wrap the lines at word boundaries or at any other character if there are words longer than the window width (this is the default).}
327\twocolitem{\windowstyle{wxTE\_CAPITALIZE}}{On PocketPC and Smartphone, causes the first letter to be capitalized.}
328\end{twocollist}
329
330See also \helpref{window styles overview}{windowstyles} and \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}.
331
332\wxheading{wxTextCtrl text format}
333
334The multiline text controls always store the text as a sequence of lines
335separated by {\tt $\backslash$n} characters, i.e. in the Unix text format even
336on non-Unix platforms. This allows the user code to ignore the differences
337between the platforms but at a price: the indices in the control such as those
338returned by \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} or
339\helpref{GetSelection}{wxtextctrlgetselection} can {\bf not} be used as
340indices into the string returned by \helpref{GetValue}{wxtextctrlgetvalue} as
341they're going to be slightly off for platforms using
342{\tt $\backslash$r$\backslash$n} as separator (as Windows does), for example.
343
344Instead, if you need to obtain a substring between the $2$ indices obtained
345from the control with the help of the functions mentioned above, you should
346use \helpref{GetRange}{wxtextctrlgetrange}. And the indices themselves can
347only be passed to other methods, for example
348\helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint} or
349\helpref{SetSelection}{wxtextctrlsetselection}.
350
351To summarize: never use the indices returned by (multiline) wxTextCtrl as
352indices into the string it contains, but only as arguments to be passed back
353to the other wxTextCtrl methods.
354
355\wxheading{wxTextCtrl styles}
356
357Multi-line text controls support the styles, i.e. provide a possibility to set
358colours and font for individual characters in it (note that under Windows {\tt
359wxTE\_RICH} style is required for style support). To use the styles you can
360either call \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} before
361inserting the text or call \helpref{SetStyle}{wxtextctrlsetstyle} later to
362change the style of the text already in the control (the first solution is
363much more efficient).
364
365In either case, if the style doesn't specify some of the attributes (for
366example you only want to set the text colour but without changing the font nor
367the text background), the values of the default style will be used for them.
368If there is no default style, the attributes of the text control itself are
369used.
370
371So the following code correctly describes what it does: the second call
372to \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} doesn't change the
373text foreground colour (which stays red) while the last one doesn't change the
374background colour (which stays grey):
375
376{\small%
377\begin{verbatim}
378 text->SetDefaultStyle(wxTextAttr(*wxRED));
379 text->AppendText("Red text\n");
380 text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
381 text->AppendText("Red on grey text\n");
382 text->SetDefaultStyle(wxTextAttr(*wxBLUE);
383 text->AppendText("Blue on grey text\n");
384\end{verbatim}
385}%
386
387\wxheading{wxTextCtrl and C++ streams}
388
389This class multiply-inherits from {\bf streambuf} where compilers allow,
390allowing code such as the following:
391
392{\small%
393\begin{verbatim}
394 wxTextCtrl *control = new wxTextCtrl(...);
395
396 ostream stream(control)
397
398 stream << 123.456 << " some text\n";
399 stream.flush();
400\end{verbatim}
401}%
402
403If your compiler does not support derivation from {\bf streambuf} and gives a
404compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
405wxTextCtrl header file.
406
407Note that independently of this setting you can always use wxTextCtrl itself
408in a stream-like manner:
409
410{\small%
411\begin{verbatim}
412 wxTextCtrl *control = new wxTextCtrl(...);
413
414 *control << 123.456 << " some text\n";
415\end{verbatim}
416}%
417
418always works. However the possibility to create an ostream associated with
419wxTextCtrl may be useful if you need to redirect the output of a function
420taking an ostream as parameter to a text control.
421
422Another commonly requested need is to redirect {\bf std::cout} to the text
423control. This could be done in the following way:
424
425{\small%
426\begin{verbatim}
427 #include <iostream>
428
429 wxTextCtrl *control = new wxTextCtrl(...);
430
431 std::streambuf *sbOld = std::cout.rdbuf();
432 std::cout.rdbuf(*control);
433
434 // use cout as usual, the output appears in the text control
435 ...
436
437 std::cout.rdbuf(sbOld);
438\end{verbatim}
439}%
440
441But wxWidgets provides a convenient class to make it even simpler so instead
442you may just do
443
444{\small%
445\begin{verbatim}
446 #include <iostream>
447
448 wxTextCtrl *control = new wxTextCtrl(...);
449
450 wxStreamToTextRedirector redirect(control);
451
452 // all output to cout goes into the text control until the exit from current
453 // scope
454\end{verbatim}
455}%
456
457See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
458details.
459
460\wxheading{Event handling}
461
462The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
463wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
464automatically, when the control has the focus.
465
466To process input from a text control, use these event handler macros to direct input to member
467functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
468
469\twocolwidtha{7cm}%
470\begin{twocollist}\itemsep=0pt
471\twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
472generated when the text changes. Notice that this event will always be sent
473when the text controls contents changes - whether this is due to user input or
474comes from the program itself (for example, if SetValue() is called)}
475\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
476generated when enter is pressed in a text control (which must have
477wxTE\_PROCESS\_ENTER style for this event to be generated).}
478\twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occurred over an URL
479in the text control (wxMSW and wxGTK2 only)}
480\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text
481into the control than the limit set by
482\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
483\end{twocollist}%
484
485\latexignore{\rtfignore{\wxheading{Members}}}
486
487
488\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlctor}
489
490\func{}{wxTextCtrl}{\void}
491
492Default constructor.
493
494\func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
495\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
496\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}}
497
498Constructor, creating and showing a text control.
499
500\wxheading{Parameters}
501
502\docparam{parent}{Parent window. Should not be NULL.}
503
504\docparam{id}{Control identifier. A value of -1 denotes a default value.}
505
506\docparam{value}{Default text value.}
507
508\docparam{pos}{Text control position.}
509
510\docparam{size}{Text control size.}
511
512\docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
513
514\docparam{validator}{Window validator.}
515
516\docparam{name}{Window name.}
517
518\wxheading{Remarks}
519
520The horizontal scrollbar ({\bf wxHSCROLL} style flag) will only be created
521for multi-line text controls.
522Without a horizontal scrollbar, text lines that don't fit in the control's
523size will be wrapped (but no newline character is inserted). Single line
524controls don't have a horizontal scrollbar, the text is automatically scrolled
525so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
526visible.
527
528% VZ: this is no longer true
529%Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
530%as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
531%apply.
532
533\wxheading{See also}
534
535\helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
536
537
538\membersection{wxTextCtrl::\destruct{wxTextCtrl}}\label{wxtextctrldtor}
539
540\func{}{\destruct{wxTextCtrl}}{\void}
541
542Destructor, destroying the text control.
543
544
545\membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
546
547\func{void}{AppendText}{\param{const wxString\& }{ text}}
548
549Appends the text to the end of the text control.
550
551\wxheading{Parameters}
552
553\docparam{text}{Text to write to the text control.}
554
555\wxheading{Remarks}
556
557After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
558the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
559
560\wxheading{See also}
561
562\helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
563
564
565\membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
566
567\func{virtual bool}{CanCopy}{\void}
568
569Returns {\tt true} if the selection can be copied to the clipboard.
570
571
572\membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
573
574\func{virtual bool}{CanCut}{\void}
575
576Returns {\tt true} if the selection can be cut to the clipboard.
577
578
579\membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
580
581\func{virtual bool}{CanPaste}{\void}
582
583Returns {\tt true} if the contents of the clipboard can be pasted into the
584text control. On some platforms (Motif, GTK) this is an approximation
585and returns {\tt true} if the control is editable, {\tt false} otherwise.
586
587
588\membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
589
590\func{virtual bool}{CanRedo}{\void}
591
592Returns {\tt true} if there is a redo facility available and the last operation
593can be redone.
594
595
596\membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
597
598\func{virtual bool}{CanUndo}{\void}
599
600Returns {\tt true} if there is an undo facility available and the last operation
601can be undone.
602
603
604\membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
605
606\func{virtual void}{Clear}{\void}
607
608Clears the text in the control.
609
610Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
611event.
612
613
614\membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
615
616\func{virtual void}{Copy}{\void}
617
618Copies the selected text to the clipboard under Motif and MS Windows.
619
620
621\membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
622
623\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
624\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos = wxDefaultPosition}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
625\param{long}{ style = 0}, \param{const wxValidator\& }{validator = wxDefaultValidator}, \param{const wxString\& }{name = wxTextCtrlNameStr}}
626
627Creates the text control for two-step construction. Derived classes
628should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlctor}\rtfsp
629for further details.
630
631
632\membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
633
634\func{virtual void}{Cut}{\void}
635
636Copies the selected text to the clipboard and removes the selection.
637
638
639\membersection{wxTextCtrl::DiscardEdits}\label{wxtextctrldiscardedits}
640
641\func{void}{DiscardEdits}{\void}
642
643Resets the internal `modified' flag as if the current edits had been saved.
644
645
646\membersection{wxTextCtrl::EmulateKeyPress}\label{wxtextctrlemulatekeypress}
647
648\func{bool}{EmulateKeyPress}{\param{const wxKeyEvent\& }{event}}
649
650This functions inserts into the control the character which would have been
651inserted if the given key event had occurred in the text control. The
652{\it event} object should be the same as the one passed to {\tt EVT\_KEY\_DOWN}
653handler previously by wxWidgets.
654
655Please note that this function doesn't currently work correctly for all keys
656under any platform but MSW.
657
658\wxheading{Return value}
659
660{\tt true} if the event resulted in a change to the control, {\tt false}
661otherwise.
662
663
664\membersection{wxTextCtrl::GetDefaultStyle}\label{wxtextctrlgetdefaultstyle}
665
666\constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
667
668Returns the style currently used for the new text.
669
670\wxheading{See also}
671
672\helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle}
673
674
675\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
676
677\constfunc{virtual long}{GetInsertionPoint}{\void}
678
679Returns the insertion point. This is defined as the zero based index of the
680character position to the right of the insertion point. For example, if
681the insertion point is at the end of the text control, it is equal to
682both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
683\helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
684
685The following code snippet safely returns the character at the insertion
686point or the zero character if the point is at the end of the control.
687
688{\small%
689\begin{verbatim}
690 char GetCurrentChar(wxTextCtrl *tc) {
691 if (tc->GetInsertionPoint() == tc->GetLastPosition())
692 return '\0';
693 return tc->GetValue[tc->GetInsertionPoint()];
694 }
695\end{verbatim}
696}%
697
698
699\membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
700
701\constfunc{virtual wxTextPos}{GetLastPosition}{\void}
702
703Returns the zero based index of the last position in the text control,
704which is equal to the number of characters in the control.
705
706
707\membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
708
709\constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
710
711Gets the length of the specified line, not including any trailing newline
712character(s).
713
714\wxheading{Parameters}
715
716\docparam{lineNo}{Line number (starting from zero).}
717
718\wxheading{Return value}
719
720The length of the line, or -1 if {\it lineNo} was invalid.
721
722
723\membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
724
725\constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
726
727Returns the contents of a given line in the text control, not including
728any trailing newline character(s).
729
730\wxheading{Parameters}
731
732\docparam{lineNo}{The line number, starting from zero.}
733
734\wxheading{Return value}
735
736The contents of the line.
737
738
739\membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
740
741\constfunc{int}{GetNumberOfLines}{\void}
742
743Returns the number of lines in the text control buffer.
744
745\wxheading{Remarks}
746
747Note that even empty text controls have one line (where the insertion point
748is), so GetNumberOfLines() never returns $0$.
749
750For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a multi-line
751text control is calculated by actually counting newline characters in the
752buffer, i.e. this function returns the number of logical lines and doesn't
753depend on whether any of them are wrapped. For all the other platforms, the
754number of physical lines in the control is returned.
755
756Also note that you may wish to avoid using functions that work with line
757numbers if you are working with controls that contain large amounts of text as
758this function has $O(N)$ complexity for $N$ being the number of lines.
759
760
761\membersection{wxTextCtrl::GetRange}\label{wxtextctrlgetrange}
762
763\constfunc{virtual wxString}{GetRange}{\param{long}{ from}, \param{long}{ to}}
764
765Returns the string containing the text starting in the positions {\it from} and
766up to {\it to} in the control. The positions must have been returned by another
767wxTextCtrl method.
768
769Please note that the positions in a multiline wxTextCtrl do {\bf not}
770correspond to the indices in the string returned by
771\helpref{GetValue}{wxtextctrlgetvalue} because of the different new line
772representations ({\tt CR} or {\tt CR LF}) and so this method should be used to
773obtain the correct results instead of extracting parts of the entire value. It
774may also be more efficient, especially if the control contains a lot of data.
775
776
777\membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
778
779\constfunc{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
780
781Gets the current selection span. If the returned values are equal, there was
782no selection.
783
784Please note that the indices returned may be used with the other wxTextctrl
785methods but don't necessarily represent the correct indices into the string
786returned by \helpref{GetValue()}{wxtextctrlgetvalue} for multiline controls
787under Windows (at least,) you should use
788\helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
789text.
790
791\wxheading{Parameters}
792
793\docparam{from}{The returned first position.}
794
795\docparam{to}{The returned last position.}
796
797\pythonnote{The wxPython version of this method returns a tuple
798consisting of the from and to values.}
799
800\perlnote{In wxPerl this method takes no parameter and returns a
8012-element list {\tt ( from, to )}.}
802
803
804\membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
805
806\func{virtual wxString}{GetStringSelection}{\void}
807
808Gets the text currently selected in the control. If there is no selection, the
809returned string is empty.
810
811
812\membersection{wxTextCtrl::GetStyle}\label{wxtextctrlgetstyle}
813
814\func{bool}{GetStyle}{\param{long }{position}, \param{wxTextAttr\& }{style}}
815
816Returns the style at this position in the text control. Not all platforms
817support this function.
818
819\wxheading{Return value}
820
821{\tt true} on success, {\tt false} if an error occurred - it may also mean that
822the styles are not supported under this platform.
823
824\wxheading{See also}
825
826\helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle}, \helpref{wxTextAttr}{wxtextattr}
827
828
829\membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
830
831\constfunc{wxString}{GetValue}{\void}
832
833Gets the contents of the control. Notice that for a multiline text control,
834the lines will be separated by (Unix-style) $\backslash$n characters, even
835under Windows where they are separated by a $\backslash$r$\backslash$n
836sequence in the native control.
837
838
839\membersection{wxTextCtrl::HitTest}\label{wxtextctrlhittest}
840
841\constfunc{wxTextCtrlHitTestResult}{HitTest}{\param{const wxPoint\& }{pt}, \param{wxTextCoord }{*col}, \param{wxTextCoord }{*row}}
842
843This function finds the character at the specified position expressed in
844pixels. If the return code is not \texttt{wxTE\_HT\_UNKNOWN} the row and column
845of the character closest to this position are returned in the \arg{col} and
846\arg{row} parameters (unless the pointers are {\tt NULL} which is allowed).
847
848Please note that this function is currently only implemented in wxUniv,
849wxMSW and wxGTK2 ports.
850
851\wxheading{See also}
852
853\helpref{PositionToXY}{wxtextctrlpositiontoxy}, \helpref{XYToPosition}{wxtextctrlxytoposition}
854
855\perlnote{In wxPerl this function takes only the position argument and
856returns a 3-element list \texttt{(result, col, row)}}.
857
858\membersection{wxTextCtrl::IsEditable}\label{wxtextctrliseditable}
859
860\constfunc{bool}{IsEditable}{\void}
861
862Returns {\tt true} if the controls contents may be edited by user (note that it
863always can be changed by the program), i.e. if the control hasn't been put in
864read-only mode by a previous call to
865\helpref{SetEditable}{wxtextctrlseteditable}.
866
867
868\membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
869
870\constfunc{bool}{IsModified}{\void}
871
872Returns {\tt true} if the text has been modified by user. Note that calling
873\helpref{SetValue}{wxtextctrlsetvalue} doesn't make the control modified.
874
875\wxheading{See also}
876
877\helpref{MarkDirty}{wxtextctrlmarkdirty}
878
879
880\membersection{wxTextCtrl::IsMultiLine}\label{wxtextctrlismultiline}
881
882\constfunc{bool}{IsMultiLine}{\void}
883
884Returns {\tt true} if this is a multi line edit control and {\tt false}
885otherwise.
886
887\wxheading{See also}
888
889\helpref{IsSingleLine}{wxtextctrlissingleline}
890
891
892\membersection{wxTextCtrl::IsSingleLine}\label{wxtextctrlissingleline}
893
894\constfunc{bool}{IsSingleLine}{\void}
895
896Returns {\tt true} if this is a single line edit control and {\tt false}
897otherwise.
898
899\wxheading{See also}
900
901\helpref{IsMultiLine}{wxtextctrlissingleline}
902
903
904\membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
905
906\func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
907
908Loads and displays the named file, if it exists.
909
910\wxheading{Parameters}
911
912\docparam{filename}{The filename of the file to load.}
913
914\wxheading{Return value}
915
916{\tt true} if successful, {\tt false} otherwise.
917
918% VZ: commenting this out as: (a) the docs are wrong (you can't replace
919% anything), (b) wxTextCtrl doesn't have any OnChar() anyhow
920%% \membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
921%%
922%% \func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
923%%
924%% Default handler for character input.
925%%
926%% \wxheading{Remarks}
927%%
928%% It is possible to intercept character
929%% input by overriding this member. Call this function
930%% to let the default behaviour take place; not calling
931%% it results in the character being ignored. You can
932%% replace the {\it keyCode} member of {\it event} to
933%% translate keystrokes.
934%%
935%% Note that Windows and Motif have different ways
936%% of implementing the default behaviour. In Windows,
937%% calling wxTextCtrl::OnChar immediately
938%% processes the character. In Motif,
939%% calling this function simply sets a flag
940%% to let default processing happen. This might affect
941%% the way in which you write your OnChar function
942%% on different platforms.
943%%
944%% \wxheading{See also}
945%%
946%% \helpref{wxKeyEvent}{wxkeyevent}
947
948
949\membersection{wxTextCtrl::MarkDirty}\label{wxtextctrlmarkdirty}
950
951\func{void}{MarkDirty}{\void}
952
953Mark text as modified (dirty).
954
955\wxheading{See also}
956
957\helpref{IsModified}{wxtextctrlismodified}
958
959
960\membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
961
962\func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
963
964This event handler function implements default drag and drop behaviour, which
965is to load the first dropped file into the control.
966
967\wxheading{Parameters}
968
969\docparam{event}{The drop files event.}
970
971\wxheading{Remarks}
972
973This is not implemented on non-Windows platforms.
974
975\wxheading{See also}
976
977\helpref{wxDropFilesEvent}{wxdropfilesevent}
978
979
980\membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
981
982\func{virtual void}{Paste}{\void}
983
984Pastes text from the clipboard to the text item.
985
986
987\membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
988
989\constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
990
991Converts given position to a zero-based column, line number pair.
992
993\wxheading{Parameters}
994
995\docparam{pos}{Position.}
996
997\docparam{x}{Receives zero based column number.}
998
999\docparam{y}{Receives zero based line number.}
1000
1001\wxheading{Return value}
1002
1003{\tt true} on success, {\tt false} on failure (most likely due to a too large position
1004parameter).
1005
1006\wxheading{See also}
1007
1008\helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
1009
1010\pythonnote{In Python, PositionToXY() returns a tuple containing the x and
1011y values, so (x,y) = PositionToXY() is equivalent to the call described
1012above.}
1013
1014\perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
1015returns a 2-element list {\tt ( x, y )}.}
1016
1017
1018\membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
1019
1020\func{virtual void}{Redo}{\void}
1021
1022If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
1023if there is no redo facility.
1024
1025
1026\membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
1027
1028\func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
1029
1030Removes the text starting at the first given position up to (but not including)
1031the character at the last position.
1032
1033\wxheading{Parameters}
1034
1035\docparam{from}{The first position.}
1036
1037\docparam{to}{The last position.}
1038
1039
1040\membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
1041
1042\func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
1043
1044Replaces the text starting at the first position up to (but not including)
1045the character at the last position with the given text.
1046
1047\wxheading{Parameters}
1048
1049\docparam{from}{The first position.}
1050
1051\docparam{to}{The last position.}
1052
1053\docparam{value}{The value to replace the existing text with.}
1054
1055
1056\membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
1057
1058\func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
1059
1060Saves the contents of the control in a text file.
1061
1062\wxheading{Parameters}
1063
1064\docparam{filename}{The name of the file in which to save the text.}
1065
1066\wxheading{Return value}
1067
1068{\tt true} if the operation was successful, {\tt false} otherwise.
1069
1070
1071\membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
1072
1073\func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
1074
1075Changes the default style to use for the new text which is going to be added
1076to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
1077\helpref{AppendText}{wxtextctrlappendtext}.
1078
1079If either of the font, foreground, or background colour is not set in\rtfsp
1080{\it style}, the values of the previous default style are used for them. If
1081the previous default style didn't set them neither, the global font or colours
1082of the text control itself are used as fall back.
1083
1084However if the {\it style} parameter is the default wxTextAttr, then the
1085default style is just reset (instead of being combined with the new style which
1086wouldn't change it at all).
1087
1088\wxheading{Parameters}
1089
1090\docparam{style}{The style for the new text.}
1091
1092\wxheading{Return value}
1093
1094{\tt true} on success, {\tt false} if an error occurred - may also mean that
1095the styles are not supported under this platform.
1096
1097\wxheading{See also}
1098
1099\helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
1100
1101
1102\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
1103
1104\func{virtual void}{SetEditable}{\param{const bool}{ editable}}
1105
1106Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
1107
1108\wxheading{Parameters}
1109
1110\docparam{editable}{If {\tt true}, the control is editable. If {\tt false}, the control is read-only.}
1111
1112\wxheading{See also}
1113
1114\helpref{IsEditable}{wxtextctrliseditable}
1115
1116
1117\membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
1118
1119\func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
1120
1121Sets the insertion point at the given position.
1122
1123\wxheading{Parameters}
1124
1125\docparam{pos}{Position to set.}
1126
1127
1128\membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
1129
1130\func{virtual void}{SetInsertionPointEnd}{\void}
1131
1132Sets the insertion point at the end of the text control. This is equivalent
1133to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
1134
1135
1136\membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
1137
1138\func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
1139
1140This function sets the maximum number of characters the user can enter into the
1141control. In other words, it allows to limit the text value length to {\it len}
1142not counting the terminating {\tt NUL} character.
1143
1144If {\it len} is $0$, the previously set max length limit, if any, is discarded
1145and the user may enter as much text as the underlying native text control
1146widget supports (typically at least 32Kb).
1147
1148If the user tries to enter more characters into the text control when it
1149already is filled up to the maximal length, a
1150{\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
1151(giving it the possibility to show an explanatory message, for example) and the
1152extra input is discarded.
1153
1154Note that under GTK+, this function may only be used with single line text controls.
1155
1156\wxheading{Compatibility}
1157
1158Only implemented in wxMSW/wxGTK starting with wxWidgets 2.3.2.
1159
1160
1161\membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
1162
1163\func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
1164
1165Selects the text starting at the first position up to (but not including) the
1166character at the last position. If both parameters are equal to $-1$ all text
1167in the control is selected.
1168
1169\wxheading{Parameters}
1170
1171\docparam{from}{The first position.}
1172
1173\docparam{to}{The last position.}
1174
1175
1176\membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
1177
1178\func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
1179
1180Changes the style of the given range. If any attribute within {\it style} is
1181not set, the corresponding attribute from \helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} is used.
1182
1183\wxheading{Parameters}
1184
1185\docparam{start}{The start of the range to change.}
1186
1187\docparam{end}{The end of the range to change.}
1188
1189\docparam{style}{The new style for the range.}
1190
1191\wxheading{Return value}
1192
1193{\tt true} on success, {\tt false} if an error occurred - it may also mean that
1194the styles are not supported under this platform.
1195
1196\wxheading{See also}
1197
1198\helpref{wxTextCtrl::GetStyle}{wxtextctrlgetstyle}, \helpref{wxTextAttr}{wxtextattr}
1199
1200
1201\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
1202
1203\func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
1204
1205Sets the text value and marks the control as not-modified (which means that
1206\helpref{IsModified}{wxtextctrlismodified} would return {\tt false} immediately
1207after the call to SetValue).
1208
1209Note that this function will generate a {\tt wxEVT\_COMMAND\_TEXT\_UPDATED}
1210event.
1211
1212\wxheading{Parameters}
1213
1214\docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
1215
1216
1217\membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
1218
1219\func{void}{ShowPosition}{\param{long}{ pos}}
1220
1221Makes the line containing the given position visible.
1222
1223\wxheading{Parameters}
1224
1225\docparam{pos}{The position that should be visible.}
1226
1227
1228\membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
1229
1230\func{virtual void}{Undo}{\void}
1231
1232If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
1233if there is no undo facility.
1234
1235
1236\membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
1237
1238\func{void}{WriteText}{\param{const wxString\& }{ text}}
1239
1240Writes the text into the text control at the current insertion position.
1241
1242\wxheading{Parameters}
1243
1244\docparam{text}{Text to write to the text control.}
1245
1246\wxheading{Remarks}
1247
1248Newlines in the text string
1249are the only control characters allowed, and they will cause appropriate
1250line breaks. See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
1251
1252After 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.
1253
1254
1255\membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
1256
1257\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
1258
1259Converts the given zero based column and line number to a position.
1260
1261\wxheading{Parameters}
1262
1263\docparam{x}{The column number.}
1264
1265\docparam{y}{The line number.}
1266
1267\wxheading{Return value}
1268
1269The position value, or -1 if {\tt x} or {\tt y} was invalid.
1270
1271
1272\membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
1273
1274\func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
1275
1276\func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
1277
1278\func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
1279
1280\func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
1281
1282\func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
1283
1284\func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
1285
1286Operator definitions for appending to a text control, for example:
1287
1288\begin{verbatim}
1289 wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1290
1291 (*wnd) << "Welcome to text control number " << 1 << ".\n";
1292\end{verbatim}
1293