LVITEM

列表视图控件（List Control）
列表视图控件是一种非常常用的控件，在需要以报表形式显示数据时，列表控件通常是最好的选择，许多专用的数据报表控件，也是在它的基础上派生而来。与树视图类似，列表控件可以由多个子项目组成，并且支持大图标、小图标、列表和报表4种方式显示信息，如图1所示。
图1 列表视图的4种显示方式
列表视图包含一个项目列表，而其中每个项目由图标、项目名称和多个子项组成，每一个子项所包含的项目的数目必须相同，属性相同的每个子项显示在同一个列中。列表视图控件有两个重要的数据结构LVCOLUMN和LVITEM。LVCOLUMN用于定义报表方式下的“列”的结构；LVITEM用于定义“项”的结构。这两个结构的定义及说明如下：

typedef struct _LVCOLUMN {
UINT mask;            //说明此结构中哪些成员是有效的
int fmt;           //列的对齐方式
int cx;            //列的初始宽度
LPTSTR pszText; //列的标题
int cchTextMax;   //pszText所指向的缓冲区的大小
int iSubItem;      //与列关联的子项的索引值，从0开始
int iImage;           //与列关联的图像列表中指定图像的索引值
int iOrder;           //第几列，0代表最左一列
} LVCOLUMN, FAR *LPLVCOLUMN;
typedef struct _LVITEM {
UINT   mask;        //说明LVITEM结构中哪些成员有效
int    iItem;       //项目的索引值(可以视为行号)从0开始
int    iSubItem;    //子项的索引值(可以视为列号)从0开始
UINT   state;       //子项的状态
UINT   stateMask;   //状态有效的屏蔽位
LPTSTR pszText;   //主项或子项的名称
int    cchTextMax; //pszText所指向的缓冲区大小
int    iImage;       //关联图像列表中指定图像的索引值
LPARAM lParam;    //程序定义的32位参数
int iIndent;          //表示图像位置缩进的单位
} LVITEM, FAR *LPLVITEM;列表项常用的属性如下：View指定程序运行后列表视图控件最初显示的方式，可以设置为Icon（大图标）、SmallIcon（小图标）、List（列表）或Report（报表）；Single selection表示每次只能选中一个项；Auto arrange使得项目在Icon和Small Icon显示方式下能够自动排序；Edit Labels表示可以编辑项目的卷标；No column header表示取消控件所有列的标题。

typedef struct _LVITEM { UINT mask; int iItem; int iSubItem; UINT state; UINT stateMask; LPTSTR pszText; int cchTextMax; int iImage; LPARAM lParam; #if (_WIN32_IE >= 0x0300) int iIndent; #endif } LVITEM, FAR *LPLVITEM;

Specifies or receives the attributes of a list view item. This structure has been updated to support a new mask value (LVIF_INDENT) that enables item indenting. This structure supersedes theLV_ITEM structure.

mask //标明列表框单元项有的特性

Set of flags that specify which members of this structure contain data to be set or which members are being requested. This can be one or more of the following flags:LVIF_TEXTThe pszText member is valid or must be filled in.LVIF_IMAGEThe iImage member is valid or must be filled in.LVIF_INDENTThe iIndent member is valid or must be filled in.LVIF_NORECOMPUTEThe control will not generate LVN_GETDISPINFO to retrieve text information if it receives a LVM_GETITEM message. Instead, the pszText member will contain LPSTR_TEXTCALLBACK.LVIF_PARAMThe lParam member is valid or must be filled in.LVIF_STATEThe state member is valid or must be filled in.LVIF_DI_SETITEMThe operating system should store the requested list item information and not ask for it again. This flag is used only with the LVN_GETDISPINFO notification message.

iItem

Zero-based index of the item to which this structure refers.

iSubItem

One-based index of the subitem to which this structure refers, or zero if this structure refers to an item rather than a subitem.

state //标明列表框单元项将要设置的（状态）动作，其有效和无效受stateMask过滤器控制

Indicates the item's state, state image, and overlay image. The stateMask member indicates the valid bits of this member.

Bits 0 through 7 of this member contain the item state flags. This can be one or more of the item state values.

Bits 8 through 11 of this member specify the one-based overlay image index. Both the full-sized icon image list and the small icon image list can have overlay images. 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 LVIS_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 theImageList_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 LVIS_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 LVM_SETIMAGELIST message.

stateMask

Value specifying which bits of the state member will be retrieved or modified. For example, setting this member to LVIS_SELECTED will cause only the item's selection state to be retrieved.

This member allows you to modify one or more item states without having to retrieve all of the item states first. For example, setting this member to LVIS_SELECTED and state to zero will cause the item's selection state to be cleared, but none of the other states will be affected.

To retrieve or modify all of the states, set this member to (UINT)-1.

You can use the macro ListView_SetItemState both to set and to clear bits.

pszText

Address of a null-terminated string containing the item text if the structure specifies item attributes. If this member is the LPSTR_TEXTCALLBACK value, the item is a callback item. Do not set the pszText member to LPSTR_TEXTCALLBACK if the list view control has LVS_SORTASCENDING orLVS_SORTDESCENDING style.

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 if the structure is receiving item attributes. This member is ignored if the structure specifies item attributes.

iImage

Index of the item's icon in the control's image list. This applies to both the large and small image list.

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

lParam

32-bit value specific to the item. If you use the LVM_SORTITEMS message, the list view control passes this value to the application-defined comparison function. You can also use theLVM_FINDITEM message to search a list view control for an item with a specified lParam value.

iIndent

Version 4.70. Number of image widths to indent the item. A single indentation equals the width of an item image. Therefore, the value 1 indents the item by the width of one image, the value 2 indents by two images, and so on. Note that this field is supported only for items. Attempting to set subitem indentation will cause the calling function to fail.

The LVITEM structure is used with a number of messages, including LVM_GETITEM, LVM_SETITEM,LVM_INSERTITEM, and LVM_DELETEITEM.

CTreeCtrl::SetItem

BOOL SetItem( TVITEM* pItem );
BOOL SetItem( HTREEITEM hItem,
              UINT nMask,
              LPCTSTR lpszItem,
              int nImage,
              int nSelectedImage,
              UINT nState,
              UINT nStateMask,
              LPARAM lParam
             );

返回值：如果成功则返回非零值；否则返回0。

参数：pItem一个指向包含新项属性的TVITEM结构的指针，就像在“Platform SDK”中描述的一样。hItem要设置其属性的项的句柄。nMask指定要设置哪些属性的整数。lpszItem一个包含了项的文本的字符串的地址。nImage项的图像在tree view控件的图像列表中的索引。nSelectedImage该项的被选择图像在tree view控件的图像列表中的索引。nState指定项的状态值。nStateMask指定要设置哪些状态。lParam一个与该项关联的32位的应用程序定义值。
说明：
此成员函数用来设置指定tree view项的属性。
在TVITEM结构中，hItem成员标识了这个项，mask成员指定了要设置的属性。如果mask成员或nMask参数指定的是TVIF_TEXT值，则pszText成员或lpszItem就是一个以空字符结尾的字符串的地址，而cchTextMax成员被忽略。如果mask（或nMask）指定的是TVIF_STATE值，则stateMask成员或nStateMask参数指定要改变的是哪一个项状态，而state成员或nState参数包含了那些状态的值。

请参阅：CTreeCtrl::GetItem