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