]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/textctrl.h
undo the last change as it results in buildbot configuration error
[wxWidgets.git] / interface / wx / textctrl.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: textctrl.h
e54c96f1 3// Purpose: interface of wxTextAttr
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
c6cf894a 9
c6cf894a 10/**
7d76fbd5 11 One of the following values can be passed to wxTextAttr::SetAlignment to determine paragraph alignment.
c6cf894a
FM
12*/
13enum 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*/
30enum wxTextAttrFlags
31{
32 wxTEXT_ATTR_TEXT_COLOUR = 0x00000001,
33 wxTEXT_ATTR_BACKGROUND_COLOUR = 0x00000002,
7d76fbd5 34
c6cf894a
FM
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,
9c4cb611 41 wxTEXT_ATTR_FONT_FAMILY = 0x04000000,
7d76fbd5
FM
42
43 /**
44 Defined as the combination of all @c wxTEXT_ATTR_FONT_* values above.
45 */
c6cf894a
FM
46 wxTEXT_ATTR_FONT = \
47 ( wxTEXT_ATTR_FONT_FACE | wxTEXT_ATTR_FONT_SIZE | wxTEXT_ATTR_FONT_WEIGHT | \
9c4cb611 48 wxTEXT_ATTR_FONT_ITALIC | wxTEXT_ATTR_FONT_UNDERLINE | wxTEXT_ATTR_FONT_ENCODING | wxTEXT_ATTR_FONT_FAMILY ),
c6cf894a
FM
49
50 wxTEXT_ATTR_ALIGNMENT = 0x00000080,
51 wxTEXT_ATTR_LEFT_INDENT = 0x00000100,
52 wxTEXT_ATTR_RIGHT_INDENT = 0x00000200,
53 wxTEXT_ATTR_TABS = 0x00000400,
c6cf894a
FM
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,
7d76fbd5 60
c6cf894a
FM
61 wxTEXT_ATTR_BULLET_STYLE = 0x00020000,
62 wxTEXT_ATTR_BULLET_NUMBER = 0x00040000,
63 wxTEXT_ATTR_BULLET_TEXT = 0x00080000,
64 wxTEXT_ATTR_BULLET_NAME = 0x00100000,
7d76fbd5
FM
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
c6cf894a
FM
73 wxTEXT_ATTR_URL = 0x00200000,
74 wxTEXT_ATTR_PAGE_BREAK = 0x00400000,
75 wxTEXT_ATTR_EFFECTS = 0x00800000,
76 wxTEXT_ATTR_OUTLINE_LEVEL = 0x01000000,
77
78 /**
7d76fbd5
FM
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.
c6cf894a
FM
81 */
82
83 wxTEXT_ATTR_CHARACTER = \
9c4cb611 84 (wxTEXT_ATTR_FONT|wxTEXT_ATTR_EFFECTS| \
c6cf894a
FM
85 wxTEXT_ATTR_BACKGROUND_COLOUR|wxTEXT_ATTR_TEXT_COLOUR|wxTEXT_ATTR_CHARACTER_STYLE_NAME|wxTEXT_ATTR_URL),
86
7d76fbd5
FM
87 /**
88 Combines all the styles regarding text paragraphs.
89 */
c6cf894a
FM
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|\
7d76fbd5 93 wxTEXT_ATTR_BULLET|wxTEXT_ATTR_PARAGRAPH_STYLE_NAME|wxTEXT_ATTR_LIST_STYLE_NAME|wxTEXT_ATTR_OUTLINE_LEVEL),
c6cf894a 94
7d76fbd5
FM
95 /**
96 Combines all previous values.
97 */
c6cf894a
FM
98 wxTEXT_ATTR_ALL = (wxTEXT_ATTR_CHARACTER|wxTEXT_ATTR_PARAGRAPH)
99};
100
101/**
7d76fbd5 102 Styles for wxTextAttr::SetBulletStyle. They can be combined together as a bitlist.
c6cf894a
FM
103*/
104enum 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/**
7d76fbd5 128 Styles for wxTextAttr::SetTextEffects(). They can be combined together as a bitlist.
c6cf894a
FM
129
130 Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH are implemented.
131*/
132enum 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/**
7d76fbd5 148 Convenience line spacing values; see wxTextAttr::SetLineSpacing().
c6cf894a
FM
149*/
150enum 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 */
165enum 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
23324ae1
FM
185/**
186 @class wxTextAttr
7c913512 187
23324ae1
FM
188 wxTextAttr represents the character and paragraph attributes, or style,
189 for a range of text in a wxTextCtrl or wxRichTextCtrl.
7c913512 190
23324ae1 191 When setting up a wxTextAttr object, pass a bitlist mask to
c6cf894a
FM
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
756e6e49 194 will be set.
7c913512 195
23324ae1
FM
196 @library{wxcore}
197 @category{richtext}
7c913512 198
e54c96f1 199 @see wxTextCtrl, wxRichTextCtrl
23324ae1 200*/
7c913512 201class wxTextAttr
23324ae1
FM
202{
203public:
204 //@{
205 /**
206 Constructors.
207 */
208 wxTextAttr();
7c913512
FM
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);
23324ae1
FM
214 //@}
215
216 /**
4cc4bfaf
FM
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).
23324ae1
FM
219 */
220 bool Apply(const wxTextAttr& style,
4cc4bfaf 221 const wxTextAttr* compareWith = NULL);
23324ae1
FM
222
223 /**
224 Creates a font from the font attributes.
225 */
328f5751 226 wxFont CreateFont() const;
23324ae1 227
7d76fbd5
FM
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
23324ae1
FM
249 /**
250 Returns the alignment flags.
c6cf894a 251 See ::wxTextAttrAlignment for a list of available styles.
23324ae1 252 */
328f5751 253 wxTextAttrAlignment GetAlignment() const;
23324ae1
FM
254
255 /**
256 Returns the background colour.
257 */
c6cf894a 258 const wxColour& GetBackgroundColour() const;
23324ae1
FM
259
260 /**
c6cf894a 261 Returns a string containing the name of the font associated with the bullet symbol.
23324ae1
FM
262 Only valid for attributes with wxTEXT_ATTR_BULLET_SYMBOL.
263 */
c6cf894a 264 const wxString& GetBulletFont() const;
23324ae1
FM
265
266 /**
267 Returns the standard bullet name, applicable if the bullet style is
268 wxTEXT_ATTR_BULLET_STYLE_STANDARD.
c6cf894a 269
23324ae1 270 Currently the following standard bullet names are supported:
c6cf894a
FM
271 - @c standard/circle
272 - @c standard/square
273 - @c standard/diamond
274 - @c standard/triangle
275
276 @note
23324ae1 277 For wxRichTextCtrl users only: if you wish your rich text controls to support
c6cf894a
FM
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.
23324ae1 281 */
c6cf894a 282 const wxString& GetBulletName() const;
23324ae1
FM
283
284 /**
285 Returns the bullet number.
286 */
328f5751 287 int GetBulletNumber() const;
23324ae1
FM
288
289 /**
290 Returns the bullet style.
c6cf894a 291 See ::wxTextAttrBulletStyle for a list of available styles.
23324ae1 292 */
328f5751 293 int GetBulletStyle() const;
23324ae1
FM
294
295 /**
296 Returns the bullet text, which could be a symbol, or (for example) cached
297 outline text.
298 */
43c48e1e 299 const wxString& GetBulletText() const;
23324ae1
FM
300
301 /**
302 Returns the name of the character style.
303 */
43c48e1e 304 const wxString& GetCharacterStyleName() const;
23324ae1
FM
305
306 /**
307 Returns flags indicating which attributes are applicable.
308 See SetFlags() for a list of available flags.
309 */
328f5751 310 long GetFlags() const;
23324ae1
FM
311
312 /**
313 Creates and returns a font specified by the font attributes in the wxTextAttr
c6cf894a
FM
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.
23324ae1 318 */
328f5751 319 wxFont GetFont() const;
23324ae1
FM
320
321 /**
322 Gets the font attributes from the given font, using only the attributes
756e6e49 323 specified by @a flags.
23324ae1
FM
324 */
325 bool GetFontAttributes(const wxFont& font,
326 int flags = wxTEXT_ATTR_FONT);
327
328 /**
329 Returns the font encoding.
330 */
328f5751 331 wxFontEncoding GetFontEncoding() const;
23324ae1
FM
332
333 /**
334 Returns the font face name.
335 */
43c48e1e 336 const wxString& GetFontFaceName() const;
23324ae1 337
9c4cb611
JS
338 /**
339 Returns the font family.
340 */
7d76fbd5 341 wxFontFamily GetFontFamily() const;
9c4cb611 342
23324ae1
FM
343 /**
344 Returns the font size in points.
345 */
328f5751 346 int GetFontSize() const;
23324ae1
FM
347
348 /**
349 Returns the font style.
350 */
7d76fbd5 351 wxFontStyle GetFontStyle() const;
23324ae1
FM
352
353 /**
354 Returns @true if the font is underlined.
355 */
328f5751 356 bool GetFontUnderlined() const;
23324ae1
FM
357
358 /**
359 Returns the font weight.
360 */
7d76fbd5 361 wxFontWeight GetFontWeight() const;
23324ae1
FM
362
363 /**
364 Returns the left indent in tenths of a millimetre.
365 */
328f5751 366 long GetLeftIndent() const;
23324ae1
FM
367
368 /**
369 Returns the left sub-indent in tenths of a millimetre.
370 */
328f5751 371 long GetLeftSubIndent() const;
23324ae1
FM
372
373 /**
c6cf894a 374 Returns the line spacing value, one of ::wxTextAttrLineSpacing values.
23324ae1 375 */
328f5751 376 int GetLineSpacing() const;
23324ae1
FM
377
378 /**
379 Returns the name of the list style.
380 */
43c48e1e 381 const wxString& GetListStyleName() const;
23324ae1
FM
382
383 /**
384 Returns the outline level.
385 */
43c48e1e 386 int GetOutlineLevel() const;
23324ae1
FM
387
388 /**
389 Returns the space in tenths of a millimeter after the paragraph.
390 */
328f5751 391 int GetParagraphSpacingAfter() const;
23324ae1
FM
392
393 /**
394 Returns the space in tenths of a millimeter before the paragraph.
395 */
328f5751 396 int GetParagraphSpacingBefore() const;
23324ae1
FM
397
398 /**
399 Returns the name of the paragraph style.
400 */
43c48e1e 401 const wxString& GetParagraphStyleName() const;
23324ae1
FM
402
403 /**
404 Returns the right indent in tenths of a millimeter.
405 */
328f5751 406 long GetRightIndent() const;
23324ae1
FM
407
408 /**
c6cf894a
FM
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.
23324ae1 413 */
43c48e1e 414 const wxArrayInt& GetTabs() const;
23324ae1
FM
415
416 /**
417 Returns the text foreground colour.
418 */
43c48e1e 419 const wxColour& GetTextColour() const;
23324ae1
FM
420
421 /**
c6cf894a
FM
422 Returns the text effect bits of interest.
423 See SetFlags() for further information.
23324ae1 424 */
328f5751 425 int GetTextEffectFlags() const;
23324ae1
FM
426
427 /**
c6cf894a
FM
428 Returns the text effects, a bit list of styles.
429 See SetTextEffects() for details.
23324ae1 430 */
328f5751 431 int GetTextEffects() const;
23324ae1
FM
432
433 /**
c6cf894a
FM
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.
23324ae1 439 */
43c48e1e 440 const wxString& GetURL() const;
23324ae1 441
7d76fbd5
FM
442 //@}
443
444
445
446 /**
447 @name HasXXX and IsXXX functions
448 */
449
450 //@{
451
23324ae1
FM
452 /**
453 Returns @true if the attribute object specifies alignment.
454 */
328f5751 455 bool HasAlignment() const;
23324ae1
FM
456
457 /**
458 Returns @true if the attribute object specifies a background colour.
459 */
328f5751 460 bool HasBackgroundColour() const;
23324ae1
FM
461
462 /**
463 Returns @true if the attribute object specifies a standard bullet name.
464 */
328f5751 465 bool HasBulletName() const;
23324ae1
FM
466
467 /**
468 Returns @true if the attribute object specifies a bullet number.
469 */
328f5751 470 bool HasBulletNumber() const;
23324ae1
FM
471
472 /**
473 Returns @true if the attribute object specifies a bullet style.
474 */
328f5751 475 bool HasBulletStyle() const;
23324ae1
FM
476
477 /**
478 Returns @true if the attribute object specifies bullet text (usually
479 specifying a symbol).
480 */
328f5751 481 bool HasBulletText() const;
23324ae1
FM
482
483 /**
484 Returns @true if the attribute object specifies a character style name.
485 */
328f5751 486 bool HasCharacterStyleName() const;
23324ae1
FM
487
488 /**
4cc4bfaf 489 Returns @true if the @a flag is present in the attribute object's flag
23324ae1
FM
490 bitlist.
491 */
328f5751 492 bool HasFlag(long flag) const;
23324ae1
FM
493
494 /**
495 Returns @true if the attribute object specifies any font attributes.
496 */
328f5751 497 bool HasFont() const;
23324ae1
FM
498
499 /**
500 Returns @true if the attribute object specifies an encoding.
501 */
328f5751 502 bool HasFontEncoding() const;
23324ae1
FM
503
504 /**
505 Returns @true if the attribute object specifies a font face name.
506 */
328f5751 507 bool HasFontFaceName() const;
23324ae1 508
9c4cb611
JS
509 /**
510 Returns @true if the attribute object specifies a font family.
511 */
512 bool HasFontFamily() const;
513
23324ae1
FM
514 /**
515 Returns @true if the attribute object specifies italic style.
516 */
328f5751 517 bool HasFontItalic() const;
23324ae1
FM
518
519 /**
520 Returns @true if the attribute object specifies a font point size.
521 */
328f5751 522 bool HasFontSize() const;
23324ae1
FM
523
524 /**
525 Returns @true if the attribute object specifies either underlining or no
526 underlining.
527 */
328f5751 528 bool HasFontUnderlined() const;
23324ae1
FM
529
530 /**
531 Returns @true if the attribute object specifies font weight (bold, light or
532 normal).
533 */
328f5751 534 bool HasFontWeight() const;
23324ae1
FM
535
536 /**
537 Returns @true if the attribute object specifies a left indent.
538 */
328f5751 539 bool HasLeftIndent() const;
23324ae1
FM
540
541 /**
542 Returns @true if the attribute object specifies line spacing.
543 */
328f5751 544 bool HasLineSpacing() const;
23324ae1
FM
545
546 /**
547 Returns @true if the attribute object specifies a list style name.
548 */
328f5751 549 bool HasListStyleName() const;
23324ae1
FM
550
551 /**
552 Returns @true if the attribute object specifies an outline level.
553 */
328f5751 554 bool HasOutlineLevel() const;
23324ae1
FM
555
556 /**
557 Returns @true if the attribute object specifies a page break before this
558 paragraph.
559 */
328f5751 560 bool HasPageBreak() const;
23324ae1
FM
561
562 /**
563 Returns @true if the attribute object specifies spacing after a paragraph.
564 */
328f5751 565 bool HasParagraphSpacingAfter() const;
23324ae1
FM
566
567 /**
568 Returns @true if the attribute object specifies spacing before a paragraph.
569 */
328f5751 570 bool HasParagraphSpacingBefore() const;
23324ae1
FM
571
572 /**
573 Returns @true if the attribute object specifies a paragraph style name.
574 */
328f5751 575 bool HasParagraphStyleName() const;
23324ae1
FM
576
577 /**
578 Returns @true if the attribute object specifies a right indent.
579 */
328f5751 580 bool HasRightIndent() const;
23324ae1
FM
581
582 /**
583 Returns @true if the attribute object specifies tab stops.
584 */
328f5751 585 bool HasTabs() const;
23324ae1
FM
586
587 /**
588 Returns @true if the attribute object specifies a text foreground colour.
589 */
328f5751 590 bool HasTextColour() const;
23324ae1
FM
591
592 /**
593 Returns @true if the attribute object specifies text effects.
594 */
328f5751 595 bool HasTextEffects() const;
23324ae1
FM
596
597 /**
598 Returns @true if the attribute object specifies a URL.
599 */
328f5751 600 bool HasURL() const;
23324ae1
FM
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 */
328f5751 606 bool IsCharacterStyle() const;
23324ae1
FM
607
608 /**
609 Returns @false if we have any attributes set, @true otherwise.
610 */
328f5751 611 bool IsDefault() const;
23324ae1
FM
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 */
328f5751 618 bool IsParagraphStyle() const;
23324ae1 619
7d76fbd5
FM
620 //@}
621
c6cf894a
FM
622
623 /**
7d76fbd5
FM
624 @name SetXXX functions
625 */
c6cf894a 626
7d76fbd5 627 //@{
23324ae1
FM
628
629 /**
c6cf894a 630 Sets the paragraph alignment. See ::wxTextAttrAlignment enumeration values.
3c4f71cc 631
c6cf894a
FM
632 Of these, wxTEXT_ALIGNMENT_JUSTIFIED is unimplemented.
633 In future justification may be supported when printing or previewing, only.
23324ae1
FM
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.
c6cf894a
FM
651
652 See GetBulletName() for a list of supported names, and how
653 to expand the range of supported types.
23324ae1
FM
654 */
655 void SetBulletName(const wxString& name);
656
657 /**
658 Sets the bullet number.
659 */
660 void SetBulletNumber(int n);
661
662 /**
c6cf894a 663 Sets the bullet style.
3c4f71cc 664
c6cf894a
FM
665 The ::wxTextAttrBulletStyle enumeration values are all supported,
666 except for wxTEXT_ATTR_BULLET_STYLE_BITMAP.
23324ae1
FM
667 */
668 void SetBulletStyle(int style);
669
670 /**
c6cf894a
FM
671 Sets the bullet text, which could be a symbol, or (for example) cached
672 outline text.
23324ae1 673 */
43c48e1e 674 void SetBulletText(const wxString& text);
23324ae1
FM
675
676 /**
677 Sets the character style name.
678 */
679 void SetCharacterStyleName(const wxString& name);
680
681 /**
c6cf894a
FM
682 Sets the flags determining which styles are being specified.
683 The ::wxTextAttrFlags values can be passed in a bitlist.
23324ae1
FM
684 */
685 void SetFlags(long flags);
686
687 /**
c6cf894a
FM
688 Sets the attributes for the given font.
689 Note that wxTextAttr does not store an actual wxFont object.
23324ae1 690 */
43c48e1e 691 void SetFont(const wxFont& font, int flags = wxTEXT_ATTR_FONT);
23324ae1
FM
692
693 /**
694 Sets the font encoding.
695 */
696 void SetFontEncoding(wxFontEncoding encoding);
697
698 /**
9c4cb611 699 Sets the font face name.
23324ae1
FM
700 */
701 void SetFontFaceName(const wxString& faceName);
702
9c4cb611
JS
703 /**
704 Sets the font family.
705 */
7d76fbd5 706 void SetFontFamily(wxFontFamily family);
9c4cb611 707
23324ae1
FM
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 */
7d76fbd5 716 void SetFontStyle(wxFontStyle fontStyle);
23324ae1
FM
717
718 /**
719 Sets the font underlining.
720 */
721 void SetFontUnderlined(bool underlined);
722
723 /**
724 Sets the font weight.
725 */
7d76fbd5 726 void SetFontWeight(wxFontWeight fontWeight);
23324ae1
FM
727
728 /**
729 Sets the left indent and left subindent in tenths of a millimetre.
23324ae1 730 The sub-indent is an offset from the left of the paragraph, and is used for all
c6cf894a
FM
731 but the first line in a paragraph.
732
733 A positive value will cause the first line to appear to the left
23324ae1 734 of the subsequent lines, and a negative value will cause the first line to be
c6cf894a
FM
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
23324ae1
FM
742 left of the actual paragraph is leftSubIndent.
743 */
744 void SetLeftIndent(int indent, int subIndent = 0);
745
746 /**
4cc4bfaf 747 Sets the line spacing. @a spacing is a multiple, where 10 means single-spacing,
c6cf894a
FM
748 15 means 1.5 spacing, and 20 means double spacing.
749 The ::wxTextAttrLineSpacing values are defined for convenience.
23324ae1
FM
750 */
751 void SetLineSpacing(int spacing);
752
753 /**
754 Sets the list style name.
755 */
756 void SetListStyleName(const wxString& name);
757
758 /**
c6cf894a
FM
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.
23324ae1
FM
763 */
764 void SetOutlineLevel(int level);
765
766 /**
767 Specifies a page break before this paragraph.
768 */
4cc4bfaf 769 void SetPageBreak(bool pageBreak = true);
23324ae1
FM
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 /**
c6cf894a
FM
804 Sets the text effect bits of interest.
805
806 You should also pass wxTEXT_ATTR_EFFECTS to SetFlags().
23324ae1
FM
807 See SetFlags() for further information.
808 */
809 void SetTextEffectFlags(int flags);
810
811 /**
812 Sets the text effects, a bit list of styles.
c6cf894a 813 The ::wxTextAttrEffects enumeration values can be used.
3c4f71cc 814
23324ae1
FM
815 Of these, only wxTEXT_ATTR_EFFECT_CAPITALS and wxTEXT_ATTR_EFFECT_STRIKETHROUGH
816 are implemented.
c6cf894a 817
23324ae1 818 wxTEXT_ATTR_EFFECT_CAPITALS capitalises text when displayed (leaving the case
c6cf894a
FM
819 of the actual buffer text unchanged), and wxTEXT_ATTR_EFFECT_STRIKETHROUGH draws
820 a line through text.
821
23324ae1 822 To set effects, you should also pass wxTEXT_ATTR_EFFECTS to SetFlags(), and call
c6cf894a
FM
823 SetTextEffectFlags() with the styles (taken from the above set) that you
824 are interested in setting.
23324ae1
FM
825 */
826 void SetTextEffects(int effects);
827
828 /**
829 Sets the URL for the content. Sets the wxTEXT_ATTR_URL style; content with this
c6cf894a
FM
830 style causes wxRichTextCtrl to show a hand cursor over it, and wxRichTextCtrl
831 generates a wxTextUrlEvent when the content is clicked.
23324ae1 832 */
4cc4bfaf 833 void SetURL(const wxString& url);
23324ae1 834
7d76fbd5
FM
835 //@}
836
837
23324ae1
FM
838 /**
839 Assignment from a wxTextAttr object.
840 */
841 void operator operator=(const wxTextAttr& attr);
842};
843
e54c96f1 844
23324ae1
FM
845/**
846 @class wxTextCtrl
7c913512 847
756e6e49
VZ
848 A text control allows text to be displayed and edited.
849
2e7789a9
VZ
850 It may be single line or multi-line. Notice that a lot of methods of the
851 text controls are found in the base wxTextEntry class which is a common
852 base class for wxTextCtrl and other controls using a single line text entry
853 field (e.g. wxComboBox).
7c913512 854
23324ae1 855 @beginStyleTable
8c6791e4 856 @style{wxTE_PROCESS_ENTER}
23324ae1
FM
857 The control will generate the event wxEVT_COMMAND_TEXT_ENTER
858 (otherwise pressing Enter key is either processed internally by the
859 control or used for navigation between dialog controls).
8c6791e4 860 @style{wxTE_PROCESS_TAB}
23324ae1
FM
861 The control will receive wxEVT_CHAR events for TAB pressed -
862 normally, TAB is used for passing to the next control in a dialog
863 instead. For the control created with this style, you can still use
864 Ctrl-Enter to pass to the next control from the keyboard.
8c6791e4 865 @style{wxTE_MULTILINE}
d911dc04
VZ
866 The text control allows multiple lines. If this style is not
867 specified, line break characters should not be used in the controls
868 value.
8c6791e4 869 @style{wxTE_PASSWORD}
23324ae1 870 The text will be echoed as asterisks.
8c6791e4 871 @style{wxTE_READONLY}
23324ae1 872 The text will not be user-editable.
8c6791e4 873 @style{wxTE_RICH}
23324ae1
FM
874 Use rich text control under Win32, this allows to have more than
875 64KB of text in the control even under Win9x. This style is ignored
876 under other platforms.
8c6791e4 877 @style{wxTE_RICH2}
23324ae1
FM
878 Use rich text control version 2.0 or 3.0 under Win32, this style is
879 ignored under other platforms
8c6791e4 880 @style{wxTE_AUTO_URL}
23324ae1
FM
881 Highlight the URLs and generate the wxTextUrlEvents when mouse
882 events occur over them. This style is only supported for wxTE_RICH
883 Win32 and multi-line wxGTK2 text controls.
8c6791e4 884 @style{wxTE_NOHIDESEL}
23324ae1
FM
885 By default, the Windows text control doesn't show the selection
886 when it doesn't have focus - use this style to force it to always
887 show it. It doesn't do anything under other platforms.
8c6791e4 888 @style{wxHSCROLL}
23324ae1
FM
889 A horizontal scrollbar will be created and used, so that text won't
890 be wrapped. No effect under wxGTK1.
8c6791e4 891 @style{wxTE_NO_VSCROLL}
23324ae1
FM
892 For multiline controls only: vertical scrollbar will never be
893 created. This limits the amount of text which can be entered into
894 the control to what can be displayed in it under MSW but not under
895 GTK2. Currently not implemented for the other platforms.
8c6791e4 896 @style{wxTE_LEFT}
23324ae1 897 The text in the control will be left-justified (default).
8c6791e4 898 @style{wxTE_CENTRE}
23324ae1
FM
899 The text in the control will be centered (currently wxMSW and
900 wxGTK2 only).
8c6791e4 901 @style{wxTE_RIGHT}
23324ae1
FM
902 The text in the control will be right-justified (currently wxMSW
903 and wxGTK2 only).
8c6791e4 904 @style{wxTE_DONTWRAP}
23324ae1
FM
905 Same as wxHSCROLL style: don't wrap at all, show horizontal
906 scrollbar instead.
8c6791e4 907 @style{wxTE_CHARWRAP}
23324ae1
FM
908 Wrap the lines too long to be shown entirely at any position
909 (wxUniv and wxGTK2 only).
8c6791e4 910 @style{wxTE_WORDWRAP}
23324ae1
FM
911 Wrap the lines too long to be shown entirely at word boundaries
912 (wxUniv and wxGTK2 only).
8c6791e4 913 @style{wxTE_BESTWRAP}
23324ae1
FM
914 Wrap the lines at word boundaries or at any other character if
915 there are words longer than the window width (this is the default).
8c6791e4 916 @style{wxTE_CAPITALIZE}
23324ae1
FM
917 On PocketPC and Smartphone, causes the first letter to be
918 capitalized.
919 @endStyleTable
7c913512 920
c6cf894a
FM
921 Note that alignment styles (wxTE_LEFT, wxTE_CENTRE and wxTE_RIGHT) can be
922 changed dynamically after control creation on wxMSW and wxGTK. wxTE_READONLY,
923 wxTE_PASSWORD and wrapping styles can be dynamically changed under wxGTK but
924 not wxMSW. The other styles can be only set during control creation.
925
756e6e49
VZ
926
927 @section textctrl_text_format wxTextCtrl Text Format
928
929 The multiline text controls always store the text as a sequence of lines
930 separated by @c '\\n' characters, i.e. in the Unix text format even on
931 non-Unix platforms. This allows the user code to ignore the differences
932 between the platforms but at a price: the indices in the control such as
933 those returned by GetInsertionPoint() or GetSelection() can @b not be used
934 as indices into the string returned by GetValue() as they're going to be
935 slightly off for platforms using @c "\\r\\n" as separator (as Windows
936 does).
937
938 Instead, if you need to obtain a substring between the 2 indices obtained
939 from the control with the help of the functions mentioned above, you should
940 use GetRange(). And the indices themselves can only be passed to other
941 methods, for example SetInsertionPoint() or SetSelection().
942
943 To summarize: never use the indices returned by (multiline) wxTextCtrl as
944 indices into the string it contains, but only as arguments to be passed
945 back to the other wxTextCtrl methods. This problem doesn't arise for
946 single-line platforms however where the indices in the control do
947 correspond to the positions in the value string.
948
949
950 @section textctrl_styles wxTextCtrl Styles.
951
952 Multi-line text controls support styling, i.e. provide a possibility to set
953 colours and font for individual characters in it (note that under Windows
954 @c wxTE_RICH style is required for style support). To use the styles you
955 can either call SetDefaultStyle() before inserting the text or call
956 SetStyle() later to change the style of the text already in the control
957 (the first solution is much more efficient).
958
959 In either case, if the style doesn't specify some of the attributes (for
960 example you only want to set the text colour but without changing the font
961 nor the text background), the values of the default style will be used for
962 them. If there is no default style, the attributes of the text control
963 itself are used.
964
965 So the following code correctly describes what it does: the second call to
966 SetDefaultStyle() doesn't change the text foreground colour (which stays
967 red) while the last one doesn't change the background colour (which stays
968 grey):
969
970 @code
971 text->SetDefaultStyle(wxTextAttr(*wxRED));
972 text->AppendText("Red text\n");
973 text->SetDefaultStyle(wxTextAttr(wxNullColour, *wxLIGHT_GREY));
974 text->AppendText("Red on grey text\n");
975 text->SetDefaultStyle(wxTextAttr(*wxBLUE);
976 text->AppendText("Blue on grey text\n");
977 @endcode
978
979
980 @section textctrl_cpp_streams wxTextCtrl and C++ Streams
981
982 This class multiply-inherits from @c std::streambuf (except for some really
983 old compilers using non-standard iostream library), allowing code such as
984 the following:
985
986 @code
987 wxTextCtrl *control = new wxTextCtrl(...);
988
989 ostream stream(control)
990
991 stream << 123.456 << " some text\n";
992 stream.flush();
993 @endcode
994
995 Note that even if your compiler doesn't support this (the symbol
996 @c wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still use
997 wxTextCtrl itself in a stream-like manner:
998
999 @code
1000 wxTextCtrl *control = new wxTextCtrl(...);
1001
1002 *control << 123.456 << " some text\n";
1003 @endcode
1004
1005 However the possibility to create an ostream associated with wxTextCtrl may
1006 be useful if you need to redirect the output of a function taking an
1007 ostream as parameter to a text control.
1008
1009 Another commonly requested need is to redirect @c std::cout to the text
1010 control. This may be done in the following way:
1011
1012 @code
1013 #include <iostream>
1014
1015 wxTextCtrl *control = new wxTextCtrl(...);
1016
1017 std::streambuf *sbOld = std::cout.rdbuf();
1018 std::cout.rdbuf(control);
1019
1020 // use cout as usual, the output appears in the text control
1021 ...
1022
1023 std::cout.rdbuf(sbOld);
1024 @endcode
1025
1026 But wxWidgets provides a convenient class to make it even simpler so
1027 instead you may just do
1028
1029 @code
1030 #include <iostream>
1031
1032 wxTextCtrl *control = new wxTextCtrl(...);
1033
1034 wxStreamToTextRedirector redirect(control);
1035
1036 // all output to cout goes into the text control until the exit from
1037 // current scope
1038 @endcode
1039
1040 See wxStreamToTextRedirector for more details.
1041
1042
1043 @section textctrl_event_handling Event Handling.
1044
1045 The following commands are processed by default event handlers in
1046 wxTextCtrl: @c wxID_CUT, @c wxID_COPY, @c wxID_PASTE, @c wxID_UNDO, @c
1047 wxID_REDO. The associated UI update events are also processed
1048 automatically, when the control has the focus.
1049
3051a44a 1050 @beginEventEmissionTable{wxCommandEvent}
756e6e49
VZ
1051 @event{EVT_TEXT(id, func)}
1052 Respond to a wxEVT_COMMAND_TEXT_UPDATED event, generated when the text
1053 changes. Notice that this event will be sent when the text controls
1054 contents changes -- whether this is due to user input or comes from the
c6cf894a
FM
1055 program itself (for example, if wxTextCtrl::SetValue() is called); see
1056 wxTextCtrl::ChangeValue() for a function which does not send this event.
1057 This event is however not sent during the control creation.
756e6e49
VZ
1058 @event{EVT_TEXT_ENTER(id, func)}
1059 Respond to a wxEVT_COMMAND_TEXT_ENTER event, generated when enter is
1060 pressed in a text control which must have wxTE_PROCESS_ENTER style for
1061 this event to be generated.
e36df657 1062 @event{EVT_TEXT_URL(id, func)}
756e6e49
VZ
1063 A mouse event occurred over an URL in the text control (wxMSW and
1064 wxGTK2 only currently).
e36df657 1065 @event{EVT_TEXT_MAXLEN(id, func)}
756e6e49 1066 This event is generated when the user tries to enter more text into the
c6cf894a 1067 control than the limit set by wxTextCtrl::SetMaxLength(), see its description.
756e6e49
VZ
1068 @endEventTable
1069
23324ae1
FM
1070 @library{wxcore}
1071 @category{ctrl}
7e59b885 1072 @appearance{textctrl.png}
7c913512 1073
e54c96f1 1074 @see wxTextCtrl::Create, wxValidator
23324ae1 1075*/
2e7789a9
VZ
1076class wxTextCtrl : public wxControl,
1077 public wxTextEntry
23324ae1
FM
1078{
1079public:
e36df657 1080 /**
c6cf894a 1081 Default ctor.
e36df657 1082 */
c6cf894a 1083 wxTextCtrl();
e36df657 1084
23324ae1
FM
1085 /**
1086 Constructor, creating and showing a text control.
3c4f71cc 1087
7c913512 1088 @param parent
4cc4bfaf 1089 Parent window. Should not be @NULL.
7c913512 1090 @param id
4cc4bfaf 1091 Control identifier. A value of -1 denotes a default value.
7c913512 1092 @param value
4cc4bfaf 1093 Default text value.
7c913512 1094 @param pos
4cc4bfaf 1095 Text control position.
7c913512 1096 @param size
4cc4bfaf 1097 Text control size.
7c913512 1098 @param style
4cc4bfaf 1099 Window style. See wxTextCtrl.
7c913512 1100 @param validator
4cc4bfaf 1101 Window validator.
7c913512 1102 @param name
4cc4bfaf 1103 Window name.
3c4f71cc 1104
c6cf894a
FM
1105 @remarks
1106 The horizontal scrollbar (wxHSCROLL style flag) will only be
756e6e49
VZ
1107 created for multi-line text controls. Without a horizontal
1108 scrollbar, text lines that don't fit in the control's size will be
c6cf894a
FM
1109 wrapped (but no newline character is inserted).
1110 Single line controls don't have a horizontal scrollbar, the text is
1111 automatically scrolled so that the insertion point is always visible.
3c4f71cc 1112
4cc4bfaf 1113 @see Create(), wxValidator
23324ae1 1114 */
7c913512 1115 wxTextCtrl(wxWindow* parent, wxWindowID id,
ccf39540 1116 const wxString& value = wxEmptyString,
7c913512
FM
1117 const wxPoint& pos = wxDefaultPosition,
1118 const wxSize& size = wxDefaultSize,
1119 long style = 0,
1120 const wxValidator& validator = wxDefaultValidator,
1121 const wxString& name = wxTextCtrlNameStr);
23324ae1
FM
1122
1123 /**
1124 Destructor, destroying the text control.
1125 */
adaaa686 1126 virtual ~wxTextCtrl();
23324ae1 1127
23324ae1 1128 /**
756e6e49
VZ
1129 Creates the text control for two-step construction.
1130
1131 This method should be called if the default constructor was used for
1132 the control creation. Its parameters have the same meaning as for the
1133 non-default constructor.
23324ae1
FM
1134 */
1135 bool Create(wxWindow* parent, wxWindowID id,
43c48e1e 1136 const wxString& value = wxEmptyString,
23324ae1 1137 const wxPoint& pos = wxDefaultPosition,
43c48e1e 1138 const wxSize& size = wxDefaultSize, long style = 0,
23324ae1
FM
1139 const wxValidator& validator = wxDefaultValidator,
1140 const wxString& name = wxTextCtrlNameStr);
1141
1142 /**
1143 Copies the selected text to the clipboard and removes the selection.
1144 */
4cc4bfaf 1145 virtual void Cut();
23324ae1
FM
1146
1147 /**
756e6e49
VZ
1148 Resets the internal modified flag as if the current changes had been
1149 saved.
23324ae1 1150 */
adaaa686 1151 virtual void DiscardEdits();
23324ae1
FM
1152
1153 /**
2e7789a9 1154 This function inserts into the control the character which would have
756e6e49
VZ
1155 been inserted if the given key event had occurred in the text control.
1156
c6cf894a
FM
1157 The @a event object should be the same as the one passed to @c EVT_KEY_DOWN
1158 handler previously by wxWidgets. Please note that this function doesn't
1159 currently work correctly for all keys under any platform but MSW.
3c4f71cc 1160
756e6e49 1161 @return
c6cf894a 1162 @true if the event resulted in a change to the control, @false otherwise.
23324ae1 1163 */
adaaa686 1164 virtual bool EmulateKeyPress(const wxKeyEvent& event);
23324ae1
FM
1165
1166 /**
1167 Returns the style currently used for the new text.
3c4f71cc 1168
4cc4bfaf 1169 @see SetDefaultStyle()
23324ae1 1170 */
43c48e1e 1171 virtual const wxTextAttr& GetDefaultStyle() const;
23324ae1 1172
23324ae1 1173 /**
756e6e49
VZ
1174 Gets the length of the specified line, not including any trailing
1175 newline character(s).
3c4f71cc 1176
7c913512 1177 @param lineNo
4cc4bfaf 1178 Line number (starting from zero).
3c4f71cc 1179
756e6e49
VZ
1180 @return
1181 The length of the line, or -1 if @a lineNo was invalid.
23324ae1 1182 */
adaaa686 1183 virtual int GetLineLength(long lineNo) const;
23324ae1
FM
1184
1185 /**
1186 Returns the contents of a given line in the text control, not including
1187 any trailing newline character(s).
3c4f71cc 1188
7c913512 1189 @param lineNo
4cc4bfaf 1190 The line number, starting from zero.
3c4f71cc 1191
756e6e49
VZ
1192 @return
1193 The contents of the line.
23324ae1 1194 */
adaaa686 1195 virtual wxString GetLineText(long lineNo) const;
23324ae1
FM
1196
1197 /**
1198 Returns the number of lines in the text control buffer.
3c4f71cc 1199
c6cf894a
FM
1200 @remarks
1201 Note that even empty text controls have one line (where the
1202 insertion point is), so GetNumberOfLines() never returns 0.
1203 For wxGTK using GTK+ 1.2.x and earlier, the number of lines in a
1204 multi-line text control is calculated by actually counting newline
1205 characters in the buffer, i.e. this function returns the number of
1206 logical lines and doesn't depend on whether any of them are wrapped.
1207 For all the other platforms, the number of physical lines in the
1208 control is returned.
1209 Also note that you may wish to avoid using functions that work with
1210 line numbers if you are working with controls that contain large
1211 amounts of text as this function has O(N) complexity for N being
1212 the number of lines.
23324ae1 1213 */
adaaa686 1214 virtual int GetNumberOfLines() const;
23324ae1 1215
23324ae1 1216 /**
756e6e49
VZ
1217 Returns the style at this position in the text control.
1218
1219 Not all platforms support this function.
3c4f71cc 1220
756e6e49
VZ
1221 @return
1222 @true on success, @false if an error occurred (this may also mean
1223 that the styles are not supported under this platform).
3c4f71cc 1224
4cc4bfaf 1225 @see SetStyle(), wxTextAttr
23324ae1 1226 */
adaaa686 1227 virtual bool GetStyle(long position, wxTextAttr& style);
23324ae1 1228
23324ae1 1229 /**
756e6e49
VZ
1230 This function finds the character at the specified position expressed
1231 in pixels.
1232
1233 If the return code is not @c wxTE_HT_UNKNOWN the row and column of the
1234 character closest to this position are returned in the @a col and @a
c6cf894a
FM
1235 row parameters (unless the pointers are @NULL which is allowed).
1236 Please note that this function is currently only implemented in wxUniv, wxMSW
756e6e49 1237 and wxGTK2 ports.
3c4f71cc 1238
4cc4bfaf 1239 @see PositionToXY(), XYToPosition()
23324ae1
FM
1240 */
1241 wxTextCtrlHitTestResult HitTest(const wxPoint& pt,
1242 wxTextCoord col,
328f5751 1243 wxTextCoord row) const;
23324ae1 1244
23324ae1 1245 /**
756e6e49
VZ
1246 Returns @true if the text has been modified by user.
1247
1248 Note that calling SetValue() doesn't make the control modified.
3c4f71cc 1249
4cc4bfaf 1250 @see MarkDirty()
23324ae1 1251 */
adaaa686 1252 virtual bool IsModified() const;
23324ae1
FM
1253
1254 /**
c6cf894a 1255 Returns @true if this is a multi line edit control and @false otherwise.
3c4f71cc 1256
4cc4bfaf 1257 @see IsSingleLine()
23324ae1 1258 */
328f5751 1259 bool IsMultiLine() const;
23324ae1
FM
1260
1261 /**
c6cf894a 1262 Returns @true if this is a single line edit control and @false otherwise.
3c4f71cc 1263
c6cf894a 1264 @see IsSingleLine(), IsMultiLine()
23324ae1 1265 */
328f5751 1266 bool IsSingleLine() const;
23324ae1
FM
1267
1268 /**
1269 Loads and displays the named file, if it exists.
3c4f71cc 1270
7c913512 1271 @param filename
4cc4bfaf 1272 The filename of the file to load.
7c913512 1273 @param fileType
4cc4bfaf 1274 The type of file to load. This is currently ignored in wxTextCtrl.
3c4f71cc 1275
756e6e49
VZ
1276 @return
1277 @true if successful, @false otherwise.
23324ae1
FM
1278 */
1279 bool LoadFile(const wxString& filename,
1280 int fileType = wxTEXT_TYPE_ANY);
1281
1282 /**
1283 Mark text as modified (dirty).
3c4f71cc 1284
4cc4bfaf 1285 @see IsModified()
23324ae1 1286 */
adaaa686 1287 virtual void MarkDirty();
23324ae1
FM
1288
1289 /**
756e6e49
VZ
1290 This event handler function implements default drag and drop behaviour,
1291 which is to load the first dropped file into the control.
3c4f71cc 1292
7c913512 1293 @param event
4cc4bfaf 1294 The drop files event.
3c4f71cc 1295
23324ae1 1296 @remarks This is not implemented on non-Windows platforms.
3c4f71cc 1297
4cc4bfaf 1298 @see wxDropFilesEvent
23324ae1
FM
1299 */
1300 void OnDropFiles(wxDropFilesEvent& event);
1301
23324ae1
FM
1302 /**
1303 Converts given position to a zero-based column, line number pair.
3c4f71cc 1304
7c913512 1305 @param pos
4cc4bfaf 1306 Position.
7c913512 1307 @param x
4cc4bfaf 1308 Receives zero based column number.
7c913512 1309 @param y
4cc4bfaf 1310 Receives zero based line number.
3c4f71cc 1311
756e6e49
VZ
1312 @return
1313 @true on success, @false on failure (most likely due to a too large
1314 position parameter).
3c4f71cc 1315
4cc4bfaf 1316 @see XYToPosition()
23324ae1 1317 */
adaaa686 1318 virtual bool PositionToXY(long pos, long* x, long* y) const;
23324ae1 1319
23324ae1
FM
1320 /**
1321 Saves the contents of the control in a text file.
3c4f71cc 1322
7c913512 1323 @param filename
4cc4bfaf 1324 The name of the file in which to save the text.
7c913512 1325 @param fileType
4cc4bfaf 1326 The type of file to save. This is currently ignored in wxTextCtrl.
3c4f71cc 1327
756e6e49
VZ
1328 @return
1329 @true if the operation was successful, @false otherwise.
23324ae1 1330 */
43c48e1e 1331 bool SaveFile(const wxString& filename = wxEmptyString,
23324ae1
FM
1332 int fileType = wxTEXT_TYPE_ANY);
1333
1334 /**
756e6e49
VZ
1335 Changes the default style to use for the new text which is going to be
1336 added to the control using WriteText() or AppendText().
1337
23324ae1 1338 If either of the font, foreground, or background colour is not set in
756e6e49
VZ
1339 @a style, the values of the previous default style are used for them.
1340 If the previous default style didn't set them neither, the global font
c6cf894a
FM
1341 or colours of the text control itself are used as fall back.
1342
1343 However if the @a style parameter is the default wxTextAttr, then the default
756e6e49 1344 style is just reset (instead of being combined with the new style which
23324ae1 1345 wouldn't change it at all).
3c4f71cc 1346
7c913512 1347 @param style
4cc4bfaf 1348 The style for the new text.
3c4f71cc 1349
756e6e49
VZ
1350 @return
1351 @true on success, @false if an error occurred (this may also mean
1352 that the styles are not supported under this platform).
3c4f71cc 1353
4cc4bfaf 1354 @see GetDefaultStyle()
23324ae1 1355 */
adaaa686 1356 virtual bool SetDefaultStyle(const wxTextAttr& style);
23324ae1 1357
23324ae1
FM
1358 /**
1359 Marks the control as being modified by the user or not.
3c4f71cc 1360
4cc4bfaf 1361 @see MarkDirty(), DiscardEdits()
23324ae1
FM
1362 */
1363 void SetModified(bool modified);
1364
23324ae1 1365 /**
756e6e49
VZ
1366 Changes the style of the given range.
1367
1368 If any attribute within @a style is not set, the corresponding
1369 attribute from GetDefaultStyle() is used.
3c4f71cc 1370
7c913512 1371 @param start
4cc4bfaf 1372 The start of the range to change.
7c913512 1373 @param end
4cc4bfaf 1374 The end of the range to change.
7c913512 1375 @param style
4cc4bfaf 1376 The new style for the range.
3c4f71cc 1377
756e6e49
VZ
1378 @return
1379 @true on success, @false if an error occurred (this may also mean
1380 that the styles are not supported under this platform).
3c4f71cc 1381
4cc4bfaf 1382 @see GetStyle(), wxTextAttr
23324ae1 1383 */
adaaa686 1384 virtual bool SetStyle(long start, long end, const wxTextAttr& style);
23324ae1 1385
23324ae1
FM
1386 /**
1387 Makes the line containing the given position visible.
3c4f71cc 1388
7c913512 1389 @param pos
4cc4bfaf 1390 The position that should be visible.
23324ae1 1391 */
adaaa686 1392 virtual void ShowPosition(long pos);
23324ae1 1393
23324ae1
FM
1394 /**
1395 Converts the given zero based column and line number to a position.
3c4f71cc 1396
7c913512 1397 @param x
4cc4bfaf 1398 The column number.
7c913512 1399 @param y
4cc4bfaf 1400 The line number.
3c4f71cc 1401
756e6e49
VZ
1402 @return
1403 The position value, or -1 if x or y was invalid.
23324ae1 1404 */
adaaa686 1405 virtual long XYToPosition(long x, long y) const;
23324ae1
FM
1406
1407 //@{
1408 /**
9e50ed28 1409 Operator definitions for appending to a text control.
756e6e49
VZ
1410
1411 These operators can be used as with the standard C++ streams, for
1412 example:
1413 @code
1414 wxTextCtrl *wnd = new wxTextCtrl(my_frame);
1415
1416 (*wnd) << "Welcome to text control number " << 1 << ".\n";
1417 @endcode
9e50ed28 1418 */
756e6e49 1419
9e50ed28
VZ
1420 wxTextCtrl& operator<<(const wxString& s);
1421 wxTextCtrl& operator<<(int i);
1422 wxTextCtrl& operator<<(long i);
1423 wxTextCtrl& operator<<(float f);
1424 wxTextCtrl& operator<<(double d);
1425 wxTextCtrl& operator<<(char c);
1426 wxTextCtrl& operator<<(wchar_t c);
23324ae1
FM
1427 //@}
1428};
1429
1430
e54c96f1 1431
23324ae1
FM
1432/**
1433 @class wxStreamToTextRedirector
7c913512 1434
23324ae1
FM
1435 This class can be used to (temporarily) redirect all output sent to a C++
1436 ostream object to a wxTextCtrl instead.
7c913512 1437
c6cf894a
FM
1438 @note
1439 Some compilers and/or build configurations don't support multiply
1440 inheriting wxTextCtrl from @c std::streambuf in which case this class is
1441 not compiled in.
1442 You also must have @c wxUSE_STD_IOSTREAM option on (i.e. set to 1) in your
1443 @c setup.h to be able to use it. Under Unix, specify @c --enable-std_iostreams
1444 switch when running configure for this.
7c913512 1445
23324ae1 1446 Example of usage:
7c913512 1447
23324ae1
FM
1448 @code
1449 using namespace std;
d00029b2
BP
1450 wxTextCtrl* text = new wxTextCtrl(...);
1451 {
23324ae1 1452 wxStreamToTextRedirector redirect(text);
7c913512 1453
23324ae1 1454 // this goes to the text control
d00029b2
BP
1455 cout << "Hello, text!" << endl;
1456 }
1457 // this goes somewhere else, presumably to stdout
1458 cout << "Hello, console!" << endl;
23324ae1 1459 @endcode
7c913512 1460
23324ae1
FM
1461 @library{wxcore}
1462 @category{logging}
7c913512 1463
e54c96f1 1464 @see wxTextCtrl
23324ae1 1465*/
7c913512 1466class wxStreamToTextRedirector
23324ae1
FM
1467{
1468public:
1469 /**
756e6e49
VZ
1470 The constructor starts redirecting output sent to @a ostr or @a cout for
1471 the default parameter value to the text control @a text.
3c4f71cc 1472
7c913512 1473 @param text
4cc4bfaf 1474 The text control to append output too, must be non-@NULL
7c913512 1475 @param ostr
4cc4bfaf 1476 The C++ stream to redirect, cout is used if it is @NULL
23324ae1 1477 */
11e3af6e 1478 wxStreamToTextRedirector(wxTextCtrl *text, ostream* ostr);
23324ae1
FM
1479
1480 /**
1481 When a wxStreamToTextRedirector object is destroyed, the redirection is ended
1482 and any output sent to the C++ ostream which had been specified at the time of
1483 the object construction will go to its original destination.
1484 */
1485 ~wxStreamToTextRedirector();
1486};
e54c96f1 1487