Tree View

The tree view widget provides a way to represent a LiveCode array visually in various ways. In its simplest form, it allows selection of key/value pairs, and folding and unfolding of nested arrays.

Tree View widget

Creating a Tree View

A tree view widget can be created by dragging it out from the Tools Palette, where it appears with the following icon:

Alternatively it can be created in script using:

create widget as "com.livecode.widget.treeview"

Using the Tree View

The content of the tree view is controlled by using the arrayData property. The following handlers can be used to set and get data on a specific pathDelimiter-delimited path rather than the whole array:

command setArrayDataOnPath pValue, pPath, @xArray
   local tKey
   set the itemdelimiter to the pathDelimiter of widget 1 of me
   put item 1 of pPath into tKey
   if the number of items in pPath is 1 then
      put pValue into xArray[tKey]
   else
      delete item 1 of pPath
      setArrayDataOnPath pValue, pPath, xArray[tKey]
   end if
end setArrayDataOnPath

command fetchArrayDataOnPath pPath, pArray, @rData
   local tKey
   set the itemdelimiter to the pathDelimiter of widget 1 of me
   put item 1 of pPath into tKey
   if the number of items in pPath is 1 then
      if tKey is not among the keys of pArray then
         return "no such key"
      else
         put pArray[tKey] into rData
         return empty
      end if
   else
      delete item 1 of pPath
      fetchArrayDataOnPath pPath, pArray[tKey], rData
   end if
end fetchArrayDataOnPath

Display Properties

The tree view widget has a number of display options:

Edit Mode

When in edit mode, there are a number of additional user-interactions available. The following two show at the end of a given line when the mouse hovers over it:

Delete array key

When the delete icon is clicked, the user is asked for confirmation to delete the key in question.

Delete array key confirm

Clicking the plus icon adds a new numerically named key underneath the nested array that was clicked. When the row contains a text value, that value is discarded and a new nested array created at the chosen key.

Add new subkey

The final one is always visible as the top row:

Clicking the 'Add new element' row that is displayed in edit mode adds a new default top-level key to the array. It has a numeric key.

Add new key

Note: As LCB does not yet allow text input, there is no way to allow a user to edit the keys and values inline. In order to provide such functionality, you would have to create fields and track the current hilitedElement.

Messages

The widget sends a number of messages in response to actions. When the underlying data changes, a dataChanged message is sent. This is handy when the widget is not readOnly and therefore the content can be changed by user interaction.

The hiliteChanged message is sent when the user clicks on a row to select or deselect it.

When a row is double-clicked, an actionDoubleClick message is sent. The actionInspect message is sent when the inspect icon is clicked - this icon is displayed when the tree view value is too long to be displayed, or contains multiple lines.

Inspect