GetItemState Method (TREEVIEW)

8.7, PLBCMP GUI Only

The GetItemState method retrieves the current state flags, overlay image index, and state image index for a specified item or row in a TREEVIEW object. The method uses the following format:

Where:

label

Optional. A Program Execution Label.

object

Required. A TREEVIEW object that is accessed.

return

Optional. A Numeric Variable that returns the item's state.

item

Required. A Numeric Variable that indicates the item within the object to access.

statemask

Optional. A numeric value whose integer bit map mask identifies the state member bits that are valid for retrieval.

Flags Affected: EOS, OVER, ZERO

Note the following:

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

2. The OVER and ZERO Condition Flags are always cleared.

3. Upon completion, {return} will a bit map of the item's current state.

4. Bits zero (0) through seven (7) contain the item's state flags as follows. The key words associated with the values are defined in PLBEQU.INC:

 

Value	Keyword	Meaning
0x2	TVIS_SELECTED	The item is selected. Its appearance depends on whether it has the focus. The item is drawn using the system colors for selection.
0x4	TVIS_CUT	The item is selected as part of a cut-and-paste operation.
0x8	TVIS_DROPHILITED	The item is selected as a drag-and-drop target.
0x10	TVIS_BOLD	The item is bold.
0x20	TVIS_EXPANDED	The item's list of child items is currently expanded; that is, the child items are visible. This value applies only to parent items.
0x40	TVIS_EXPANDEDONCE	The item's list of child items has been expanded at least once. This value applies only to parent items.
0x80	TVIS_EXPANDPARTIAL	Available in Version 4.70 of commctrl. The item is partially expanded. In this state, some but not all, of the child items are visible and the parent item's plus symbol is displayed.

5. Bits eight (8) through eleven (11) specify the one-based overlay image index. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK value:

 

Value	Keyword	Meaning
0xF00	TVIS_OVERLAYMASK	Mask for the bits used to specify the item's overlay image index

6. When you set or retrieve an item's overlay image index, you must specify the TVIS_OVERLAYMASK in the {StateMask} parameter.

7. A state image is displayed next to an item's icon to indicate an application-defined state. Specify the state image list by executing the SetImageList method. To set an item's state image, include the TVIS_STATEIMAGEMASK value in the StateMask.

8. Bits 12 through 15 of the state member operand specify the index in the state image list of the drawn image. To indicate that the item has no state image, set the index to zero. This convention means that image zero in the state image list cannot be used as a state image. To isolate bits 12 through 15 of the state member, use the TVIS_STATEIMAGEMASK mask:

 

Value	Keyword	Meaning
0xF000	TVIS_STATEIMAGEMASK	Mask for the bits used to specify the item's state image index

9. When you set or retrieve an item's state image index, you must specify the TVIS_STATEIMAGEMASK in the Statemask member.

10. If you are retrieving an item's state, set the bits of the stateMask member to indicate the return bits in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bit.

See Also: Method Syntax, TREEVIEW Methods