In the previous topic we covered how to implement a simple checkbox for each item in the tree control. In this topic we cover a slightly different implementation. The checkbox for each item will indicate whether the item is checked or not and it will also indicate whether any of its descendant is checked or not. The main reason for visually indicating whether a descendant is checked is that it is easier for the user to determine if there are checked items in the outline and if there is a checked item, it is easy to navigate to it.
Step 1: Create bitmap with checkbox images
Create a bitmap that will provide the images needed for the checkbox. The images in the bitmap below are 13×13 pixels. The first image is blank since this bitmap is going to be used for the state image list. The next image indicates an unchecked item. The third image indicates a checked item. The fourth image indicates an unchecked item but conveys that at least one of the descendant item is checked. The fifth image indicates a checked item and also indicates that at least one of the descendant item is checked.
Step 2: Initialize the state image list
Setting up state images has been covered in a previous topic. If the tree control class has a member variable m_imageState then here’s how to set the image list.
m_tree.m_imageState.Create( IDB_STATE, 13, 1, RGB(255,255,255) ); m_tree.SetImageList( &(m_tree.m_imageState), TVSIL_STATE );
Step 3: Insert items with the checkbox as a state image
If you are using TV_INSERTSTRUCT to insert an item into the tree control, then specify the state and the stateMask in the TV_ITEM member. The index of the state image is specified by using the macro INDEXTOSTATEIMAGEMASK. You can also use the SetItemState() function.
SetItemState( hItem, INDEXTOSTATEIMAGEMASK(1), TVIS_STATEIMAGEMASK );
Step 4: Add enumeration for check operation and state
Since we are dealing with four different check states, it makes the code more readable if we define an enumeration for the different states. We also define an enumeration to list the different operations on the check state.
// Attributes public: enum CheckState{ NOSTATE = 0, UNCHECKED, CHECKED, CHILD_CHECKED, SELF_AND_CHILD_CHECKED }; enum CheckType{ CHECK, UNCHECK, TOGGLE, REFRESH };
Step 5: Define SetCheck() function
When we check an item, the parent items are also updated to indicate that a descendant is checked. Similarly, when we uncheck an item, the parents item have to be updated again. We may also need to update the parents state if an item is moved.
Depending on the value of nCheck, the function determines what the new state of the item should be. If nCheck is REFRESH, only the immediate children items are scanned to determine if the checkbox should be red ( to indicate that a child is checked ). The function then updates the parent items.
// SetCheck - Check, uncheck, toggle or refresh an item // hItem - Item that is to be updated // nCheck - CHECK, UNCHECK, TOGGLE OR REFRESH BOOL CTreeCtrlX::SetCheck( HTREEITEM hItem, CheckType nCheck ) { if( hItem == NULL ) return FALSE; UINT nState = GetItemState( hItem, TVIS_STATEIMAGEMASK ) >> 12; // Determine the new check state if ( nCheck == CHECK ) { if( nState == CHECKED || nState == SELF_AND_CHILD_CHECKED ) return TRUE; switch( nState ) { case UNCHECKED: nState = CHECKED; break; case CHILD_CHECKED: nState = SELF_AND_CHILD_CHECKED; break; } } else if( nCheck == UNCHECK ) { if( nState == UNCHECKED || nState == CHILD_CHECKED ) return TRUE; switch( nState ) { case CHECKED: nState = UNCHECKED; break; case SELF_AND_CHILD_CHECKED: nState = CHILD_CHECKED; break; } } else if( nCheck == TOGGLE ) { switch( nState ) { case UNCHECKED: nState = CHECKED; break; case CHECKED: nState = UNCHECKED; break; case CHILD_CHECKED: nState = SELF_AND_CHILD_CHECKED; break; case SELF_AND_CHILD_CHECKED: nState = CHILD_CHECKED; break; } } else if( nCheck == REFRESH ) { // Scan children to determine new state BOOL bChildSelected = FALSE; HTREEITEM htiChild = GetChildItem( hItem ); // Scan children while( htiChild ) { UINT nChildState = GetItemState( htiChild, TVIS_STATEIMAGEMASK ) >> 12; if( nChildState != UNCHECKED && nChildState != NOSTATE ) { bChildSelected = TRUE; break; } htiChild = GetNextItem( htiChild, TVGN_NEXT ); } if( bChildSelected ) { if( nState == CHECKED ) nState = SELF_AND_CHILD_CHECKED; else if( nState == UNCHECKED ) nState = CHILD_CHECKED; } else { if( nState == SELF_AND_CHILD_CHECKED ) nState = CHECKED; else if( nState == CHILD_CHECKED ) nState = UNCHECKED; } } SetItemState( hItem, INDEXTOSTATEIMAGEMASK(nState), TVIS_STATEIMAGEMASK ); if( nState == CHECKED || ( REFRESH && (nState == SELF_AND_CHILD_CHECKED || nState == CHILD_CHECKED) ) ) { // Mark the parents to indicate that a child item is selected. // Use checkbox with red border. while( (hItem = GetParentItem( hItem )) != NULL ) { nState = GetItemState( hItem, TVIS_STATEIMAGEMASK ) >> 12; if( nState == UNCHECKED ) SetItemState( hItem, INDEXTOSTATEIMAGEMASK(CHILD_CHECKED), TVIS_STATEIMAGEMASK ); else if ( nState == CHECKED ) SetItemState( hItem, INDEXTOSTATEIMAGEMASK(SELF_AND_CHILD_CHECKED), TVIS_STATEIMAGEMASK ); } } else if( nState == UNCHECKED ) { // Maybe the parent ( ancestors ) state needs to be adjusted if // no more children selected. while( (hItem = GetParentItem( hItem )) != NULL ) { BOOL bChildSelected = FALSE; HTREEITEM htiChild = GetChildItem( hItem ); // Scan children while( htiChild ) { UINT nChildState = GetItemState( htiChild, TVIS_STATEIMAGEMASK ) >> 12; if( nChildState != UNCHECKED && nChildState != NOSTATE ) { bChildSelected = TRUE; break; } htiChild = GetNextItem( htiChild, TVGN_NEXT ); } if( bChildSelected ) { // The parent does not need to be updated // since there are other children still selected break; } else { // The parent item has no more children selected. // Mark accordingly UINT nParentState = GetItemState( hItem, TVIS_STATEIMAGEMASK ) >> 12; if( nParentState == CHILD_CHECKED ) SetItemState( hItem, INDEXTOSTATEIMAGEMASK(UNCHECKED), TVIS_STATEIMAGEMASK ); else if ( nParentState == SELF_AND_CHILD_CHECKED ) SetItemState( hItem, INDEXTOSTATEIMAGEMASK(CHECKED), TVIS_STATEIMAGEMASK ); } } } return TRUE; }
Step 6: Add code to OnLButtonDown to toggle checkbox
When the user clicks on the checkbox, then the checkbox state has to be toggled. We use the HitTest() function to determine if the click was on the checkbox.
void CTreeCtrlX::OnLButtonDown(UINT nFlags, CPoint point) { UINT uFlags=0; HTREEITEM hItem = HitTest(point,&uFlags); if( uFlags & TVHT_ONITEMSTATEICON ) { SetCheck( hItem, TOGGLE ); return; } }
Step 7: Add code to OnKeyDown to toggle checkbox
This step provides the keyboard interface for checking and unchecking an item. The key used is usually the space key, so we will use the space key. The code is nearly the same as in the previous step. Instead of using HitTest() to determine the item handle, we use the function GetSelectedItem().
void CTreeCtrlX::OnKeyDown(UINT nChar, UINT nRepCnt, UINT nFlags) { if( nChar == VK_SPACE ) { HTREEITEM hItem = GetSelectedItem(); SetCheck( hItem, TOGGLE ); return; } }
Step 8: Define helper functions
Define helper functions to determine whether an item is checked or not and to iterate through the checked items. The purpose of the functions is very clear from the function names. The GetFirstCheckedItem() and the GetNextCheckedItem() are optimized. They look at the item state before deciding whether it should search the children items. The GetPrevCheckedItem() function searches sequentially through all items. I leave it as an exercise to optimize this function.
BOOL CTreeCtrlX::IsItemChecked(HTREEITEM hItem) { int iImage = GetItemState( hItem, TVIS_STATEIMAGEMASK )>>12; return iImage == CHECKED || iImage == SELF_AND_CHILD_CHECKED; } HTREEITEM CTreeCtrlX::GetFirstCheckedItem() { for ( HTREEITEM hItem = GetRootItem(); hItem!=NULL; ) { int iImage = GetItemState( hItem, TVIS_STATEIMAGEMASK )>>12; if ( iImage == CHECKED || iImage == SELF_AND_CHILD_CHECKED ) return hItem; if( iImage != CHILD_CHECKED ) { HTREEITEM hti = GetNextItem( hItem, TVGN_NEXT ); if( hti == NULL ) hItem = GetNextItem( hItem ); else hItem = hti; } else hItem = GetNextItem( hItem ); } return NULL; } HTREEITEM CTreeCtrlX::GetNextCheckedItem( HTREEITEM hItem ) { hItem = GetNextItem( hItem ); while( hItem!=NULL ) { int iImage = GetItemState( hItem, TVIS_STATEIMAGEMASK )>>12; if ( iImage == CHECKED || iImage == SELF_AND_CHILD_CHECKED ) return hItem; if( iImage != CHILD_CHECKED ) { HTREEITEM hti = GetNextItem( hItem, TVGN_NEXT ); if( hti == NULL ) hItem = GetNextItem( hItem ); else hItem = hti; } else hItem = GetNextItem( hItem ); } return NULL; } HTREEITEM CTreeCtrlX::GetPrevCheckedItem( HTREEITEM hItem ) { for ( hItem = GetPrevItem( hItem ); hItem!=NULL; hItem = GetPrevItem( hItem ) ) if ( IsItemChecked(hItem) ) return hItem; return NULL; }
The GetNextItem() function with single argument and the GetPrevItem() function have been
defined earlier in the Get next item in outline and the Get previous item in outline topics.