]> git.saurik.com Git - wxWidgets.git/blame - interface/textctrl.h
add handling of wxWrapSizer flags (part of ticket 9468)
[wxWidgets.git] / interface / textctrl.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: textctrl.h
e54c96f1 3// Purpose: interface of wxTextAttr
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxTextAttr
11 @wxheader{textctrl.h}
7c913512 12
23324ae1
FM
13 wxTextAttr represents the character and paragraph attributes, or style,
14 for a range of text in a wxTextCtrl or wxRichTextCtrl.
7c913512 15
23324ae1 16 When setting up a wxTextAttr object, pass a bitlist mask to
756e6e49
VZ
17 wxTextAttr::SetFlags to indicate which style elements should be changed. As
18 a convenience, when you call a setter such as SetFont, the relevant bit
19 will be set.
7c913512 20
23324ae1
FM
21 @library{wxcore}
22 @category{richtext}
7c913512 23
e54c96f1 24 @see wxTextCtrl, wxRichTextCtrl
23324ae1 25*/
7c913512 26class wxTextAttr
23324ae1
FM
27{
28public:
29 //@{
30 /**
31 Constructors.
32 */
33 wxTextAttr();
7c913512
FM
34 wxTextAttr(const wxColour& colText,
35 const wxColour& colBack = wxNullColour,
36 const wxFont& font = wxNullFont,
37 wxTextAttrAlignment alignment = wxTEXT_ALIGNMENT_DEFAULT);
38 wxTextAttr(const wxTextAttr& attr);
23324ae1
FM
39 //@}
40
41 /**
4cc4bfaf
FM
42 Applies the attributes in @a style to the original object, but not those
43 attributes from @a style that are the same as those in @a compareWith (if passed).
23324ae1
FM
44 */
45 bool Apply(const wxTextAttr& style,
4cc4bfaf 46 const wxTextAttr* compareWith = NULL);
23324ae1
FM
47
48 /**
49 Creates a font from the font attributes.
50 */
328f5751 51 wxFont CreateFont() const;
23324ae1
FM
52
53 /**
54 Returns the alignment flags.
55 See SetAlignment() for a list of available styles.
56 */
328f5751 57 wxTextAttrAlignment GetAlignment() const;
23324ae1
FM
58
59 /**
60 Returns the background colour.
61 */
328f5751 62 const wxColour GetBackgroundColour() const;
23324ae1
FM
63
64 /**
65 Returns a string containing the name of the font associated with the bullet
66 symbol.
67 Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
68 */
328f5751 69 const wxString GetBulletFont() const;
23324ae1
FM
70
71 /**
72 Returns the standard bullet name, applicable if the bullet style is
73 wxTEXT_ATTR_BULLET_STYLE_STANDARD.
74 Currently the following standard bullet names are supported:
23324ae1
FM
75 @c standard/circle
76 @c standard/square
77 @c standard/diamond
78 @c standard/triangle
23324ae1
FM
79 For wxRichTextCtrl users only: if you wish your rich text controls to support
80 further bullet graphics, you can derive a
81 class from wxRichTextRenderer or wxRichTextStdRenderer, override @c
82 DrawStandardBullet and @c EnumerateStandardBulletNames, and
83 set an instance of the class using wxRichTextBuffer::SetRenderer.
84 */
328f5751 85 const wxString GetBulletName() const;
23324ae1
FM
86
87 /**
88 Returns the bullet number.
89 */
328f5751 90 int GetBulletNumber() const;
23324ae1
FM
91
92 /**
93 Returns the bullet style.
94 See SetBulletStyle() for a list of available styles.
95 */
328f5751 96 int GetBulletStyle() const;
23324ae1
FM
97
98 /**
99 Returns the bullet text, which could be a symbol, or (for example) cached
100 outline text.
101 */
328f5751 102 const wxString GetBulletText() const;
23324ae1
FM
103
104 /**
105 Returns the name of the character style.
106 */
328f5751 107 const wxString GetCharacterStyleName() const;
23324ae1
FM
108
109 /**
110 Returns flags indicating which attributes are applicable.
111 See SetFlags() for a list of available flags.
112 */
328f5751 113 long GetFlags() const;
23324ae1
FM
114
115 /**
116 Creates and returns a font specified by the font attributes in the wxTextAttr
117 object. Note that
118 wxTextAttr does not store a wxFont object, so this is only a temporary font.
119 For greater
120 efficiency, access the font attributes directly.
121 */
328f5751 122 wxFont GetFont() const;
23324ae1
FM
123
124 /**
125 Gets the font attributes from the given font, using only the attributes
756e6e49 126 specified by @a flags.
23324ae1
FM
127 */
128 bool GetFontAttributes(const wxFont& font,
129 int flags = wxTEXT_ATTR_FONT);
130
131 /**
132 Returns the font encoding.
133 */
328f5751 134 wxFontEncoding GetFontEncoding() const;
23324ae1
FM
135
136 /**
137 Returns the font face name.
138 */
328f5751 139 const wxString GetFontFaceName() const;
23324ae1
FM
140
141 /**
142 Returns the font size in points.
143 */
328f5751 144 int GetFontSize() const;
23324ae1
FM
145
146 /**
147 Returns the font style.
148 */
328f5751 149 int GetFontStyle() const;
23324ae1
FM
150
151 /**
152 Returns @true if the font is underlined.
153 */
328f5751 154 bool GetFontUnderlined() const;
23324ae1
FM
155
156 /**
157 Returns the font weight.
158 */
328f5751 159 int GetFontWeight() const;
23324ae1
FM
160
161 /**
162 Returns the left indent in tenths of a millimetre.
163 */
328f5751 164 long GetLeftIndent() const;
23324ae1
FM
165
166 /**
167 Returns the left sub-indent in tenths of a millimetre.
168 */
328f5751 169 long GetLeftSubIndent() const;
23324ae1
FM
170
171 /**
172 Returns the line spacing value, one of wxTEXT_ATTR_LINE_SPACING_NORMAL,
173 wxTEXT_ATTR_LINE_SPACING_HALF, and wxTEXT_ATTR_LINE_SPACING_TWICE.
174 */
328f5751 175 int GetLineSpacing() const;
23324ae1
FM
176
177 /**
178 Returns the name of the list style.
179 */
328f5751 180 const wxString GetListStyleName() const;
23324ae1
FM
181
182 /**
183 Returns the outline level.
184 */
328f5751 185 bool GetOutlineLevel() const;
23324ae1
FM
186
187 /**
188 Returns the space in tenths of a millimeter after the paragraph.
189 */
328f5751 190 int GetParagraphSpacingAfter() const;
23324ae1
FM
191
192 /**
193 Returns the space in tenths of a millimeter before the paragraph.
194 */
328f5751 195 int GetParagraphSpacingBefore() const;
23324ae1
FM
196
197 /**
198 Returns the name of the paragraph style.
199 */
328f5751 200 const wxString GetParagraphStyleName() const;
23324ae1
FM
201
202 /**
203 Returns the right indent in tenths of a millimeter.
204 */
328f5751 205 long GetRightIndent() const;
23324ae1
FM
206
207 /**
208 Returns an array of tab stops, each expressed in tenths of a millimeter. Each
209 stop
210 is measured from the left margin and therefore each value must be larger than
211 the last.
212 */
328f5751 213 const wxArrayInt GetTabs() const;
23324ae1
FM
214
215 /**
216 Returns the text foreground colour.
217 */
328f5751 218 const wxColour GetTextColour() const;
23324ae1
FM
219
220 /**
221 Returns the text effect bits of interest. See SetFlags() for further
222 information.
223 */
328f5751 224 int GetTextEffectFlags() const;
23324ae1
FM
225
226 /**
227 Returns the text effects, a bit list of styles. See SetTextEffects() for
228 details.
229 */
328f5751 230 int GetTextEffects() const;
23324ae1
FM
231
232 /**
233 Returns the URL for the content. Content with wxTEXT_ATTR_URL style
234 causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
235 generates
236 a wxTextUrlEvent when the content is clicked.
237 */
328f5751 238 const wxString GetURL() const;
23324ae1
FM
239
240 /**
241 Returns @true if the attribute object specifies alignment.
242 */
328f5751 243 bool HasAlignment() const;
23324ae1
FM
244
245 /**
246 Returns @true if the attribute object specifies a background colour.
247 */
328f5751 248 bool HasBackgroundColour() const;
23324ae1
FM
249
250 /**
251 Returns @true if the attribute object specifies a standard bullet name.
252 */
328f5751 253 bool HasBulletName() const;
23324ae1
FM
254
255 /**
256 Returns @true if the attribute object specifies a bullet number.
257 */
328f5751 258 bool HasBulletNumber() const;
23324ae1
FM
259
260 /**
261 Returns @true if the attribute object specifies a bullet style.
262 */
328f5751 263 bool HasBulletStyle() const;
23324ae1
FM
264
265 /**
266 Returns @true if the attribute object specifies bullet text (usually
267 specifying a symbol).
268 */
328f5751 269 bool HasBulletText() const;
23324ae1
FM
270
271 /**
272 Returns @true if the attribute object specifies a character style name.
273 */
328f5751 274 bool HasCharacterStyleName() const;
23324ae1
FM
275
276 /**
4cc4bfaf 277 Returns @true if the @a flag is present in the attribute object's flag
23324ae1
FM
278 bitlist.
279 */
328f5751 280 bool HasFlag(long flag) const;
23324ae1
FM
281
282 /**
283 Returns @true if the attribute object specifies any font attributes.
284 */
328f5751 285 bool HasFont() const;
23324ae1
FM
286
287 /**
288 Returns @true if the attribute object specifies an encoding.
289 */
328f5751 290 bool HasFontEncoding() const;
23324ae1
FM
291
292 /**
293 Returns @true if the attribute object specifies a font face name.
294 */
328f5751 295 bool HasFontFaceName() const;
23324ae1
FM
296
297 /**
298 Returns @true if the attribute object specifies italic style.
299 */
328f5751 300 bool HasFontItalic() const;
23324ae1
FM
301
302 /**
303 Returns @true if the attribute object specifies a font point size.
304 */
328f5751 305 bool HasFontSize() const;
23324ae1
FM
306
307 /**
308 Returns @true if the attribute object specifies either underlining or no
309 underlining.
310 */
328f5751 311 bool HasFontUnderlined() const;
23324ae1
FM
312
313 /**
314 Returns @true if the attribute object specifies font weight (bold, light or
315 normal).
316 */
328f5751 317 bool HasFontWeight() const;
23324ae1
FM
318
319 /**
320 Returns @true if the attribute object specifies a left indent.
321 */
328f5751 322 bool HasLeftIndent() const;
23324ae1
FM
323
324 /**
325 Returns @true if the attribute object specifies line spacing.
326 */
328f5751 327 bool HasLineSpacing() const;
23324ae1
FM
328
329 /**
330 Returns @true if the attribute object specifies a list style name.
331 */
328f5751 332 bool HasListStyleName() const;
23324ae1
FM
333
334 /**
335 Returns @true if the attribute object specifies an outline level.
336 */
328f5751 337 bool HasOutlineLevel() const;
23324ae1
FM
338
339 /**
340 Returns @true if the attribute object specifies a page break before this
341 paragraph.
342 */
328f5751 343 bool HasPageBreak() const;
23324ae1
FM
344
345 /**
346 Returns @true if the attribute object specifies spacing after a paragraph.
347 */
328f5751 348 bool HasParagraphSpacingAfter() const;
23324ae1
FM
349
350 /**
351 Returns @true if the attribute object specifies spacing before a paragraph.
352 */
328f5751 353 bool HasParagraphSpacingBefore() const;
23324ae1
FM
354
355 /**
356 Returns @true if the attribute object specifies a paragraph style name.
357 */
328f5751 358 bool HasParagraphStyleName() const;
23324ae1
FM
359
360 /**
361 Returns @true if the attribute object specifies a right indent.
362 */
328f5751 363 bool HasRightIndent() const;
23324ae1
FM
364
365 /**
366 Returns @true if the attribute object specifies tab stops.
367 */
328f5751 368 bool HasTabs() const;
23324ae1
FM
369
370 /**
371 Returns @true if the attribute object specifies a text foreground colour.
372 */
328f5751 373 bool HasTextColour() const;
23324ae1
FM
374
375 /**
376 Returns @true if the attribute object specifies text effects.
377 */
328f5751 378 bool HasTextEffects() const;
23324ae1
FM
379
380 /**
381 Returns @true if the attribute object specifies a URL.
382 */
328f5751 383 bool HasURL() const;
23324ae1
FM
384
385 /**
386 Returns @true if the object represents a character style, that is,
387 the flags specify a font or a text background or foreground colour.
388 */
328f5751 389 bool IsCharacterStyle() const;
23324ae1
FM
390
391 /**
392 Returns @false if we have any attributes set, @true otherwise.
393 */
328f5751 394 bool IsDefault() const;
23324ae1
FM
395
396 /**
397 Returns @true if the object represents a paragraph style, that is,
398 the flags specify alignment, indentation, tabs, paragraph spacing, or
399 bullet style.
400 */
328f5751 401 bool IsParagraphStyle() const;
23324ae1
FM
402
403 //@{
404 /**
4cc4bfaf 405 Creates a new @c wxTextAttr which is a merge of @a base and
756e6e49
VZ
406 @a overlay. Properties defined in @a overlay take precedence over those
407 in @a base. Properties undefined/invalid in both are undefined in the
23324ae1
FM
408 result.
409 */
410 void Merge(const wxTextAttr& overlay);
7c913512
FM
411 static wxTextAttr Merge(const wxTextAttr& base,
412 const wxTextAttr& overlay);
23324ae1
FM
413 //@}
414
415 /**
756e6e49 416 Sets the paragraph alignment. These are the possible values for @a alignment:
3c4f71cc 417
23324ae1
FM
418 Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented. In future justification
419 may be supported
420 when printing or previewing, only.
421 */
422 void SetAlignment(wxTextAttrAlignment alignment);
423
424 /**
425 Sets the background colour.
426 */
427 void SetBackgroundColour(const wxColour& colBack);
428
429 /**
430 Sets the name of the font associated with the bullet symbol.
431 Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
432 */
433 void SetBulletFont(const wxString& font);
434
435 /**
436 Sets the standard bullet name, applicable if the bullet style is
437 wxTEXT_ATTR_BULLET_STYLE_STANDARD.
438 See GetBulletName() for a list
439 of supported names, and how to expand the range of supported types.
440 */
441 void SetBulletName(const wxString& name);
442
443 /**
444 Sets the bullet number.
445 */
446 void SetBulletNumber(int n);
447
448 /**
449 Sets the bullet style. The following styles can be passed:
3c4f71cc 450
23324ae1
FM
451 Currently wxTEXT_ATTR_BULLET_STYLE_BITMAP is not supported.
452 */
453 void SetBulletStyle(int style);
454
455 /**
456 Sets the bullet text, which could be a symbol, or (for example) cached outline
457 text.
458 */
459 void SetBulletText(const wxString text);
460
461 /**
462 Sets the character style name.
463 */
464 void SetCharacterStyleName(const wxString& name);
465
466 /**
467 Sets the flags determining which styles are being specified. The following
468 flags can be passed in a bitlist:
469 */
470 void SetFlags(long flags);
471
472 /**
473 Sets the attributes for the given font. Note that wxTextAttr does not store an
474 actual wxFont object.
475 */
476 void SetFont(const wxFont& font);
477
478 /**
479 Sets the font encoding.
480 */
481 void SetFontEncoding(wxFontEncoding encoding);
482
483 /**
484 Sets the paragraph alignment.
485 */
486 void SetFontFaceName(const wxString& faceName);
487
488 /**
489 Sets the font size in points.
490 */
491 void SetFontSize(int pointSize);
492
493 /**
494 Sets the font style (normal, italic or slanted).
495 */
496 void SetFontStyle(int fontStyle);
497
498 /**
499 Sets the font underlining.
500 */
501 void SetFontUnderlined(bool underlined);
502
503 /**
504 Sets the font weight.
505 */
506 void SetFontWeight(int fontWeight);
507
508 /**
509 Sets the left indent and left subindent in tenths of a millimetre.
23324ae1
FM
510 The sub-indent is an offset from the left of the paragraph, and is used for all
511 but the
512 first line in a paragraph. A positive value will cause the first line to appear
513 to the left
514 of the subsequent lines, and a negative value will cause the first line to be
515 indented
516 relative to the subsequent lines.
23324ae1
FM
517 wxRichTextBuffer uses indentation to render a bulleted item. The left indent is
518 the distance between
519 the margin and the bullet. The content of the paragraph, including the first
520 line, starts
521 at leftMargin + leftSubIndent. So the distance between the left edge of the
522 bullet and the
523 left of the actual paragraph is leftSubIndent.
524 */
525 void SetLeftIndent(int indent, int subIndent = 0);
526
527 /**
4cc4bfaf 528 Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
23324ae1
FM
529 15 means 1.5 spacing, and 20 means double spacing. The following constants are
530 defined for convenience:
531 */
532 void SetLineSpacing(int spacing);
533
534 /**
535 Sets the list style name.
536 */
537 void SetListStyleName(const wxString& name);
538
539 /**
540 Specifies the outline level. Zero represents normal text. At present, the
541 outline level is
542 not used, but may be used in future for determining list levels and for
543 applications
544 that need to store document structure information.
545 */
546 void SetOutlineLevel(int level);
547
548 /**
549 Specifies a page break before this paragraph.
550 */
4cc4bfaf 551 void SetPageBreak(bool pageBreak = true);
23324ae1
FM
552
553 /**
554 Sets the spacing after a paragraph, in tenths of a millimetre.
555 */
556 void SetParagraphSpacingAfter(int spacing);
557
558 /**
559 Sets the spacing before a paragraph, in tenths of a millimetre.
560 */
561 void SetParagraphSpacingBefore(int spacing);
562
563 /**
564 Sets the name of the paragraph style.
565 */
566 void SetParagraphStyleName(const wxString& name);
567
568 /**
569 Sets the right indent in tenths of a millimetre.
570 */
571 void SetRightIndent(int indent);
572
573 /**
574 Sets the tab stops, expressed in tenths of a millimetre.
575 Each stop is measured from the left margin and therefore each value must be
576 larger than the last.
577 */
578 void SetTabs(const wxArrayInt& tabs);
579
580 /**
581 Sets the text foreground colout.
582 */
583 void SetTextColour(const wxColour& colText);
584
585 /**
586 Sets the text effect bits of interest. You should also pass wxTEXT_ATTR_EFFECTS
587 to SetFlags().
588 See SetFlags() for further information.
589 */
590 void SetTextEffectFlags(int flags);
591
592 /**
593 Sets the text effects, a bit list of styles.
23324ae1 594 The following styles can be passed:
3c4f71cc 595
23324ae1
FM
596 Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
597 are implemented.
598 wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
599 of the actual buffer
600 text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws a line through text.
23324ae1
FM
601 To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
602 SetTextEffectFlags() with the styles (taken from the
603 above set) that you are interested in setting.
604 */
605 void SetTextEffects(int effects);
606
607 /**
608 Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
609 style
610 causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
611 generates
612 a wxTextUrlEvent when the content is clicked.
613 */
4cc4bfaf 614 void SetURL(const wxString& url);
23324ae1
FM
615
616 /**
617 Assignment from a wxTextAttr object.
618 */
619 void operator operator=(const wxTextAttr& attr);
620};
621
756e6e49
VZ
622/**
623 Describes the possible return values of wxTextCtrl::HitTest().
624
625 The element names correspond to the relationship between the point asked
626 for and the character returned, e.g. @c wxTE_HT_BEFORE means that the point
627 is before (leftward or upward) it and so on.
628 */
629enum wxTextCtrlHitTestResult
630{
631 /// Indicates that wxTextCtrl::HitTest() is not implemented on this
632 /// platform.
633 wxTE_HT_UNKNOWN = -2,
634
635 /// The point is before the character returned.
636 wxTE_HT_BEFORE,
637
638 /// The point is directly on the character returned.
639 wxTE_HT_ON_TEXT,
640
641 /// The point is below the last line of the control.
642 wxTE_HT_BELOW,
643
644 /// The point is beyond the end of line containing the character returned.
645 wxTE_HT_BEYOND
646};
23324ae1 647
e54c96f1 648
23324ae1
FM
649/**
650 @class wxTextCtrl
651 @wxheader{textctrl.h}
7c913512 652
756e6e49
VZ
653 A text control allows text to be displayed and edited.
654
655 It may be single line or multi-line.
7c913512 656
23324ae1 657 @beginStyleTable
8c6791e4 658 @style{wxTE_PROCESS_ENTER}
23324ae1
FM
659 The control will generate the event wxEVT_COMMAND_TEXT_ENTER
660 (otherwise pressing Enter key is either processed internally by the
661 control or used for navigation between dialog controls).
8c6791e4 662 @style{wxTE_PROCESS_TAB}
23324ae1
FM
663 The control will receive wxEVT_CHAR events for TAB pressed -
664 normally, TAB is used for passing to the next control in a dialog
665 instead. For the control created with this style, you can still use
666 Ctrl-Enter to pass to the next control from the keyboard.
8c6791e4 667 @style{wxTE_MULTILINE}
23324ae1 668 The text control allows multiple lines.
8c6791e4 669 @style{wxTE_PASSWORD}
23324ae1 670 The text will be echoed as asterisks.
8c6791e4 671 @style{wxTE_READONLY}
23324ae1 672 The text will not be user-editable.
8c6791e4 673 @style{wxTE_RICH}
23324ae1
FM
674 Use rich text control under Win32, this allows to have more than
675 64KB of text in the control even under Win9x. This style is ignored
676 under other platforms.
8c6791e4 677 @style{wxTE_RICH2}
23324ae1
FM
678 Use rich text control version 2.0 or 3.0 under Win32, this style is
679 ignored under other platforms
8c6791e4 680 @style{wxTE_AUTO_URL}
23324ae1
FM
681 Highlight the URLs and generate the wxTextUrlEvents when mouse
682 events occur over them. This style is only supported for wxTE_RICH
683 Win32 and multi-line wxGTK2 text controls.
8c6791e4 684 @style{wxTE_NOHIDESEL}
23324ae1
FM
685 By default, the Windows text control doesn't show the selection
686 when it doesn't have focus - use this style to force it to always
687 show it. It doesn't do anything under other platforms.
8c6791e4 688 @style{wxHSCROLL}
23324ae1
FM
689 A horizontal scrollbar will be created and used, so that text won't
690 be wrapped. No effect under wxGTK1.
8c6791e4 691 @style{wxTE_NO_VSCROLL}
23324ae1
FM
692 For multiline controls only: vertical scrollbar will never be
693 created. This limits the amount of text which can be entered into
694 the control to what can be displayed in it under MSW but not under
695 GTK2. Currently not implemented for the other platforms.
8c6791e4 696 @style{wxTE_LEFT}
23324ae1 697 The text in the control will be left-justified (default).
8c6791e4 698 @style{wxTE_CENTRE}
23324ae1
FM
699 The text in the control will be centered (currently wxMSW and
700 wxGTK2 only).
8c6791e4 701 @style{wxTE_RIGHT}
23324ae1
FM
702 The text in the control will be right-justified (currently wxMSW
703 and wxGTK2 only).
8c6791e4 704 @style{wxTE_DONTWRAP}
23324ae1
FM
705 Same as wxHSCROLL style: don't wrap at all, show horizontal
706 scrollbar instead.
8c6791e4 707 @style{wxTE_CHARWRAP}
23324ae1
FM
708 Wrap the lines too long to be shown entirely at any position
709 (wxUniv and wxGTK2 only).
8c6791e4 710 @style{wxTE_WORDWRAP}
23324ae1
FM
711 Wrap the lines too long to be shown entirely at word boundaries
712 (wxUniv and wxGTK2 only).
8c6791e4 713 @style{wxTE_BESTWRAP}
23324ae1
FM
714 Wrap the lines at word boundaries or at any other character if
715 there are words longer than the window width (this is the default).
8c6791e4 716 @style{wxTE_CAPITALIZE}
23324ae1
FM
717 On PocketPC and Smartphone, causes the first letter to be
718 capitalized.
719 @endStyleTable
7c913512 720
756e6e49
VZ
721
722 @section textctrl_text_format wxTextCtrl Text Format
723
724 The multiline text controls always store the text as a sequence of lines
725 separated by @c '\\n' characters, i.e. in the Unix text format even on
726 non-Unix platforms. This allows the user code to ignore the differences
727 between the platforms but at a price: the indices in the control such as
728 those returned by GetInsertionPoint() or GetSelection() can @b not be used
729 as indices into the string returned by GetValue() as they're going to be
730 slightly off for platforms using @c "\\r\\n" as separator (as Windows
731 does).
732
733 Instead, if you need to obtain a substring between the 2 indices obtained
734 from the control with the help of the functions mentioned above, you should
735 use GetRange(). And the indices themselves can only be passed to other
736 methods, for example SetInsertionPoint() or SetSelection().
737
738 To summarize: never use the indices returned by (multiline) wxTextCtrl as
739 indices into the string it contains, but only as arguments to be passed
740 back to the other wxTextCtrl methods. This problem doesn't arise for
741 single-line platforms however where the indices in the control do
742 correspond to the positions in the value string.
743
744
745 @section textctrl_styles wxTextCtrl Styles.
746
747 Multi-line text controls support styling, i.e. provide a possibility to set
748 colours and font for individual characters in it (note that under Windows
749 @c wxTE_RICH style is required for style support). To use the styles you
750 can either call SetDefaultStyle() before inserting the text or call
751 SetStyle() later to change the style of the text already in the control
752 (the first solution is much more efficient).
753
754 In either case, if the style doesn't specify some of the attributes (for
755 example you only want to set the text colour but without changing the font
756 nor the text background), the values of the default style will be used for
757 them. If there is no default style, the attributes of the text control
758 itself are used.
759
760 So the following code correctly describes what it does: the second call to
761 SetDefaultStyle() doesn't change the text foreground colour (which stays
762 red) while the last one doesn't change the background colour (which stays
763 grey):
764
765 @code
766 text->SetDefaultStyle(wxTextAttr(*wxRED));
767 text->AppendText("Red text\n");
768 text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
769 text->AppendText("Red on grey text\n");
770 text->SetDefaultStyle(wxTextAttr(*wxBLUE);
771 text->AppendText("Blue on grey text\n");
772 @endcode
773
774
775 @section textctrl_cpp_streams wxTextCtrl and C++ Streams
776
777 This class multiply-inherits from @c std::streambuf (except for some really
778 old compilers using non-standard iostream library), allowing code such as
779 the following:
780
781 @code
782 wxTextCtrl *control = new wxTextCtrl(...);
783
784 ostream stream(control)
785
786 stream << 123.456 << " some text\n";
787 stream.flush();
788 @endcode
789
790 Note that even if your compiler doesn't support this (the symbol
791 @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use
792 wxTextCtrl itself in a stream-like manner:
793
794 @code
795 wxTextCtrl *control = new wxTextCtrl(...);
796
797 *control << 123.456 << " some text\n";
798 @endcode
799
800 However the possibility to create an ostream associated with wxTextCtrl may
801 be useful if you need to redirect the output of a function taking an
802 ostream as parameter to a text control.
803
804 Another commonly requested need is to redirect @c std::cout to the text
805 control. This may be done in the following way:
806
807 @code
808 #include <iostream>
809
810 wxTextCtrl *control = new wxTextCtrl(...);
811
812 std::streambuf *sbOld = std::cout.rdbuf();
813 std::cout.rdbuf(control);
814
815 // use cout as usual, the output appears in the text control
816 ...
817
818 std::cout.rdbuf(sbOld);
819 @endcode
820
821 But wxWidgets provides a convenient class to make it even simpler so
822 instead you may just do
823
824 @code
825 #include <iostream>
826
827 wxTextCtrl *control = new wxTextCtrl(...);
828
829 wxStreamToTextRedirector redirect(control);
830
831 // all output to cout goes into the text control until the exit from
832 // current scope
833 @endcode
834
835 See wxStreamToTextRedirector for more details.
836
837
838 @section textctrl_event_handling Event Handling.
839
840 The following commands are processed by default event handlers in
841 wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c
842 wxID_REDO. The associated UI update events are also processed
843 automatically, when the control has the focus.
844
845 To process input from a text control, use these event handler macros to
846 direct input to member functions that take a wxCommandEvent argument.
847
848 @beginEventTable{wxCommandEvent}
849 @event{EVT_TEXT(id, func)}
850 Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
851 changes. Notice that this event will be sent when the text controls
852 contents changes -- whether this is due to user input or comes from the
853 program itself (for example, if SetValue() is called); see
854 ChangeValue() for a function which does not send this event.} This
855 event is however not sent during the control creation.
856
857 @event{EVT_TEXT_ENTER(id, func)}
858 Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
859 pressed in a text control which must have wxTE_PROCESS_ENTER style for
860 this event to be generated.
861
862 @event{EVT_TEXT_URL(id, func}}
863 A mouse event occurred over an URL in the text control (wxMSW and
864 wxGTK2 only currently).
865
866 @event{EVT_TEXT_MAXLEN(id, func}}
867 This event is generated when the user tries to enter more text into the
868 control than the limit set by SetMaxLength(), see its description.
869 @endEventTable
870
23324ae1
FM
871 @library{wxcore}
872 @category{ctrl}
0c7fe6f2 873 <!-- @appearance{textctrl.png} -->
7c913512 874
e54c96f1 875 @see wxTextCtrl::Create, wxValidator
23324ae1
FM
876*/
877class wxTextCtrl : public wxControl
878{
879public:
880 //@{
881 /**
882 Constructor, creating and showing a text control.
3c4f71cc 883
7c913512 884 @param parent
4cc4bfaf 885 Parent window. Should not be @NULL.
7c913512 886 @param id
4cc4bfaf 887 Control identifier. A value of -1 denotes a default value.
7c913512 888 @param value
4cc4bfaf 889 Default text value.
7c913512 890 @param pos
4cc4bfaf 891 Text control position.
7c913512 892 @param size
4cc4bfaf 893 Text control size.
7c913512 894 @param style
4cc4bfaf 895 Window style. See wxTextCtrl.
7c913512 896 @param validator
4cc4bfaf 897 Window validator.
7c913512 898 @param name
4cc4bfaf 899 Window name.
3c4f71cc 900
23324ae1 901 @remarks The horizontal scrollbar (wxHSCROLL style flag) will only be
756e6e49
VZ
902 created for multi-line text controls. Without a horizontal
903 scrollbar, text lines that don't fit in the control's size will be
904 wrapped (but no newline character is inserted). Single line
905 controls don't have a horizontal scrollbar, the text is
906 automatically scrolled so that the insertion point is always
907 visible.
3c4f71cc 908
4cc4bfaf 909 @see Create(), wxValidator
23324ae1
FM
910 */
911 wxTextCtrl();
7c913512
FM
912 wxTextCtrl(wxWindow* parent, wxWindowID id,
913 const wxString& value = "",
914 const wxPoint& pos = wxDefaultPosition,
915 const wxSize& size = wxDefaultSize,
916 long style = 0,
917 const wxValidator& validator = wxDefaultValidator,
918 const wxString& name = wxTextCtrlNameStr);
23324ae1
FM
919 //@}
920
921 /**
922 Destructor, destroying the text control.
923 */
924 ~wxTextCtrl();
925
926 /**
927 Appends the text to the end of the text control.
3c4f71cc 928
7c913512 929 @param text
4cc4bfaf 930 Text to write to the text control.
3c4f71cc 931
23324ae1 932 @remarks After the text is appended, the insertion point will be at the
756e6e49
VZ
933 end of the text control. If this behaviour is not desired, the
934 programmer should use GetInsertionPoint and SetInsertionPoint.
3c4f71cc 935
4cc4bfaf 936 @see WriteText()
23324ae1
FM
937 */
938 void AppendText(const wxString& text);
939
940 /**
756e6e49
VZ
941 Call this function to enable auto-completion of the text typed in a
942 single-line text control using the given @a choices.
943
944 Notice that currently this function is only implemented in wxGTK2 and
945 wxMSW ports and does nothing under the other platforms.
3c4f71cc 946
1e24c2af 947 @since 2.9.0
3c4f71cc 948
756e6e49
VZ
949 @return
950 @true if the auto-completion was enabled or @false if the operation
951 failed, typically because auto-completion is not supported by the
952 current platform.
3c4f71cc 953
4cc4bfaf 954 @see AutoCompleteFileNames()
23324ae1
FM
955 */
956 bool AutoComplete(const wxArrayString& choices);
957
958 /**
756e6e49
VZ
959 Call this function to enable auto-completion of the text typed in a
960 single-line text control using all valid file system paths.
961
962 Notice that currently this function is only implemented in wxGTK2 port
963 and does nothing under the other platforms.
3c4f71cc 964
1e24c2af 965 @since 2.9.0
3c4f71cc 966
756e6e49
VZ
967 @return
968 @true if the auto-completion was enabled or @false if the operation
969 failed, typically because auto-completion is not supported by the
970 current platform.
3c4f71cc 971
4cc4bfaf 972 @see AutoComplete()
23324ae1
FM
973 */
974 bool AutoCompleteFileNames();
975
976 /**
977 Returns @true if the selection can be copied to the clipboard.
978 */
979 virtual bool CanCopy();
980
981 /**
982 Returns @true if the selection can be cut to the clipboard.
983 */
984 virtual bool CanCut();
985
986 /**
987 Returns @true if the contents of the clipboard can be pasted into the
756e6e49
VZ
988 text control.
989
990 On some platforms (Motif, GTK) this is an approximation and returns
991 @true if the control is editable, @false otherwise.
23324ae1
FM
992 */
993 virtual bool CanPaste();
994
995 /**
756e6e49
VZ
996 Returns @true if there is a redo facility available and the last
997 operation can be redone.
23324ae1
FM
998 */
999 virtual bool CanRedo();
1000
1001 /**
756e6e49
VZ
1002 Returns @true if there is an undo facility available and the last
1003 operation can be undone.
23324ae1
FM
1004 */
1005 virtual bool CanUndo();
1006
1007 /**
756e6e49
VZ
1008 Sets the text value and marks the control as not-modified (which means
1009 that IsModified() would return @false immediately after the call to
1010 SetValue).
1011
1012 This functions does not generate the @c wxEVT_COMMAND_TEXT_UPDATED
1013 event but otherwise is identical to SetValue().
23324ae1 1014 See @ref overview_progevent "this topic" for more information.
3c4f71cc 1015
1e24c2af 1016 @since 2.7.1
3c4f71cc 1017
7c913512 1018 @param value
756e6e49
VZ
1019 The new value to set. It may contain newline characters if the text
1020 control is multi-line.
23324ae1
FM
1021 */
1022 virtual void ChangeValue(const wxString& value);
1023
1024 /**
1025 Clears the text in the control.
756e6e49 1026
23324ae1 1027 Note that this function will generate a @c wxEVT_COMMAND_TEXT_UPDATED
756e6e49 1028 event, i.e. its effect is identical to calling @c SetValue("").
23324ae1
FM
1029 */
1030 virtual void Clear();
1031
1032 /**
756e6e49 1033 Copies the selected text to the clipboard.
23324ae1
FM
1034 */
1035 virtual void Copy();
1036
1037 /**
756e6e49
VZ
1038 Creates the text control for two-step construction.
1039
1040 This method should be called if the default constructor was used for
1041 the control creation. Its parameters have the same meaning as for the
1042 non-default constructor.
23324ae1
FM
1043 */
1044 bool Create(wxWindow* parent, wxWindowID id,
1045 const wxString& value = "",
1046 const wxPoint& pos = wxDefaultPosition,
1047 const wxSize& size = wxDefaultSize,
1048 long style = 0,
1049 const wxValidator& validator = wxDefaultValidator,
1050 const wxString& name = wxTextCtrlNameStr);
1051
1052 /**
1053 Copies the selected text to the clipboard and removes the selection.
1054 */
4cc4bfaf 1055 virtual void Cut();
23324ae1
FM
1056
1057 /**
756e6e49
VZ
1058 Resets the internal modified flag as if the current changes had been
1059 saved.
23324ae1
FM
1060 */
1061 void DiscardEdits();
1062
1063 /**
756e6e49
VZ
1064 This functions inserts into the control the character which would have
1065 been inserted if the given key event had occurred in the text control.
1066
1067 The @a event object should be the same as the one passed to @c
1068 EVT_KEY_DOWN handler previously by wxWidgets. Please note that this
1069 function doesn't currently work correctly for all keys under any
1070 platform but MSW.
3c4f71cc 1071
756e6e49
VZ
1072 @return
1073 @true if the event resulted in a change to the control, @false
1074 otherwise.
23324ae1
FM
1075 */
1076 bool EmulateKeyPress(const wxKeyEvent& event);
1077
1078 /**
1079 Returns the style currently used for the new text.
3c4f71cc 1080
4cc4bfaf 1081 @see SetDefaultStyle()
23324ae1 1082 */
328f5751 1083 const wxTextAttr GetDefaultStyle() const;
23324ae1
FM
1084
1085 /**
756e6e49
VZ
1086 Returns the insertion point, or cursor, position.
1087
1088 This is defined as the zero based index of the character position to
1089 the right of the insertion point. For example, if the insertion point
1090 is at the end of the single-line text control, it is equal to both
1091 GetLastPosition() and GetValue().length() (but notice that the latter
1092 equality is not necessarily true for multiline edit controls which may
1093 use multiple new line characters).
23324ae1 1094 */
328f5751 1095 virtual long GetInsertionPoint() const;
23324ae1
FM
1096
1097 /**
1098 Returns the zero based index of the last position in the text control,
1099 which is equal to the number of characters in the control.
1100 */
328f5751 1101 virtual wxTextPos GetLastPosition() const;
23324ae1
FM
1102
1103 /**
756e6e49
VZ
1104 Gets the length of the specified line, not including any trailing
1105 newline character(s).
3c4f71cc 1106
7c913512 1107 @param lineNo
4cc4bfaf 1108 Line number (starting from zero).
3c4f71cc 1109
756e6e49
VZ
1110 @return
1111 The length of the line, or -1 if @a lineNo was invalid.
23324ae1 1112 */
328f5751 1113 int GetLineLength(long lineNo) const;
23324ae1
FM
1114
1115 /**
1116 Returns the contents of a given line in the text control, not including
1117 any trailing newline character(s).
3c4f71cc 1118
7c913512 1119 @param lineNo
4cc4bfaf 1120 The line number, starting from zero.
3c4f71cc 1121
756e6e49
VZ
1122 @return
1123 The contents of the line.
23324ae1 1124 */
328f5751 1125 wxString GetLineText(long lineNo) const;
23324ae1
FM
1126
1127 /**
1128 Returns the number of lines in the text control buffer.
3c4f71cc 1129
23324ae1 1130 @remarks Note that even empty text controls have one line (where the
4cc4bfaf
FM
1131 insertion point is), so GetNumberOfLines() never
1132 returns 0.
23324ae1 1133 */
328f5751 1134 int GetNumberOfLines() const;
23324ae1
FM
1135
1136 /**
756e6e49
VZ
1137 Returns the string containing the text starting in the positions
1138 @a from and up to @a to in the control.
1139
1140 The positions must have been returned by another wxTextCtrl method.
23324ae1 1141 Please note that the positions in a multiline wxTextCtrl do @b not
756e6e49
VZ
1142 correspond to the indices in the string returned by GetValue() because
1143 of the different new line representations (@c CR or @c CR LF) and so
1144 this method should be used to obtain the correct results instead of
1145 extracting parts of the entire value. It may also be more efficient,
1146 especially if the control contains a lot of data.
23324ae1 1147 */
328f5751 1148 virtual wxString GetRange(long from, long to) const;
23324ae1
FM
1149
1150 /**
756e6e49
VZ
1151 Gets the current selection span.
1152
1153 If the returned values are equal, there was no selection. Please note
1154 that the indices returned may be used with the other wxTextCtrl methods
1155 but don't necessarily represent the correct indices into the string
1156 returned by GetValue() for multiline controls under Windows (at least,)
1157 you should use GetStringSelection() to get the selected text.
3c4f71cc 1158
7c913512 1159 @param from
4cc4bfaf 1160 The returned first position.
7c913512 1161 @param to
4cc4bfaf 1162 The returned last position.
23324ae1 1163 */
328f5751 1164 virtual void GetSelection(long* from, long* to) const;
23324ae1
FM
1165
1166 /**
756e6e49
VZ
1167 Gets the text currently selected in the control.
1168
1169 If there is no selection, the returned string is empty.
23324ae1
FM
1170 */
1171 virtual wxString GetStringSelection();
1172
1173 /**
756e6e49
VZ
1174 Returns the style at this position in the text control.
1175
1176 Not all platforms support this function.
3c4f71cc 1177
756e6e49
VZ
1178 @return
1179 @true on success, @false if an error occurred (this may also mean
1180 that the styles are not supported under this platform).
3c4f71cc 1181
4cc4bfaf 1182 @see SetStyle(), wxTextAttr
23324ae1
FM
1183 */
1184 bool GetStyle(long position, wxTextAttr& style);
1185
1186 /**
756e6e49
VZ
1187 Gets the contents of the control.
1188 Notice that for a multiline text control, the lines will be separated
1189 by (Unix-style) @c \\n characters, even under Windows where they are
1190 separated by a @c \\r\\n sequence in the native control.
23324ae1 1191 */
328f5751 1192 wxString GetValue() const;
23324ae1
FM
1193
1194 /**
756e6e49
VZ
1195 This function finds the character at the specified position expressed
1196 in pixels.
1197
1198 If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
1199 character closest to this position are returned in the @a col and @a
1200 row parameters (unless the pointers are @NULL which is allowed). Please
1201 note that this function is currently only implemented in wxUniv, wxMSW
1202 and wxGTK2 ports.
3c4f71cc 1203
4cc4bfaf 1204 @see PositionToXY(), XYToPosition()
23324ae1
FM
1205 */
1206 wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1207 wxTextCoord col,
328f5751 1208 wxTextCoord row) const;
23324ae1
FM
1209
1210 /**
756e6e49
VZ
1211 Returns @true if the controls contents may be edited by user (note that
1212 it always can be changed by the program).
1213
1214 In other words, this functions returns @true if the control hasn't been
1215 put in read-only mode by a previous call to SetEditable().
23324ae1 1216 */
328f5751 1217 bool IsEditable() const;
23324ae1
FM
1218
1219 /**
756e6e49
VZ
1220 Returns @true if the control is currently empty.
1221
1222 This is the same as @c GetValue().empty() but can be much more
1223 efficient for the multiline controls containing big amounts of text.
3c4f71cc 1224
1e24c2af 1225 @since 2.7.1
23324ae1 1226 */
328f5751 1227 bool IsEmpty() const;
23324ae1
FM
1228
1229 /**
756e6e49
VZ
1230 Returns @true if the text has been modified by user.
1231
1232 Note that calling SetValue() doesn't make the control modified.
3c4f71cc 1233
4cc4bfaf 1234 @see MarkDirty()
23324ae1 1235 */
328f5751 1236 bool IsModified() const;
23324ae1
FM
1237
1238 /**
1239 Returns @true if this is a multi line edit control and @false
1240 otherwise.
3c4f71cc 1241
4cc4bfaf 1242 @see IsSingleLine()
23324ae1 1243 */
328f5751 1244 bool IsMultiLine() const;
23324ae1
FM
1245
1246 /**
1247 Returns @true if this is a single line edit control and @false
1248 otherwise.
3c4f71cc 1249
4cc4bfaf 1250 @see @ref issingleline() IsMultiLine
23324ae1 1251 */
328f5751 1252 bool IsSingleLine() const;
23324ae1
FM
1253
1254 /**
1255 Loads and displays the named file, if it exists.
3c4f71cc 1256
7c913512 1257 @param filename
4cc4bfaf 1258 The filename of the file to load.
7c913512 1259 @param fileType
4cc4bfaf 1260 The type of file to load. This is currently ignored in wxTextCtrl.
3c4f71cc 1261
756e6e49
VZ
1262 @return
1263 @true if successful, @false otherwise.
23324ae1
FM
1264 */
1265 bool LoadFile(const wxString& filename,
1266 int fileType = wxTEXT_TYPE_ANY);
1267
1268 /**
1269 Mark text as modified (dirty).
3c4f71cc 1270
4cc4bfaf 1271 @see IsModified()
23324ae1
FM
1272 */
1273 void MarkDirty();
1274
1275 /**
756e6e49
VZ
1276 This event handler function implements default drag and drop behaviour,
1277 which is to load the first dropped file into the control.
3c4f71cc 1278
7c913512 1279 @param event
4cc4bfaf 1280 The drop files event.
3c4f71cc 1281
23324ae1 1282 @remarks This is not implemented on non-Windows platforms.
3c4f71cc 1283
4cc4bfaf 1284 @see wxDropFilesEvent
23324ae1
FM
1285 */
1286 void OnDropFiles(wxDropFilesEvent& event);
1287
1288 /**
1289 Pastes text from the clipboard to the text item.
1290 */
1291 virtual void Paste();
1292
1293 /**
1294 Converts given position to a zero-based column, line number pair.
3c4f71cc 1295
7c913512 1296 @param pos
4cc4bfaf 1297 Position.
7c913512 1298 @param x
4cc4bfaf 1299 Receives zero based column number.
7c913512 1300 @param y
4cc4bfaf 1301 Receives zero based line number.
3c4f71cc 1302
756e6e49
VZ
1303 @return
1304 @true on success, @false on failure (most likely due to a too large
1305 position parameter).
3c4f71cc 1306
4cc4bfaf 1307 @see XYToPosition()
23324ae1 1308 */
328f5751 1309 bool PositionToXY(long pos, long* x, long* y) const;
23324ae1
FM
1310
1311 /**
756e6e49
VZ
1312 If there is a redo facility and the last operation can be redone,
1313 redoes the last operation.
1314
1315 Does nothing if there is no redo facility.
23324ae1
FM
1316 */
1317 virtual void Redo();
1318
1319 /**
756e6e49
VZ
1320 Removes the text starting at the first given position up to (but not
1321 including) the character at the last position.
3c4f71cc 1322
7c913512 1323 @param from
4cc4bfaf 1324 The first position.
7c913512 1325 @param to
4cc4bfaf 1326 The last position.
23324ae1
FM
1327 */
1328 virtual void Remove(long from, long to);
1329
1330 /**
756e6e49
VZ
1331 Replaces the text starting at the first position up to (but not
1332 including) the character at the last position with the given text.
3c4f71cc 1333
7c913512 1334 @param from
4cc4bfaf 1335 The first position.
7c913512 1336 @param to
4cc4bfaf 1337 The last position.
7c913512 1338 @param value
4cc4bfaf 1339 The value to replace the existing text with.
23324ae1
FM
1340 */
1341 virtual void Replace(long from, long to, const wxString& value);
1342
1343 /**
1344 Saves the contents of the control in a text file.
3c4f71cc 1345
7c913512 1346 @param filename
4cc4bfaf 1347 The name of the file in which to save the text.
7c913512 1348 @param fileType
4cc4bfaf 1349 The type of file to save. This is currently ignored in wxTextCtrl.
3c4f71cc 1350
756e6e49
VZ
1351 @return
1352 @true if the operation was successful, @false otherwise.
23324ae1
FM
1353 */
1354 bool SaveFile(const wxString& filename,
1355 int fileType = wxTEXT_TYPE_ANY);
1356
1357 /**
756e6e49
VZ
1358 Changes the default style to use for the new text which is going to be
1359 added to the control using WriteText() or AppendText().
1360
23324ae1 1361 If either of the font, foreground, or background colour is not set in
756e6e49
VZ
1362 @a style, the values of the previous default style are used for them.
1363 If the previous default style didn't set them neither, the global font
1364 or colours of the text control itself are used as fall back. However if
1365 the @a style parameter is the default wxTextAttr, then the default
1366 style is just reset (instead of being combined with the new style which
23324ae1 1367 wouldn't change it at all).
3c4f71cc 1368
7c913512 1369 @param style
4cc4bfaf 1370 The style for the new text.
3c4f71cc 1371
756e6e49
VZ
1372 @return
1373 @true on success, @false if an error occurred (this may also mean
1374 that the styles are not supported under this platform).
3c4f71cc 1375
4cc4bfaf 1376 @see GetDefaultStyle()
23324ae1
FM
1377 */
1378 bool SetDefaultStyle(const wxTextAttr& style);
1379
1380 /**
756e6e49
VZ
1381 Makes the text item editable or read-only, overriding the
1382 @b wxTE_READONLY flag.
3c4f71cc 1383
7c913512 1384 @param editable
756e6e49
VZ
1385 If @true, the control is editable. If @false, the control is
1386 read-only.
3c4f71cc 1387
4cc4bfaf 1388 @see IsEditable()
23324ae1
FM
1389 */
1390 virtual void SetEditable(const bool editable);
1391
1392 /**
1393 Sets the insertion point at the given position.
3c4f71cc 1394
7c913512 1395 @param pos
4cc4bfaf 1396 Position to set.
23324ae1
FM
1397 */
1398 virtual void SetInsertionPoint(long pos);
1399
1400 /**
756e6e49
VZ
1401 Sets the insertion point at the end of the text control.
1402
1403 This is equivalent to calling wxTextCtrl::SetInsertionPoint() with
1404 wxTextCtrl::GetLastPosition() argument.
23324ae1
FM
1405 */
1406 virtual void SetInsertionPointEnd();
1407
1408 /**
756e6e49
VZ
1409 This function sets the maximum number of characters the user can enter
1410 into the control.
1411
1412 In other words, it allows to limit the text value length to @a len not
1413 counting the terminating @c NUL character. If @a len is 0, the
1414 previously set max length limit, if any, is discarded and the user may
1415 enter as much text as the underlying native text control widget
1416 supports (typically at least 32Kb). If the user tries to enter more
1417 characters into the text control when it already is filled up to the
1418 maximal length, a @c wxEVT_COMMAND_TEXT_MAXLEN event is sent to notify
1419 the program about it (giving it the possibility to show an explanatory
1420 message, for example) and the extra input is discarded. Note that in
1421 wxGTK this function may only be used with single line text controls.
23324ae1
FM
1422 */
1423 virtual void SetMaxLength(unsigned long len);
1424
1425 /**
1426 Marks the control as being modified by the user or not.
3c4f71cc 1427
4cc4bfaf 1428 @see MarkDirty(), DiscardEdits()
23324ae1
FM
1429 */
1430 void SetModified(bool modified);
1431
1432 /**
5f5d1e48 1433 Selects the text starting at the first position up to (but not
756e6e49
VZ
1434 including) the character at the last position.
1435
1436 If both parameters are equal to -1 all text in the control is selected.
3c4f71cc 1437
7c913512 1438 @param from
4cc4bfaf 1439 The first position.
7c913512 1440 @param to
4cc4bfaf 1441 The last position.
5f5d1e48
VS
1442
1443 @see SelectAll()
23324ae1
FM
1444 */
1445 virtual void SetSelection(long from, long to);
1446
5f5d1e48
VS
1447 /**
1448 Selects all text in the control.
1449
1450 @see SetSelection()
1451 */
1452 virtual void SelectAll();
1453
23324ae1 1454 /**
756e6e49
VZ
1455 Changes the style of the given range.
1456
1457 If any attribute within @a style is not set, the corresponding
1458 attribute from GetDefaultStyle() is used.
3c4f71cc 1459
7c913512 1460 @param start
4cc4bfaf 1461 The start of the range to change.
7c913512 1462 @param end
4cc4bfaf 1463 The end of the range to change.
7c913512 1464 @param style
4cc4bfaf 1465 The new style for the range.
3c4f71cc 1466
756e6e49
VZ
1467 @return
1468 @true on success, @false if an error occurred (this may also mean
1469 that the styles are not supported under this platform).
3c4f71cc 1470
4cc4bfaf 1471 @see GetStyle(), wxTextAttr
23324ae1
FM
1472 */
1473 bool SetStyle(long start, long end, const wxTextAttr& style);
1474
1475 /**
756e6e49
VZ
1476 Sets the text value and marks the control as not-modified (which means
1477 that IsModified() would return @false immediately after the call to
1478 SetValue).
1479
1480 Note that this function generates a @c wxEVT_COMMAND_TEXT_UPDATED
1481 event, to avoid this you can use ChangeValue() instead.
3c4f71cc 1482
7c913512 1483 @param value
756e6e49
VZ
1484 The new value to set. It may contain newline characters if the text
1485 control is multi-line.
23324ae1
FM
1486 */
1487 virtual void SetValue(const wxString& value);
1488
1489 /**
1490 Makes the line containing the given position visible.
3c4f71cc 1491
7c913512 1492 @param pos
4cc4bfaf 1493 The position that should be visible.
23324ae1
FM
1494 */
1495 void ShowPosition(long pos);
1496
1497 /**
756e6e49
VZ
1498 If there is an undo facility and the last operation can be undone,
1499 undoes the last operation.
1500
1501 Does nothing if there is no undo facility.
23324ae1
FM
1502 */
1503 virtual void Undo();
1504
1505 /**
1506 Writes the text into the text control at the current insertion position.
3c4f71cc 1507
7c913512 1508 @param text
4cc4bfaf 1509 Text to write to the text control.
3c4f71cc 1510
23324ae1 1511 @remarks Newlines in the text string are the only control characters
756e6e49
VZ
1512 allowed, and they will cause appropriate line breaks. See () and
1513 AppendText() for more convenient ways of writing to the window.
23324ae1
FM
1514 */
1515 void WriteText(const wxString& text);
1516
1517 /**
1518 Converts the given zero based column and line number to a position.
3c4f71cc 1519
7c913512 1520 @param x
4cc4bfaf 1521 The column number.
7c913512 1522 @param y
4cc4bfaf 1523 The line number.
3c4f71cc 1524
756e6e49
VZ
1525 @return
1526 The position value, or -1 if x or y was invalid.
23324ae1
FM
1527 */
1528 long XYToPosition(long x, long y);
1529
1530 //@{
1531 /**
9e50ed28 1532 Operator definitions for appending to a text control.
756e6e49
VZ
1533
1534 These operators can be used as with the standard C++ streams, for
1535 example:
1536 @code
1537 wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1538
1539 (*wnd) << "Welcome to text control number " << 1 << ".\n";
1540 @endcode
9e50ed28 1541 */
756e6e49 1542
9e50ed28
VZ
1543 wxTextCtrl& operator<<(const wxString& s);
1544 wxTextCtrl& operator<<(int i);
1545 wxTextCtrl& operator<<(long i);
1546 wxTextCtrl& operator<<(float f);
1547 wxTextCtrl& operator<<(double d);
1548 wxTextCtrl& operator<<(char c);
1549 wxTextCtrl& operator<<(wchar_t c);
23324ae1
FM
1550 //@}
1551};
1552
1553
e54c96f1 1554
23324ae1
FM
1555/**
1556 @class wxStreamToTextRedirector
1557 @wxheader{textctrl.h}
7c913512 1558
23324ae1
FM
1559 This class can be used to (temporarily) redirect all output sent to a C++
1560 ostream object to a wxTextCtrl instead.
7c913512 1561
1f1d2182 1562 @note Some compilers and/or build configurations don't support multiply
23324ae1 1563 inheriting wxTextCtrl from @c std::streambuf in which
7c913512 1564 case this class is not compiled in. You also must have @c wxUSE_STD_IOSTREAM
23324ae1
FM
1565 option on (i.e. set to 1) in your setup.h to be able to use it. Under Unix,
1566 specify @c --enable-std_iostreams switch when running configure for this.
7c913512 1567
23324ae1 1568 Example of usage:
7c913512 1569
23324ae1
FM
1570 @code
1571 using namespace std;
7c913512 1572
23324ae1 1573 wxTextCtrl *text = new wxTextCtrl(...);
7c913512 1574
23324ae1
FM
1575 {
1576 wxStreamToTextRedirector redirect(text);
7c913512 1577
23324ae1
FM
1578 // this goes to the text control
1579 cout "Hello, text!" endl;
1580 }
7c913512 1581
23324ae1
FM
1582 // this goes somewhere else, presumably to stdout
1583 cout "Hello, console!" endl;
1584 @endcode
7c913512
FM
1585
1586
23324ae1
FM
1587 @library{wxcore}
1588 @category{logging}
7c913512 1589
e54c96f1 1590 @see wxTextCtrl
23324ae1 1591*/
7c913512 1592class wxStreamToTextRedirector
23324ae1
FM
1593{
1594public:
1595 /**
756e6e49
VZ
1596 The constructor starts redirecting output sent to @a ostr or @a cout for
1597 the default parameter value to the text control @a text.
3c4f71cc 1598
7c913512 1599 @param text
4cc4bfaf 1600 The text control to append output too, must be non-@NULL
7c913512 1601 @param ostr
4cc4bfaf 1602 The C++ stream to redirect, cout is used if it is @NULL
23324ae1 1603 */
4cc4bfaf 1604 wxStreamToTextRedirector(wxTextCtrl text, ostream* ostr = NULL);
23324ae1
FM
1605
1606 /**
1607 When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1608 and any output sent to the C++ ostream which had been specified at the time of
1609 the object construction will go to its original destination.
1610 */
1611 ~wxStreamToTextRedirector();
1612};
e54c96f1 1613