IUP::Text - [GUI element] editable text field (single/multi-line, plain/rich-text)
Creates an editable text field.
$txt = IUP::Text->new( MULTILINE=>"YES", FORMATTING=>"YES"); $txt->SetAttribute( ADDFORMATTAG_HANDLE => IUP::User->new( ALIGNMENT=>"CENTER", SPACEAFTER=>"10", FONTSIZE=>"24", SELECTION=>"3,1:3,50", )); $txt->SetAttribute( ADDFORMATTAG_HANDLE => IUP::User->new( BGCOLOR=>"255 128 64", UNDERLINE=>"SINGLE", WEIGHT=>"BOLD", SELECTION=>"3,7:3,11", )); $txt->SetAttribute( ADDFORMATTAG_HANDLE => IUP::User->new( ITALIC=>"YES", STRIKEOUT=>"YES", SELECTION=>"2,1:2,12", ));
$text = IUP::Text->new( VALUE=>"text text text" );
Returns: the identifier of the created element, or undef if an error occurs.
undef
NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.
new()
ATTRIBUTE=>'value'
CALLBACKNAME=>\&func
For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:
[Windows and GTK Only] (non inheritable)
Text alignment. Possible values: "ALEFT", "ARIGHT", "ACENTER".
Default: "ALEFT". In Motif, text is always left aligned.
(write-only)
Inserts a text at the end of the current text. In the Multiline, if APPENDNEWLINE=YES, a "\n" character will be automatically inserted before the appended text if the current text is not empty(APPENDNEWLINE default is YES). Ignored if set before map.
Background color of the text. Default: the global attribute TXTBGCOLOR.
(creation only)
Shows a border around the text. Default: "YES".
(creation only) (non inheritable)
enables the focus traversal of the control. In Windows the control will still get the focus when clicked. Default: YES.
(non inheritable)
Position of the insertion point. Its format depends in MULTILINE=YES. The first position, lin or col, is "1".
For multiple lines a string with the "<lin>,<col>" format, where lin and col are integer numbers corresponding to the caret's position.
For single line a string in the "<col>" format, where col is an integer number corresponding to the caret's position.
When lin is greater than the number of lines, the caret is placed at the last line. When col is greater than the number of characters in the given line, the caret is placed after the last character of the line.
If the caret is not visible the text is scrolled to make it visible.
In Windows, if the element does not have the focus the returned value is the position of the first character of the current selection. The caret is only displayed if the element has the keyboard focus, but its position can be changed even if not visible. When changed it will also change the selection but the text will be scrolled only when it receives the focus.
XXX-needs-fix-after-adding-UTF8-support
Also the position of the insertion point, but using a zero based character unique index "pos". Useful for indexing the VALUE string.
clear, cut, copy or paste the selection to or from the clipboard. Values: "CLEAR", "CUT", "COPY" or "PASTE". In Windows UNDO is also available, and REDO is available when FORMATTING=YES.
(read-only)
Returns the number of characters in the text. (since iup-3.5)
[Windows Only] (non inheritable)
Text that is displayed when there is no text at the control. It works as a textual cue, or tip to prompt the user for input. Valid only for MULTILINE=NO, and it is not available for Windows 2000.
Enable or disable the drag&drop of files. Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled.
Text color. Default: the global attribute TXTFGCOLOR.
Allows a custom filter to process the characters: Can be LOWERCASE, UPPERCASE or NUMBER (only numbers allowed).
When enabled allow the use of text formatting attributes. In GTK is always enabled, but only when MULTILINE=YES. Default: NO.
Inserts a text in the caret's position, also replaces the current selection if any. Ignored if set before map.
Returns the number of characters in the line where the caret is. When MULTILINE=NO returns always "1". (since iup-3.5)
Returns the text of the line where the caret is. It does not include the "\n" character. When MULTILINE=NO returns the same as VALUE. (since iup-3.5)
Defines a mask that will filter interactive text input.
Allows the edition of multiple lines. In single line mode some characters are invalid, like "\t", "\r" and "\n". Default: NO.
Maximum number of characters allowed for keyboard input, larger text can still be set using attributes. The maximum value is the limit of the VALUE attribute. The "0" value is the same as maximum. Default: maximum.
Turns the overwrite mode ON or OFF. Works only when FORMATTING=YES.
Internal margin. Works just like the MARGIN attribute of the IUP::Hbox and IUP::Vbox containers, but uses a different name to avoid inheritance problems. Default value: "0x0". In Windows, only the horizontal value is used. (GTK 2.10 for single line)
[Windows and GTK Only] (creation only, non inheritable)
Hide the typed character using an "*". Default: "NO".
Allows the user only to read the contents, without changing it. Restricts keyboard input only, text value can still be changed using attributes. Navigation keys are still available. Possible values: "YES", "NO". Default: NO.
Valid only when MULTILINE=YES. Associates an automatic horizontal and/or vertical scrollbar to the multiline. Can be: "VERTICAL", "HORIZONTAL", "YES" (both) or "NO" (none). Default: "YES". For all systems, when SCROLLBAR!=NO the natural size will always include its size even if the native system hides the scrollbar. If =item AUTOHIDE=YES scrollbars are visible only if they are necessary, by default AUTOHIDE=NO. In Windows when FORMATTING=NO, AUTOHIDE is not supported. In Motif AUTOHIDE is not supported.
(non inheritable, write only)
Scroll the text to make the given position visible. It uses the same format and reference of the CARET attribute ("lin:col" or "col" starting at 1).
Scroll the text to make the given position visible. It uses the same format and reference of the CARETPOS attribute ("pos" starting at 0).
Selection text. Returns undef if there is no selection. When changed replaces the current selection. Similar to INSERT, but does nothing if there is no selection.
Selection interval. Returns undef if there is no selection. Its format depends in MULTILINE=YES. The first position, lin or col, is "1".
For multiple lines a string in the "<lin1>,<col1>:<lin2>,<col2>"format, where lin1, col1, lin2 and col2 are integer numbers corresponding to the selection's interval. col2 correspond to the character after the last selected character.
For single line a string in the "<col1>:<col2>" format, where col1 and col2 are integer numbers corresponding to the selection's interval. col2 correspond to the character after the last selected character.
In Windows, when changing the selection the caret position is also changed.
The values ALL and NONE are also accepted independently of MULTILINE.
Same as SELECTION but using a zero based character index "<pos1>:<pos2>". Useful for indexing the VALUE string. The values ALL and NONE are also accepted.
Since the contents can be changed by the user, the Natural Size is not affected by the text contents . In IUP 2.x the Natural Size was defined by the number of lines in the text and the with of the largest line. For IUP 3, use VISIBLECOLUMNS and VISIBLELINES to control the Natural Size.
(non inheritable, creation only)
Enables a spin control attached to the element. Default: NO. The spin increments and decrements an integer number. The editing in the element is still available.
The current value of the spin. The value is limited to the minimum and maximum values.
The maximum value. Default: 100.
The minimum value. Default: 0.
The increment value. Default: 1.
The position of the spin. Can be LEFT or RIGHT. Default: RIGHT. In GTK is always RIGHT.
If the position reach a limit it continues from the opposite limit. Default: NO.
Enables the automatic update of the text contents. Default: YES. Use SPINAUTO=NO and the VALUE attribute during SPIN_CB to control the text contents when the spin is incremented.
In Windows, the increment is multiplied by 5 after 2 seconds and multiplied by 20 after 5 seconds of a spin button pressed. In GTK, the increment change is progressively accelerated when a spin button is pressed.
[Windows and GTK Only]
Valid only when MULTILINE=YES. Controls the number of characters for a tab stop. Default: 8.
Text entered by the user. The '\n' character indicates a new line, valid only when MULTILINE=YES. After the element is mapped and if there is no text will return the empty string "".
(non inheritable) (write-only)
sets VALUE but first checks if it is validated by MASK. If not does nothing. (since iup-3.4)
Defines the number of visible columns for the Natural Size, this means that will act also as minimum number of visible columns. It uses a wider character size then the one used for the SIZE attribute so strings will fit better without the need of extra columns. As for SIZE you can set to undef after map to use it as an initial value. Default 5
When MULTILINE=YES defines the number of visible lines for the Natural Size, this means that will act also as minimum number of visible lines. As for SIZE you can set to undef after map to use it as an initial value. Default: 1
Valid only when MULTILINE=YES. If enabled will force a word wrap of lines that are greater than the with of the control, and the horizontal scrollbar will be removed. Default: NO.
The following common attributes are also accepted:
ACTIVE, FONT, EXPAND, SCREENPOSITION, POSITION, MINSIZE, MAXSIZE, WID, TIP, RASTERSIZE, ZORDER, VISIBLE
For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:
Action generated when the text is edited, but before its value is actually changed. Can be generated when using the keyboard, undo system or from the clipboard.
Callback handler prototype:
sub action_handler { my ($self, $c, $new_value) = @_; #... }
$self: reference to the element (IUP::Text) that activated the event
$c: valid alpha numeric character or 0.
$new_value: Represents the new text value.
Returns: IUP_CLOSE will be processed, but the change will be ignored. If IUP_IGNORE, the system will ignore the new value. If c is valid and returns a valid alpha numeric character, this new character will be used instead. The VALUE attribute can be changed only if IUP_IGNORE is returned.
Action generated when any mouse button is pressed or released. Use ConvertXYToPos to convert (x,y) coordinates in character positioning.
Action generated when the caret/cursor position is changed.
sub caret_cb_handler { my ($self, $lin, $col, $pos) = @_; #... }
$lin, $col: line and column number (start at 1).
$pos: 0 based character position.
For single line controls lin is always 1, and pos is always col-1.
Action generated when one or more files are dropped in the element.
Action generated when the mouse is moved. Use ConvertXYToPos to convert (x,y) coordinates in character positioning.
Action generated when a spin button is pressed. Valid only when SPIN=YES. When this callback is called the ACTION callback is not called. The VALUE attribute can be changed during this callback only if SPINAUTO=NO.
sub spin_cb_handler { my ($self, $pos) = @_; #... }
$pos: the value of the spin (after it was incremented).
Returns: IUP_IGNORE is processed in Windows and Motif.
Called after the value was interactively changed by the user.
sub valuechanged_cb_handler { my ($self) = @_; #... }
The following common callbacks are also accepted:
MAP_CB, UNMAP_CB, GETFOCUS_CB, KILLFOCUS_CB, ENTERWINDOW_CB, LEAVEWINDOW_CB, K_ANY, HELP_CB
$pos = $text->TextConvertLinColToPos($lin, $col);
Converts a (lin, col) character positioning into an absolute position. For single line controls pos is always col-1.
($lin, $col) = $text->TextConvertPosToLinCol($pos);
Converts an absolute position into a (lin, col) character positioning. For single line controls lin is always 1, and col is always pos+1.
When MULTILINE=YES the Enter key will add a new line, and the Tab key will insert a Tab. So the "DEFAULTENTER" button will not be processed when the element has the keyboard focus, also to change focus to the next element press <Ctrl>+<Tab>.
In Windows, if you press a Ctrl+key combination that is not supported by the control, then a beep is sound.
XXX-needs-fix-after-adding-UTF8-support When using UTF-8 strings be aware that all attributes are indexed by characters, NOT by byte index, because some characters in UTF-8 can use more than one byte. This also applies to Windows if FORMATTING=YES depending on the Windows codepage (for example East Asian codepage where some characters take two bytes).
Here is a list of the common keys for all drivers. Other keys are available depending on the driver.
Navigation:
Keys Action -------------------------------------------------- Arrows move by individual characters/lines Ctrl+Arrows move by words/paragraphs Home/End move to begin/end line Ctrl+Home/End move to begin/end text PgUp/PgDn move vertically by pages Ctrl+PgUp/PgDn move horizontally by pages
Selection:
Keys Action -------------------------------------------------- Shift+Arrows select charaters Ctrl+A select all
Deleting:
Keys Action -------------------------------------------------- Del delete the character at right Backspace delete the character at left
Clipboard:
Keys Action -------------------------------------------------- Ctrl+C copy Ctrl+X cut Ctrl+V paste
The element IUP::Text is used in the following sample scripts:
0-basic/button.pl - IUP::Button example
0-basic/cbox.pl - IUP::Cbox example
0-basic/colorbrowser.pl - IUP::ColorBrowser example
0-basic/frame2.pl - IUP::Image example
0-basic/item.pl - IUP::Item Example
0-basic/layoutdialog.pl - IUP::LayoutDialog example
0-basic/mask_simple.pl - IUP::Text + MASK example
0-basic/menu.pl - IUP::Menu example
0-basic/sbox1.pl - IUP::Sbox example
0-basic/sbox2.pl - IUP::Sbox example
0-basic/separator.pl - IUP::Separator example
0-basic/submenu.pl - IUP::Submenu example
0-basic/tabs2.pl - IUP::Tabs example
0-basic/text1.pl - IUP::Text (single line) example
0-basic/text2.pl - IUP::Text example
0-basic/text_font.pl - IUP::Text (font) example
0-basic/text_format.pl - IUP::Text (formating) example
0-basic/text_multiline.pl - IUP::Text (multiline) example
0-basic/tree_set_attrs.pl - IUP::Tree example (attributes)
0-basic/zbox.pl - IUP::Zbox example
1-apps/app-mdi.pl - IUP app example
1-apps/app-plot-demo.pl - dials for zooming
1-apps/app-sample1.pl - example used for screenshot - IUP.pod
1-apps/app-sample2.pl - example based on the original sample.c
IUP::List
The original doc: iuptext.html
To install IUP, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IUP
CPAN shell
perl -MCPAN -e shell install IUP
For more information on module installation, please visit the detailed CPAN module installation guide.