]> git.saurik.com Git - wxWidgets.git/blame_incremental - docs/latex/wx/text.tex
1. GetCwd() now has the volume argument, Normalize() works correctly for the
[wxWidgets.git] / docs / latex / wx / text.tex
... / ...
CommitLineData
1%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextAttr %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2
3\section{\class{wxTextAttr}}\label{wxtextattr}
4
5wxTextAttr represents the attributes, or style, for a range of text in a\rtfsp
6\helpref{wxTextCtrl}{wxtextctrl}.
7
8\wxheading{Derived from}
9
10No base class
11
12\wxheading{Include files}
13
14<wx/textctrl.h>
15
16\latexignore{\rtfignore{\wxheading{Members}}}
17
18\membersection{wxTextAttr::wxTextAttr}\label{wxtextattrctor}
19
20\func{}{wxTextAttr}{\void}
21
22\func{}{wxTextAttr}{\param{const wxColour\& }{colText}, \param{const wxColour\& }{colBack = wxNullColour}, \param{const wxFont\& }{font = wxNullFont}}
23
24The constructors initialize one or more of the text foreground and background
25colours and font. The values not initialized in the constructor can be set
26later, otherwise \helpref{wxTextCtrl::SetStyle}{wxtextctrlsetstyle} will use
27the default values for them.
28
29\membersection{wxTextAttr::GetBackgroundColour}
30
31\constfunc{const wxColour\&}{GetBackgroundColour}{\void}
32
33Return the background colour specified by this attribute.
34
35\membersection{wxTextAttr::GetFont}
36
37\constfunc{const wxFont\&}{GetFont}{\void}
38
39Return the text font specified by this attribute.
40
41\membersection{wxTextAttr::GetTextColour}
42
43\constfunc{const wxColour\&}{GetTextColour}{\void}
44
45Return the text colour specified by this attribute.
46
47\membersection{wxTextAttr::HasBackgroundColour}
48
49\constfunc{bool}{HasBackgroundColour}{\void}
50
51Returns {\tt TRUE} if this style specifies the background colour to use.
52
53\membersection{wxTextAttr::HasFont}
54
55\constfunc{bool}{HasFont}{\void}
56
57Returns {\tt TRUE} if this style specifies the font to use.
58
59\membersection{wxTextAttr::HasTextColour}
60
61\constfunc{bool}{HasTextColour}{\void}
62
63Returns {\tt TRUE} if this style specifies the foreground colour to use.
64
65\membersection{wxTextAttr::IsDefault}
66
67\constfunc{bool}{IsDefault}{\void}
68
69Returns {\tt TRUE} if this style specifies any non-default attributes.
70
71%%%%%%%%%%%%%%%%%%%%%%%%%%%% wxTextCtrl %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
72
73\section{\class{wxTextCtrl}}\label{wxtextctrl}
74
75A text control allows text to be displayed and edited. It may be
76single line or multi-line.
77
78\wxheading{Derived from}
79
80streambuf\\
81\helpref{wxControl}{wxcontrol}\\
82\helpref{wxWindow}{wxwindow}\\
83\helpref{wxEvtHandler}{wxevthandler}\\
84\helpref{wxObject}{wxobject}
85
86\wxheading{Include files}
87
88<wx/textctrl.h>
89
90\wxheading{Window styles}
91
92\twocolwidtha{5cm}
93\begin{twocollist}\itemsep=0pt
94\twocolitem{\windowstyle{wxTE\_PROCESS\_ENTER}}{The control will generate
95the message wxEVENT\_TYPE\_TEXT\_ENTER\_COMMAND (otherwise pressing <Enter> is
96either processed internally by the control or used for navigation between
97dialog controls).}
98\twocolitem{\windowstyle{wxTE\_PROCESS\_TAB}}{The control will receieve
99EVT\_CHAR messages for TAB pressed - normally, TAB is used for passing to the
100next control in a dialog instead. For the control created with this style,
101you can still use Ctrl-Enter to pass to the next control from the keyboard.}
102\twocolitem{\windowstyle{wxTE\_MULTILINE}}{The text control allows multiple lines.}
103\twocolitem{\windowstyle{wxTE\_PASSWORD}}{The text will be echoed as asterisks.}
104\twocolitem{\windowstyle{wxTE\_READONLY}}{The text will not be user-editable.}
105\twocolitem{\windowstyle{wxTE\_RICH}}{Use rich text control under Win32, this
106allows to have more than 64Kb of text in the control even under Win9x. This
107style is ignored under other platforms.}
108\twocolitem{\windowstyle{wxTE\_AUTO\_URL}}{Highlight the URLs and generate the
109wxTextUrlEvents when mouse events occur over them. This style is supported
110under Win32 only and requires wxTE\_RICH.}
111\twocolitem{\windowstyle{wxTE\_NOHIDESEL}}{By default, the Windows text control
112doesn't show the selection when it doesn't have focus - use this style to force
113it to always show it. It doesn't do anything under other platforms.}
114\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
115\end{twocollist}
116
117See also \helpref{window styles overview}{windowstyles} and
118\helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
119
120\wxheading{wxTextCtrl styles}
121
122Multi-line text controls support the styles, i.e. provide a possibility to set
123colours and font for individual characters in it (note that under Windows {\tt
124wxTE\_RICH} style is required for style support). To use the styles you can
125either call \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} before
126inserting the text or call \helpref{SetStyle}{wxtextctrlsetstyle} later to
127change the style of the text already in the control (the first solution is
128much more efficient).
129
130In either case, if the style doesn't specify some of the attributes (for
131example you only want to set the text colour but without changing the font nor
132the text background), the values of the default style will be used for them.
133If there is no default style, the attributes of the text control itself are
134used.
135
136So the following code correctly describes what it does: the second call
137to \helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle} doesn't change the
138text foreground colour (which stays red) while the last one doesn't change the
139background colour (which stays grey):
140
141{\small%
142\begin{verbatim}
143 text->SetDefaultStyle(wxTextAttr(*wxRED));
144 text->AppendText("Red text\n");
145 text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
146 text->AppendText("Red on grey text\n");
147 text->SetDefaultStyle(wxTextAttr(*wxBLUE);
148 text->AppendText("Blue on grey text\n");
149\end{verbatim}
150}%
151
152\wxheading{wxTextCtrl and C++ streams}
153
154This class multiply-inherits from {\bf streambuf} where compilers allow,
155allowing code such as the following:
156
157{\small%
158\begin{verbatim}
159 wxTextCtrl *control = new wxTextCtrl(...);
160
161 ostream stream(control)
162
163 stream << 123.456 << " some text\n";
164 stream.flush();
165\end{verbatim}
166}%
167
168If your compiler does not support derivation from {\bf streambuf} and gives a
169compile error, define the symbol {\bf NO\_TEXT\_WINDOW\_STREAM} in the
170wxTextCtrl header file.
171
172Note that independently of this setting you can always use wxTextCtrl itself
173in a stream-like manner:
174
175{\small%
176\begin{verbatim}
177 wxTextCtrl *control = new wxTextCtrl(...);
178
179 *control << 123.456 << " some text\n";
180\end{verbatim}
181}%
182
183always works. However the possibility to create an ostream associated with
184wxTextCtrl may be useful if you need to redirect the output of a function
185taking an ostream as parameter to a text control.
186
187Another commonly requested need is to redirect {\bf std::cout} to the text
188control. This could be done in the following way:
189
190{\small%
191\begin{verbatim}
192 #include <iostream>
193
194 wxTextCtrl *control = new wxTextCtrl(...);
195
196 std::streambuf *sbOld = std::cout.rdbuf();
197 std::cout.rdbuf(*control);
198
199 // use cout as usual, the output appears in the text control
200 ...
201
202 std::cout.rdbuf(sbOld);
203\end{verbatim}
204}%
205
206But wxWindows provides a convenient class to make it even simpler so instead
207you may just do
208
209{\small%
210\begin{verbatim}
211 #include <iostream>
212
213 wxTextCtrl *control = new wxTextCtrl(...);
214
215 wxStreamToTextRedirector redirect(control);
216
217 // all output to cout goes into the text control until the exit from current
218 // scope
219\end{verbatim}
220}%
221
222See \helpref{wxStreamToTextRedirector}{wxstreamtotextredirector} for more
223details.
224
225\wxheading{Event handling}
226
227The following commands are processed by default event handlers in wxTextCtrl: wxID\_CUT, wxID\_COPY,
228wxID\_PASTE, wxID\_UNDO, wxID\_REDO. The associated UI update events are also processed
229automatically, when the control has the focus.
230
231To process input from a text control, use these event handler macros to direct input to member
232functions that take a \helpref{wxCommandEvent}{wxcommandevent} argument.
233
234\twocolwidtha{7cm}%
235\begin{twocollist}\itemsep=0pt
236\twocolitem{{\bf EVT\_TEXT(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_UPDATED event,
237generated when the text changes. Notice that this event will always be sent
238when the text controls contents changes - whether this is due to user input or
239comes from the program itself (for example, if SetValue() is called)}
240\twocolitem{{\bf EVT\_TEXT\_ENTER(id, func)}}{Respond to a wxEVT\_COMMAND\_TEXT\_ENTER event,
241generated when enter is pressed in a single-line text control.}
242\twocolitem{{\bf EVT\_TEXT\_URL(id, func)}}{A mouse event occured over an URL
243in the text control (Win32 only)}
244\twocolitem{{\bf EVT\_TEXT\_MAXLEN(id, func)}}{User tried to enter more text
245into the control than the limit set by
246\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
247\end{twocollist}%
248
249\latexignore{\rtfignore{\wxheading{Members}}}
250
251\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
252
253\func{}{wxTextCtrl}{\void}
254
255Default constructor.
256
257\func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
258\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
259\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
260
261Constructor, creating and showing a text control.
262
263\wxheading{Parameters}
264
265\docparam{parent}{Parent window. Should not be NULL.}
266
267\docparam{id}{Control identifier. A value of -1 denotes a default value.}
268
269\docparam{value}{Default text value.}
270
271\docparam{pos}{Text control position.}
272
273\docparam{size}{Text control size.}
274
275\docparam{style}{Window style. See \helpref{wxTextCtrl}{wxtextctrl}.}
276
277\docparam{validator}{Window validator.}
278
279\docparam{name}{Window name.}
280
281\wxheading{Remarks}
282
283The horizontal scrollbar ({\bf wxTE\_HSCROLL} style flag) will only be created for multi-line text controls.
284Without a horizontal scrollbar, text lines that don't fit in the control's
285size will be wrapped (but no newline character is inserted). Single line
286controls don't have a horizontal scrollbar, the text is automatically scrolled
287so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
288visible.
289
290% VZ: this is no longer true
291%Under Windows, if the {\bf wxTE\_MULTILINE} style is used, the window is implemented
292%as a Windows rich text control with unlimited capacity. Otherwise, normal edit control limits
293%apply.
294
295\wxheading{See also}
296
297\helpref{wxTextCtrl::Create}{wxtextctrlcreate}, \helpref{wxValidator}{wxvalidator}
298
299\membersection{wxTextCtrl::\destruct{wxTextCtrl}}
300
301\func{}{\destruct{wxTextCtrl}}{\void}
302
303Destructor, destroying the text control.
304
305\membersection{wxTextCtrl::AppendText}\label{wxtextctrlappendtext}
306
307\func{void}{AppendText}{\param{const wxString\& }{ text}}
308
309Appends the text to the end of the text control.
310
311\wxheading{Parameters}
312
313\docparam{text}{Text to write to the text control.}
314
315\wxheading{Remarks}
316
317After the text is appended, the insertion point will be at the end of the text control. If this behaviour is not desired,
318the programmer should use \helpref{GetInsertionPoint}{wxtextctrlgetinsertionpoint} and \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}.
319
320\wxheading{See also}
321
322\helpref{wxTextCtrl::WriteText}{wxtextctrlwritetext}
323
324\membersection{wxTextCtrl::CanCopy}\label{wxtextctrlcancopy}
325
326\func{virtual bool}{CanCopy}{\void}
327
328Returns TRUE if the selection can be copied to the clipboard.
329
330\membersection{wxTextCtrl::CanCut}\label{wxtextctrlcancut}
331
332\func{virtual bool}{CanCut}{\void}
333
334Returns TRUE if the selection can be cut to the clipboard.
335
336\membersection{wxTextCtrl::CanPaste}\label{wxtextctrlcanpaste}
337
338\func{virtual bool}{CanPaste}{\void}
339
340Returns TRUE if the contents of the clipboard can be pasted into the
341text control. On some platforms (Motif, GTK) this is an approximation
342and returns TRUE if the control is editable, FALSE otherwise.
343
344\membersection{wxTextCtrl::CanRedo}\label{wxtextctrlcanredo}
345
346\func{virtual bool}{CanRedo}{\void}
347
348Returns TRUE if there is a redo facility available and the last operation
349can be redone.
350
351\membersection{wxTextCtrl::CanUndo}\label{wxtextctrlcanundo}
352
353\func{virtual bool}{CanUndo}{\void}
354
355Returns TRUE if there is an undo facility available and the last operation
356can be undone.
357
358\membersection{wxTextCtrl::Clear}\label{wxtextctrlclear}
359
360\func{virtual void}{Clear}{\void}
361
362Clears the text in the control.
363
364\membersection{wxTextCtrl::Copy}\label{wxtextctrlcopy}
365
366\func{virtual void}{Copy}{\void}
367
368Copies the selected text to the clipboard under Motif and MS Windows.
369
370\membersection{wxTextCtrl::Create}\label{wxtextctrlcreate}
371
372\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
373\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
374\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
375
376Creates the text control for two-step construction. Derived classes
377should call or replace this function. See \helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}\rtfsp
378for further details.
379
380\membersection{wxTextCtrl::Cut}\label{wxtextctrlcut}
381
382\func{virtual void}{Cut}{\void}
383
384Copies the selected text to the clipboard and removes the selection.
385
386\membersection{wxTextCtrl::DiscardEdits}
387
388\func{void}{DiscardEdits}{\void}
389
390Resets the internal `modified' flag as if the current edits had been saved.
391
392\membersection{wxTextCtrl::GetDefaultStyle}{wxtextctrlgetdefaultstyle}
393
394\constfunc{const wxTextAttr\& }{GetDefaultStyle}{\void}
395
396Returns the style currently used for the new text.
397
398\wxheading{See also}
399
400\helpref{SetDefaultStyle}{wxtextctrlsetdefaultstyle}
401
402\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
403
404\constfunc{virtual long}{GetInsertionPoint}{\void}
405
406Returns the insertion point. This is defined as the zero based index of the
407character position to the right of the insertion point. For example, if
408the insertion point is at the end of the text control, it is equal to
409both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
410\helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
411
412The following code snippet safely returns the character at the insertion
413point or the zero character if the point is at the end of the control.
414
415{\small%
416\begin{verbatim}
417 char GetCurrentChar(wxTextCtrl *tc) {
418 if (tc->GetInsertionPoint() == tc->GetLastPosition())
419 return '\0';
420 return tc->GetValue[tc->GetInsertionPoint()];
421 }
422\end{verbatim}
423}%
424
425\membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
426
427\constfunc{virtual long}{GetLastPosition}{\void}
428
429Returns the zero based index of the last position in the text control,
430which is equal to the number of characters in the control.
431
432\membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
433
434\constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
435
436Gets the length of the specified line, not including any trailing newline
437character(s).
438
439\wxheading{Parameters}
440
441\docparam{lineNo}{Line number (starting from zero).}
442
443\wxheading{Return value}
444
445The length of the line, or -1 if {\it lineNo} was invalid.
446
447\membersection{wxTextCtrl::GetLineText}\label{wxtextctrlgetlinetext}
448
449\constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
450
451Returns the contents of a given line in the text control, not including
452any trailing newline character(s).
453
454\wxheading{Parameters}
455
456\docparam{lineNo}{The line number, starting from zero.}
457
458\wxheading{Return value}
459
460The contents of the line.
461
462\membersection{wxTextCtrl::GetNumberOfLines}\label{wxtextctrlgetnumberoflines}
463
464\constfunc{int}{GetNumberOfLines}{\void}
465
466Returns the number of lines in the text control buffer.
467
468\wxheading{Remarks}
469
470Note that even empty text controls have one line (where the insertion point
471is), so GetNumberOfLines() never returns 0.
472
473For gtk\_text (multi-line) controls, the number of lines is
474calculated by actually counting newline characters in the buffer. You
475may wish to avoid using functions that work with line numbers if you are
476working with controls that contain large amounts of text.
477
478\membersection{wxTextCtrl::GetSelection}\label{wxtextctrlgetselection}
479
480\func{virtual void}{GetSelection}{\param{long*}{ from}, \param{long*}{ to}}
481
482Gets the current selection span. If the returned values are equal, there was
483no selection.
484
485Please note that the indices returned may be used with the other wxTextctrl
486methods but don't necessarily represent the correct indices into the string
487returned by \helpref{GetValue()}{wxtextctrlgetvalue} for multiline controls
488under Windows (at least,) you should use
489\helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
490text.
491
492\wxheading{Parameters}
493
494\docparam{from}{The returned first position.}
495
496\docparam{to}{The returned last position.}
497
498\pythonnote{The wxPython version of this method returns a tuple
499consisting of the from and to values.}
500
501\perlnote{In wxPerl this method takes no parameter and returns a
5022-element list {\tt ( from, to )}.}
503
504\membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
505
506\func{virtual wxString}{GetStringSelection}{\void}
507
508Gets the text currently selected in the control. If there is no selection, the
509returned string is empty.
510
511\membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
512
513\constfunc{wxString}{GetValue}{\void}
514
515Gets the contents of the control. Notice that for a multiline text control,
516the lines will be separated by (Unix-style) $\backslash$n characters, even under
517Windows where they are separated by a $\backslash$r$\backslash$n sequence in the native control.
518
519\membersection{wxTextCtrl::IsModified}\label{wxtextctrlismodified}
520
521\constfunc{bool}{IsModified}{\void}
522
523Returns TRUE if the text has been modified.
524
525\membersection{wxTextCtrl::LoadFile}\label{wxtextctrlloadfile}
526
527\func{bool}{LoadFile}{\param{const wxString\& }{ filename}}
528
529Loads and displays the named file, if it exists.
530
531\wxheading{Parameters}
532
533\docparam{filename}{The filename of the file to load.}
534
535\wxheading{Return value}
536
537TRUE if successful, FALSE otherwise.
538
539\membersection{wxTextCtrl::OnChar}\label{wxtextctrlonchar}
540
541\func{void}{OnChar}{\param{wxKeyEvent\& }{event}}
542
543Default handler for character input.
544
545\wxheading{Remarks}
546
547It is possible to intercept character
548input by overriding this member. Call this function
549to let the default behaviour take place; not calling
550it results in the character being ignored. You can
551replace the {\it keyCode} member of {\it event} to
552translate keystrokes.
553
554Note that Windows and Motif have different ways
555of implementing the default behaviour. In Windows,
556calling wxTextCtrl::OnChar immediately
557processes the character. In Motif,
558calling this function simply sets a flag
559to let default processing happen. This might affect
560the way in which you write your OnChar function
561on different platforms.
562
563\wxheading{See also}
564
565\helpref{wxKeyEvent}{wxkeyevent}
566
567\membersection{wxTextCtrl::OnDropFiles}\label{wxtextctrlondropfiles}
568
569\func{void}{OnDropFiles}{\param{wxDropFilesEvent\& }{event}}
570
571This event handler function implements default drag and drop behaviour, which
572is to load the first dropped file into the control.
573
574\wxheading{Parameters}
575
576\docparam{event}{The drop files event.}
577
578\wxheading{Remarks}
579
580This is not implemented on non-Windows platforms.
581
582\wxheading{See also}
583
584\helpref{wxDropFilesEvent}{wxdropfilesevent}
585
586\membersection{wxTextCtrl::Paste}\label{wxtextctrlpaste}
587
588\func{virtual void}{Paste}{\void}
589
590Pastes text from the clipboard to the text item.
591
592\membersection{wxTextCtrl::PositionToXY}\label{wxtextctrlpositiontoxy}
593
594\constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
595
596Converts given position to a zero-based column, line number pair.
597
598\wxheading{Parameters}
599
600\docparam{pos}{Position.}
601
602\docparam{x}{Receives zero based column number.}
603
604\docparam{y}{Receives zero based line number.}
605
606\wxheading{Return value}
607
608TRUE on success, FALSE on failure (most likely due to a too large position
609parameter).
610
611\wxheading{See also}
612
613\helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
614
615\pythonnote{In Python, PositionToXY() returns a tuple containing the x and
616y values, so (x,y) = PositionToXY() is equivalent to the call described
617above.}
618
619\perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
620returns a 2-element list {\tt ( x, y )}.}
621
622\membersection{wxTextCtrl::Redo}\label{wxtextctrlredo}
623
624\func{virtual void}{Redo}{\void}
625
626If there is a redo facility and the last operation can be redone, redoes the last operation. Does nothing
627if there is no redo facility.
628
629\membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
630
631\func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
632
633Removes the text starting at the first given position up to (but not including)
634the character at the last position.
635
636\wxheading{Parameters}
637
638\docparam{from}{The first position.}
639
640\docparam{to}{The last position.}
641
642\membersection{wxTextCtrl::Replace}\label{wxtextctrlreplace}
643
644\func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
645
646Replaces the text starting at the first position up to (but not including)
647the character at the last position with the given text.
648
649\wxheading{Parameters}
650
651\docparam{from}{The first position.}
652
653\docparam{to}{The last position.}
654
655\docparam{value}{The value to replace the existing text with.}
656
657\membersection{wxTextCtrl::SaveFile}\label{wxtextctrlsavefile}
658
659\func{bool}{SaveFile}{\param{const wxString\& }{ filename}}
660
661Saves the contents of the control in a text file.
662
663\wxheading{Parameters}
664
665\docparam{filename}{The name of the file in which to save the text.}
666
667\wxheading{Return value}
668
669TRUE if the operation was successful, FALSE otherwise.
670
671\membersection{wxTextCtrl::SetDefaultStyle}\label{wxtextctrlsetdefaultstyle}
672
673\func{bool}{SetDefaultStyle}{\param{const wxTextAttr\& }{style}}
674
675Changes the default style to use for the new text which is going to be added
676to the control using \helpref{WriteText}{wxtextctrlwritetext} or\rtfsp
677\helpref{AppendText}{wxtextctrlappendtext}.
678
679If either of the font, foreground, or background colour is not set in\rtfsp
680{\it style}, the values of the previous default style are used for them. If
681the previous default style didn't set them neither, the global font or colours
682of the text control itself are used as fall back.
683
684\wxheading{Parameters}
685
686\docparam{style}{The style for the new text.}
687
688\wxheading{Return value}
689
690{\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
691the styles are not supported under this platform.
692
693\wxheading{See also}
694
695\helpref{GetDefaultStyle}{wxtextctrlgetdefaultstyle}
696
697\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
698
699\func{virtual void}{SetEditable}{\param{const bool}{ editable}}
700
701Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
702
703\wxheading{Parameters}
704
705\docparam{editable}{If TRUE, the control is editable. If FALSE, the control is read-only.}
706
707\membersection{wxTextCtrl::SetInsertionPoint}\label{wxtextctrlsetinsertionpoint}
708
709\func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
710
711Sets the insertion point at the given position.
712
713\wxheading{Parameters}
714
715\docparam{pos}{Position to set.}
716
717\membersection{wxTextCtrl::SetInsertionPointEnd}\label{wxtextctrlsetinsertionpointend}
718
719\func{virtual void}{SetInsertionPointEnd}{\void}
720
721Sets the insertion point at the end of the text control. This is equivalent
722to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
723
724\membersection{wxTextCtrl::SetMaxLength}\label{wxtextctrlsetmaxlength}
725
726\func{virtual void}{SetMaxLength}{\param{unsigned long }{len}}
727
728This function sets the maximum number of characters the user can enter into the
729control. In other words, it allows to limit the text value length to {\it len}
730not counting the terminating {\tt NUL} character.
731
732If {\it len} is $0$, the previously set max length limi, if any, is discarded
733and the user may enter as much text as the underlying native text control
734widget supports (typically at least 32Kb).
735
736If the user tries to enter more characters into the text control when it
737already is filled up to the maximal length, a
738{\tt wxEVT\_COMMAND\_TEXT\_MAXLEN} event is sent to notify the program about it
739(giving it the possibility to show an explanatory message, for example) and the
740extra input is discarded.
741
742Note that this function may only be used with single line text controls.
743
744\wxheading{Compatibility}
745
746Only implemented in wxMSW/wxGTK starting with wxWindows 2.3.2.
747
748\membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
749
750\func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
751
752Selects the text starting at the first position up to (but not including) the character at the last position.
753
754\wxheading{Parameters}
755
756\docparam{from}{The first position.}
757
758\docparam{to}{The last position.}
759
760\membersection{wxTextCtrl::SetStyle}\label{wxtextctrlsetstyle}
761
762\func{bool}{SetStyle}{\param{long }{start}, \param{long }{end}, \param{const wxTextAttr\& }{style}}
763
764Changes the style of the selection. If either of the font, foreground, or
765background colour is not set in {\it style}, the values of\rtfsp
766\helpref{GetDefaultStyle()}{wxtextctrlgetdefaultstyle} are used.
767
768\wxheading{Parameters}
769
770\docparam{start}{The start of selection to change.}
771
772\docparam{end}{The end of selection to change.}
773
774\docparam{style}{The new style for the selection.}
775
776\wxheading{Return value}
777
778{\tt TRUE} on success, {\tt FALSE} if an error occured - may also mean that
779the styles are not supported under this platform.
780
781\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
782
783\func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
784
785Sets the text value and marks the control as not-modified.
786
787\wxheading{Parameters}
788
789\docparam{value}{The new value to set. It may contain newline characters if the text control is multi-line.}
790
791\membersection{wxTextCtrl::ShowPosition}\label{wxtextctrlshowposition}
792
793\func{void}{ShowPosition}{\param{long}{ pos}}
794
795Makes the line containing the given position visible.
796
797\wxheading{Parameters}
798
799\docparam{pos}{The position that should be visible.}
800
801\membersection{wxTextCtrl::Undo}\label{wxtextctrlundo}
802
803\func{virtual void}{Undo}{\void}
804
805If there is an undo facility and the last operation can be undone, undoes the last operation. Does nothing
806if there is no undo facility.
807
808\membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
809
810\func{void}{WriteText}{\param{const wxString\& }{ text}}
811
812Writes the text into the text control at the current insertion position.
813
814\wxheading{Parameters}
815
816\docparam{text}{Text to write to the text control.}
817
818\wxheading{Remarks}
819
820Newlines in the text string
821are the only control characters allowed, and they will cause appropriate
822line breaks. See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
823
824After 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.
825
826\membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
827
828\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
829
830Converts the given zero based column and line number to a position.
831
832\wxheading{Parameters}
833
834\docparam{x}{The column number.}
835
836\docparam{y}{The line number.}
837
838\wxheading{Return value}
839
840The position value.
841
842\membersection{wxTextCtrl::operator \cinsert}\label{wxtextctrlinsert}
843
844\func{wxTextCtrl\&}{operator \cinsert}{\param{const wxString\& }{s}}
845
846\func{wxTextCtrl\&}{operator \cinsert}{\param{int}{ i}}
847
848\func{wxTextCtrl\&}{operator \cinsert}{\param{long}{ i}}
849
850\func{wxTextCtrl\&}{operator \cinsert}{\param{float}{ f}}
851
852\func{wxTextCtrl\&}{operator \cinsert}{\param{double}{ d}}
853
854\func{wxTextCtrl\&}{operator \cinsert}{\param{char}{ c}}
855
856Operator definitions for appending to a text control, for example:
857
858\begin{verbatim}
859 wxTextCtrl *wnd = new wxTextCtrl(my_frame);
860
861 (*wnd) << "Welcome to text control number " << 1 << ".\n";
862\end{verbatim}
863