INSERTITEM

7.8.5, PLBCMP GUI Only

The INSERTITEM instruction adds an entry to a list object or modifies the text in an EDITTEXT object. It uses one of the following formats:

(1)	[label]	INSERTITEM	{object},{afteritem},{data}
(2)	[label]	INSERTITEM	{dialog},{dialog-no},{afteritem},{data}

Where:

label

Optional. A Program Execution Label.

object

Required. A previously defined and created object or pointer to an object into which an item is inserted.

afteritem

Required. A Numeric Variable, numeric literal, or Expression that indicates the existing item number after which the item is added.

data

Required. A previously defined Character String Variable or Literal containing the data that is inserted into the object.

dialog

Required. A previously defined and created DIALOG object or pointer to a DIALOG object into which an item is inserted.

dialog-no

Required. A Numeric Variable, Literal or Expression that contains the dialog item number of the COMBOBOX, POPUPMENU, or DATALIST dialog item from which an item is deleted.

Flags Affected: NONE

Note the following:

For all objects except an EDITTEXT object, the item is added after the item number given in the {afteritem} operand. A zero in the {afteritem} operand causes the inserted item to become the first item. If the {afteritem} operand contains a number that is larger than the number of items in the object, the new item is added at the end of all the items.
For an EDITTEXT object, the value of the {after-item} parameter determines the operation that is performed. A value of zero indicates that the {data} string is appended to the end of the current edit text data. A value of one indicates that the {data} string is inserted after the ending position of selected text. A starting position and ending position for selected text is specified using the SETITEM instruction.
The maximum amount of data that may be placed in a DATALIST or EDITTEXT object is limited by the operating system.
The {data} operand is the actual data used for the menu line or data list entry.
An object must be CREATEd before using INSERTITEM. If this is not done, a runtime error of O105 is generated.
DATALIST items may contain tab characters (0x9) allowing alignment of data in columns as defined by the TABSTOPS property.
Multiple logical records may be loaded into a DATALIST or COMBOBOX in a single operation. An embedded 0x7F character in {data} is identified as a logical record terminator. The detection of the 0x7F is a default action by the runtime for the INSERTITEM and SETITEM instructions and the AddString and InsertString methods. These operations provide improved load times when using the PL/B Application Server. The feature may be enabled or disabled by using the SETMODE *USE7F instruction.