IupText
Definition: |
include pGUI.e
Ihandle ih = IupText([integer rtn=NULL,] string attributes="", dword_seq args={}) |
||
Description: |
Creates an editable text field.
func: a callback address, usually specified as Icallback("name"). For more information on the attributes and args parameters see IupSetAttributes. This is a paranormalised function. Returns: the identifier of the created element. |
||
pwa/p2js: | Supported. | ||
See Also: | IupList, IupGLText | ||
Notes: |
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. When using UTF-8 strings in GTK 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). Internal Drag&Drop support is enabled by default. But in Windows the internal Drag&Drop is enabled only if FORMATTING=YES. In GTK the internal Drag&Drop can NOT be disabled, so it will conflict with the Drag & Drop attributes and callbacks. Navigation, Selection and Clipboard Keys Here is a list of the common keys for all drivers. Other keys are available depending on the driver.
An IupMultiLine is just an IupText with MULTILINE=YES. Some examples can be seen in demo\pGUI\sample.exw |
||
Auxiliary Functions |
integer pos = IupTextConvertLinColToPos(Ihandle ih, integer lin, col) Converts a (lin, col) character positioning into an absolute position. lin and col starts at 1, pos starts at 0. For single line controls pos is always "col-1". integer {lin,col} = IupTextConvertPosToLinCol(Ihandle ih, integer pos) Converts an absolute position into a (lin, col) character positioning. lin and col starts at 1, pos starts at 0. For single line controls lin is always 1, and col is always "pos+1". |
||
Attributes: | |||
ALIGNMENT |
[Windows and GTK Only] (non inheritable) text alignment. Possible values: "ALEFT", "ARIGHT", "ACENTER". Default: "ALEFT". In Motif, text is always left aligned. |
||
APPEND? | (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. | ||
BGCOLOR? | Background color of the text. Default: the global attribute TXTBGCOLOR. | ||
BORDER | (creation only) Shows a border around the text. Default: "YES". | ||
CANFOCUS |
(creation only) (non inheritable) enables the focus traversal of the control. In Windows the control will still get the focus when clicked. Default: YES. (since 3.0) |
||
PROPAGATEFOCUS | (non inheritable) enables the focus callback forwarding to the next native parent with FOCUS_CB defined. Default: NO. (since 3.23) | ||
CARET |
(non inheritable) Character 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. See the Notes above if using UTF-8 strings in GTK. |
||
CARETPOS |
(non inheritable) Also the character position of the insertion point, but using a zero based character unique index "pos". Useful for indexing the VALUE string. See the Notes above if using UTF-8 strings in GTK. (since 3.0) |
||
CHANGECASE |
(non inheritable) Change case according to given conversion. Can be UPPER, LOWER, TOGGLE, or TITLE. TITLE case change first letter of words separated by spaces to upper case others to lower case, but first letter is changed only if word has more than 3 characters, for instance: "Best of the World". Supports Latin-1 encoding only, even when using UTF-8. Does not depend on current locale. (since 3.28) |
||
CLIPBOARD |
(write-only) 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. (since 3.0) |
||
COUNT | (read-only) returns the number of characters in the text, including the line breaks. (since 3.5) | ||
CUEBANNER? |
[Windows and GTK Only] (non inheritable) a 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 works only when Visual Styles are enabled. (since 3.0) [GTK 3.2] (GTK support added in IUP 3.20) |
||
DROPFILESTARGET |
[Windows and GTK Only] (non inheritable) Enable or disable the drop of files. Default: NO, but if DROPFILES_CB is defined when the element is mapped then it will be automatically enabled. (since 3.0) |
||
FGCOLOR | Text color. Default: the global attribute TXTFGCOLOR. | ||
FILTER? |
[Windows Only] (non inheritable) allows a custom filter to process the characters: Can be LOWERCASE, UPPERCASE or NUMBER (only numbers allowed). (since 3.0) |
||
FORMATTING? |
[Windows and GTK Only] (non inheritable) When enabled allow the use of text formatting attributes. In GTK is always enabled, but only when MULTILINE=YES. Default: NO. (since 3.0) (See below) |
||
INSERT? |
(write-only) Inserts a text in the caret’s position, also replaces the current selection if any. Ignored if set before map. |
||
LINECOUNT | (read-only) returns the number of lines in the text. When MULTILINE=NO returns always "1". (since 3.5) | ||
LINEVALUE |
(read-only) 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 3.5) |
||
LOADRTF |
(write-only) [Windows Only]: loads formatted text from a Rich Text Format file given its filename. The attribute LOADRTFSTATUS is set to OK or FAILED after the file is loaded. (since 3.28) |
||
SAVERTF |
(write-only) [Windows Only]: saves formatted text to a Rich Text Format file given its filename. The attribute SAVERTFSTATUS is set to OK or FAILED after the file is saved. (since 3.28) |
||
MASK+ | (non inheritable) Defines a mask that will filter interactive text input. | ||
MULTILINE? |
(creation only) (non inheritable) allows the edition of multiple lines. In single line mode some characters are invalid, like "\t", "\r" and "\n". Default: NO. When set to Yes will also reset the SCROLLBAR attribute to Yes. |
||
NC |
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. |
||
NOHIDESEL | [Windows Only] do not hide the selection when the control loses its focus. Default: Yes. (since 3.16) | ||
OVERWRITE |
[Windows and GTK Only] (non inheritable) turns the overwrite mode ON or OFF. Works only when FORMATTING=YES. (since 3.0) |
||
PADDING+ |
internal margin. Works just like the MARGIN attribute of the IupHbox and IupVbox containers,
but uses a different name to avoid inheritance problems. Default value: "0x0". In Windows, only the horizontal value is used. (since 3.0) (GTK 2.10 for single line) |
||
CPADDING | same as PADDING but using the units of the SIZE attribute. It will actually set the PADDING attribute. (since 3.29) | ||
PASSWORD | (creation only) [Windows and GTK Only] (non inheritable) Hide the typed character using an "*". Default: "NO". | ||
READONLY? |
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. |
||
SCROLLBAR? |
(creation only) 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 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. |
||
SCROLLTO |
(non inheritable, write only) Scroll the text to make the given character position visible. It uses the same format and reference of the CARET attribute ("lin:col" or "col" starting at 1). In Windows, when FORMATTING=Yes "col" is ignored. (since 3.0) |
||
SCROLLTOPOS |
(non inheritable, write only) Scroll the text to make the given character position visible. It uses the same format and reference of the CARETPOS attribute ("pos" starting at 0). (since 3.0) |
||
SELECTEDTEXT |
(non inheritable) Selection text. Returns NULL if there is no selection. When changed replaces the current selection. Similar to INSERT, but does nothing if there is no selection. |
||
SELECTION |
(non inheritable) Selection interval in characters. Returns NULL 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 (since 3.0). See the Notes above if using UTF-8 strings in GTK. |
||
SELECTIONPOS |
(non inheritable) 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. See the Notes above if using UTF-8 strings in GTK. (since 3.0) |
||
SIZE+ |
(non inheritable) Since the contents can be changed by the user, the Natural Size is not affected by the text contents (since 3.0). Use VISIBLECOLUMNS and VISIBLELINES to control the Natural Size. |
||
SPIN+ |
(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. (since 3.0) For an example, or rather four, see demo\pGUI\boids3d.exw. |
||
SPINVALUE |
(non inheritable) the current value of the spin. The value is limited to the minimum and maximum values. |
||
SPINMAX+ | (non inheritable) the maximum value. Default: 100. | ||
SPINMIN+ | (non inheritable) the minimum value. Default: 0. | ||
SPININC | (non inheritable) the increment value. Default: 1. | ||
SPINALIGN | (creation only) the position of the spin. Can be LEFT or RIGHT. Default: RIGHT. In GTK is always RIGHT. | ||
SPINWRAP | (creation only) if the position reach a limit it continues from the opposite limit. Default: NO. | ||
SPINAUTO |
(creation only) 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. |
||
TABSIZE |
[Windows and GTK Only] Valid only when MULTILINE=YES. Controls the number of characters for a tab stop. Default: 8. |
||
VALUE+ |
(non inheritable) Text displayed to or entered/modified 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 "". |
||
VALUEMASKED |
(non inheritable) (write-only) sets VALUE but first checks if it is validated by MASK. If not does nothing. (since 3.4) |
||
VISIBLECOLUMNS? |
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 NULL after map to use it as an initial value. Default: 5 (since 3.0) |
||
VISIBLELINES |
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 NULL after map to use it as an initial value. Default: 1 (since 3.0) |
||
WORDWRAP? |
(creation only) 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. |
||
also |
ACTIVE+,
FONT,
NAME?,
EXPAND+,
SCREENPOSITION,
POSITION,
MINSIZE,
MAXSIZE,
WID,
TIP?,
RASTERSIZE+,
ZORDER,
VISIBLE,
THEME: also accepted.
Drag & Drop attributes are supported. See Notes above. |
||
Formatting: | (only applies when FORMATTING is YES) | ||
ADDFORMATTAG |
[write only] (non inheritable) Name of a format tag element to be added to the IupText. The name is associated in C using IupSetHandle. The name association must be done before setting the attribute. It will set the ADDFORMATTAG_HANDLE with the associated handle. |
||
ADDFORMATTAG_HANDLE |
[write only] (non inheritable) Handle of a format tag element to be added to the IupText. The tag element will be automatically destroyed when the IupText is mapped. If the IupText is already mapped, the format tag is immediately destroyed when the attribute is set. The format tag can NOT be reused. |
||
REMOVEFORMATTING |
[write only] (non inheritable) Removes the formatting of the current selection if Yes or NULL, and from all text if ALL is used. |
||
Format Tag: |
The format tag element is a simple IupUser element with some known attributes that
will be interpreted when the tag is updated in the native system.
The formatting depends on the existing text, so if VALUE attribute is set, all formatting is lost. You must set it again for the new text. If the FONT attribute of the IupText is set then it will affect the format of all characters in the text. The default values can not be dynamically changed. |
||
General Format Tag Attributes | |||
BULK |
flag that means this tag is composed by several tags as its children. Used to optimize format tag modifications. Default: NO. (since 3.3) |
||
CLEANOUT | when BULK=Yes is used to clear all the formatting at start. Default: NO. (since 3.3) | ||
SELECTION/SELECTIONPOS |
same as the IupText SELECTION/SELECTIONPOS attributes. If not defined the IupText attribute will be used. If the IupText attribute is also not defined then the current position will receive the format, so new text inserted or typed will be formatted with the tag (this is not working in GTK). Different tags that use the same selection interval are combined. Setting these attributes here will not change the current setting in IupText (since 3.3). |
||
UNITS |
[Windows Only]:
By default all distance units are integers in pixels, but in Windows you can also specify
integer units in TWIPs (one twip is 1/1440 of an inch). Can be TWIP or PIXELS. Default: PIXELS. |
||
Paragraph Format Tag Attributes | |||
ALIGNMENT | Can be JUSTIFY, RIGHT, CENTER and LEFT. Default: LEFT. | ||
INDENT |
paragraph indentation, the distance between the margin and the paragraph. In Windows the right indentation, and the indentation of the second and subsequent lines (relative to the indentation of the first line) can be independently set using the INDENTRIGHT and INDENTOFFSET attributes, but only when INDENT is set. |
||
LINESPACING |
the distance between lines of the same paragraph. In Windows, the values SINGLE, ONEHALF and DOUBLE can be used. |
||
NUMBERING |
[Windows Only]:
Can be BULLET (bullet symbol), ARABIC (arabic numbers - 1,2,3...), LCLETTER (lowercase letters - a,b,c...), UCLETTER (uppercase letters - A,B,C...), LCROMAN (lowercase Roman numerals - i,ii,iii...), UCROMAN (uppercase Roman numerals - I,II,III...), and NONE. Default: NONE. |
||
NUMBERINGSTYLE |
[Windows Only]:
Can be RIGHTPARENTESES "a)", PARENTESES "(a)", PERIOD "a.", NONUMBER (it will skip the numbering or bullet for the item) and NONE "". Default: NONE. |
||
NUMBERINGTAB | [Windows Only]: Minimum distance from a paragraph numbering or bullet to the paragraph text. | ||
SPACEAFTER | distance left empty above the paragraph. | ||
SPACEBEFORE | distance left empty below the paragraph. | ||
TABSARRAY |
a sequence of tab positions and alignment up to 32 tabs. It uses the format:"pos align pos align pos align...". Position is the distance relative to the left margin and alignment can be LEFT, CENTER, RIGHT and DECIMAL. In GTK only LEFT is currently supported. When DECIMAL alignment is used, the text is aligned according to a decimal point or period in the text, it is normally used to align numbers. |
||
Character Format Tag Attributes | |||
BGCOLOR | string containing a color in the format "rrr ggg bbb" for the background of the text. | ||
DISABLED | [Windows Only]: Can be YES or NO. Default NO. Set the visual appearance to disabled. | ||
FGCOLOR | string containing a color in the format "rrr ggg bbb" for the text. | ||
FONTSCALE |
a size scale relative to the selected or current size. Values greatter than 1 will increase the font. Values smaller than 1 will shrink the font. Default: 1.0. The following values are also accepted: "XX-SMALL" (0.58), "X-SMALL" (0.64), "SMALL" (0.83), "MEDIUM" (1.0), "LARGE" (1.2), "X-LARGE" (1.44), "XX-LARGE" (1.73). |
||
FONTFACE | the face name of the font. | ||
FONTSIZE | the size of the font in pixels or points. Pixel size uses negative values. | ||
ITALIC | Can be YES or NO. Default NO. | ||
LANGUAGE |
[GTK Only]: A text with a description of the text language. The same value can be used in the "SYSTEMLANGUAGE" global attribute. |
||
RISE |
the distance, positive or negative from the base line. Can also use the values SUPERSCRIPT and SUBSCRIPT, but this values will also reduce the size of the font. |
||
SMALLCAPS | [GTK Only]: Can be YES or NO. Default NO. (Does not work always, depends on the font) | ||
PROTECTED | Can be YES or NO. Default NO. When set to YES the selected text can NOT be edited. | ||
STRETCH |
[GTK Only]: Can be EXTRA_CONDENSED, CONDENSED, SEMI_CONDENSED, NORMAL, SEMI_EXPANDED, EXPANDED and EXTRA_EXPANDED. Default NORMAL. (Does not work always, depends on the font) |
||
STRIKEOUT | Can be YES or NO. Default NO. | ||
UNDERLINE | Can be SINGLE, DOUBLE, DOTTED or NONE. Default NONE. DOTTED is supported only in Windows. | ||
WEIGHT | Can be EXTRALIGHT, LIGHT, NORMAL, SEMIBOLD, BOLD, EXTRABOLD and HEAVY. Default: NORMAL. | ||
Examples | |||
Ihandle formattag IupSetAttribute(text, "FORMATTING", "YES") formattag = IupUser() IupSetAttribute(formattag, "ALIGNMENT", "CENTER") IupSetAttribute(formattag, "SPACEAFTER", "10") IupSetAttribute(formattag, "FONTSIZE", "24") IupSetAttribute(formattag, "SELECTION", "3,1:3,50") IupSetAttribute(text, "ADDFORMATTAG_HANDLE", formattag) formattag = IupUser() IupSetAttribute(formattag, "BGCOLOR", "255 128 64") IupSetAttribute(formattag, "UNDERLINE", "SINGLE") IupSetAttribute(formattag, "WEIGHT", "BOLD") IupSetAttribute(formattag, "SELECTION", "3,7:3,11") IupSetAttribute(text, "ADDFORMATTAG_HANDLE", formattag) formattag = IupUser() IupSetAttribute(formattag, "ITALIC", "YES") IupSetAttribute(formattag, "STRIKEOUT", "YES") IupSetAttribute(formattag, "SELECTION", "2,1:2,12") IupSetAttribute(text, "ADDFORMATTAG_HANDLE", formattag) |
|||
Example: |
When FORMATTING=YES in Windows or GTK (formatting attributes are set to a formatag object that it is a IupUser):
|
||
Callbacks: | |||
ACTION |
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.
function action_cb(Ihandle ih, integer c, atom pNewValue) ih: identifier of the element that activated the event. c: valid alpha numeric character or 0. pNewValue: Represents the new text value (char*). 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. |
||
BUTTON_CB | Action generated when any mouse button is pressed or released. Use IupConvertXYToPos() to convert (x,y) coordinates in character positioning. (since 3.0) | ||
CARET_CB |
Action generated when the caret/cursor position is changed.
function caret_cb(Ihandle ih, integer lin, col, pos) ih: identifier of the element that activated the event. 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". |
||
DROPFILES_CB | [Windows and GTK Only] Action generated when one or more files are dropped in the element. (since 3.0) | ||
MOTION_CB | Action generated when the mouse is moved. Use IupConvertXYToPos() to convert (x,y) coordinates in character positioning. (since 3.0) | ||
SPIN_CB |
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. (since 3.0) function spin_cb(Ihandle ih, integer pos) ih: identifier of the element that activated the event. pos: the value of the spin (after it was incremented). Returns: IUP_IGNORE is processed in Windows and Motif. |
||
VALUECHANGED_CB |
Called after the value was interactively changed by the user. (since 3.0)
function value_changed(Ihandle ih) ih: identifier of the element that activated the event. |
||
also |
MAP_CB,
UNMAP_CB,
DESTROY_CB,
GETFOCUS_CB,
KILLFOCUS_CB,
ENTERWINDOW_CB,
LEAVEWINDOW_CB,
K_ANY,
HELP_CB: All common callbacks are supported.
Drag & Drop callbacks are supported. See Notes above. |