]> git.saurik.com Git - wxWidgets.git/blame - 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
eda40bfc
VZ
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
a660d684
KB
73\section{\class{wxTextCtrl}}\label{wxtextctrl}
74
75A text control allows text to be displayed and edited. It may be
71777e2c 76single line or multi-line.
a660d684
KB
77
78\wxheading{Derived from}
79
80streambuf\\
81\helpref{wxControl}{wxcontrol}\\
82\helpref{wxWindow}{wxwindow}\\
83\helpref{wxEvtHandler}{wxevthandler}\\
84\helpref{wxObject}{wxobject}
85
954b8ae6
JS
86\wxheading{Include files}
87
88<wx/textctrl.h>
89
a660d684
KB
90\wxheading{Window styles}
91
92\twocolwidtha{5cm}
93\begin{twocollist}\itemsep=0pt
c50f1fb9
VZ
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.}
a660d684
KB
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.}
c57e3339
VZ
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.}
5a8f04e3
VZ
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.}
9c884972 114\twocolitem{\windowstyle{wxHSCROLL}}{A horizontal scrollbar will be created. No effect under GTK+.}
a660d684
KB
115\end{twocollist}
116
eef97940 117See also \helpref{window styles overview}{windowstyles} and
f66205b6 118\helpref{wxTextCtrl::wxTextCtrl}{wxtextctrlconstr}.
a660d684 119
eda40bfc
VZ
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
d73e6791 152\wxheading{wxTextCtrl and C++ streams}
a660d684 153
d73e6791
VZ
154This class multiply-inherits from {\bf streambuf} where compilers allow,
155allowing code such as the following:
a660d684
KB
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
d73e6791
VZ
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.
9c884972 171
d73e6791
VZ
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.
a660d684 224
5de76427
JS
225\wxheading{Event handling}
226
e702ff0f
JS
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
5de76427
JS
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,
a1665b22
VZ
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)}
5de76427
JS
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.}
f2616db5
VZ
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
eef97940 245into the control than the limit set by
f2616db5 246\helpref{SetMaxLength}{wxtextctrlsetmaxlength}.}
5de76427
JS
247\end{twocollist}%
248
a660d684
KB
249\latexignore{\rtfignore{\wxheading{Members}}}
250
251\membersection{wxTextCtrl::wxTextCtrl}\label{wxtextctrlconstr}
252
253\func{}{wxTextCtrl}{\void}
254
255Default constructor.
256
eaaa6a06 257\func{}{wxTextCtrl}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
36b3b54a 258\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
eaaa6a06 259\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
a660d684
KB
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
86975656
RD
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
71777e2c
HH
285size will be wrapped (but no newline character is inserted). Single line
286controls don't have a horizontal scrollbar, the text is automatically scrolled
86975656 287so that the \helpref{insertion point}{wxtextctrlgetinsertionpoint} is always
71777e2c
HH
288visible.
289
c57e3339
VZ
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.
a660d684
KB
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
ca8b28f2
JS
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
a660d684
KB
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
eaaa6a06 372\func{bool}{Create}{\param{wxWindow* }{parent}, \param{wxWindowID}{ id},\rtfsp
36b3b54a 373\param{const wxString\& }{value = ``"}, \param{const wxPoint\& }{pos}, \param{const wxSize\& }{size = wxDefaultSize},\rtfsp
eaaa6a06 374\param{long}{ style = 0}, \param{const wxValidator\& }{validator}, \param{const wxString\& }{name = ``text"}}
a660d684
KB
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
eda40bfc
VZ
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
a660d684
KB
402\membersection{wxTextCtrl::GetInsertionPoint}\label{wxtextctrlgetinsertionpoint}
403
404\constfunc{virtual long}{GetInsertionPoint}{\void}
405
71777e2c
HH
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
86975656
RD
409both \helpref{GetValue()}{wxtextctrlgetvalue}.Length() and
410\helpref{GetLastPosition()}{wxtextctrlgetlastposition}.
71777e2c
HH
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()];
86975656 421 }
71777e2c
HH
422\end{verbatim}
423}%
a660d684
KB
424
425\membersection{wxTextCtrl::GetLastPosition}\label{wxtextctrlgetlastposition}
426
427\constfunc{virtual long}{GetLastPosition}{\void}
428
86975656 429Returns the zero based index of the last position in the text control,
71777e2c 430which is equal to the number of characters in the control.
a660d684
KB
431
432\membersection{wxTextCtrl::GetLineLength}\label{wxtextctrlgetlinelength}
433
434\constfunc{int}{GetLineLength}{\param{long}{ lineNo}}
435
86975656 436Gets the length of the specified line, not including any trailing newline
71777e2c 437character(s).
a660d684
KB
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
eaaa6a06 449\constfunc{wxString}{GetLineText}{\param{long}{ lineNo}}
a660d684 450
71777e2c
HH
451Returns the contents of a given line in the text control, not including
452any trailing newline character(s).
a660d684
KB
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
71777e2c
HH
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
ca8b28f2
JS
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
18414479
VZ
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
eef97940
RD
488under Windows (at least,) you should use
489\helpref{GetStringSelection()}{wxtextctrlgetstringselection} to get the selected
18414479
VZ
490text.
491
ca8b28f2
JS
492\wxheading{Parameters}
493
494\docparam{from}{The returned first position.}
495
496\docparam{to}{The returned last position.}
497
86975656
RD
498\pythonnote{The wxPython version of this method returns a tuple
499consisting of the from and to values.}
500
5873607e
VZ
501\perlnote{In wxPerl this method takes no parameter and returns a
5022-element list {\tt ( from, to )}.}
503
eef97940 504\membersection{wxTextCtrl::GetStringSelection}\label{wxtextctrlgetstringselection}
18414479 505
eef97940 506\func{virtual wxString}{GetStringSelection}{\void}
18414479
VZ
507
508Gets the text currently selected in the control. If there is no selection, the
509returned string is empty.
510
a660d684
KB
511\membersection{wxTextCtrl::GetValue}\label{wxtextctrlgetvalue}
512
513\constfunc{wxString}{GetValue}{\void}
514
9750fc42 515Gets the contents of the control. Notice that for a multiline text control,
b2cf617c
JS
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.
a660d684
KB
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
71777e2c
HH
578\wxheading{Remarks}
579
b2cf617c 580This is not implemented on non-Windows platforms.
71777e2c 581
a660d684
KB
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
0efe5ba7 594\constfunc{bool}{PositionToXY}{\param{long }{pos}, \param{long *}{x}, \param{long *}{y}}
a660d684 595
71777e2c 596Converts given position to a zero-based column, line number pair.
a660d684
KB
597
598\wxheading{Parameters}
599
600\docparam{pos}{Position.}
601
71777e2c 602\docparam{x}{Receives zero based column number.}
a660d684 603
71777e2c
HH
604\docparam{y}{Receives zero based line number.}
605
606\wxheading{Return value}
607
0efe5ba7 608TRUE on success, FALSE on failure (most likely due to a too large position
71777e2c 609parameter).
a660d684
KB
610
611\wxheading{See also}
612
613\helpref{wxTextCtrl::XYToPosition}{wxtextctrlxytoposition}
614
71777e2c
HH
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
5873607e
VZ
619\perlnote{In wxPerl this method only takes the {\tt pos} parameter, and
620returns a 2-element list {\tt ( x, y )}.}
621
ca8b28f2
JS
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
a660d684
KB
629\membersection{wxTextCtrl::Remove}\label{wxtextctrlremove}
630
eaaa6a06 631\func{virtual void}{Remove}{\param{long}{ from}, \param{long}{ to}}
a660d684 632
71777e2c
HH
633Removes the text starting at the first given position up to (but not including)
634the character at the last position.
a660d684
KB
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
eaaa6a06 644\func{virtual void}{Replace}{\param{long}{ from}, \param{long}{ to}, \param{const wxString\& }{value}}
a660d684 645
86975656 646Replaces the text starting at the first position up to (but not including)
71777e2c 647the character at the last position with the given text.
a660d684
KB
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
71777e2c 665\docparam{filename}{The name of the file in which to save the text.}
a660d684
KB
666
667\wxheading{Return value}
668
669TRUE if the operation was successful, FALSE otherwise.
670
eda40bfc
VZ
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
a660d684
KB
697\membersection{wxTextCtrl::SetEditable}\label{wxtextctrlseteditable}
698
699\func{virtual void}{SetEditable}{\param{const bool}{ editable}}
700
b2cf617c 701Makes the text item editable or read-only, overriding the {\bf wxTE\_READONLY} flag.
a660d684
KB
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
eaaa6a06 709\func{virtual void}{SetInsertionPoint}{\param{long}{ pos}}
a660d684 710
71777e2c 711Sets the insertion point at the given position.
a660d684
KB
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
71777e2c
HH
721Sets the insertion point at the end of the text control. This is equivalent
722to \helpref{SetInsertionPoint}{wxtextctrlsetinsertionpoint}(\helpref{GetLastPosition}{wxtextctrlgetlastposition}()).
a660d684 723
d7eee191
VZ
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
5949fba6
VZ
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
d7eee191 736If the user tries to enter more characters into the text control when it
eef97940 737already is filled up to the maximal length, a
d7eee191
VZ
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
a660d684
KB
748\membersection{wxTextCtrl::SetSelection}\label{wxtextctrlsetselection}
749
eaaa6a06 750\func{virtual void}{SetSelection}{\param{long}{ from}, \param{long}{ to}}
a660d684 751
71777e2c 752Selects the text starting at the first position up to (but not including) the character at the last position.
a660d684
KB
753
754\wxheading{Parameters}
755
756\docparam{from}{The first position.}
757
758\docparam{to}{The last position.}
759
eda40bfc
VZ
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
a660d684
KB
781\membersection{wxTextCtrl::SetValue}\label{wxtextctrlsetvalue}
782
783\func{virtual void}{SetValue}{\param{const wxString\& }{ value}}
784
f6bcfd97 785Sets the text value and marks the control as not-modified.
a660d684
KB
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
eaaa6a06 793\func{void}{ShowPosition}{\param{long}{ pos}}
a660d684
KB
794
795Makes the line containing the given position visible.
796
797\wxheading{Parameters}
798
799\docparam{pos}{The position that should be visible.}
800
ca8b28f2
JS
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
a660d684
KB
808\membersection{wxTextCtrl::WriteText}\label{wxtextctrlwritetext}
809
810\func{void}{WriteText}{\param{const wxString\& }{ text}}
811
86975656 812Writes the text into the text control at the current insertion position.
a660d684
KB
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
abaa2936 822line breaks. See \helpref{wxTextCtrl::\cinsert}{wxtextctrlinsert} and \helpref{wxTextCtrl::AppendText}{wxtextctrlappendtext} for more convenient ways of writing to the window.
71777e2c
HH
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.
a660d684
KB
825
826\membersection{wxTextCtrl::XYToPosition}\label{wxtextctrlxytoposition}
827
eaaa6a06 828\func{long}{XYToPosition}{\param{long}{ x}, \param{long}{ y}}
a660d684 829
71777e2c 830Converts the given zero based column and line number to a position.
a660d684
KB
831
832\wxheading{Parameters}
833
71777e2c 834\docparam{x}{The column number.}
a660d684 835
71777e2c 836\docparam{y}{The line number.}
a660d684
KB
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
abaa2936 856Operator definitions for appending to a text control, for example:
a660d684
KB
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