SetItemState Method (LISTVIEW)

PLBCMP GUI Only

The SetItemState method changes the state of an item within a LISTVIEW object. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A LISTVIEW object that is modified.

return

Optional. A Numeric Variable that indicates the success or failure of the method.

index

Required. A decimal number or Numeric Variable that specifies the zero-based item or row to modify.

state

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

statemask

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

Flags Affected: EOS, OVER, ZERO

Note the following:

1. The {state} value is a constant as defined in PLBMETH.INC or a numeric variable indicating one of the following states:

 

Value	Constant	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.
0xF00	LVIS_OVERLAYMASK	has its overlay image index set.
0xF000	LVIS_STATEIMAGEMASK	has its state image mask set.

2. When using the PL/B Web Server, only the LVIS_FOCUSED and LVIS_SELECTED state values are supported. Any other state values are meaningless and disregarded.

3. The required {statemask} is a value from the table above that indicates the valid initial state values. An item's state value includes a set of bit flags. The state value can also include image list indexes that indicate the item's state image and overlay image.

4. The {statemask} parameter specifies the state bits modified, and the {state} parameter specifies the new value for those bits. To set a bit in the item's internal state, set it in both the {statemask} and {state} parameters. To clear a bit in the item's internal state, set it in the {statemask} parameter and clear it in the {state] parameter. To leave a bit unchanged in the item's internal state, clear it in the {statemask} parameter.

5. Upon completion, {return} will contain the status of the modification as follows. $TRUE and $FALSE are defined in PLBEQU.INC:

 

Value	Constant	The modification ...
0	$FALSE	failed.
1	$TRUE	was successful.

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

6. The OVER and EOS Condition Flags are always cleared.

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

8. If the {index} is specified with a '-1' value, the {state} value is applied to all of the items in the LISTVIEW object.

See Also: Method Syntax, LISTVIEW Methods