A tree control presents information as a hierarchy, with items that may be expanded to show further items. Items in a tree control are referenced by wTreeItem handles, which may be tested for validity by calling wTreeItem.isOk().

Appearance:

Superclass:	wControl

Styles:

Styles	Description
wTrNoButtons	For convenience to document that no buttons are to be drawn.
wTrHasButtons	Use this style to show + and - buttons to the left of parent items.
wTrHasLines	Use this style to show vertical level connectors.
wTrEditLabels	Use this style if you wish the user to be able to edit labels in the tree control.
wTrFullRowHighLight	Use this style to have the background colour and the selection highlight extend over the entire horizontal row of the tree control window. Cannot use with wTrHasLines.
wTrLinesAtRoot	Use this style to show lines between root nodes.
wTrCheckBox	Enables check boxes for items.
wTrTwistButtons	Selects alternative style of +/- buttons and shows rotating ("twisting") arrows instead. Windows vista later.
wTrNoHScroll	Disables horizontal scrolling.
wTrNoScroll	Disables both horizontal and vertical scrolling.
wTrSingleExpand	Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree view.

Events:	wTreeEvent

Types

wTreeCtrl_Compare = proc (data1: int; data2: int; data: int): int: Comparing callback function prototype used in sortChildren()
wTreeCtrl_ItemCompare = proc (item1: wTreeItem; item2: wTreeItem; data: int): int: Comparing callback function prototype used in sortChildren()

Consts

wTrNoButtons = 0
wTrHasButtons = 0x00000001
wTrHasLines = 0x00000002
wTrEditLabels = 0x00000008
wTrFullRowHighLight = 0x00001000
wTrLinesAtRoot = 0x00000004
wTrCheckBox = 0x00000100
wTrTwistButtons = 1152921504606846976'i64
wTrNoHScroll = 0x00008000
wTrNoScroll = 0x00002000
wTrSingleExpand = 0x00000400
wTrShowSelectAlways = 0x00000020
wTreeItemStateBold = 0x00000010
wTreeItemStateCut = 0x00000004
wTreeItemStateDropHighlighted = 0x00000008
wTreeItemStateSelected = 0x00000002
wTreeImageCallback = -1
wTreeImageNone = -2
wTreeIgnore = -3
wTreeItemIconNormal = 0
wTreeItemIconSelected = 1
wTreeHittestAbove = 0x00000100
wTreeHittestBelow = 0x00000200
wTreeHittestNoWhere = 0x00000001
wTreeHittestOnItemButton = 0x00000010
wTreeHittestOnItemIcon = 0x00000002
wTreeHittestOnItemIndent = 0x00000008
wTreeHittestOnItemLabel = 0x00000004
wTreeHittestOnItemRight = 0x00000020
wTreeHittestOnItemStateIcon = 0x00000040
wTreeHittestOnItem = 70
wTreeHittestToLeft = 0x00000800
wTreeHittestToRight = 0x00000400

Procs

proc TreeItem(treeCtrl: wTreeCtrl; handle: HTREEITEM): wTreeItem {...}{.inline, raises: [], tags: [].}

Default constructor.

proc `==`(a, b: wTreeItem): bool {...}{.inline, raises: [], tags: [].}

Checks for equality between two wTreeItem.

proc isOk(self: wTreeItem): bool {...}{.inline, raises: [], tags: [].}

Returns true if this instance is referencing a valid tree item.

proc unset(self: var wTreeItem) {...}{.inline, raises: [], tags: [].}

Unset the tree item.

proc getHandle(self: wTreeItem): HTREEITEM {...}{.raises: [], tags: [].}

Gets the real tree item handle.

proc getTreeCtrl(self: wTreeItem): wTreeCtrl {...}{.raises: [], tags: [].}

Gets the tree control this item associated to.

proc getParent(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}

Gets the parent of this item.

proc getFirstChild(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}

Gets the first child of the item.

proc getPrevSibling(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}

Gets the previous slbling of the item.

proc getNextSibling(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}

Gets the next slbling of the item.

proc getLastChild(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}

Gets the last child of the item.

proc getChildrenCount(self: wTreeItem; recursively = true): int {...}{.raises: [wNilAccess], tags: [].}

Gets the number of items in the branch. If recursively is true, returns the total number of descendants, otherwise only one level of children is counted.

proc len(self: wTreeItem): int {...}{.raises: [wNilAccess], tags: [].}

Gets the number of children in this item.

proc getChildren(self: wTreeItem): seq[wTreeItem] {...}{.raises: [wNilAccess], tags: [].}

Returns all children as a seq.

proc getAllChildren(self: wTreeItem): seq[wTreeItem] {...}{.raises: [wNilAccess], tags: [].}

Returns all children including descendants as a seq.

proc set(self: wTreeItem; text = ""; image = wTreeIgnore; selImage = wTreeIgnore; state = 0; flag = true) {...}{.raises: [wNilAccess], tags: [].}

Sets the item attributes.

proc setText(self: wTreeItem; text: string) {...}{.inline, raises: [wNilAccess], tags: [].}

Sets the item text.

proc setBold(self: wTreeItem; flag = true) {...}{.inline, raises: [wNilAccess], tags: [].}

Makes the item appear in bold or not.

proc setCut(self: wTreeItem; flag = true) {...}{.inline, raises: [wNilAccess], tags: [].}

Makes the item appear in cut-and-paste operation or not.

proc setSelection(self: wTreeItem; flag = true) {...}{.inline, raises: [wNilAccess], tags: [].}

Makes the item appear in selected or not. Notice: this will broken single selection states, don't use this if possible.

proc setDropHighlight(self: wTreeItem; flag = true) {...}{.inline, raises: [wNilAccess], tags: [].}

Makes the item appear in Drag'n'Drop actions or not.

proc select(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Select, focus, and ensure visible of the item, also unselect others.

proc scrollTo(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Scrolls the specified item into view.

proc unselect(self: wTreeItem) {...}{.inline, raises: [wNilAccess], tags: [].}

Unselects this item. Notice: this will broken single selection states, don't use this if possible.

proc setImage(self: wTreeItem; image = wTreeIgnore; selImage = wTreeIgnore) {...}{. raises: [wNilAccess], tags: [].}

Sets the specified item's image.

proc setData(self: wTreeItem; data: int) {...}{.raises: [wNilAccess], tags: [].}

Sets the item associated data.

proc setState(self: wTreeItem; state: range[0 .. 15]) {...}{.raises: [wNilAccess], tags: [].}

Sets the item state image. If state > 0, the 1-based state image will be displayed. state = 0 to disable the state image. PS. State image stored in the imagelist specified by setImageList(which=wImageListState).

proc setHasChildren(self: wTreeItem; flag = true) {...}{.raises: [wNilAccess], tags: [].}

Force appearance of the button next to the item.

proc expand(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Expands the item.

proc collapse(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Collapses the item.

proc collapseAndReset(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Collapses the given item and removes all children.

proc toggle(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Toggles the item between collapsed and expanded states.

proc getText(self: wTreeItem): string {...}{.raises: [wNilAccess], tags: [].}

Returns the item text.

proc isBold(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is in bold state.

proc isCut(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is in cut-and-paste operation state.

proc isDropHighlight(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is in drop hightlight state.

proc isSelected(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is in selected state.

proc isExpanded(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is expanded.

proc isFocused(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is focused.

proc getImage(self: wTreeItem): int {...}{.raises: [wNilAccess], tags: [].}

Gets the item image.

proc getSelImage(self: wTreeItem): int {...}{.raises: [wNilAccess], tags: [].}

Gets the selected item image.

proc getData(self: wTreeItem): int {...}{.raises: [wNilAccess], tags: [].}

Returns the data associated with the item.

proc getState(self: wTreeItem): int {...}{.raises: [wNilAccess], tags: [].}

Gets the item state image.

proc hasChildren(self: wTreeItem): bool {...}{.raises: [wNilAccess], tags: [].}

Returns true if the item is in having children state. Notice this only gets the state that can be set by setHasChildren().

proc expandAllChildren(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Expands the item and all its children recursively.

proc collapseAllChildren(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Collapses this item and all of its children, recursively.

proc getBoundingRect(self: wTreeItem; textOnly = false): wRect {...}{.raises: [wNilAccess], tags: [].}

Retrieves the rectangle bounding the item. If textOnly is true, only the rectangle around the item's label will be returned, otherwise the item's image is also taken into account. The return value is wDefaultRect if not successfully, for example, if the item is currently invisible. Notice that the rectangle coordinates are logical, not physical ones. So, for example, the x coordinate may be negative if the tree has a horizontal scrollbar and its position is not 0.

proc isVisible(self: wTreeItem): bool {...}{.raises: [wNilAccess, Exception], tags: [RootEffect].}

Returns true if the item is visible on the screen.

proc getNextVisible(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess, Exception], tags: [RootEffect].}

Returns the next visible item or an invalid item if this item is the last visible one. Notice: The item itself must be visible.

proc getPrevVisible(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess, Exception], tags: [RootEffect].}

Returns the previous visible item or an invalid item if this item is the first visible one. Notice: The item itself must be visible.

proc ensureVisible(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Scrolls and/or expands items to ensure that the item is visible.

proc delete(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Deletes the specified item.

proc deleteChildren(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Deletes all children of the given item (but not the item itself).

proc toggleSelection(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Toggles the item between selected and unselected states.

proc selectChildren(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Select all the immediate children of the given parent.

proc editLabel(self: wTreeItem): wTextCtrl {...}{.discardable, raises: [wNilAccess], tags: [].}

Starts editing the label of the item.

proc sortChildren(self: wTreeItem; recursively = false) {...}{.raises: [wNilAccess], tags: [].}

Sorts the children of the item by text (alphabetically).

proc sortChildren(self: wTreeItem; callback: wTreeCtrl_Compare; data: int = 0; recursively = false) {...}{.raises: [wNilAccess], tags: [].}

Sorts the children of the item. The value passed into callback function is the data associated with the item

proc sortChildren(self: wTreeItem; callback: wTreeCtrl_ItemCompare; data: int = 0; recursively = false) {...}{.raises: [wNilAccess, KeyError], tags: [].}

Sorts the children of the item. The value passed into callback function is the wTreeItem object.

proc setFocused(self: wTreeItem) {...}{.raises: [wNilAccess], tags: [].}

Sets the currently focused item. Use select() instead of this if possible.

proc getFirstRoot(self: wTreeCtrl): wTreeItem {...}{.raises: [], tags: [].}

Returns the first root item for the tree control.

proc getRootItem(self: wTreeCtrl): wTreeItem {...}{.inline, raises: [], tags: [].}

Returns the first root item for the tree control. The same as getFirstRoot().

proc getFirstVisibleItem(self: wTreeCtrl): wTreeItem {...}{.raises: [], tags: [].}

Returns the first visible item.

proc getFocusedItem(self: wTreeCtrl): wTreeItem {...}{.raises: [], tags: [].}

Returns the item last clicked or otherwise selected.

proc getSelections(self: wTreeCtrl): seq[wTreeItem] {...}{.raises: [wNilAccess], tags: [].}

Returns currently selected items.

proc hitTest(self: wTreeCtrl; x: int; y: int): tuple[item: wTreeItem, flag: int] {...}{. raises: [], tags: [].}

Calculates which (if any) item is under the given point, returning the tree item at this point plus extra information flags. flags is a bitlist of the following:

Flag	Description
wTreeHittestAbove	Above the client area.
wTreeHittestBelow	Below the client area.
wTreeHittestNoWhere	In the client area but below the last item.
wTreeHittestOnItemButton	On the button associated with an item.
wTreeHittestOnItemIcon	On the bitmap associated with an item.
wTreeHittestOnItemIndent	In the indentation associated with an item.
wTreeHittestOnItemLabel	On the label (string) associated with an item.
wTreeHittestOnItemRight	In the area to the right of an item.
wTreeHittestOnItemStateIcon	On the state icon for a tree view item that is in a user-defined state.
wTreeHittestOnItem	OnItemIcon or OnItemLabel or OnItemStateIcon.
wTreeHittestToLeft	To the right of the client area.
wTreeHittestToRight	To the left of the client area.

proc hitTest(self: wTreeCtrl; pos: wPoint): tuple[item: wTreeItem, flag: int] {...}{.inline, raises: [], tags: [].}

The same as hitTest().

proc unselectAll(self: wTreeCtrl) {...}{.raises: [wNilAccess], tags: [].}

Removes the selection from all items.

proc expandAll(self: wTreeCtrl) {...}{.raises: [wNilAccess], tags: [].}

Expands all items in the tree.

proc collapseAll(self: wTreeCtrl) {...}{.raises: [wNilAccess], tags: [].}

Collapses all items in the tree.

proc deleteAllItems(self: wTreeCtrl) {...}{.raises: [], tags: [].}

Deletes all items in the control.

proc clearFocusedItem(self: wTreeCtrl) {...}{.raises: [], tags: [].}

Clears the currently focused item.

proc getCount(self: wTreeCtrl): int {...}{.raises: [], tags: [].}

Returns the number of items in the control.

proc len(self: wTreeCtrl): int {...}{.inline, raises: [], tags: [].}

Returns the number of items in the control. The same as getCount().

proc isEmpty(self: wTreeCtrl): bool {...}{.inline, raises: [], tags: [].}

Returns true if the control is empty.

proc addRoot(self: wTreeCtrl; text: string; image = wTreeImageNone; selImage = wTreeIgnore; data: int = 0): wTreeItem {...}{.discardable, raises: [], tags: [].}

Adds the root node to the tree, returning the new item.

proc appendItem(self: wTreeCtrl; parent: wTreeItem; text: string; image = wTreeImageNone; selImage = wTreeIgnore; data: int = 0): wTreeItem {...}{. discardable, raises: [], tags: [].}

Appends an item to the end of the branch identified by parent, return a new item.

proc prependItem(self: wTreeCtrl; parent: wTreeItem; text: string; image = wTreeImageNone; selImage = wTreeIgnore; data: int = 0): wTreeItem {...}{. discardable, raises: [], tags: [].}

Appends an item as the first child of parent, return a new item.

proc insertItem(self: wTreeCtrl; parent: wTreeItem; prev: wTreeItem; text: string; image = wTreeImageNone; selImage = wTreeIgnore; data: int = 0): wTreeItem {...}{. discardable, raises: [], tags: [].}

Inserts an item after a given one (previous).

proc insertItem(self: wTreeCtrl; parent: wTreeItem; pos: int; text: string; image = wTreeImageNone; selImage = wTreeIgnore; data: int = 0): wTreeItem {...}{. discardable, raises: [wNilAccess], tags: [].}

Inserts an item before one identified by its position (pos).

proc setImageList(self: wTreeCtrl; imageList: wImageList; which = wImageListNormal) {...}{. raises: [wNilAccess], tags: [].}

Sets the image list associated with the control. which is one of wImageListNormal, wImageListState.

proc getImageList(self: wTreeCtrl; which = wImageListNormal): wImageList {...}{.raises: [], tags: [].}

Returns the specified image list. which is one of wImageListNormal, wImageListState.

proc getIndent(self: wTreeCtrl): int {...}{.raises: [], tags: [].}

Returns the current tree control indentation.

proc setIndent(self: wTreeCtrl; indent: int) {...}{.raises: [], tags: [].}

Sets the indentation for the tree control.

proc enableInsertMark(self: wTreeCtrl; flag = true) {...}{.inline, raises: [], tags: [].}

Enables or disables insert mark durgn Drag'n'Drop action.

proc cancelDrag(self: wTreeCtrl) {...}{.raises: [], tags: [].}

Cancel Drag'n'Drop action.

proc endDrag(self: wTreeCtrl) {...}{.raises: [Exception], tags: [RootEffect].}

Ends Drag'n'Drop action.

proc init(self: wTreeCtrl; parent: wWindow; id: wCommandID = wDefaultID; pos = wDefaultPoint; size = wDefaultSize; style: wStyle = wTrNoButtons) {...}{.raises: [ wNilAccess, wWindowError, wCursorError, wBrushError, Exception, IndexDefect, wFontError], tags: [RootEffect].}

Initializes a tree control.

proc TreeCtrl(parent: wWindow; id: wCommandID = wDefaultID; pos = wDefaultPoint; size = wDefaultSize; style: wStyle = wTrNoButtons): wTreeCtrl {...}{.inline, discardable, raises: [wNilAccess, wWindowError, wCursorError, wBrushError, Exception, IndexDefect, wFontError], tags: [RootEffect].}

Constructor.

Methods

method setBackgroundColor(self: wTreeCtrl; color: wColor) {...}{.raises: [Exception], tags: [RootEffect].}: Sets the background color of the control.
method setForegroundColor(self: wTreeCtrl; color: wColor) {...}{.raises: [Exception], tags: [RootEffect].}: Sets the foreground color of the control.
method getBestSize(self: wTreeCtrl): wSize {...}{.raises: [wNilAccess], tags: [].}
method release(self: wTreeCtrl) {...}{.raises: [], tags: [].}: Release all the resources during destroying. Used internally.

Iterators

iterator items(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}: Iterate each child in this item.
iterator allItems(self: wTreeItem): wTreeItem {...}{.raises: [wNilAccess], tags: [].}: Iterate each child in this item, including all descendants.
iterator items(self: wTreeCtrl): wTreeItem {...}{.raises: [wNilAccess], tags: [].}: Iterate each child in this control.
iterator allItems(self: wTreeCtrl): wTreeItem {...}{.raises: [wNilAccess], tags: [].}: Iterate each child in this control, including all descendants.