Classes defining TCheckListBox - a List Box with Check Box items.

checklst.pas implements the TCheckListBox control which displays a list with check box items. The following components are added to the Lazarus IDE component palette:

Additional Tab

- TCheckListBox

Defines an object procedure signalled when an item in TCheckListBox is clicked.

TCheckListClicked is an object procedure type that defines an event handler signalled when an item in TCheckListBox is clicked. TCheckListClicked is the type used to implement the OnItemClick event handler in TCheckListBox. Applications must provide an implementation of the type and assign to the event handler to respond to the event notification.

TObject instance for the event notification.
Ordinal position for the item clicked in the control.
The base class for TCheckListBox, a list box with check box items.

TCustomCheckListBox is a TCustomListBox descendant which defines the base class used to implement TCheckListBox. It is a list box control which displays check boxes for items added to the list. It provides the scrolling, selection, and drawing styles inherited from the ancestor class. It also includes the ability to render its items as a check box, and respond to mouse or keyboard events when the checked state for an item is toggled.

Gets the value for the indexed Checked property.
Value for the property.
Ordinal position in Items for the affected entry.
Gets value for the indexed Header property.
Value for the property.
Ordinal position in Items for the affected entry.
Gets the value for the indexed ItemEnabled property.
Value for the property.
Ordinal position in Items for the affected entry.
Gets the value for the indexed State property.
Value for the property.
Ordinal position in Items for the affected entry.
Sets the value for the indexed Checked property.
Ordinal position in Items for the check box updated in the method.
New value for the property.
Notifies the widget set class when the state for the specified item has been changed.
No actions are performed in the method if a handle has not been allocated for the control.
Ordinal position in Items for the affected entry.
Check box state applied to the item.
Notifies the widget set class when the Enabled state for the specified item has been changed.
No actions are performed in the method if a handle has not been allocated for the control.
Ordinal position in Items for the affected entry.
Enabled state applied to the item.
Notifies the widget set class when the specified item should be drawn as a header instead of a check box.
No actions are performed in the method if a handle has not been allocated for the control.
Ordinal position in Items for the affected entry.
True when the item is a header; False when it is a check box.
Performs actions needed when an entry in Items is changed using the keyboard or mouse.

DoChange is a procedure used to respond to the LCL LM_CHANGED message, and performs actions needed when an entry in Items is changed using the keyboard or mouse. DoChange calls ClickCheck to signal the OnClickCheck event handler (when assigned). It also calls the ItemClick method to signal the OnItemClick event handler (when assigned).

LCL message processed and applied in the method.
Sets the value for the indexed Header property.
Ordinal position in Items for the property value.
Value for the property; True indicates a header, and False indicates a check box.
Sets the value for the indexed ItemEnabled property.
Ordinal position in Items for the property value.
New value for the property; True indicates a header, and False indicates a check box.
Sets the value for the indexed State property.
Ordinal position in Items for the new property value.
New value for the property.
Stores the data for an item at the specified position in the cache for item data.
Ordinal position for the entry in Items stored in the method.
Pointer to the item data stored in the cache.
Retrieves data for an item at the specified position from the cache for item data.
Ordinal position for the item updated from the item data cache.
Pointer to the data retrieved in the method.
Sets the creation parameters for the control handle.

CreateParams is an overridden procedure used to set the creation parameters for the class instance. It calls the inherited method on entry, and sets the list box drawing style flag for the class instance.

Parameters applied to the control, including the Owner drawing style.
Adjusts the drawing area for the specified item, and renders it on the control.

DrawItem is an overridden procedure used to render the item specified in AIndex to the drawing area in ARect. DrawItem ensures that sufficient space is reserved for the check box drawn for an item on the list box.

The Header property determines whether a check box is required for the item, and GetCheckWidth is called to get the width for the check box when needed. ARect is updated to increase or decrease the horizontal boundary depending on the value in UseRightToLeftAlignment; The right boundary is decremented for RTL, and the left boundary is incremented for LTR.

DrawItem calls the inherited method to render the item on the list box for the control.

TCustomListBox.Items
Ordinal position in Items for the entry drawn in the method.
TRectangle with the drawing area for the item.
TOwnerDrawState for Items in the control.
Gets the data size for a TCachedItemData entry in the item cache.

GetCachedDataSize is an overridden Integer function used to get the data size for a TCachedItemData entry in the item data cache. The return value contains the number of bytes needed for the TCachedItemData entry including the offset in the cache.

Number of bytes required for cached item data.
Gets the width required for the check box drawn for Items on the control.
Width needed to draw a check box.
Reads the data for the control from the specified stream.

ReadData is a procedure used to read the data for Items in the control from the specified TStream instance.

TStream instance with the data read in the method.
Writes data for the control to the specified stream.

WriteData is a procedure used write data for the control to the TStream instance.

TStream instance where data for the control is written in the method.
Performs actions needed when a value in the control is about to change.

ClickCheck is a method used to perform actions needed when a value in the control is about to change.

ClickCheck signals the OnClickCheck event handler (when assigned) using the current class instance as the object for the event notification. Use OnClickCheck to implement the actions needed when the control has been changed.

ClickCheck is called when the LM_CHANGED message is handled for the control, and occurs prior to calling the ItemClick method where the OnItemClick event handler is signalled.

ClickCheck is also called from the KeyDown method when the Space key has been pressed while the control has focus. It is called after ItemIndex has been range adjusted (when needed) and the inherited Click method is called. In addition, the value in Checked has already been toggled before the method is called. ClickCheck is not called for the keystroke when the check box item in ItemIndex is not enabled.

Performs actions when the specified check box has been changed using the mouse or the keyboard.

ItemClick is a method used to perform actions need when the value for the check box item in AIndex has been changed. AIndex is the ordinal position for the check box in the Items for the control. ItemClick signals the OnItemClick event handler (when assigned) using the current class instance and the value in AIndex as arguments.

ItemClick is called when the LM_CHANGED message is handled for the control, and occurs after the ClickCheck method has been called to signal the OnClickCheck event handler.

ItemClick is also called from the KeyDown method when the Space key has been pressed while the control is focused. It occurs after the value in ItemIndex is range adjusted (if needed) and the inherited Click method has been called. In addition, the value in Checked has already been toggled before the method is called. ItemClick is not called for the key event when the check box item in ItemIndex is not enabled.

Ordinal position for the check box.
Handles key down messages for the control.

KeyDown is an overridden method in TCustomCheckListBox used to handle key down messages for the control. KeyDown ensures that the value for the current check box is toggled when the Space key is pressed while the control has focus.

This includes setting ItemIndex to 0 when it has a value not valid for the Items defined in the control. The inherited Click method is called if ItemIndex is range adjusted. This behavior is Delphi (version 7 at least) compatible.

If the check box at ItemIndex has its ItemEnabled property set to True, the value in Checked is toggled. The ClickCheck and ItemClick methods are called to trigger the corresponding event handlers. The value in Key is set to VK_UNKNOWN when the keystroke has been handled in the method.

The inherited KeyDown method is called to handle other key down events.

TWinControl.KeyDown TCustomListBox.Click
Keystroke examined in the method.
Shift, Control, or Alt modifier for the keystroke.
Recalculates the height for check box Items in the control when the Font is changed.

FontChanged is an overridden method in TCustomListBox used to perform actions when the Font for the control has been changed. FontChanged calls the inherited method on entry. The value in ItemHeight is updated (at run-time) when the control Style is set to lbStandard.

TCustomListBox.ItemHeight TCustomListBox.Style TWinControl.FontChanged TControl.Font
TObject instance for the change notification.
Constructor for the class instance.

Create is the overridden constructor for TCustomCheckListBox. It calls the inherited Create method, and sets the component style flag for the control. It also calls the inherited GetCachedDataSize method to determine the storage size needed for each cached item in the control.

TCustomListBox.Create TCustomListBox.GetCachedDataSize
Owner of the class instance.
Calculates the height for an item displayed in the check list control.

MeasureItem is an overridden method used to calculate the height for an item displayed in the check list control.

MeasureItem re-implements the method from the ancestor class, and calculates the item height when the Style property is set to lbStandard. The values from CalculateStandardItemHeight and GetSystemMetrics (using SM_CYMENUCHECK) are compared to get the item height. The larger of the two values is stored in the TheHeight argument.

When Style is set to a value other than lbStandard, the inherited method is called to calculate the item height using the OnMeasureItem event handler.

TCustomListBox.CalculateStandardItemHeight TCustomListBox.MeasureItem TCustomListBox.OnMeasureItem TCustomListBox.Style GetSystemMetrics
Ordinal position for the check box item measured in the method.
Returns the calculated height for the check box item.
Toggles the Checked, Unchecked, Grayed state for the specified item in the control.

Toggle is a procedure used to toggle the checked, unchecked, or grayed state for the item at the specified position in Items.

Toggle ensures the value in the AllowGrayed property is respected in the operation. When AllowGrayed is True, the following order is used for toggling to the next available check box state:

1. cbUnchecked
2. cbChecked
3. cbGrayed
4. Rinse and repeat

When AllowGrayed is False, the following order is used for toggling to the next available check box state:

1. cbUnchecked
2. cbChecked
3. Rinse and repeat

Use Checked to set a specific item to a specified Boolean checked state value. Use State to get or set the check box state as a TCheckBoxState value. Use CheckAll to change the checked state and disposition for all Items in the control.

TCustomListBox.Items
Ordinal position of the item state toggled in the method.
Sets the specified values for State, AllowGrayed, and ItemEnabled for all Items in Control.

CheckAll is a procedure used to set the specified values for the State, AllowGrayed, and ItemEnabled properties for all Items in the control. The default value for both aAllowGrayed and aAllowDisabled is True. CheckAll iterates over the entries in the Items property and updates the State property to match the value in the arguments to the method.

Use Checked to set a specific item to a specified Boolean checked state value. Use State to get or set the check box state as a TCheckBoxState value. Use ItemEnabled to get or set the enabled state for a specific entry in Items.

TCustomListBox.Items
Check box state applied to Items in the control`
AllowGrayed property value applied to Items in the control.
ItemEnabled property value applied to Items in the control.
Swaps the values for the State properties in the Items at the specified ordinal positions.
Ordinal position for the first item affected in the method.
Ordinal position for the second item affected in the method.
Indicates if the item can use the "grayed" (or unselectable) check box state.

AllowGrayed is a Boolean property which indicates if Items in the control can use the "grayed" (or unselectable) check box State. The default value for the property is False, and indicates that only Checked and Unchecked values can be used in the State property.

Provides indexed access to the Boolean Checked or Unchecked state for Items in the control.

Checked is an indexed Boolean property which provides access to the Checked or Unchecked state for Items in the control. The value for the property is True when State contains any value other than cbUnchecked. Setting the value for the property updates State to contain either cbChecked (when True) or cbUnchecked (when False).

Ordinal position for the entry in Items affected in the method.
Provides indexed access to header usage status for Items in the control.

Header is an indexed Boolean property which indicates if the specified item is used as a header (instead of a check box) in the control. When the property contains True, the item is rendered as text and does not include any check box behavior.

Reading the value in Header causes the CheckIndex method to be called to validate the value in Index. If a handle has been allocated for the control, the GetHeader method in the widget set class is called to get the value for the property. Otherwise, the cached item data for the control is examined to get the property value.

Setting a new value for the property causes the CheckIndex method to be called to validate the value in Index. If a handle has been allocated for the control, the SendItemHeader method is called to set the value for the property. Otherwise, the cached item data for the control is updated.

TCustomListBox.Items
Ordinal position for the item affected in the method.
Provides indexed access to the enabled state for Items in the control.

ItemEnabled is an indexed Boolean property which provides access to the enabled state for Items in the control. When the property value is True, the item can be selected to change its State or Checked values. When it is False, it behaves as if the check box has been disabled for the item.

Reading the value for the property cause the CheckIndex method to be called to validate the value in Index. If a handle has been allocated for the control, the GetItemEnabled method in the widget set class is called to get the value for the property. Otherwise, the disabled state in cached item data is examined to get the property value.

Setting the value for the property causes the CheckIndex method to be called to validate the value in Index. If a handle has been allocated for the control, the SetItemEnabled method in the widget set class is called to set the value for the property. Otherwise, the disabled state in cached item data is update with the new property value.

Use the Enabled property to indicate whether the check list box control can be updated.

TCustomListBox.Items TControl.Enabled
Ordinal position for the item affected in the method.
Provides indexed access to the TCheckBoxState for Items in the control.

State is an indexed TCheckBoxState property which provides access to the check box state for Items in the control. The TCheckBoxState enumeration value indicates whether the specified item is in a Checked, Unchecked, or Grayed state.

Reading the value in State causes the CheckIndex method to be called to validate the value in AIndex. If a handle has been allocated for the control, the GetState method in the widget set class is called to get the value for the property. Otherwise, the cached item data for the control is examined to get the value for the property.

Setting the value in State causes the CheckIndex method to be called to validate the value in AIndex. If a handle has been allocated for the control, the SendItemState method is called to set the value for the property in the widget set class. Otherwise, the cached item data for the control is updated with the new property value.

Use Checked to get or set the check box state for an item in the control using a Boolean value. Use CheckAll to set the check box state for all Items in the control. Use Toggle to select the next check box state for an item in the control.

TCustomListBox.Items
Ordinal position for the Item examined in the property.
Event handler signalled when a check box in the control has been changed.

OnClickCheck is a TNotifyEvent property with the event handler signalled when the check box state for one of the list items has been changed.

Applications must implement and assign a procedure using the TNotifyEvent signature to respond to the notification. The Sender argument contains the TCheckListBox instance for the notification, and allows access to its properties and methods.

OnClickCheck is signalled (when assigned) from the ClickCheck method. ClickCheck is called from methods like DoChange (private) and KeyDown. This causes OnClickCheck to be signalled when the mouse is clicked on a check box, and when the value for the current item is Toggled using the Space key.

OnClickCheck is signalled before other event handlers like OnItemClick, OnSelectionChange, and OnClick.

OnClickCheck and OnItemClick are not signalled when the checked state for an item is changed in code using Checked, State, CheckAll, or Toggle.

Use OnItemClick for the event signalled with the item index for the affected check box in the control.

TCustomListBox.OnSelectionChange TCustomListBox.OnClick TNotifyEvent
Event handler signalled when the check box state for a specific item has been changed.

OnItemClick is a TCheckListClicked property with the event handler signalled when the check box state has been changed for a specific item in the check list control.

OnItemClick can be used to perform actions needed when the check box State has been toggled. Arguments passed to the event handler identify the check list control (Sender) and the position of the check box (Index) in the Items for the control.

Applications must assign an object procedure that implements the signature for the event handler to respond to the notification.

OnItemClick is signalled from the ItemClick method when the control executes its DoChange (private) or KeyDown methods. This means that the event is signalled when a check box is clicked with the mouse, and when the Space key is pressed on a selected item in the control.

OnItemClick is signalled after the OnClickCheck event handler, and before event handlers like OnSelectionChange and OnClick.

OnClickCheck and OnItemClick are not signalled when the checked state for an item is changed in code using Checked, State, CheckAll, or Toggle.

Use OnClickCheck to perform control-level actions needed when a check box is changed.

TCustomListBox.Items TCustomListBox.ItemIndex TCustomListBox.OnSelectionChange TCustomListBox.OnClick
TCheckListBox
implements a list box with check boxes for its items.

TCheckListBox is a TCustomCheckListBox descendant which implements a scrollable list box which displays check boxes for each of its items.

Use the Items property to define the caption for entries that appear in the control. Each of the Items can have a state of checked or unchecked (or "grayed" when AllowGrayed is set). Use the properties and methods such as Toggle, CheckAll, Checked, ItemEnabled, and State to maintain the items in the control.

It provides the scrolling, selection, and drawing styles inherited from the ancestor class. It also includes the ability to render its items as a check box, and to respond to mouse or keyboard events when an item is toggled.

Use the event handlers in the class to perform actions needed when one or more items are clicked or change their state value. Use OnItemClick to process item changes individually.

TCheckListBox sets the visibility for properties defined in the ancestor class.

Adds TCheckListBox to the Lazarus IDE.
Register
is a procedure used to add the TCheckListBox class to the Additional tab in the Lazarus IDE.