InsertItem Method (LISTVIEW)

PLBCMP GUI Only

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

Where:

label

Optional. A Program Execution 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 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 a user-defined value.

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.

Flags Affected: EOS, OVER, ZERO

Note the following:

1. To insert an item or row at the end of a LISTVIEW, use an {index} that is larger than the current number of rows.

2. If an item is inserted in the middle of the object, the item at {index} and all rows below {index} are shifted down.

3. If no {index} is specified, the default value is zero (0) which will result in a push down list.

4. {index} is ignored if the sorted property is enabled.

5. The optional {state} value determines the item's initial state 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.

 

6. The optional {statemask} is a value from the table above which indicates the valid initial state values.

7. Upon completion, {return} will contain the new item number or -1 if the method fails.

8. If the value returned is zero, the ZERO Condition Flag is set.

9. If {return} is too small to contain the new item number, the OVER Condition Flag is set.

10. The EOS Condition Flag is always cleared.

11. For improved performance in the Application Server environment, do not specify the optional return value and parameters unless needed.

See Also: Method Syntax, LISTVIEW Methods