TVN_DELETEITEM
Tree View Control Reference

TVN_DELETEITEM


TVN_DELETEITEM 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that an item is being deleted. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemOld member is a TVITEM structure whose hItem and lParam members contain valid information about the item being deleted.

If the lParam member of the TVITEM structure points to memory allocated by your application, you can free it when you receive the TVN_DELETEITEM notification message.

TVN_ENDLABELEDIT

TVN_ENDLABELEDIT 
    ptvdi = (LPNMTVDISPINFO) lParam 

Notifies a tree view control's parent window about the end of label editing for an item. This notification message is sent in the form of a WM_NOTIFY message.

ptvdi
Address of an NMTVDISPINFOstructure. The item member of this structure is a TVITEM structure whose hItem, lParam, and pszText members contain valid information about the item that was edited.
If label editing was canceled, the pszText member of the TVITEM structure is NULL; otherwise, pszText is the address of the edited text.

If the pszText member is NULL, the return value is ignored.

If you specified the LPSTR_TEXTCALLBACK value for this item and the pszText member is non-NULL, your TVN_ENDLABELEDIT handler should copy the text from pszText to your local storage.

TVN_GETDISPINFO

TVN_GETDISPINFO 
    lptvdi = (LPNMTVDISPINFO) lParam 

Requests that a tree view control's parent window provide information needed to display or sort an item. This notification message is sent in the form of a WM_NOTIFY message.

lptvdi
Address of an NMTVDISPINFO structure. The item member is a TVITEM structure whose mask, hItem, state, and lParam members specify the type of information required. You must fill the members of the structure with the appropriate information.

This notification is sent under the following circumstances:

TVN_GETINFOTIP

TVN_GETINFOTIP
    lpGetInfoTip = (LPNMTVGETINFOTIP)lParam;

Sent by a tree view control that has the TVS_INFOTIP style. This notification is sent when the control is requesting additional text information to be displayed in a tooltip. The notification is sent in the form of a WM_NOTIFY message.

lpGetInfoTip
Address of an NMTVGETINFOTIP structure that contains information about this notification.

This notification is only sent by tree view controls that have the TVS_INFOTIP style.

Version 4.71

TVN_ITEMEXPANDED

TVN_ITEMEXPANDED 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that a parent item's list of child items has expanded or collapsed. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list expanded or collapsed. For a list of possible values, see the description of the TVM_EXPAND message.

TVN_ITEMEXPANDING

TVN_ITEMEXPANDING 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that a parent item's list of child items is about to expand or collapse. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemNew member is a TVITEM structure that contains valid information about the parent item in the hItem, state, and lParam members. The action member indicates whether the list is to expand or collapse. For a list of possible values, see the description of the TVM_EXPAND message.

TVN_KEYDOWN

TVN_KEYDOWN 
    ptvkd = (LPNMTVKEYDOWN) lParam 

Notifies a tree view control's parent window that the user pressed a key and the tree view control has the input focus. This notification message is sent in the form of a WM_NOTIFY message.

ptvkd
Address of an NMTVKEYDOWN structure. The wVKey member specifies the virtual key code.

TVN_SELCHANGED

TVN_SELCHANGED 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that the selection has changed from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemOld and itemNew members of the NMTREEVIEW structure are TVITEM structures that contain information about the previously selected item and the newly selected item. Only the mask, hItem, state, and lParam members of these structures are valid. The stateMask members of the TVITEM structures specified by itemOld and itemNew are undefined on input.
The action member of the NMTREEVIEW structure indicates the type of action that caused the selection to change. It can be one of the following values:
TVC_BYKEYBOARD By a keystroke.
TVC_BYMOUSE By a mouse click.
TVC_UNKNOWN Unknown.

TVN_SELCHANGING

TVN_SELCHANGING 
    pnmtv = (LPNMTREEVIEW) lParam 

Notifies a tree view control's parent window that the selection is about to change from one item to another. This notification message is sent in the form of a WM_NOTIFY message.

pnmtv
Address of an NMTREEVIEW structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

TVN_SETDISPINFO

TVN_GETDISPINFO 
    lptvdi = (LPNMTVDISPINFO) lParam 

Notifies a tree view control's parent window that it must update the information it maintains about an item. This notification message is sent in the form of a WM_NOTIFY message.

lptvdi
Address of an NMTVDISPINFO structure. The itemOld and itemNew members contain valid information about the currently selected item and the newly selected item. The action member indicates whether a mouse or keyboard action is causing the selection to change. For a list of possible values, see the description of the TVN_SELCHANGED notification message.

If the pszText member of the item's TVITEM structure is the LPSTR_TEXTCALLBACK value, the control sends this notification to set the item's text. In this case, the mask member of lptvdi will have the TVIF_TEXT flag set.

TVN_SINGLEEXPAND

TVN_SINGLEEXPAND
    lpnmtv = (LPNMTREEVIEW)lParam;

Sent by a tree view control with the TVS_SINGLEEXPAND style when the user opens or closes a tree item using a single click of the mouse. This notification is sent in the form of a WM_NOTIFY message.

lpnmtv
Address of an NMTREEVIEW structure that contains information about this notification.

This notification is only sent by tree view controls that have the TVS_SINGLEEXPAND style.

Version 4.71

Tree View Control Structures

This section contains information about the structures used with tree view controls.

NMTREEVIEW

typedef struct tagNMTREEVIEW {
    NMHDR hdr; 
    UINT action; 
    TVITEM itemOld; 
    TVITEM itemNew; 
    POINT ptDrag; 
} NMTREEVIEW, FAR *LPNMTREEVIEW; 

Contains information about a tree view notification message. This structure is identical to the NM_TREEVIEW structure, but it has been renamed to follow current naming conventions.

hdr
NMHDR structure that contains information about this notification message.
action
Specifies a notification-specific action flag.
itemOld
Specifies a TVITEM structure that contains information about the old item state. This member is zero for notification messages that do not use it.
itemNew
Specifies a TVITEM structure that contains information about the new item state. This member is zero for notification messages that do not use it.
ptDrag
Specifies a POINT structure that contains the client coordinates of the mouse at the time the event occurred that caused the notification message to be sent.

See also WM_NOTIFY

NMTVCUSTOMDRAW

typedef struct tagNMTVCUSTOMDRAW {
    NMCUSTOMDRAW nmcd;
    COLORREF clrText;
    COLORREF clrTextBk;
#if (_WIN32_IE >= 0x0400)
    int iLevel;
#endif
} NMTVCUSTOMDRAW, *LPNMTVCUSTOMDRAW;

Contains information specific to an NM_CUSTOMDRAW notification message sent by a tree view control.

nmcd
NMCUSTOMDRAW structure that contains general custom draw information.
clrText
COLORREF value representing the color that will be used to display text foreground in the list view control.
clrTextBk
COLORREF value representing the color that will be used to display text background in the list view control.
iLevel
Version 4.71. Zero-based level of the item being drawn. The root item is at level zero, a child of the root item is at level one, and so on.

Version 4.70

NMTVDISPINFO

typedef struct tagNMTVDISPINFO {
    NMHDR hdr; 
    TVITEM item; 
} NMTVDISPINFO, FAR *LPNMTVDISPINFO; 

Contains and receives display information for a tree view item. This structure is identical to the TV_DISPINFO structure, but it has been renamed to follow current naming conventions.

hdr
NMHDR structure that contains information about this notification message.
item
Specifies a TVITEM structure that identifies and contains information about the tree view item. The mask member of the TVITEM structure specifies which information is being set or retrieved. It can be one or more of the following values:
TVIF_CHILDREN The cChildren member specifies, or is to receive, a value that indicates whether the item has child items.
TVIF_IMAGE The iImage member specifies, or is to receive, the index of the item's nonselected icon in the image list.
TVIF_SELECTEDIMAGE The iSelectedImage member specifies, or is to receive, the index of the item's selected icon in the image list.
TVIF_TEXT The pszText member specifies the new item text or the address of a buffer that is to receive the item text.

If the structure is receiving item text, you typically copy the text to the buffer pointed to by the pszText member of the TVITEM structure. However, you can return a string in the pszText member instead. If you do so, you cannot change or delete the string until the corresponding item text is deleted or until two additional TVN_GETDISPINFO notification messages have been sent.

See also TVN_SETDISPINFO, WM_NOTIFY

NMTVGETINFOTIP

typedef struct tagNMTVGETINFOTIP {
    NMHDR hdr;
    LPTSTR pszText;
    int cchTextMax;
    HTREEITEM hItem;
    LPARAM lParam;
} NMTVGETINFOTIP, *LPNMTVGETINFOTIP;

Contains and receives tree view item information needed to display a tooltip for an item. This structure is used with the TVN_GETINFOTIP notification message.

hdr
NMHDR structure that contains information about this notification message.
pszText
Address of a character buffer that contains the text to be displayed. If you wish to change the text displayed in the tooltip, you will need to modify the contents of this buffer. The size of this buffer is specified by the ccTextMax structure.
cchTextMax
Size of the buffer at pszText, in characters. Although you should never assume that this buffer will be of any particular size, the INFOTIPSIZE value can be used for design purposes.
hItem
Tree handle to the item for which the tooltip is being displayed.
lParam
32-bit, application-defined data associated with the item for which the tooltip is being displayed.

NMTVKEYDOWN

typedef struct tagTVKEYDOWN {
    NMHDR hdr;
    WORD wVKey;
    UINT flags;
} NMTVKEYDOWN, FAR *LPNMTVKEYDOWN;

Contains information about a keyboard event in a tree view control. This structure is used with the TVN_KEYDOWN notification message. The structure is identical to the TV_KEYDOWN structure, but it has been renamed to follow current naming conventions.

hdr
NMHDR structure that contains information about this notification message.
wVKey
Virtual key code.
flags
Always zero.

See also WM_NOTIFY

TVHITTESTINFO

 typedef struct tagTVHITTESTINFO {
    POINT pt;
    UINT flags;
    HTREEITEM hItem;
} TVHITTESTINFO, FAR *LPTVHITTESTINFO;

Contains information used to determine the location of a point relative to a tree view control. This structure is used with the TVM_HITTEST message. The structure is identical to the TV_HITTESTINFO structure, but it has been renamed to follow current naming conventions.

pt
Client coordinates of the point to test.
flags
Variable that receives information about the results of a hit test. This member can be one or more of the following values:
TVHT_ABOVE Above the client area.
TVHT_BELOW Below the client area.
TVHT_NOWHERE In the client area, but below the last item.
TVHT_ONITEM On the bitmap or label associated with an item.
TVHT_ONITEMBUTTON On the button associated with an item.
TVHT_ONITEMICON On the bitmap associated with an item.
TVHT_ONITEMINDENT In the indentation associated with an item.
TVHT_ONITEMLABEL On the label (string) associated with an item.
TVHT_ONITEMRIGHT In the area to the right of an item.
TVHT_ONITEMSTATEICON On the state icon for a tree view item that is in a user-defined state.
TVHT_TOLEFT To the left of the client area.
TVHT_TORIGHT To the right of the client area.
hItem
Handle to the item that occupies the point.

TVINSERTSTRUCT

typedef struct tagTVINSERTSTRUCT {
    HTREEITEM hParent;
    HTREEITEM hInsertAfter;
#if (_WIN32_IE >= 0x0400)
    union
    {
        TVITEMEX itemex;
        TVITEM item;
    } DUMMYUNIONNAME;
#else
    TVITEM item;
#endif
} TVINSERTSTRUCT, FAR *LPTVINSERTSTRUCT;

Contains information used to add a new item to a tree view control. This structure is used with the TVM_INSERTITEM message. The structure is identical to the TV_INSERTSTRUCT structure, but it has been renamed to follow current naming conventions.

hParent
Handle to the parent item. If this member is the TVI_ROOT value or NULL, the item is inserted at the root of the tree view control.
hInsertAfter
Handle to 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.
itemex
Version 4.71. TVITEMEX structure that contains information about the item to add.
item
TVITEM structure that contains information about the item to add.

TVITEM

typedef struct tagTVITEM{
    UINT      mask;
    HTREEITEM hItem;
    UINT      state;
    UINT      stateMask;
    LPTSTR    pszText;
    int       cchTextMax;
    int       iImage;
    int       iSelectedImage;
    int       cChildren;
    LPARAM    lParam;
} TVITEM, FAR *LPTVITEM;

Specifies or receives attributes of a tree view item. This structure is identical to the TV_ITEM structure, but it has been renamed to follow current naming conventions. New applications should use this 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 one or more of the following values:
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. When setting the state of an item, the stateMask member indicates the bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree View Control Item States.

Bits 8 through 11 of this member specify the one-based overlay image index. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, you should use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the TVIS_STATEIMAGEMASK mask. To set the state image index, you should use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the TVM_SETIMAGELIST message.

stateMask
Specifies the bits of the state member that are valid. If you are retrieving an item's state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bits.
pszText
Address of 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 address of the buffer that receives the item text.
cchTextMax
Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set 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 nonselected 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 can be one of the following values:
zero The item has no child items.
one 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.

TVITEMEX

typedef struct tagTVITEMEX{
    UINT      mask;
    HTREEITEM hItem;
    UINT      state;
    UINT      stateMask;
    LPTSTR    pszText;
    int       cchTextMax;
    int       iImage;
    int       iSelectedImage;
    int       cChildren;
    LPARAM    lParam;
    int       iIntegral;
} TVITEMEX, FAR *LPTVITEMEX;

Specifies or receives attributes of a tree view item. This structure is an enhancement to the TVITEM structure. New applications should use this structure where appropriate.

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 one or more of the following values:
TVIF_CHILDREN The cChildren member is valid.
TVIF_HANDLE The hItem member is valid.
TVIF_IMAGE The iImage member is valid.
TVIF_INTEGRAL The iIntegral 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
Set of bit flags and image list indexes that indicate the item's state. When setting the state of an item, the stateMask member indicates the bits of this member that are valid. When retrieving the state of an item, this member returns the current state for the bits indicated in the stateMask member.

Bits 0 through 7 of this member contain the item state flags. For a list of possible item state flags, see Tree View Control Item States.

Bits 8 through 11 of this member specify the one-based overlay image index. The overlay image is superimposed over the item's icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the TVIS_OVERLAYMASK mask. To set the overlay image index in this member, you should use the INDEXTOOVERLAYMASK macro. The image list's overlay images are set with the ImageList_SetOverlayImage function.

Bits 12 through 15 of this member specify the state image index. The state image is displayed next to an item's icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the TVIS_STATEIMAGEMASK mask. To set the state image index, use the INDEXTOSTATEIMAGEMASK macro. The state image index specifies the index of the image in the state image list that should be drawn. The state image list is specified with the TVM_SETIMAGELIST message.

stateMask
Specifies the bits of the state member that are valid. If you are retrieving an item's state, set the bits of the stateMask member to indicate the bits to be returned in the state member. If you are setting an item's state, set the bits of the stateMask member to indicate the bits of the state member that you want to set. To set or retrieve an item's overlay image index, set the TVIS_OVERLAYMASK bits. To set or retrieve an item's state image index, set the TVIS_STATEIMAGEMASK bits.
pszText
Address of 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 address of the buffer that receives the item text.
cchTextMax
Size of the buffer pointed to by the pszText member, in characters. If this structure is being used to set 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 nonselected 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 can be one of the following values:
zero The item has no child items.
one 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.
iIntegral
Specifies the height of the item. This height is in increments of the standard item height (see TVM_SETITEMHEIGHT). By default, each item gets one increment of item height. Setting this member to two will give the item twice the standard height, setting this member to three will give the item three times the standard height, and so on. The tree view control does not draw in this extra area. This extra space can be used by the application for drawing when using custom draw.

Version 4.71

TVSORTCB

typedef struct tagTVSORTCB{
    HTREEITEM hParent;
    PFNTVCOMPARE lpfnCompare;
    LPARAM lParam;
} TVSORTCB, FAR *LPTVSORTCB;

Contains information used to sort child items in a tree view control. This structure is used with the TVM_SORTCHILDRENCB message. This structure is identical to the TV_SORTCB structure, but it has been renamed to follow current naming conventions.

hParent
Handle to the parent item.
lpfnCompare
Address of an application-defined callback function, which is called during a sort operation each time the relative order of two list items needs to be compared. The callback function has the following form:
 
	int CALLBACK CompareFunc(LPARAM lParam1, LPARAM lParam2, 
		LPARAM lParamSort); 
The callback function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

The lParam1 and lParam2 parameters correspond to the lParam member of the TVITEM structure for the two items being compared. The lParamSort parameter corresponds to the lParam member of this structure.

lParam
Application-defined 32-bit value that gets passed as the lParamSort argument in the callback function specified in lpfnCompare.

© 1997 Microsoft Corporation. All rights reserved. Terms of Use.