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