TCheckListBox

Description

Displays a scrollable list with check boxes next to each item.

Remarks

TCheckListBox is similar to TListBox, except that each item has a check box next to it. Users can check or uncheck items in the list.

TCheckListBox Properties

Property AllowGrayed: Boolean (R/W)

Determines whether check box can be in a 'grayed' state. If AllowGrayed is set to true, each item has three possible states: checked, unchecked, and grayed. If AllowGrayed is set to false, each item has only two possible states: checked and unchecked.

Note: It is also possible to disable individual items while still showing whether they are checked or unchecked. To disable items without using the grayed state, use the ItemEnabled property.

Property Checked(Index: Integer): Boolean (R/W)

Indicates which items are checked. For each member of the Items array, Checked is true if a check mark appears in the item's check box. Checked corresponds to the cbChecked state; that is, Checked is true when State = cbChecked and false when State = cbUnchecked or State = cbGrayed.

Note: Items that have been disabled using the ItemEnabled property may still have a state of cbChecked and a Checked property of true.

Property Flat: Boolean (R/W)

Determines whether the check boxes appear three-dimensional. When Flat is true (the default), the check boxes in the list box have flat borders. Setting Flat to false gives the check boxes raised borders, which create a three-dimensional look.

Property ItemEnabled(Index: Integer): Boolean (R/W)

Enables or disables individual items in the list. Use ItemEnabled to enable or disable individual list items without using the cbGrayed state. Using ItemEnabled allows the list box to display check marks for items with a state of cbChecked while still graying the item and preventing the user from changing its state. For each member of the Items array, ItemEnabled is true if the user can change the state of the item. Enabled items have a state of cbChecked or cbUnchecked. ItemEnabled is false when State =cbGrayed or when the item has been explicitly disabled using this property.

Property Header(Index: Integer): Boolean (R/W)

Indicates which items act as headers. Set Header to true to specify that an item in the check listbox acts as a header rather than a selectable item. By setting Header to true for various items in the list, you can divide the check listbox into multiple sections, where each header labels the beginning of a section. When Header is true for an item, the list box does not display a check box next to the item, but rather, it displays only the item's text. This item is drawn with a background color of HeaderBackgroundColor and a font color of HeaderColor, which can be used to make it visually distinct from the checkable items in the list box. Index is the index of the item.

Property State: Enumeration (cbUnchecked, cbChecked, cbGrayed) (R/W)

Indicates which items are checked. For each member of the Items array, State indicates whether its check box is selected (cbChecked), deselected (cbUnchecked), or grayed (cbGrayed). State combines the information provided by the Boolean Checked property and the Boolean ItemEnabled property:

• When Checked is true, State is cbChecked. (However, when Checked is false, State may be either cbUnchecked or cbGrayed.)
• When State is cbGrayed, ItemEnabled is false. (However, ItemEnabled may also be false when State is cbUnchecked or cbChecked.)

TCheckListBox Events

Event OnClickCheck

Occurs when the user selects or deselects an item's check box. Write an OnClickCheck event handler to implement any special processing that should occur when the user checks or unchecks an item.

Note: This event does not occur for items that are grayed (State=cbGrayed) or disabled (ItemEnabled=false).