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.

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"

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

The tree view widget has a number of display options:

• alternateRowBackgrounds - Whether the alternate rows of the widget have different backgrounds or not.
• hilitedElement - The selected row, given by a pathDelimiter-delimited path.
• readOnly - Whether the options to modify elements of the underlying array are present or not. See the Edit Mode section for more information on what is not visible in read-only mode.
• separatorRatio - Manipulates the size of the view columns.
• showBorder - Whether the widget has a border or not.
• showSeparator - Whether the separator bar between keys and values is showing or not.
• sortOrder - Manipulates the order in which elements of the tree view are displayed, with respect to the current sortType.
• sortType - Manipulates the type of ordering in which elements of the tree view are displayed.
• arrayStyle - Whether the tree view should display its contents in array style or as a standard tree view.

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 keys

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

• Add new sub-keys

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.

The final one is always visible as the top row:

• Add new top-level keys

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.

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.

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.