ListBoxes and TreeListBoxes - Checkbox Items [Revelation On-Line Wiki]

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
{{tag>category:"presentation server" }}

====== ListBoxes and TreeListBoxes - Checkbox Items ======

=== Published 16 JAN 2024 at 12:33:45PM ===

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. 

==== The CHECKBOXES property ====

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.

==== The CHECKED property ====

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.

<code wp-block-code>
// 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 )
</code>

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

<code wp-block-code>
// 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 )
</code>

==== The CHECKEDX property ====

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. 

==== CHECKEDLIST property ====

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.

<code wp-block-code>
AllCheckedItems = Get_Property( CtrlEntID, "CHECKEDLIST" )

CheckedCount = FieldCount( AllCheckedItems, @Fm )
For N = 1 To CheckedCount 
 CheckedItemNo = AllCheckedItems
Next
</code>

==== CHECKEDLISTTEXT property ====

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.

<code wp-block-code>
AllCheckedItemsText = Get_Property( CtrlEntID, "CHECKEDLISTTEXT" )

CheckedCount = FieldCount( AllCheckedItemsText, @Fm )
For N = 1 To CheckedCount 
 CheckedItemText = AllCheckedItemsText
Next
</code>

===== Conclusion =====

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

===== Bonus Trivia =====

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.




=== Comments ===





== Original ID: revdevx.com/?p=3916 ==