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