• EditText class
• Auto-tab on single-line EditText
• Line wrapping on multi-line EditText

Usually, an EditText object immediately follows an associated StaticText label in the same Dialog hierarchy level. If the EditText is editable, the StaticText label usually defines an accelerator key to move the keyboard focus to the EditText object.

If editable, an EditText object provides the undo functionality through the Ctrl+Z or Meta+Z key combination and is subject to the configured insert and/or overwrite editing mode. If configured, the user may toggle between insert and overwrite mode using the INSERT key.

When an editable single-line EditText receives the keyboard focus, the content is selected unless a mouse click moved the focus or the overwrite editing mode is active.

When the keyboard focus is moved away from an editable EditText, a nonzero rule value is returned to the program. Depending on the object which receives the keyboard focus, this may be subject to the RuleOverride functionality.

By default, editable EditText objects have a clipboard context menu assigned which is opened when the context menu mouse button is clicked. For details, please refer to the Context menus documentation.

add : string, set

If used with a multi-line EditText, adds new text to the end of the content. Lines are separated by LF (ASCII 10).

If used with a single-line EditText, the content is replaced.

align : string, get/set

Specifies how the content of a single-line EditText is horizontally aligned.

Possible values are:
 "left"
 "center"
 "right"

The default value is "left".

autotab : integer, get/set

Specifies the auto-tab behavior. The autotab attribute value may be set to the sum of the modes below:

1		The focus is moved to the next object in the Dialog tab order if text is entered and maxchars are reached, or if the cursor-right key is used while the EditText content is not empty and the EditText cursor is at the rightmost position.
2		The focus is moved to the previous object in the Dialog tab order if the backspace key is used to delete the last character, or if the cursor-left key is used while the EditText cursor is at the leftmost position.
4		Moving the focus does not submit the EditText rule value to the program.

The default value is 0 (auto-tab disabled).

Notes:

• The autotab attribute has no effect if used with multi-line EditText objects.

• For details, please refer to the auto-tab documentation below.

• Requires JDLG version 1.7.0 or newer.

border : integer, get/set

Provided for ASCII DLG backward compatibility.

The EditText border visibility and thickness cannot be specified. An EditText always has a (platform or look-and-feel specific) border.

The default value is 1.

class : string, get

Returns "EditText".

clear : integer or string, set

Deletes the entire content. The argument is ignored.

content : string, get/set

Used to get or set the content. If used with a multi-line EditText, lines are separated by LF (ASCII 10).

cx : integer, get/set

Current column of the text cursor (starting with 0).

cy : integer, get/set

Current line of the text cursor (starting with 0). If used with a single-line EditText, this is always 0.

delln : integer, set

If used with a multi-line EditText, deletes the specified number of lines, starting with the current line (cy).

If used with a single-line EditText, the entire content is deleted (see also clear above).

editable : integer, get/set

Nonzero (default): The EditText is editable.
Zero: The EditText is not editable.

fitfont : integer, get/set

If nonzero, adjusts the EditText width and/or height to the size of the font which is used to display the content. In certain cases, this may help to avoid clipped content.

Supported values:

0 (default)		The EditText size is not adjusted.
1		The EditText width is adjusted to the font width of the "X" character, multiplied by the width of the EditText object in Dialog raster units. This requires a nonzero horizontal layout mode.
2		The EditText height is adjusted to the font height, multiplied by the height of the EditText object in Dialog raster units. This requires a nonzero vertical layout mode.
3		Combination of 1 and 2 above.

Note: JDLG versions before 1.7.0 might show unexpected behavior if the fitfont attribute is used with multi-line EditText objects.

hsb : integer, get/set

No function (provided for ASCII DLG backward compatibility).
A multi-line EditText displays the horizontal scroll bar if required.
See also vsb below.

ins : string, set

Inserts new text before the cx/cy text cursor position. If used with a multi-line EditText, lines are separated by LF (ASCII 10).

ispassword : integer, get/set

Zero (default): The EditText content is normally displayed.
Nonzero: The content is masked, so that the EditText may be used for password entry.

Note: This attribute has no effect if used with a multi-line EditText.

length : integer, get

returns the content length.

line[] or line : string, get/set

If used with a multi-line EditText, gets or sets the line with the specified index (starting with 1). If used without an index or with a zero index, the current line (cy) is affected.

If used with a single-line EditText, the entire content is affected.

Note: On DLG SET, a new line is appended if the specified line does not exist. On DLG GET, if used with an index, ERROR 660 is issued if the specified line does not exist. If used without an index or with a zero index, DLG GET returns an empty string if the specified line does not exist.

linewrap : string, get/set

Enable line wrapping, select soft or hard line wrapping.

Possible values are:

"none" (default)		disable line wrapping
"soft"		enable soft line wrapping
"hard"		enable hard line wrapping

Notes:

• The linewrap attribute has no effect if used with single-line EditText objects.

• The line break point may be configured to fall on a word boundary if possible, or to use the rightmost character position.

• For details, please refer to the line wrapping documentation below.

• Requires JDLG version 1.7.0 or newer.

maxchars : integer, get/set

Limits the maximum number of characters the EditText may contain. If used with a multi-line EditText, this includes the LF (ASCII 10) line separators.

maxlines : integer, get/set

Limits the maximum number of text lines in a multi-line EditText.
If used with a single-line EditText, this attribute has no effect.

multiline : integer, get/set

Zero (default): Specifies a single-line EditText object.
Nonzero: Specifies a multi-line EditText object.

rule : integer, get/set

If nonzero and the EditText is editable, the rule value is returned to the program, along with the path of the EditText object, when the keyboard focus is moved away from the EditText. Depending on the object which receives the keyboard focus, this may be subject to the RuleOverride functionality.

The default rule value is zero.

See also the documentation of the common rule attribute and the RuleOverride functionality.

tcdelay : integer, get/set

Specifies a delay in milliseconds before the tcrule value is returned to the program.

The default tcdelay value is 500 (milliseconds).

See also tcrule below.

tcminchars : integer, get/set

When characters are added, the tcrule value is not submitted as long as the content length is less than tcminchars.

The default tcminchars value is 1.

See also tcrule below.

tcrule : integer, get/set

If nonzero, the tcrule value is returned to the program, along with the path of the EditText object, while the user is editing the content (i.e., before the keyboard focus is moved away).

The tcdelay and tcminchars attributes configure how often the tcrule value is returned to the program.

This, for example, allows to implement an autocomplete function. The tcrule value is returned to the program when the user has typed the beginning of a search term. The user does not need to press the ENTER or TAB key.

The default tcrule value is zero.

See also the documentation of the common rule attribute, and tcdelay and tcminchars above.

title : string, get

No function (provided for ASCII DLG backward compatibility).
Always returns an empty string.

vheight : integer, get

If used with a multi-line EditText, returns the current number of lines. If used with a single-line EditText, returns zero if the content is empty, otherwise returns 1.

vsb : integer, get/set

No function (provided for ASCII DLG backward compatibility).
A multi-line EditText displays the vertical scroll bar if required.
See also hsb above.

vwidth : integer, get

If used with a multi-line EditText, returns the number of characters of the currently widest line. If used with a single-line EditText, returns the content length.

wrapmode : string, get/set

Configure the line wrapping break point to fall on a word boundary if possible, or to use the rightmost character position.

Possible values are:

"word" (default)		if possible, line breaks fall on a word boundary
"char"		line breaks fall on the rightmost character position

Notes:

• The wrapmode attribute has no effect if used with single-line EditText objects.

• If the linewrap attribute is not set or set to "none", the wrapmode attribute has no effect.

• For details, please refer to the line wrapping documentation below.

• Requires JDLG version 1.7.0 or newer.

In another usage scenario, multiple EditText objects could be connected so that they interact as a unit.

Notes:

• Has no effect on multi-line EditText objects.
• Requires JDLG version 1.7.0 or newer.

The auto-tab function may be configured in various ways:

• If text is entered and maxchars are reached, the focus is moved to the next object in the Dialog tab order.

• If the backspace key is used to delete the last character, the focus is moved to the previous object in the Dialog tab order.

• If the cursor-right key is used while the EditText content is not empty and the EditText cursor is at the rightmost position, the focus is moved to the next object in the Dialog tab order.

• If the cursor-left key is used while the EditText cursor is at the leftmost position, the focus is moved to the previous object in the Dialog tab order.

• The auto-tab mode allows to specify whether or not moving the focus submits the EditText rule to the program.

Example 1:

A group of multiple EditText objects is used to enter an account number, where each has the w and maxchars attributes both set to 4, so that the account number is entered in groups of 4 characters.

To enable auto-tab between these EditText objects:

• leftmost EditText object has autotab set to 1
• middle EditText objects have autotab set to 3 (modes 1 + 2)
• rightmost EditText object has autotab set to 2

Example 2:

Same as above, but the EditText rule is not submitted to the program while auto-tab moves the focus.

The rule is submitted when the TAB or ENTER key is pressed or if a mouse click moves the focus. This way, all EditText objects in the group behave as if they were one EditText, and consequently their rule attribute values are identical.

To enable auto-tab between these EditText objects:

• leftmost EditText object has autotab set to 5 (modes 1 + 4)
• middle EditText objects have autotab set to 7 (modes 1 + 2 + 4)
• rightmost EditText object has autotab set to 6 (modes 2 + 4)

With soft line wrapping enabled lines are visually wrapped but the content is not modified, while hard line wrapping modifies the content by adding LF (ASCII 10) line separators at each break point.

For example, if hard line wrapping is used, the lines returned by DLG GET "EditText.content" contain LF line separators at each visual break point. With soft line wrapping on the other hand, LF separators appear in the content where inserted (ENTER key) or where present in the original content.

If line wrapping is enabled and the maxlines attribute should limit the visual number of lines, hard line wrapping must be configured.

Notes:

• Has no effect on single-line EditText objects.
• Requires JDLG version 1.7.0 or newer.