• ComboBox class

If the editable attribute is set to zero, a ComboBox object behaves similar to a PopText. However, a PopText provides more functionality.

Usually, a ComboBox object immediately follows an associated StaticText label in the same Dialog hierarchy level. The StaticText label usually defines an accelerator key to move the keyboard focus to the ComboBox object.

If editable, a ComboBox 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 ComboBox 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 a ComboBox, 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 ComboBox 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

Adds new items to the end of the item list.
Items are separated by LF (ASCII 10).

align : string, get/set

Specifies how the content and the items in the item list are horizontally aligned.

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

The default value is "left".

boxheight : integer, get/set

Specifies the height of the box displaying the item list, i.e., how many items are visible. If the item list contains more than the specified number of items, a vertical scroll bar is displayed.

The default value is 8.

boxwidth : integer, get/set

Allows to set the box displaying the item list wider than the ComboBox object.

The default value is zero (item list width is equal to ComboBox width).

Notes:

• The box displaying the item list is at least as wide as the ComboBox object. Setting boxwidth less than or equal to the ComboBox width has no effect.

• Requires JDLG version 2.0.14 or newer.

class : string, get

Returns "ComboBox".

clear : integer or string, set

Deletes the content and the item list. The argument is ignored.

content : string, get/set

Used to get or set the content.

editable : integer, get/set

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

Note: A ComboBox that is not editable behaves similar to a PopText. However, a PopText provides more functionality.

items : string, get/set

Used to get or set all items in the item list at once.
Items are separated by LF (ASCII 10).

line[] or line : string, get/set

Gets or sets the item in the item list with the specified index (starting with 1). If used without an index or with a zero index, the content is affected.

Note: On DLG SET, if used with an index, a new item is appended if the specified item does not exist. On DLG GET, if used with an index, ERROR 660 is issued if the specified item does not exist.

list : string, get/set

Alias for the items attribute (see above).

maxchars : integer, get/set

Limits the maximum number of characters.

open : integer, get/set

If nonzero, the item list is automatically opened when an editable ComboBox object receives the keyboard focus, provided that the item list is not empty.

This, for example, could be useful to implement an autocomplete function. When focused, the user may immediately navigate any search results, the user does not need to manually open the item list first.

The default open value is zero.

See also tcrule below.

rule : integer, get/set

If nonzero, the rule value is returned to the program, along with the path of the ComboBox object, when the keyboard focus is moved away from the ComboBox. 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.

Note: Unlike a PopText object, a ComboBox that is not editable does not submit the rule value when the selected line changes.

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 ComboBox 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 open, tcdelay, tcminchars above.