Adding elements to the tree

The elements addition to the tree is provided by different variants of InserItem() function:

HTREEITEM CTreeCtrl::InsertItem( LPTV_INSERTSTRUCT lpInsertStruct );

HTREEITEM CTreeCtrl::InsertItem(UINT nMask, LPCTSTR lpszItem, int nImage, int nSelectedImage, UINT nState, UINT nStateMask, LPARAM lParam, HTREEITEM hParent, HTREEITEM hInsertAfter );

HTREEITEM CTreeCtrl::InsertItem( LPCTSTR lpszItem, HTREEITEM hParent = TVI_ROOT, HTREEITEM hInsertAfter = TVI_LAST );

HTREEITEM CTreeCtrl::InsertItem( LPCTSTR lpszItem, int nImage, int nSelectedImage, HTREEITEM hParent = TVI_ROOT, HTREEITEM hInsertAfter = TVI_LAST);

Here are the following parameters:

lpInsertStruct   A pointer to a TV_INSERTSTRUCT that specifies the attributes of the tree view item to be inserted.

nMask   Integer specifying which attributes to set.

lpszItem   Address of a string containing the item's text.

nImage   Index of the item's image in the tree view control's image list.

nSelectedImage   Index of the item's selected image in the tree view control's image list.

nState   Specifies values for the item's states.

nStateMask   Specifies which states are to be set.

lParam   A 32-bit application-specific value associated with the item.

hParent   Handle of the inserted item's parent.

hInsertAfter    Handle of the item after which the new item is to be inserted.

The TV_INSERTSTRUCT structure is defined as follows:

typedef struct _TV_INSERTSTRUCT {

HTREEITEM hParent;

HTREEITEM hInsertAfter;

TV_ITEM item;

} TV_INSERTSTRUCT;

hParent   Handle of the parent item. If this parameter is the TVI_ROOT value or NULL, the item is inserted at the root of the tree view control.

hInsertAfter   Handle of the item after which the new item is to be inserted or one of the following values:

TVI_FIRST   Inserts the item at the beginning of the list.

TVI_LAST   Inserts the item at the end of the list.

TVI_SORT   Inserts the item into the list in alphabetical order.

item   A TV_ITEM structure, which contains information about the item to be added to the tree view control.

In it’s turn, TV_ITEM structure has such view:

The TV_ITEM structure specifies or receives attributes of a tree-view item.

typedef struct _TV_ITEM { tvi

UINT mask;

HTREEITEM hItem;

UINT state;

UINT stateMask;

LPSTR pszText;

int cchTextMax;

int iImage;

int iSelectedImage;

int cChildren;

LPARAM lParam;

} TV_ITEM, FAR *LPTV_ITEM;

The elements of structure:

mask - Array of flags that indicate which of the other structure members contain valid data. When this structure is used with the TVM_GETITEM message, the mask member indicates the item attributes to retrieve. This member can be a combination of the following values:

Value	Meaning
TVIF_CHILDREN	The cChildren member is valid.
TVIF_HANDLE	The hItem member is valid.
TVIF_IMAGE	The iImage member is valid.
TVIF_PARAM	The lParam member is valid.
TVIF_SELECTEDIMAGE	The iSelectedImage member is valid.
TVIF_STATE	The state and stateMask members are valid.
TVIF_TEXT	The pszText and cchTextMax members are valid.

hItem - Identifies the item to which this structure refers.

state - A set of bit flags and image list indexes that indicate the item’s state. For a list of item state bit flags, see Tree-View Item States. For information about the state image and overlay image indexes, see Tree-View Image Lists.

When setting the state of an item, the stateMask member indicates the bits of the state member that are valid. When retrieving the state of an item, the state member returns the current state for the bits indicated in the stateMask member.

stateMask - Specifies the bits of the state member that are valid.

pszText - Pointer to a null-terminated string that contains the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the parent window is responsible for storing the name. In this case, the tree-view control sends the parent window a TVN_GETDISPINFO notification message when it needs the item text for displaying, sorting, or editing, and a TVN_SETDISPINFO notification message when the item text changes.

If the structure is receiving item attributes, this member is the pointer to the buffer that receives the item text.

cchTextMax - Size of the buffer pointed to by the pszText member if the structure is receiving item attributes. If the structure specifies item attributes, this member is ignored.

iImage - Index in the tree-view control’s image list of the icon image to use when the item is in the non-selected state.

If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

iSelectedImage - Index in the tree-view control’s image list of the icon image to use when the item is in the selected state. If this member is the I_IMAGECALLBACK value, the parent window is responsible for storing the index. In this case, the tree-view control sends the parent a TVN_GETDISPINFO notification message to get the index when it needs to display the image.

cChildren - Flag that indicates whether the item has associated child items. This member is one of the following values:

Value	Meaning
zero	The item has no child items.
1	The item has one or more child items.
I_CHILDRENCALLBACK	The parent window keeps track of whether the item has child items. In this case, when the tree-view control needs to display the item, the control sends the parent a TVN_GETDISPINFO notification message to determine whether the item has child items.

If the tree-view control has the TVS_HASBUTTONS style, it uses this member to determine whether to display the button indicating the presence of child items. You can use this member to force the control to display the button even though the item does not have any child items inserted. This allows you to display the button while minimizing the control’s memory usage by inserting child items only when the item is visible or expanded.

lParam - A 32-bit value to associate with the item.

The expansion and collapsing on tree nodes

To expand or collapse the tree MFC propose the expand function implementation:

BOOL CTreeCtrl::Expand( HTREEITEM hItem, UINT nCode );

Here are the parameters:

hItem   Handle of the tree item being expanded.

nCode   A flag indicating the type of action to be taken. This flag can have one of the following values:

TVE_COLLAPSE   Collapses the list.

TVE_COLLAPSERESET   Collapses the list and removes the child items.

TVE_EXPAND   Expands the list.

TVE_TOGGLE   Collapses the list if it is currently expanded or expands it if it is currently collapsed.

All the function activity depends on element, defined in hItem parameter.

Some function to work with trees

To retrieve the currently selected item of the tree view control use such function:

HTREEITEM CTreeCtrl::GetSelectedItem( );

To select the element we can use special Select() function:

BOOL CTreeCtrl::Select( HTREEITEM hItem, UINT nCode );

We the such parameters:

hItem   Handle of a tree item.

nCode   The type of action to take. This parameter can be one of the following values: TVGN_CARET   Sets the selection to the given item.

TVGN_DROPHILITE   Redraws the given item in the style used to indicate the target of a drag-and-drop operation.

TVGN_FIRSTVISIBLE   Scrolls the tree view vertically so that the given item is the first visible item.

If nCode contains the value TVGN_CARET, the parent window receives the TVN_SELCHANGING and TVN_SELCHANGED notification messages. In addition, if the specified item is the child of a collapsed parent item, the parent's list of child items is expanded to reveal the specified item. In this case, the parent window receives the TVN_ITEMEXPANDING and TVN_ITEMEXPANDED notification messages.

To receive the information on element, use GetItem() function:

BOOL CTreeCtrl::GetItem( TV_ITEM* pItem );

Here, pItem   A pointer to a TV_ITEM structure.

In otherwise case – to set the information on element user SetItem() function:

BOOL CTreeCtrl::SetItem( TV_ITEM* pItem );

BOOL CTreeCtrl::SetItem( HTREEITEM hItem, UINT nMask, LPCTSTR lpszItem, int nImage, int nSelectedImage, UINT nState, UINT nStateMask, LPARAM lParam );

Parameters:

pItem   A pointer to a TV_ITEM structure that contains the new item attributes. hItem   Handle of the item whose attributes are to be set.

nMask   Integer specifying which attributes to set.

lpszItem   Address of a string containing the item's text.

nImage   Index of the item's image in the tree view control's image list.

nSelectedImage   Index of the item's selected image in the tree view control's image list.

nState   Specifies values for the item's states.

nStateMask   Specifies which states are to be set.

lParam    A 32-bit application-specific value associated with the item.

In the TV_ITEM structure, the hItem member identifies the item, and the mask member specifies which attributes to set.

If the mask member or the nMask parameter specifies the TVIF_TEXT value, the pszText member or the lpszItem is the address of a null-terminated string and the cchTextMax member is ignored. If mask (or nMask) specifies the TVIF_STATE value, the stateMask member or the nStateMask parameter specifies which item states to change and the state member or nState parameter contains the values for those states.

To delete the element of the tree, you can use DeleteItem():

BOOL CTreeCtrl::DeleteItem( HTREEITEM hItem );

hItem   Handle of the tree item to be deleted. If hitem has the TVI_ROOT value, all items are deleted from the tree view control.

The messages of Tree view controls

On any action execution, there will be send the WM_NOTIFY message. The identity codes for that messages have the following values:

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

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

TVN_DELETEITEM - notifies a tree-view control’s parent window that an item is being deleted.

TVN_ITEMEXPANDED - notifies a tree-view control’s parent window that a parent item’s list of child items has expanded or collapsed

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

TVN_SELCHANGED - notifies a tree-view control’s parent window that the selection has changed from one item to another.

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

Here, we shall consider the basic elements of program to implement the properties of tree view control. So, that items:

1. In the resources of project create the items to implement: “Expand” – to expand the elements of the tree (at some point of expanding); ”Expand All” – to expand all the nodes of the tree; “Collapse” – to close all the elements of the tree;

2. Include such elements to main window class:

Class CMainWin : public CFrameWnd

{CTreeCtrl m_Tree; // the object of window to view the tree

void InitTree(); // the function to initiate the window of tree viewing

public:

CMainWin();

void OnExpand();

void OnExpandAll();

void OnCollapse();

void OnExit();

void OnPaint();

void OnTreeChange(NMHDR *hdr,

LRESULT *NotUsed);

DECLARE_MESSAGE_MAP()

};

3. Define the global variables:

HTREEITEM hTreeCtrl[NUM];

HTREEITEM hTreeCurrent;

4. Make some changes in the main window constructor:

CMainWin::CMainWin()

{Create(NULL,"Window with toolbars", WS_OVERLAPPEDWINDOW, rectDefault, NULL, MAKEINTRESOURCE(IDR_MENU1));

InitCommonControls();

RECT r;

r.left=r.top=30;

r.right=120;r.bottom=100;

m_Tree.Create(WS_VISIBLE | WS_CHILD | WS_BORDER | TVS_HASLINES | TVS_HASBUTTONS | TVS_LINESATROOT,

r,this,ID_TREE);

InitTree();

}

5. Define the function to initiate the function of tree viewing:

void CMainWin::InitTree()

{TV_INSERTSTRUCT tvs;

TV_ITEM tvi;

tvs.hInsertAfter = TVI_LAST;

tvi.mask=TVIF_TEXT;

tvi.pszText="One";

tvs.hParent=TVI_ROOT;

tvs.item=tvi;

hTreeCtrl[0]=m_Tree.InsertItem(&tvs);

hTreeCurrent=hTreeCtrl[0];

tvi.pszText="Two";

tvs.hParent=hTreeCtrl[0];

tvs.item=tvi;

hTreeCtrl[1]=m_Tree.InsertItem(&tvs);

tvi.pszText="Three";

tvs.hParent=hTreeCtrl[1];

tvs.item=tvi;

hTreeCtrl[2]=m_Tree.InsertItem(&tvs);

tvi.pszText="Four";

tvs.hParent=hTreeCtrl[2];

tvs.item=tvi;

hTreeCtrl[3]=m_Tree.InsertItem(&tvs);

tvi.pszText="Five";

tvs.hParent=hTreeCtrl[2];

tvs.item=tvi;

hTreeCtrl[4]=m_Tree.InsertItem(&tvs);

}

2. Define the messages map:

BEGIN_MESSAGE_MAP(CMainWin,CFrameWnd)

ON_COMMAND(ID_CHANGE,OnChange)

ON_COMMAND(ID_TREE_EXPAND,OnExpand)

ON_COMMAND(ID_TREE_EXPANDALL,OnExpandAll)

ON_COMMAND(ID_TREE_COLLAPSE,OnCollapse)

ON_NOTIFY(TVN_SELCHANGED,ID_TREE,OnTreeChange)

ON_NOTIFY_RANGE(TTN_NEEDTEXT,0,IDR_TOOLBAR1,OnTTip)

ON_WM_PAINT()

ON_WM_SIZE()

END_MESSAGE_MAP()

3. Define the handlers:

void CMainWin::OnExpand() // handler to expand the tree’s node

{m_Tree.Expand(hTreeCurrent,TVE_EXPAND);}

void CMainWin::OnExpandAll() // handler to expand all the nodes of the tree

{int i;

for(i=0;i<NUM;i++)

m_Tree.Expand(hTreeCtrl[i],TVE_EXPAND);

}

void CMainWin::OnCollapse() // handler to collapse the tree’s nodes

{m_Tree.Expand(hTreeCurrent,TVE_COLLAPSE);}

void CMainWin::OnPaint() // handler to redraw the window

{CPaintDC dc(this);

TV_ITEM tvi;

char str1[40];

char str2[40];

tvi.hItem = hTreeCurrent;

tvi.pszText = str1;

tvi.cchTextMax = sizeof(str1)-1;

tvi.mask=TVIF_TEXT | TVIF_HANDLE;

m_Tree.GetItem(&tvi); // retrieves the name of new selected element

wsprintf(str2,"Current Selection %s",tvi.pszText);

dc.TextOut(2,150,str2,strlen(str2));

}

// OnTreeChange() function retrieves information on selected element and redraws the window

void CMainWin::OnTreeChange(NMHDR * hdr, LRESULT * NotUsed)

{hTreeCurrent=m_Tree.GetSelectedItem();

InvalidateRect(NULL);

}