Using Tree View Controls

About tree view

A tree-view control is a window that displays a hierarchical list of items, such as the headings in a document, the entries in an index, or the files and directories on a disk. Each item consists of a label and an optional bitmapped image, and each item can have a list of subitems associated with it. By clicking an item, the user can expand and collapse the associated list of subitems. The following illustration shows a tree-view control that displays a table of contents.

Creating the control

Tree view controls are created in the same manner as the standard control types, either through the dialog editor or manually with the CONTROL statement using @TREEVIEW for the control type.

Tree view control styles

The following list view style flags can be specified in the CONTROL statement or by ticking the corresponding check box in the control properties of the dialog editor:

@TVSDISABLEDRAGDROP

Prevents the tree-view control from sending @TVNBEGINDRAG notification messages.

@TVSEDITLABELS

Allows the user to edit the labels of tree-view items.

@TVSFULLROWSELECT

Enables full-row selection in the tree view. The entire row of the selected item is highlighted, and clicking anywhere on an item's row causes it to be selected. This style cannot be used in conjunction with the @TVSHASLINES style.

@TVSHASBUTTONS

Displays plus (+) and minus (-) buttons next to parent items. The user clicks the buttons to expand or collapse a parent item's list of child items. To include buttons with items at the root of the tree view, @TVSLINESATROOT must also be specified.

@TVSHASLINES

Uses lines to show the hierarchy of items.

@TVSINFOTIP

Obtains ToolTip information by sending the @TVNGETINFOTIP notification.

@TVSLINESATROOT

Uses lines to link items at the root of the tree-view control. This value is ignored if @TVSHASLINES is not also specified.

@TVSNOHSCROLL

Disables horizontal scrolling in the control. The control will not display any horizontal scroll bars.

@TVSNONEVENHEIGHT

Sets the height of the items to an odd height with the TVM_SETITEMHEIGHT message. By default, the height of items must be an even value.

@TVSNOSCROLL

Disables both horizontal and vertical scrolling in the control. The control will not display any scroll bars.

@TVSNOTOOLTIPS

Disables tool tips.

@TVSRTLREADING

Causes text to be displayed from right-to-left (RTL). Usually, windows display text left-to-right (LTR). Windows can be mirrored to display languages such as Hebrew or Arabic that read RTL. Typically, tree-view text is displayed in the same direction as the text in its parent window. If @TVSRTLREADING is set, tree-view text reads in the opposite direction from the text in the parent window.

@TVSSHOWSELALWAYS

Causes a selected item to remain selected when the tree-view control loses focus.

@TVSSINGLEEXPAND

Causes the item being selected to expand and the item being unselected to collapse upon selection in the tree view. If the user holds down the CTRL key while selecting an item, the item being unselected will not be collapsed.

@TVSTRACKSELECT

Enables hot tracking in a tree view control.

Statements and functions for controlling the tree view

handle = tvInsertItem(win as WINDOW, id as INT, strText as STRING, parent as UINT)

Inserts a  new item into a tree view control. If parent is NULL then the item is inserted at the ROOT level.

Returns a handle to the new item.

handle = tvGetSelectedItem(win as WINDOW, id as UINT)

Returns a handle to the currently selected item if any

success = tvGetItemText(win as WINDOW, id as UINT, handle as UINT, pstrText as STRING, cchTextMax as UINT)

Retrieves the text of an item. pstrText is the string to receive the text and cchTextMax is the dimension of the string.

Returns TRUE if text could be retrieved or FALSE if your string is too small.

success = tvSetItemText(win as WINDOW, id as UINT, handle as UINT, strText as STRING)

Sets the text of an item

Returns TRUE on success, FALSE if item doesn't exist.

success = tvDeleteItem(win as WINDOW, id as UINT, handle as UINT)

Deletes an item in the tree view

Returns TRUE on success, FALSE if item doesn't exist.

success = tvDeleteAllItems(win as WINDOW, id as UINT)

Removes all items in the tree view

Returns TRUE on success, FALSE otherwise

success = tvSelectItem(win as WINDOW, id as UINT, handle as UINT)

Selects an item in the tree view

Returns TRUE on success, FALSE otherwise

data = tvGetItemData(win as WINDOW, id as UINT, handle as UINT)

Retrieves a user defined unsigned integer from an item.

tvSetItemData(win as WINDOW, id as UINT, handle as UINT, nData as UINT)

Stores a user defined unsigned integer in an item.

Notification messages

A tree view control sends notification messages to the parent window or dialog in the @NOTIFYCODE variable. The ID of the control is found in @CONTROLID the same as standard controls. The following notification messages are supported:

@TVNBEGINDRAG

Notifies a tree-view control's parent window that a drag-and-drop operation involving the left mouse button is being initiated.

@TVNBEGINLABELEDIT

Notifies a tree-view control's parent window about the start of label editing for an item.

@TVNBEGINRDRAG

Notifies a tree-view control's parent window about the initiation of a drag-and-drop operation involving the right mouse button.

@TVNDELETEITEM

Notifies a tree-view control's parent window that an item is being deleted.

@TVNENDLABELEDIT

Notifies a tree-view control's parent window about the end of label editing for an item.

@TVNGETDISPINFO

Requests that a tree-view control's parent window provide information needed to display or sort an item.

@TVNGETINFOTIP

Sent by a tree-view control that has the @TVSINFOTIP style. This notification is sent when the control is requesting additional text information to be displayed in a ToolTip.

@TVNITEMEXPANDED

Notifies a tree-view control's parent window that a parent item's list of child items has expanded or collapsed.

@TVNITEMEXPANDING

Notifies a tree-view control's parent window that a parent item's list of child items is about to expand or collapse.

@TVNKEYDOWN

Notifies a tree-view control's parent window that the user pressed a key and the tree-view control has the input focus.

@TVNSELCHANGED

Notifies a tree-view control's parent window that the selection has changed from one item to another.

@TVNSELCHANGING

Notifies a tree-view control's parent window that the selection is about to change from one item to another.

@TVNSETDISPINFO

Notifies a tree-view control's parent window that it must update the information it maintains about an item.

@TVNSINGLEEXPAND

Sent by a tree-view control with the @TVSSINGLEEXPAND style when the user opens or closes a tree item using a single click of the mouse.

UDT's used with the tree view control.

Certain notification messages send a pointer to a UDT in @LPARAM. Access the UDT using C style pointer dereferencing. The NMHDR type is a built in UDT and is common to all notification messages:

TYPE NMHDR

  DEF hwndFrom as UINT

  DEF idFrom as INT

  DEF code as INT

ENDTYPE

The NMTVGETINFOTIP UDT contains and receives tree-view item information needed to display a ToolTip for an item. This structure is used with the @TVNGETINFOTIP notification message.

TYPE NMTVGETINFOTIP

  NMHDR hdr

  POINTER pszText

  int cchTextMax

  UINT hItem

  UINT lParam

ENDTYPE

The NMTVKEYDOWN UDT contains information about a keyboard event in a tree-view control. This structure is used with the @TVNKEYDOWN notification message.

TYPE NMTVKEYDOWN {

  NMHDR hdr

  WORD wVKey

  UINT flags

ENDTYPE