# The MIT License (MIT)
#
# Copyright (C) 2026 Scott Duensing
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to
# deal in the Software without restriction, including without limitation the
# rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
# sell copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.  IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
# FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
# IN THE SOFTWARE.

.section Widgets
.topic widget.treeview
.title TreeView
.toc 0 TreeView
.index TreeView
.index TreeItem
.index wgtTreeView
.index wgtTreeItem
.index wgtTreeViewGetSelected

.h2 TreeView

A hierarchical tree control with expandable/collapsible nodes. Supports single and multi-selection and drag-to-reorder. Tree items are added as children of the TreeView or of other tree items to create nested hierarchies.

Header: widgets/treeView.h

.h3 Creation

.code
WidgetT *tv    = wgtTreeView(parent);
WidgetT *root  = wgtTreeItem(tv, "Root");
WidgetT *child = wgtTreeItem(root, "Child");
.endcode

.h3 API Functions

.index wgtTreeViewSetSelected
.index wgtTreeViewSetMultiSelect
.index wgtTreeViewSetReorderable
.index wgtTreeItemSetExpanded
.index wgtTreeItemIsExpanded
.index wgtTreeItemIsSelected
.index wgtTreeItemSetSelected

.table
  Function                                              Description
  --------                                              -----------
  WidgetT *wgtTreeView(parent)                          Create a tree view control.
  WidgetT *wgtTreeItem(parent, text)                    Add a tree item as a child of the tree view or another tree item.
  WidgetT *wgtTreeViewGetSelected(w)                    Get the currently selected tree item (NULL if none).
  void wgtTreeViewSetSelected(w, item)                  Set the selected tree item.
  void wgtTreeViewSetMultiSelect(w, multi)              Enable or disable multi-selection.
  void wgtTreeViewSetReorderable(w, reorderable)        Enable drag-to-reorder of items.
  void wgtTreeItemSetExpanded(w, expanded)              Expand or collapse a tree item.
  bool wgtTreeItemIsExpanded(w)                         Check if a tree item is expanded.
  bool wgtTreeItemIsSelected(w)                         Check if a tree item is selected (multi-select mode).
  void wgtTreeItemSetSelected(w, selected)              Select or deselect a tree item.
.endtable

.h3 API Struct (wgtRegisterApi "treeview")

.table
  Slot              Function
  ----              --------
  create            wgtTreeView
  getSelected       wgtTreeViewGetSelected
  setSelected       wgtTreeViewSetSelected
  setMultiSelect    wgtTreeViewSetMultiSelect
  setReorderable    wgtTreeViewSetReorderable
  item              wgtTreeItem
  itemSetExpanded   wgtTreeItemSetExpanded
  itemIsExpanded    wgtTreeItemIsExpanded
  itemIsSelected    wgtTreeItemIsSelected
  itemSetSelected   wgtTreeItemSetSelected
.endtable

.h3 Properties

No widget-specific properties.

.h3 Methods (BASIC Interface)

.table
  Method                                Description
  ------                                -----------
  AddChildItem parentIdx%, text$        Add a child node under the node at the given index.
  AddItem text$                         Add a root-level node.
  Clear                                 Remove all nodes.
  GetItemText(index%)                   Returns the text of the node at the given depth-first index.
  IsExpanded(index%)                    Returns True if the node is expanded.
  IsItemSelected(index%)                Returns True if the node is selected.
  ItemCount()                           Returns the total number of nodes.
  SetExpanded index%, expanded          Expand or collapse the node.
  SetItemSelected index%, selected      Select or deselect the node.
  SetMultiSelect multi                  Enable or disable multi-selection.
  SetReorderable reorderable            Enable or disable drag-to-reorder.
.endtable

.h3 Events

.table
  Callback     Description
  --------     -----------
  onClick      Fires when a tree item is clicked.
  onDblClick   Fires when a tree item is double-clicked.
  onChange     Fires when the selection changes.
.endtable

.h3 Default Event

"Click" (VB basName: TreeView).
