tutorial 31: listview control
we will learn how to create and use the listview control in this tutorial.
theory:
a listview control is one of the common controls like treeview, richedit etc. you are familiar with it even if you may not know it by its name. for example, the right pane of windows explorer is a listview control. a listview control is good for displaying items. in this regard, it's like a listbox but with enhanced capabilities.
you can create a listview control in two ways. the first method is also the easiest one: create it with a resource editor. just don't forget to call initcommoncontrols within your asm source code. the other method is to call createwindowex in your source code. you must specify the correct window class name for the control, ie. syslistview32. the window class "wc_listview" is incorrect.
there are four methods of viewing data in a listview control: icon, small icon, list and report views. you can see examples of these views by selecting view->large icons (icon view), small icons (small icon view), list (list view) and details (report view). views are just data representation methods:they only affect the appearances of data. for example, you can have a lot of data in the listview control, but if you want, you can view only some of them. report view is the most informative one while the remaining views give less info. you can specify the view you want when you create a listview control. you can later change the view by calling setwindowlong, specifying gwl_style flag.
now that we know how to create a listview control, we will continue on how to use it. i'll focus on report view which can demonstrate many features of listview control. the steps in using a listview control are as follows:
- create a listview control with createwindowex, specifying syslistview32 as the class name. you can specify the initial view at this time.
- (if exists) create and initialize image lists to be used with the listview items.
- insert column(s) into the listview control. this step is necessary if the listview control will use report view.
- insert items and subitems into the listview control.
columns
in report view, there are one or more columns. you can think of the arrangement of data in the report view as a table: the data are arranged in rows and columns. you must have at least one column in your listview control (only in report view). in views other than report, you need not insert a column because there can be one and only one column in those views.
you can insert a column by sending lvm_insertcolumn to the listview control.
lvm_insertcolumn
wparam = icol
lparam = pointer to a lv_column structure
icol is the column number, starting from 0.
lv_column contains information about the column to be inserted. it has the following definition:
lv_column struct
imask dd ?
fmt dd ?
lx dd ?
psztext dd ?
cchtextmax dd ?
isubitem dd ?
iimage dd ?
iorder dd ?
lv_column ends
| field name | meanings |
|---|---|
| imask |
a collection of flags that governs which members in this structure are valid. the reason behind this member is that not all members in this structure are used at the same time. some members are used in some situations. and this structure is used both for input and output. thus it's important that you *mark* the members that are used in this call to windows so windows knows which members are valid. the available flags are: lvcf_fmt = the fmt member is valid. you can combine the above flags. for example, if you want to specify the text label of the column, you must supply the pointer to the string in psztext member. and you must tell windows that psztext member contains data by specifying lvcf_text flag in this field else windows will ignore the value in psztext. |
| fmt |
specify the alignment of items/subitems in the column. the available values are: lvcfmt_center = text is centered. |
| lx | the width of the column, in pixels. you can later change the width of the column with lvm_setcolumnwidth. |
| psztext | contains a pointer to the name of the column if this structure is used to set the column's properties. if this structure is used to receive the properties of a column, this field contains a pointer to a buffer large enough to receive the name of the column that will be returned. in that case, you must give the size of the buffer in cchtextmax below. you can ignore cchtextmax if you want to set the name of the column because the name must be an asciiz string which windows can determine the length. |
| cchtextmax | the size, in bytes, of the buffer specified in psztext above. this member is used only when you use this structure to receive info about a column. if you use this structure to set the properties of a column, this field is ignored. |
| isubitem | specify the index of subitem associated with this column. this value is used as a marker which subitem this column is associated with. if you want, you can specify an absurd number in this field and your listview control will still run like a breeze. the use of this field is best demonstrated when you have the column number and need to know with which subitem this column is associated. you can query the listview control by sending lvm_getcolumn message to it, specifying lvcf_subitem in the imask member. the listview control will fill the isubitem member with whatever value you specify in this field when the column is inserted. in order for this method to work, you need to input the correct subitem index into this field. |
| iimage and iorder | used with internet explorer 3.0 upwards. i don't have info about them. |
