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