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