Share via


Creating a Tree View (Windows Embedded CE 6.0)

1/6/2010

A tree-view control is a hierarchical display of labeled items. Any item in a tree-view control can have a list of subitems that are known as child items and that are associated with it. An item that has one or more child items is called a parent item. A child item is displayed below its parent item and is indented to indicate that it is subordinate to the parent item. An item that has no parent item appears at the top of the hierarchy and is known as a root item.

To create a tree-view control

  1. Specify the WC_ TREEVIEW class in the lpClassName parameter of the CreateWindowEx function.

    This class is registered when the DLL for the common control is loaded. You can use the InitCommonControls function to ensure that this DLL is loaded. To register the tree-view class, use the InitCommonControlsEx function and specify the ICC_TREEVIEW_CLASSES flag as the dwICC member of the INITCOMMONCONTROLSEX structure that you pass in the lpInitCtrls parameter.

  2. Specify a tree-view style in the dwStyle parameter of the CreateWindowEx function.

    Tree-view styles govern the appearance of a tree-view control. You set the initial styles when you create the tree-view control. You can retrieve and change the styles after you create the tree-view control by using the GetWindowLong and SetWindowLong functions. For a complete listing of supported styles, see Window and Control Styles.

  3. Add one or more items to the tree-view control by sending the TVM_INSERTITEM message.

    The TVM_INSERTITEM message returns a handle to the HTREEITEM type, which uniquely identifies the item. This message also includes a TV_INSERTSTRUCT structure that specifies the handle to the parent item and the handle to the item after which the new item is to be inserted. When adding an item, specify the handle to the parent item of the new item. If you specify NULL or the TVI_ROOT value instead of a handle to the parent item handle in TV_INSERTSTRUCT, the item is added as a root item. The second handle must identify either a child item of the specified parent or one of the following values: TVI_FIRST, TVI_LAST, or TVI_SORT.

    When you specify the TVI_FIRST value or the TVI_LAST value, the tree-view control places the new item at the beginning or the end of the list of child items of the specified parent item. When you specify the TVI_SORT value, the tree-view control inserts the new item into the list of child items in alphabetical order, based on the text of the item labels. You can put the list of child items of a parent item in alphabetical order by using the TVM_SORTCHILDREN message. The TVM_SORTCHILDRENCB message enables you to sort child items, based on criteria that you define. When you use the latter message, you specify an application-defined callback function that the tree-view control can call when the relative order of two child items must be determined.

    Note

    A tree-view control uses memory that is allocated from the heap of the process that creates the tree-view control. The maximum number of items in a tree view is based on the amount of memory that is available in the heap.

At any time, the state of the list of child items of a parent item can be expanded, partially expanded, or collapsed. When the state is expanded, the child items of the expanded section are displayed below the parent item. When the state is collapsed, child items are not displayed. The list shifts between the expanded and collapsed states when a user double-taps the parent item or, if the parent has the TVS_HASBUTTONS style, when a user clicks the button that is associated with the parent item. You can expand or collapse the child items by using the TVM_EXPAND message. A tree-view control sends the parent window a TVN_ITEMEXPANDING message when the list of child items of a parent item is about to be expanded or collapsed. This message gives an application the opportunity to prevent the change or to set any attributes of the parent item that depend on the state of the list of child items. After changing the state of the list, the tree-view control sends the parent window a TVN_ITEMEXPANDED message. When a list of child items is expanded, it is indented relative to the parent item. Set the amount of indentation by using the TVM_SETINDENT message, or retrieve the current amount of indentation by using the TVM_GETINDENT message.

The following code example shows how to create a tree-view control.

DWORD dwStyle;                // Style flags of the tree view
INITCOMMONCONTROLSEX  iccex;  // INITCOMMONCONTROLSEX structure

// Initialize the INITCOMMONCONTROLSEX structure.
iccex.dwSize = sizeof (INITCOMMONCONTROLSEX);
iccex.dwICC = ICC_TREEVIEW_CLASSES;

// Register tree-view control classes from the DLL for the common 
// control.
//.
InitCommonControlsEx (&iccex);

// Get the rectangle for the client area.
GetClientRect (hwnd, &rcClient);

// Create the command bar and insert menu.
g_hwndCB = CommandBar_Create (g_hInst, hwnd, 1);
CommandBar_InsertMenubar (g_hwndCB, g_hInst, IDR_MENU, 0);
CommandBar_AddAdornments (g_hwndCB, 0, 0);

// Get the height of the command bar.
iCBHeight = CommandBar_Height (g_hwndCB);

// Assign the window styles for the tree view.
dwStyle = WS_VISIBLE | WS_CHILD | TVS_HASLINES | TVS_LINESATROOT | 
          TVS_HASBUTTONS;

// Create the tree-view control.
g_hwndTreeView = CreateWindowEx (
    0, 
    WC_TREEVIEW,          // Class name
    TEXT("Tree View"),     // Window name
    dwStyle,              // Window style
    0,                    // x-coordinate of the upper-left corner
    iCBHeight + 1,        // y-coordinate of the upper-left corner
    rcClient.right,       // The width of the window for the edit control 
    rcClient.bottom - (iCBHeight + 1), 
                          // The height of the window for the edit 
                          // control
    hwnd,                 // Window handle to the parent window
    (HMENU) IDC_TREEVIEW, // The tree-view control identifier
    g_hInst,              // The instance handle
    NULL);                // Specify NULL for this parameter when you 
                          // create a control

// Be sure that the tree view actually was created.
 if (!g_hwndTreeView)
  return 0;

See Also

Concepts

Working with Common Controls