1wxTextCtrl(3)              Erlang Module Definition              wxTextCtrl(3)
2
3
4

NAME

6       wxTextCtrl - Functions for wxTextCtrl class
7

DESCRIPTION

9       A text control allows text to be displayed and edited.
10
11       It  may  be  single line or multi-line. Notice that a lot of methods of
12       the text controls are found in the base wxTextEntry (not implemented in
13       wx)  class  which  is a common base class for wxTextCtrl and other con‐
14       trols using a single line text entry field (e.g. wxComboBox).
15
16       Styles
17
18       This class supports the following styles:
19
20       wxTextCtrl Text Format
21
22       The multiline text controls always store the  text  as  a  sequence  of
23       lines  separated  by '\n' characters, i.e. in the Unix text format even
24       on non-Unix platforms. This allows the user code to ignore the  differ‐
25       ences  between the platforms but at a price: the indices in the control
26       such as those returned by getInsertionPoint/1 or getSelection/1 can not
27       be  used  as  indices into the string returned by getValue/1 as they're
28       going to be slightly off for platforms using "\\r\\n" as separator  (as
29       Windows does).
30
31       Instead,  if  you  need to obtain a substring between the 2 indices ob‐
32       tained from the control with the help of the functions mentioned above,
33       you  should  use  getRange/3.  And  the  indices themselves can only be
34       passed to other methods, for example setInsertionPoint/2  or  setSelec‐
35       tion/3.
36
37       To  summarize: never use the indices returned by (multiline) wxTextCtrl
38       as indices into the string it contains, but only  as  arguments  to  be
39       passed back to the other wxTextCtrl methods. This problem doesn't arise
40       for single-line platforms however where the indices in the  control  do
41       correspond to the positions in the value string.
42
43       wxTextCtrl Positions and Coordinates
44
45       It  is  possible  to use either linear positions, i.e. roughly (but not
46       always exactly, as explained in the previous section) the index of  the
47       character in the text contained in the control or X-Y coordinates, i.e.
48       column and line of the character when working with this  class  and  it
49       provides the functions positionToXY/2 and xYToPosition/3 to convert be‐
50       tween the two.
51
52       Additionally, a position in the control can be converted to its coordi‐
53       nates  in pixels using PositionToCoords() (not implemented in wx) which
54       can be useful to e.g. show a popup menu near the given character.  And,
55       in  the  other direction, HitTest() (not implemented in wx) can be used
56       to find the character under, or near, the given pixel coordinates.
57
58       To be more precise, positions actually refer to the gaps between  char‐
59       acters  and  not the characters themselves. Thus, position 0 is the one
60       before the very first character in the control and so is a valid  posi‐
61       tion even when the control is empty. And if the control contains a sin‐
62       gle character, it has two valid positions: 0 before this character  and
63       1  -  after  it. This, when the documentation of various functions men‐
64       tions "invalid position", it doesn't consider the position  just  after
65       the last character of the line to be invalid, only the positions beyond
66       that one (e.g. 2 and greater in the single character example) are actu‐
67       ally invalid.
68
69       wxTextCtrl Styles.
70
71       Multi-line text controls support styling, i.e. provide a possibility to
72       set colours and font for individual characters in it (note  that  under
73       Windows  wxTE_RICH  style  is  required  for style support). To use the
74       styles you can either call setDefaultStyle/2 before inserting the  text
75       or call setStyle/4 later to change the style of the text already in the
76       control (the first solution is much more efficient).
77
78       In either case, if the style doesn't specify  some  of  the  attributes
79       (for  example you only want to set the text colour but without changing
80       the font nor the text background), the values of the default style will
81       be  used  for them. If there is no default style, the attributes of the
82       text control itself are used.
83
84       So the following code correctly describes what it does: the second call
85       to  setDefaultStyle/2  doesn't change the text foreground colour (which
86       stays red) while the last one  doesn't  change  the  background  colour
87       (which stays grey):
88
89       wxTextCtrl and C++ Streams
90
91       This  class  multiply-inherits from std::streambuf (except for some re‐
92       ally old compilers using non-standard iostream library), allowing  code
93       such as the following:
94
95       Note  that  even  if  your build of wxWidgets doesn't support this (the
96       symbol wxHAS_TEXT_WINDOW_STREAM has value of 0 then) you can still  use
97       wxTextCtrl itself in a stream-like manner:
98
99       However  the  possibility  to create a std::ostream associated with wx‐
100       TextCtrl may be useful if you need to redirect the output of a function
101       taking a std::ostream as parameter to a text control.
102
103       Another  commonly  requested  need is to redirect std::cout to the text
104       control. This may be done in the following way:
105
106       But wxWidgets provides a convenient class to make it  even  simpler  so
107       instead you may just do
108
109       See wxStreamToTextRedirector (not implemented in wx) for more details.
110
111       Event Handling.
112
113       The  following  commands are processed by default event handlers in wx‐
114       TextCtrl: wxID_CUT, wxID_COPY, wxID_PASTE,  wxID_UNDO,  wxID_REDO.  The
115       associated  UI update events are also processed automatically, when the
116       control has the focus.
117
118       See: create/4, wxValidator (not implemented in wx)
119
120       This class is derived (and can use functions) from: wxControl  wxWindow
121       wxEvtHandler
122
123       wxWidgets docs: wxTextCtrl
124

EVENTS

126       Event   types  emitted  from  this  class:  command_text_updated,  com‐
127       mand_text_enter, text_maxlen
128

DATA TYPES

130       wxTextCtrl() = wx:wx_object()
131

EXPORTS

133       new() -> wxTextCtrl()
134
135              Default ctor.
136
137       new(Parent, Id) -> wxTextCtrl()
138
139              Types:
140
141                 Parent = wxWindow:wxWindow()
142                 Id = integer()
143
144       new(Parent, Id, Options :: [Option]) -> wxTextCtrl()
145
146              Types:
147
148                 Parent = wxWindow:wxWindow()
149                 Id = integer()
150                 Option =
151                     {value, unicode:chardata()} |
152                     {pos, {X :: integer(), Y :: integer()}} |
153                     {size, {W :: integer(), H :: integer()}} |
154                     {style, integer()} |
155                     {validator, wx:wx_object()}
156
157              Constructor, creating and showing a text control.
158
159              Remark: The horizontal scrollbar  (wxHSCROLL  style  flag)  will
160              only be created for multi-line text controls. Without a horizon‐
161              tal scrollbar, text lines that don't fit in the  control's  size
162              will  be  wrapped (but no newline character is inserted). Single
163              line controls don't have a horizontal scrollbar, the text is au‐
164              tomatically scrolled so that the insertion point is always visi‐
165              ble.
166
167              See: create/4, wxValidator (not implemented in wx)
168
169       destroy(This :: wxTextCtrl()) -> ok
170
171              Destructor, destroying the text control.
172
173       appendText(This, Text) -> ok
174
175              Types:
176
177                 This = wxTextCtrl()
178                 Text = unicode:chardata()
179
180              Appends the text to the end of the text control.
181
182              Remark: After the text is appended, the insertion point will  be
183              at  the  end  of  the text control. If this behaviour is not de‐
184              sired,  the  programmer  should  use   getInsertionPoint/1   and
185              setInsertionPoint/2.
186
187              See: writeText/2
188
189       canCopy(This) -> boolean()
190
191              Types:
192
193                 This = wxTextCtrl()
194
195              Returns true if the selection can be copied to the clipboard.
196
197       canCut(This) -> boolean()
198
199              Types:
200
201                 This = wxTextCtrl()
202
203              Returns true if the selection can be cut to the clipboard.
204
205       canPaste(This) -> boolean()
206
207              Types:
208
209                 This = wxTextCtrl()
210
211              Returns true if the contents of the clipboard can be pasted into
212              the text control.
213
214              On some platforms (Motif, GTK) this is an approximation and  re‐
215              turns true if the control is editable, false otherwise.
216
217       canRedo(This) -> boolean()
218
219              Types:
220
221                 This = wxTextCtrl()
222
223              Returns  true if there is a redo facility available and the last
224              operation can be redone.
225
226       canUndo(This) -> boolean()
227
228              Types:
229
230                 This = wxTextCtrl()
231
232              Returns true if there is an undo facility available and the last
233              operation can be undone.
234
235       clear(This) -> ok
236
237              Types:
238
239                 This = wxTextCtrl()
240
241              Clears the text in the control.
242
243              Note  that  this function will generate a wxEVT_TEXT event, i.e.
244              its effect is identical to calling SetValue("").
245
246       copy(This) -> ok
247
248              Types:
249
250                 This = wxTextCtrl()
251
252              Copies the selected text to the clipboard.
253
254       create(This, Parent, Id) -> boolean()
255
256              Types:
257
258                 This = wxTextCtrl()
259                 Parent = wxWindow:wxWindow()
260                 Id = integer()
261
262       create(This, Parent, Id, Options :: [Option]) -> boolean()
263
264              Types:
265
266                 This = wxTextCtrl()
267                 Parent = wxWindow:wxWindow()
268                 Id = integer()
269                 Option =
270                     {value, unicode:chardata()} |
271                     {pos, {X :: integer(), Y :: integer()}} |
272                     {size, {W :: integer(), H :: integer()}} |
273                     {style, integer()} |
274                     {validator, wx:wx_object()}
275
276              Creates the text control for two-step construction.
277
278              This method should be called if the default constructor was used
279              for  the  control creation. Its parameters have the same meaning
280              as for the non-default constructor.
281
282       cut(This) -> ok
283
284              Types:
285
286                 This = wxTextCtrl()
287
288              Copies the selected text to the clipboard and  removes  it  from
289              the control.
290
291       discardEdits(This) -> ok
292
293              Types:
294
295                 This = wxTextCtrl()
296
297              Resets  the internal modified flag as if the current changes had
298              been saved.
299
300       changeValue(This, Value) -> ok
301
302              Types:
303
304                 This = wxTextCtrl()
305                 Value = unicode:chardata()
306
307              Sets the new text control value.
308
309              It also marks the control as not-modified which means  that  Is‐
310              Modified()  would  return  false  immediately  after the call to
311              changeValue/2.
312
313              The insertion point is set to the start of the control (i.e. po‐
314              sition 0) by this function.
315
316              This functions does not generate the wxEVT_TEXT event but other‐
317              wise is identical to setValue/2.
318
319              See overview_events_prog for more information.
320
321              Since: 2.7.1
322
323       emulateKeyPress(This, Event) -> boolean()
324
325              Types:
326
327                 This = wxTextCtrl()
328                 Event = wxKeyEvent:wxKeyEvent()
329
330              This function inserts into the control the character which would
331              have  been  inserted  if the given key event had occurred in the
332              text control.
333
334              The event object should  be  the  same  as  the  one  passed  to
335              EVT_KEY_DOWN  handler  previously by wxWidgets. Please note that
336              this function doesn't currently work correctly for all keys  un‐
337              der any platform but MSW.
338
339              Return:  true  if the event resulted in a change to the control,
340              false otherwise.
341
342       getDefaultStyle(This) -> wxTextAttr:wxTextAttr()
343
344              Types:
345
346                 This = wxTextCtrl()
347
348              Returns the style currently used for the new text.
349
350              See: setDefaultStyle/2
351
352       getInsertionPoint(This) -> integer()
353
354              Types:
355
356                 This = wxTextCtrl()
357
358              Returns the insertion point, or cursor, position.
359
360              This is defined as the zero based index of the  character  posi‐
361              tion  to  the  right of the insertion point. For example, if the
362              insertion point is at the end of the single-line  text  control,
363              it is equal to getLastPosition/1.
364
365              Notice  that  insertion  position is, in general, different from
366              the index of the character the cursor position at in the  string
367              returned  by  getValue/1.  While this is always the case for the
368              single line controls, multi-line controls can use two characters
369              "\\r\\n"  as line separator (this is notably the case under MSW)
370              meaning that indices in the control and  its  string  value  are
371              offset by 1 for every line.
372
373              Hence to correctly get the character at the current cursor posi‐
374              tion, taking into account that there can be none if  the  cursor
375              is at the end of the string, you could do the following:
376
377       getLastPosition(This) -> integer()
378
379              Types:
380
381                 This = wxTextCtrl()
382
383              Returns  the  zero  based index of the last position in the text
384              control, which is equal to the number of characters in the  con‐
385              trol.
386
387       getLineLength(This, LineNo) -> integer()
388
389              Types:
390
391                 This = wxTextCtrl()
392                 LineNo = integer()
393
394              Gets  the length of the specified line, not including any trail‐
395              ing newline character(s).
396
397              Return: The length of the line, or -1 if lineNo was invalid.
398
399       getLineText(This, LineNo) -> unicode:charlist()
400
401              Types:
402
403                 This = wxTextCtrl()
404                 LineNo = integer()
405
406              Returns the contents of a given line in the  text  control,  not
407              including any trailing newline character(s).
408
409              Return: The contents of the line.
410
411       getNumberOfLines(This) -> integer()
412
413              Types:
414
415                 This = wxTextCtrl()
416
417              Returns the number of lines in the text control buffer.
418
419              The  returned  number  is the number of logical lines, i.e. just
420              the count of the number of newline characters in the  control  +
421              1,  for  wxGTK  and  wxOSX/Cocoa ports while it is the number of
422              physical lines, i.e. the count of lines actually  shown  in  the
423              control, in wxMSW. Because of this discrepancy, it is not recom‐
424              mended to use this function.
425
426              Remark: Note that even empty text controls have one line  (where
427              the insertion point is), so getNumberOfLines/1 never returns 0.
428
429       getRange(This, From, To) -> unicode:charlist()
430
431              Types:
432
433                 This = wxTextCtrl()
434                 From = To = integer()
435
436              Returns the string containing the text starting in the positions
437              from and up to to in the control.
438
439              The positions must have  been  returned  by  another  wxTextCtrl
440              method. Please note that the positions in a multiline wxTextCtrl
441              do not correspond to the indices in the string returned by  get‐
442              Value/1 because of the different new line representations (CR or
443              CR LF) and so this method should be used to obtain  the  correct
444              results  instead of extracting parts of the entire value. It may
445              also be more efficient, especially if the control contains a lot
446              of data.
447
448       getSelection(This) -> {From :: integer(), To :: integer()}
449
450              Types:
451
452                 This = wxTextCtrl()
453
454              Gets the current selection span.
455
456              If the returned values are equal, there was no selection. Please
457              note that the indices returned may be used with  the  other  wx‐
458              TextCtrl methods but don't necessarily represent the correct in‐
459              dices into the string returned by getValue/1 for multiline  con‐
460              trols  under  Windows (at least,) you should use getStringSelec‐
461              tion/1 to get the selected text.
462
463       getStringSelection(This) -> unicode:charlist()
464
465              Types:
466
467                 This = wxTextCtrl()
468
469              Gets the text currently selected in the control.
470
471              If there is no selection, the returned string is empty.
472
473       getStyle(This, Position, Style) -> boolean()
474
475              Types:
476
477                 This = wxTextCtrl()
478                 Position = integer()
479                 Style = wxTextAttr:wxTextAttr()
480
481              Returns the style at this position in the text control.
482
483              Not all platforms support this function.
484
485              Return: true on success, false if an error  occurred  (this  may
486              also  mean  that  the  styles are not supported under this plat‐
487              form).
488
489              See: setStyle/4, wxTextAttr
490
491       getValue(This) -> unicode:charlist()
492
493              Types:
494
495                 This = wxTextCtrl()
496
497              Gets the contents of the control.
498
499              Notice that for a multiline text control, the lines will be sep‐
500              arated  by  (Unix-style) \n characters, even under Windows where
501              they are separated by a \r\n sequence in the native control.
502
503       isEditable(This) -> boolean()
504
505              Types:
506
507                 This = wxTextCtrl()
508
509              Returns true if the controls contents  may  be  edited  by  user
510              (note that it always can be changed by the program).
511
512              In  other  words,  this  functions  returns  true if the control
513              hasn't been put in read-only mode by a previous call  to  setEd‐
514              itable/2.
515
516       isModified(This) -> boolean()
517
518              Types:
519
520                 This = wxTextCtrl()
521
522              Returns true if the text has been modified by user.
523
524              Note that calling setValue/2 doesn't make the control modified.
525
526              See: markDirty/1
527
528       isMultiLine(This) -> boolean()
529
530              Types:
531
532                 This = wxTextCtrl()
533
534              Returns true if this is a multi line edit control and false oth‐
535              erwise.
536
537              See: isSingleLine/1
538
539       isSingleLine(This) -> boolean()
540
541              Types:
542
543                 This = wxTextCtrl()
544
545              Returns true if this is a single line  edit  control  and  false
546              otherwise.
547
548              See: isSingleLine/1, isMultiLine/1
549
550       loadFile(This, Filename) -> boolean()
551
552              Types:
553
554                 This = wxTextCtrl()
555                 Filename = unicode:chardata()
556
557       loadFile(This, Filename, Options :: [Option]) -> boolean()
558
559              Types:
560
561                 This = wxTextCtrl()
562                 Filename = unicode:chardata()
563                 Option = {fileType, integer()}
564
565              Loads and displays the named file, if it exists.
566
567              Return: true if successful, false otherwise.
568
569       markDirty(This) -> ok
570
571              Types:
572
573                 This = wxTextCtrl()
574
575              Mark text as modified (dirty).
576
577              See: isModified/1
578
579       paste(This) -> ok
580
581              Types:
582
583                 This = wxTextCtrl()
584
585              Pastes text from the clipboard to the text item.
586
587       positionToXY(This, Pos) -> Result
588
589              Types:
590
591                 Result = {Res :: boolean(), X :: integer(), Y :: integer()}
592                 This = wxTextCtrl()
593                 Pos = integer()
594
595              Converts  given  position  to  a  zero-based column, line number
596              pair.
597
598              Return: true on success, false on failure (most likely due to  a
599              too large position parameter).
600
601              See: xYToPosition/3
602
603       redo(This) -> ok
604
605              Types:
606
607                 This = wxTextCtrl()
608
609              If  there  is  a redo facility and the last operation can be re‐
610              done, redoes the last operation.
611
612              Does nothing if there is no redo facility.
613
614       remove(This, From, To) -> ok
615
616              Types:
617
618                 This = wxTextCtrl()
619                 From = To = integer()
620
621              Removes the text starting at the first given position up to (but
622              not including) the character at the last position.
623
624              This function puts the current insertion point position at to as
625              a side effect.
626
627       replace(This, From, To, Value) -> ok
628
629              Types:
630
631                 This = wxTextCtrl()
632                 From = To = integer()
633                 Value = unicode:chardata()
634
635              Replaces the text starting at the first position up to (but  not
636              including)  the  character  at  the last position with the given
637              text.
638
639              This function puts the current insertion point position at to as
640              a side effect.
641
642       saveFile(This) -> boolean()
643
644              Types:
645
646                 This = wxTextCtrl()
647
648       saveFile(This, Options :: [Option]) -> boolean()
649
650              Types:
651
652                 This = wxTextCtrl()
653                 Option = {file, unicode:chardata()} | {fileType, integer()}
654
655              Saves the contents of the control in a text file.
656
657              Return: true if the operation was successful, false otherwise.
658
659       setDefaultStyle(This, Style) -> boolean()
660
661              Types:
662
663                 This = wxTextCtrl()
664                 Style = wxTextAttr:wxTextAttr()
665
666              Changes the default style to use for the new text which is going
667              to be added to the control.
668
669              This applies both  to  the  text  added  programmatically  using
670              writeText/2  or appendText/2 and to the text entered by the user
671              interactively.
672
673              If either of the font, foreground, or background colour  is  not
674              set  in style, the values of the previous default style are used
675              for them. If the previous default style didn't set them neither,
676              the  global  font or colours of the text control itself are used
677              as fall back.
678
679              However if the style parameter is the default  wxTextAttr,  then
680              the  default style is just reset (instead of being combined with
681              the new style which wouldn't change it at all).
682
683              Return: true on success, false if an error  occurred  (this  may
684              also  mean  that  the  styles are not supported under this plat‐
685              form).
686
687              See: getDefaultStyle/1
688
689       setEditable(This, Editable) -> ok
690
691              Types:
692
693                 This = wxTextCtrl()
694                 Editable = boolean()
695
696              Makes the  text  item  editable  or  read-only,  overriding  the
697              wxTE_READONLY flag.
698
699              See: isEditable/1
700
701       setInsertionPoint(This, Pos) -> ok
702
703              Types:
704
705                 This = wxTextCtrl()
706                 Pos = integer()
707
708              Sets the insertion point at the given position.
709
710       setInsertionPointEnd(This) -> ok
711
712              Types:
713
714                 This = wxTextCtrl()
715
716              Sets the insertion point at the end of the text control.
717
718              This  is equivalent to calling setInsertionPoint/2 with getLast‐
719              Position/1 argument.
720
721       setMaxLength(This, Len) -> ok
722
723              Types:
724
725                 This = wxTextCtrl()
726                 Len = integer()
727
728              This function sets the maximum number of characters the user can
729              enter into the control.
730
731              In  other words, it allows limiting the text value length to len
732              not counting the terminating NUL character.
733
734              If len is 0, the previously set max length  limit,  if  any,  is
735              discarded  and the user may enter as much text as the underlying
736              native text control widget supports (typically at  least  32Kb).
737              If the user tries to enter more characters into the text control
738              when it already is filled  up  to  the  maximal  length,  a  wx‐
739              EVT_TEXT_MAXLEN  event  is  sent  to notify the program about it
740              (giving it the possibility to show an explanatory  message,  for
741              example) and the extra input is discarded.
742
743              Note  that  in  wxGTK this function may only be used with single
744              line text controls.
745
746       setSelection(This, From, To) -> ok
747
748              Types:
749
750                 This = wxTextCtrl()
751                 From = To = integer()
752
753              Selects the text starting at the first position up to  (but  not
754              including) the character at the last position.
755
756              If  both  parameters  are equal to -1 all text in the control is
757              selected.
758
759              Notice that the insertion point will be moved to  from  by  this
760              function.
761
762              See: SelectAll() (not implemented in wx)
763
764       setStyle(This, Start, End, Style) -> boolean()
765
766              Types:
767
768                 This = wxTextCtrl()
769                 Start = End = integer()
770                 Style = wxTextAttr:wxTextAttr()
771
772              Changes the style of the given range.
773
774              If  any attribute within style is not set, the corresponding at‐
775              tribute from getDefaultStyle/1 is used.
776
777              Return: true on success, false if an error  occurred  (this  may
778              also  mean  that  the  styles are not supported under this plat‐
779              form).
780
781              See: getStyle/3, wxTextAttr
782
783       setValue(This, Value) -> ok
784
785              Types:
786
787                 This = wxTextCtrl()
788                 Value = unicode:chardata()
789
790              Sets the new text control value.
791
792              It also marks the control as not-modified which means  that  Is‐
793              Modified() would return false immediately after the call to set‐
794              Value/2.
795
796              The insertion point is set to the start of the control (i.e. po‐
797              sition  0)  by  this  function  unless the control value doesn't
798              change at all, in which case the insertion point is left at  its
799              original position.
800
801              Note  that,  unlike  most  other functions changing the controls
802              values, this function generates a  wxEVT_TEXT  event.  To  avoid
803              this you can use changeValue/2 instead.
804
805       showPosition(This, Pos) -> ok
806
807              Types:
808
809                 This = wxTextCtrl()
810                 Pos = integer()
811
812              Makes the line containing the given position visible.
813
814       undo(This) -> ok
815
816              Types:
817
818                 This = wxTextCtrl()
819
820              If  there  is an undo facility and the last operation can be un‐
821              done, undoes the last operation.
822
823              Does nothing if there is no undo facility.
824
825       writeText(This, Text) -> ok
826
827              Types:
828
829                 This = wxTextCtrl()
830                 Text = unicode:chardata()
831
832              Writes the text into the text control at the  current  insertion
833              position.
834
835              Remark: Newlines in the text string are the only control charac‐
836              ters allowed, and they will cause appropriate line  breaks.  See
837              operator<<()  and appendText/2 for more convenient ways of writ‐
838              ing to the window. After  the  write  operation,  the  insertion
839              point  will  be  at  the end of the inserted text, so subsequent
840              write operations will be appended. To append text after the user
841              may  have  interacted  with  the control, call setInsertionPoin‐
842              tEnd/1 before writing.
843
844       xYToPosition(This, X, Y) -> integer()
845
846              Types:
847
848                 This = wxTextCtrl()
849                 X = Y = integer()
850
851              Converts the given zero based column and line number to a  posi‐
852              tion.
853
854              Return: The position value, or -1 if x or y was invalid.
855
856
857
858wxWidgets team.                     wx 2.1                       wxTextCtrl(3)
Impressum