ListBoxes and TreeListBoxes - Checkbox Items

A recent question on the Revelation forum touched on the subject of using checkbox items in LISTBOX and TREELISTBOX controls, and this highlighted the need to document some of the new properties in OpenInsight v10 that support this functionality. In this post we'll take a look at how you can use these to make adding checkbox items to your controls a simple task.

In previous versions of OpenInsight adding checkboxes to items was done with "smoke and mirrors", i.e. actual item images were used to represent the checkbox, and the control itself had no concept of a checked state for any of it's contents. Usually, when the user clicked on the item's checkbox image, the UPDATE method was used toggle the image from checked to unchecked and vice versa. The checked state would be obtained by looking at the image number using the LIST property. Unfortunately this technique has two main drawbacks:

• The code for detecting the mouse clicks can be complex, and when added to the image manipulation code itself the intent of the code can become obscured.
• The images themselves must be maintained manually and updated to match the current Windows visual styling.

In OpenInsight v10 checkbox items are supported "natively" so that the control itself knows which items are "checked" and exposes the properties described below to support this. This results in less coding and a much cleaner program. 

This is a simple boolean property that can be set in the Form Designer or at runtime. Setting it to TRUE$ ensures that all items in the control are drawn with a checkbox - this is all that needs to be done to use checkbox items.

This property allows you to get or set the checked state of one or more items using an @fm-delimited dynamic array of boolean flags.

// Set the second and fourth items in the LISTBOX to checked, ensure the
// third item is NOT checked.
 
CheckedItems = Get_Property( CtrlEntID, "CHECKED" )
CheckedItems<2> = TRUE$
CheckedItems<3> = FALSE$
CheckedItems<4> = TRUE$
 
Call Set_Property_Only( CtrlEntID, "CHECKED", CheckedItems )

The CHECKED property may also be used with the index parameter to get or set the state of a single item at a time:

// Set the ninth item to checked, and uncheck the tenth item
Call Set_Property_Only( CtrlEntID, "CHECKED", TRUE$, 9 )
Call Set_Property_Only( CtrlEntID, "CHECKED", FALSE$, 10 )

This property is similar to the CHECKED property but only applies to TREELISTBOX controls, and gets or sets the checked state for all items in the fully expanded list. 

This property returns an @fm-delimited dynamic array of item indexes that have been checked. This is an optimization property so that you don't have to iterate over the CHECKED property to find out what has been checked.

AllCheckedItems = Get_Property( CtrlEntID, "CHECKEDLIST" )
 
CheckedCount = FieldCount( AllCheckedItems, @Fm )
For N = 1 To CheckedCount 
 CheckedItemNo = AllCheckedItems
Next

This property is similar to the CHECKEDLIST property except that it returns an @fm-delimited dynamic array of text for the checked items rather than their index.

AllCheckedItemsText = Get_Property( CtrlEntID, "CHECKEDLISTTEXT" )
 
CheckedCount = FieldCount( AllCheckedItemsText, @Fm )
For N = 1 To CheckedCount 
 CheckedItemText = AllCheckedItemsText
Next

So that wraps up this short post on checkbox items - hopefully you'll find them much easier to use in your v10 applications.

The CHECKED property name is a synonym for the original OpenInsight CHECK property name, and you may use either as it suits you - Here at Revelation we prefer to use CHECKED as it feels more natural. Note that this convention applies to other controls like the CHECKBOX control too.