InsertItemEx Method (LISTVIEW)

PLBCMP GUI Only

The InsertItemEx method adds a new item into a LISTVIEW object. The method uses the following format:

[label]	{object}.InsertItemEx	[GIVING {return}] USING [Text=]{text*}[:
		[Index=]{index*}][:
		[Image=]{image*}][:
		[Param=]{param*}][:
		[State=]{state*}][:
		[Statemask=]{statemask*}][:
		[Subitem1=]{stext*}][:
		[Subitem2=]{stext*}][:
		...
		[Subitem39=]{stext*}][:
		[Subitem40=]{stext*}]]

Where:

label

object

Required. A LISTVIEW object into which an item is inserted.

return

Optional. A Numeric Variable that returns the new item's zero-based row.

text

Required. A Character String Variable or literal that specifies the label associated with the new item.

index

Optional. A Numeric Variable that specifies the new item's zero-based requested row.

image

Optional. A Numeric Variable that specifies an IMAGELIST object index to associate with the item.

param

Optional. A decimal number or Numeric Variable that specifies the user-defined value associated with the item.

state

Optional. A decimal number or Numeric Variable that specifies the initial item state as described below.

statemask

Optional. A decimal number or Numeric Variable that specifies the valid state values as described below.

stext

Optional. A Character String Variable or literal that specifies the text associated with a sub item in the new item.

Flags Affected: EOS, OVER, ZERO

Note the following:

To insert an item or row at the end of a LISTVIEW, use an {index} that is larger than the current number of rows.
If an item is inserted in the middle of the object, the item at {index} and all rows below {index} are shifted down.
If no {index} is specified, the default value is zero (0) which will result in a push down list.
{index} is ignored if the sorted property is enabled.
The optional {state} value determines the item's initial state. This value must be repeated in {statemask}. Allowed values are as follows:

Value	Constant	Initially the item ...
0x1	LVIS_FOCUSED	has the focus and is surrounded by a standard focus rectangle. Although more than item may be selected, only one item can have focus.
0x2	LVIS_SELECTED	is selected. The appearance of a selected item depends on whether it has the focus and the system colors used to indicate selection.
0x4	LVIS_CUT	is marked.
0x8	LVIS_DROPHILITED	is highlighted as a drag-and-drop target.

The optional {statemask} is a value from the table above which indicates what values can be used in {state}.
Upon completion, {return} will contain the new item number or -1 if the method fails.
If the value returned is zero, the ZERO Condition Flag is set.
If {return} is too small to contain the new item number, the OVER Condition Flag is set.
The EOS Condition Flag is always cleared.
For improved performance in the Application Server environment, do not specify the optional return value or parameters unless needed.