CQuadStateTree

• Download source - 8.7 KB
• Download demo no EXE - 55.7 KB
• Download demo - 55.7 KB

Introduction

I was in need of a tree control with several features that are not found in the standard CTreeCtrl:

1. Checkboxes with indeterminate state. When a tree item's child items are not all in the same state then that item's checkbox should show an indeterminate state.
2. Setting a parent tree item's checkbox state to checked or unchecked should automatically set all its child tree item's states to the same state.
3. Setting a child tree item's checkbox state to checked or unchecked should automatically set its parent tree item's state to the appropriate state.
4. Not all the items in the tree need to have a checkboxes. Sometimes, the root of the tree just needs to be a labeled place holder.
5. Notifications. It would be really nice if the parent window of the tree control recieved detailed notification messages when a tree item's checkbox state changes.
6. Ability to block a change in a checkbox state. When a notification (see above) is received by the parent window, it should be possible to block the checkbox state from changing.

Presented in this article is the CQuadStateTree class that delivers all these requirements, plus a few more.

Background

Why Quad State you may ask? It is because each checkbox in the tree control can have four states. Of course, there is the basic checked and unchecked, and the familiar indeterminate state. But I have added a forth state which is 'none'. You may say that 'none' is not a state, but it actually is. How else would one specify that a tree item not have a checkbox when the rest of the tree control does have them?

Of course to have the 'none' state make any sense there has to be a basic restriction placed on it. The restriction being that in order for a tree item to have a 'none' state, all of its parent items up the tree, all the way up to the root, must also be in the 'none' state. It makes no sense to able to select a parent item and not be able to select a child item.

Using the Code

The first step for using this code in your own projects is to add the QuadStateTree.h and QuadStateTree.cpp files to your project. Then in any file that needs access to the CQuadStateTree class, you just have to #include QuadStateTree.h.

Since CQuadStateTree is derived from CTreeCtrl, you can use this class the exact same way you would use CTreeCtrl with the following API exceptions:

CQuadStateTree Data Types

The CQuadStateTree uses the following custom data types.

TVCS_CHECKSTATE

The TVCS_CHECKSTATE enum defines the four possible checkbox states.

Syntax

enum TVCS_CHECKSTATE
{
    TVCS_NONE          = -1,
    TVCS_UNCHECKED     =  0,
    TVCS_CHECKED       =  1,
    TVCS_INDETERMINATE =  2 
};

Members

NMTVNCHECK

The NMTVNCHECK structure contains information about a change in a tree item's checkbox state.

Syntax

typedef struct tagTVNCHECK    
{
    NMHDR hdr;                     
    HTREEITEM hTreeItem;           
    LPARAM lParam;                 
    TVCS_CHECKSTATE OldCheckState; 
    TVCS_CHECKSTATE NewCheckState; 
    HTREEITEM TriggerItem;         
} NMTVNCHECK, *LPNMTVNCHECK;

Members

CQuadStateTree Notification Messages

TVN_CHECK notification code

The TVN_CHECK notification is sent to the parent window as a WM_NOTIFY message to inform the parent that a checkbox is about to change state.

Syntax

TVN_CHECK

    pNMTvnCheck = (LPNMTVNCHECK) lParam

Parameters

Return Value

If the hTreeItem and TriggerItem members of the NMTVNCHECK structure are pointing to the same tree item then returning a non-zero value will stop the tree item checkbox from changing.

In all other cases, the return value is ignored.

ON_TVN_CHECK Message map macro

Use the ON_TVN_CHECK macro to define an TVN_CHECK notification handler function.

Syntax

ON_TVN_CHECK(<nID>, <pFunction>)

Parameters

Remarks

pFunction must be declared with the following prototype:

afx_msg void memberFxn( NMHDR * pNMHDR, LRESULT * pResult );

where the italicized parameters are:

pNMHDR
A pointer to a NMHDR structure which can be cast to a LPNMTVNCHECK structure pointer.

pResult
A pointer to the result code that you set before you return.

CQuadStateTree Member Functions

CQuadStateTree::CQuadStateTree

Class constructor that is called to construct a CQuadStateTree object.

Syntax

CQuadStateTree();

CQuadStateTree::~CQuadStateTree

Class destructor that is called when a CQuadStateTree object is deleted.

Syntax

virtual ~CQuadStateTree();

CQuadStateTree::GetCheck

Syntax

TVCS_CHECKSTATE GetCheck(
    HTREEITEM hTreeItem) const;

Parameter

Return Value

Returns a TVCS_CHECKSTATE enum indicating the current state of the checkbox.

Remarks

This function is identical to CTreeCtrl::GetCheck. The only difference is that the return value is returned as a TVCS_CHECKSTATE enum instead of a BOOL.

CQuadStateTree::SetCheck

Syntax

BOOL SetCheck (
    HTREEITEM hTreeItem,
    TVCS_CHECKSTATE NewCheckState = TVCS_CHECKED);

Parameters

Return Value

Nonzero if successful; otherwise zero.

Remarks

SetCheck() will return zero for the following reasons:

1. NewCheckState is TVCS_INDETERMINATE. The TVCS_INDETERMINATE state will only be set by the control when a tree item's children are in different states. It is not possible to set TVCS_INDETERMINATE via SetCheck().
2. NewCheckState is TVCS_NONE. The only way to set a checkbox to TVCS_NONE state is if all hTreeItem's parent tree items are already set to TVCS_NONE. To set TVCS_NONE state you have to start at the tree's root item and work your way down.

CQuadStateTree::Create

Call this function to create a control (a child window) and associate it with the CQuadStateTree object.

Syntax

virtual BOOL Create(
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

CQuadStateTree::CreateEx

Call this function to create a control (a child window) and associate it with the CQuadStateTree object.

Syntax

virtual BOOL CreateEx(
    DWORD dwExStyle,
    DWORD dwStyle,
    const RECT& rect,
    CWnd* pParentWnd,
    UINT nID);

Parameters

Remarks

I have not explored the tree view extended styles, so I have no idea how they will influence this control.

Deriving from CQuadStateTree

CQuadStateTree has to handle several different messages in order to work properly. If you derive your own control from CQuadStateTree and you handle the same messages in derived class, be sure to call the CQuadStateTree message handler functions from your message handler functions.

Listed here is the messages that CQuadStateTree handles and the name of the functions that handle them:

History

• November 28, 2014 - Initial release