LISTVIEW statement

Purpose

Manipulate a LISTVIEW control in order to set/retrieve data.

Syntax

LISTVIEW DELETE COLUMN hDlg, id&, col&
LISTVIEW DELETE ITEM hDlg, id&, item&
LISTVIEW FIND hDlg, id&, item&, StrExpr TO datav&
LISTVIEW FIND EXACT hDlg, id&, item&, StrExpr TO datav&
LISTVIEW FIT CONTENT hDlg, id&, col&
LISTVIEW FIT HEADER hDlg, id&, col&
LISTVIEW GET COLUMN hDlg, id&, col& TO datav&
LISTVIEW GET COUNT hDlg, id& TO datav&
LISTVIEW GET HEADER hDlg, id&, col& TO txtv$

LISTVIEW GET HEADERID hDlg, id& TO hLV, idv&
LISTVIEW GET MODE hDlg, id& TO datav&
LISTVIEW GET SELCOUNT hDlg, id& TO datav&

LISTVIEW GET SELECT hDlg, id& [, item&] TO datav&
LISTVIEW GET STATE hDlg, id&, item&, col& TO datav&
LISTVIEW GET STYLEXX hDlg, id& TO datav&
LISTVIEW GET TEXT hDlg, id&, item&, col& TO txtv$
LISTVIEW GET USER hDlg, id&, item& TO datav&
LISTVIEW INSERT COLUMN hDlg, id&, col&, StrExpr, ColWidth&, format&
LISTVIEW INSERT ITEM hDlg, id&, item&, image&, StrExpr
LISTVIEW RESET hDlg, id&
LISTVIEW SELECT hDlg, id&, item& [, col&]
LISTVIEW SET COLUMN hDlg, id&, col&, NumExpr
LISTVIEW SET HEADER hDlg, id&, col&, StrExpr
LISTVIEW SET IMAGE hDlg, id&, item&, NumExpr
LISTVIEW SET IMAGE2 hDlg, id&, item&, NumExpr
LISTVIEW SET IMAGELIST hDlg, id&, hLst, NumExpr
LISTVIEW SET MODE hDlg, id&, NumExpr
LISTVIEW SET OVERLAY hDlg, id&, item&, NumExpr
LISTVIEW SET STYLEXX hDlg, id&, NumExpr
LISTVIEW SET TEXT hDlg, id&, item&, col&, StrExpr
LISTVIEW SET USER hDlg, id&, item&, NumExpr
LISTVIEW SORT hDlg, id&, col& [, options...]
LISTVIEW UNSELECT hDlg, id&, item&, [col&]
LISTVIEW VISIBLE hDlg, id&, item&

hDlg

Handle of the dialog that owns the ListView.

hLst

Handle of the ImageList to be used for graphical items.

hLV

Handle of the ListView Control.

id&

The control identifier assigned with CONTROL ADD LISTVIEW.

item&

A data item number. First=1, second=2...

col&

A vertical column number. First=1, second=2...

NumExpr

A numeric expression passed as a parameter.

StrExpr

A string expression passed as a parameter.

txtv$

A string variable to which result text is assigned.

datav&

A long integer variable to which result data is assigned.

Remarks

There are 4 general display modes available with a LISTVIEW control. The initial display mode is established at the time the control is created, as a part of the control style parameter. It may be changed from time to time with LISTVIEW SET MODE.

Mode 0	Icon Mode - String data items are displayed left to right, wrapped to multiple lines as necessary. If a small icon IMAGELIST is attached to the LISTVIEW control, images from that list are displayed with each data item.
Mode 1	Report Mode - String data items are displayed as a list, top to bottom, one item per line. The control may have one or more columns, with header text to describe each of them. Additional sub-items may be displayed in each column, by specifying a column number greater than one. This is the most frequently used ListView mode, and the default mode if not specified at the time the control is created. In this mode, it's often convenient to think of the item number as a row number. If a small icon IMAGELIST is attached to the LISTVIEW control, images from that list are displayed with each data item.
Mode 2	Small Icon Mode - String data items are displayed left to right, wrapped to multiple lines as necessary. If a small icon IMAGELIST is attached to the LISTVIEW control, images from that list are displayed with each data item.
Mode 3	List Mode - String data items are displayed as a list, top to bottom, one item per line. This mode is very similar in appearance to a standard LISTBOX control. In this mode, it's often convenient to think of the item number as a row number. If a small icon IMAGELIST is attached to the LISTVIEW control, images from that list are displayed with each data item.

In all of the following descriptions, the LISTVIEW control which is the subject of the statement is identified by the handle of the dialog that owns the LISTVIEW (hDlg), and the unique control identifier (id&) you gave it upon creation in CONTROL ADD LISTVIEW.

Each data item (or sub-item) is referenced by a combination of its item number (item&) and its column number (col&). A primary data item always has a column number of 1, while sub-items always have a column number greater than 1. Sub-items are only displayed in Report Mode. In all other display modes, they are hidden from view.

It's important to note that both primary item numbers (item&) and sub-item column numbers (col&) start at 1. The first=1, the second=2, and so forth.

LISTVIEW DELETE COLUMN hDlg, id&, col&

The column specified by col&, including its associated header text (if any), is deleted from the LISTVIEW control. The column number (col&) is indexed to 1 (1=first, 2=second, etc.). Column one of a list-view control cannot be deleted. If you must delete column one, insert a zero length dummy column one and delete column two and above. This is a limitation of the Microsoft Windows Listview control and not a PowerBASIC limitation.

LISTVIEW DELETE ITEM hDlg, id&, item&

The data item specified by item& is deleted from the LISTVIEW control. The row number (item&) is indexed to 1 (1=first, 2=second, etc.).

LISTVIEW FIND hDlg, id&, item&, StrExpr TO datav&

Strings in the first column of a LISTVIEW are searched to find the first string which begins with the data in StrExpr, regardless of any characters which follow. Comparisons are not case-sensitive. Strings are searched beginning with the string specified by item&, and ending with the last string in the LISTVIEW. Searching does not wrap to the beginning of the list. The row number (item&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTVIEW starting with the first string, item& should be set to one (1). If a matching string is found, the index value of the match is assigned to the variable specified by datav&. If no match is found, the value zero (0) is assigned to it.

LISTVIEW FIND EXACT hDlg, id&, item&, StrExpr TO datav&

Strings in the first column of a LISTVIEW are searched to find the first string which exactly matches the data in StrExpr. Comparisons are not case-sensitive. Strings are searched beginning with the string specified by item&, and ending with the last string in the LISTVIEW. Searching does not wrap to the beginning of the list. The row number (item&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTVIEW starting with the first string, item& should be set to one (1). If a matching string is found, the index value of the match is assigned to the variable specified by datav&. If no match is found, the value zero (0) is assigned to it.

LISTVIEW FIT CONTENT hDlg, id&, col&

The width of the column specified by col& is adjusted to fit the width of the data items displayed in that column. The column number (col&) is indexed to 1 (1=first, 2=second, etc.).

LISTVIEW FIT HEADER hDlg, id&, col&

The width of the column specified by col& is adjusted to fit the width of the rows displayed in that column, and the header text at the top of that column. The column number (col&) is indexed to 1 (1=first, 2=second, etc.). If the specified column is the last column, its width is set to fill the remaining width of the list-view control.

LISTVIEW GET COLUMN hDlg, id&, col& TO datav&

The width of the designated column is retrieved from the ListView and assigned to the variable specified by datav&. The width is specified in either pixels or dialog units, depending upon which was used at creation. The value col& specifies the column number (1=first, 2=second, etc.).

LISTVIEW GET COUNT hDlg, id& TO datav&

The number of rows in the LISTVIEW is retrieved, and assigned to the long integer variable specified by datav&.

LISTVIEW GET HEADER hDlg, id&, col& TO txtv$

Column header text is retrieved from the LISTVIEW and assigned to the string variable specified by txtv$. The value col& specifies the column number (1=first, 2=second, etc.).

LISTVIEW GET HEADERID hDlg, id& TO hLV, idv&

The handle of the LISTVIEW control and the ID of HEADER control (a child of the LISTVIEW) are retrieved and assigned to the variables represented by hLV and idv& respectively. These two items may then be used with the HEADER statement for advanced handling of the header control which is embedded in the LISTVIEW.

LISTVIEW GET MODE hDlg, id& TO datav&

The display mode of the specified LISTVIEW control is retrieved and assigned to the variable designated by datav&. Possible mode values are 0=icon mode, 1=report mode, 2=small icon mode, 3=list mode.

LISTVIEW GET SELCOUNT hDlg, id& TO datav&

The LISTVIEW is interrogated to determine the number of primary data items which are currently selected. This count is assigned to the long integer variable specified by datav&. To determine the count of sub-items selections, you must execute LISTVIEW GET STATE on every active sub-item.

LISTVIEW GET SELECT hDlg, id& [, item&] TO datav&

The LISTVIEW is interrogated to determine the next primary data item which is currently selected. The parameter item& specifies the starting item number for the search, to facilitate retrieving multiple selected items. To start at the beginning, use an item& of one (1), or just omit that parameter. The selected item number is assigned to the long integer variable specified by datav&. If no selected items are found, the value zero (0) is returned. To find selected sub-items, you must execute LISTVIEW GET STATE on remaining active sub-items.

LISTVIEW GET STATE hDlg, id&, item&, col& TO datav&

A data item is tested to see if it is currently selected. The values of item&/col& specify the position of the data item (1=first, 2=second, etc.). If the item is selected, -1 (true) is assigned to the variable specified by datav&. Otherwise, 0 (false) is assigned to it.

LISTVIEW GET STYLEXX hDlg, id& TO datav&

ListView controls offer a number of optional additional style attributes which are unique and specific to a ListView. This statement retrieves the current setting of this special extended style, and assigns it to the long integer variable specified by datav&. A list of the available extended styles can be found under LISTVIEW SET STYLEXXX. This special extended style is named STYLEXX to distinguish it from the primary style and extended style specified in CONTROL ADD LISTVIEW.

LISTVIEW GET TEXT hDlg, id&, item&, col& TO txtv$

A string data item is retrieved from the LISTVIEW control and assigned to the string variable specified by txtv$. The values of item&/col& specify the position of the data item (1=first, 2=second, etc.).

LISTVIEW GET USER hDlg, id&, item& TO datav&

Each row in a LISTVIEW may have a long integer user value associated with it at the discretion of the programmer. This user value is retrieved with LISTVIEW GET USER. The numeric value item& specifies which user value is requested, 1 for the first row, 2 for the second row, etc. The returned user value is assigned to the long integer variable specified by datav&. LISTVIEW user values are assigned with the LISTVIEW SET USER statement. In addition to these LISTVIEW user values, every DDT control offers an additional eight user values which can be accessed with CONTROL GET USER and CONTROL SET USER.

LISTVIEW INSERT COLUMN hDlg, id&, col&, StrExpr, ColWidth&, format&

A new vertical column is defined for Report Mode of this LISTVIEW control. The value col& specifies the column number (1=first, 2=second, etc.). StrExpr describes the text name of the column header. The value ColWidth& specifies the width of the column in either dialog units or pixels, depending upon which was specified at creation. The value format& describes the format and justification of the text: 0=left, 1=right, 2=center. Column 1 is always left-justified, regardless of what is requested here. When inserting a new column 1, the contents of the original column 1 are copied to the new column 1. This only occurs when inserting a new left most column, when inserting other columns, no data is copied to the new column. This is a limitation of the Microsoft Windows Listview control and not a PowerBASIC limitation.

LISTVIEW INSERT ITEM hDlg, id&, item&, image&, StrExpr

A new row is added to this LISTVIEW control. The value item& specifies the row number (1=first, 2=second, etc.), and StrExpr tells the text to be displayed in the first column. The remaining columns are empty, but you can fill them by executing LISTVIEW SET TEXT. If an IMAGELIST has been attached to this control, the parameter image& specifies which image should be displayed (1=first, 2=second, etc.). If no image is needed, the value 0 should be used.

LISTVIEW RESET hDlg, id&

All data items are deleted from the specified LISTVIEW control. Any columns, and their associated headers, which may have been defined for Report Display mode are retained without change.

LISTVIEW SELECT hDlg, id&, item& [, col&]

The string data item specified by item&/col& is chosen as selected text for the LISTVIEW control and the item is highlighted. The values of item&/col& = 1 for the first item, 2 for the second item, etc. If the optional parameter col& is not given, the default value of 1 is used to select the primary data item.

LISTVIEW SET COLUMN hDlg, id&, col&, NumExpr

The width of a LISTVIEW column is changed to that designated by the NumExpr. The value is specified in either dialog units or pixels, depending upon which was used at creation. The value col& specifies the column number (1=first, 2=second, etc.). If NumExpr is -1, then the column width is adjusted to fit the data items in that column. If NumExpr is -2, the column width is adjusted to fit both the data items and the header text. These options are functionally identical to LISTVIEW FIT CONTENT and LISTVIEW FIT HEADER.

LISTVIEW SET HEADER hDlg, id&, col&, StrExpr

New column header text is displayed above the specified column on the LISTVIEW control. The string expression StrExpr specifies the new header text, while the value col& specifies the column number (1=first, 2=second, etc.).

LISTVIEW SET IMAGE hDlg, id&, item&, NumExpr

The image specified by NumExpr (1=first, 2=second, etc.) is displayed next to the item specified by item&. If no IMAGELIST is attached to the LISTVIEW, nothing is displayed.

LISTVIEW SET IMAGE2 hDlg, id&, item&, NumExpr

The image specified by NumExpr (1=first, 2=second, etc.) is displayed as a secondary "status" image next to the primary image. If NumExpr evaluates to zero, no secondary image is displayed. A secondary image is usually used to specify item status, with an image such as a check mark. Secondary images are generally not displayed in either of the icon modes. If no Status Image List is attached to the LISTVIEW (using the LISTVIEW IMAGELIST statement), nothing is displayed. A maximum of 15 status images are supported, so NumExpr must evaluate in the range of 1-15.

LISTVIEW SET IMAGELIST hDlg, id&, hLst, NumExpr

The IMAGELIST specified by hLst is attached to this LISTVIEW control. The value of NumExpr specifies the type of IMAGELIST:

%LVSIL_NORMAL	Large icons
%LVSIL_SMALL	Small icons
%LVSIL_STATE	Status images

Up to three IMAGELIST structures may be attached to each LISTVIEW to display images as needed with each data item. Depending upon the mode in effect, icons are extracted from either the large icon or small icon list for that purpose. If a status image list is also attached, the LISTVIEW SET IMAGE2 statement may be used to display a secondary image. When the LISTVIEW control is destroyed, any attached IMAGELIST is automatically destroyed unless the %LVS_SHAREIMAGELISTS style was specified at the time the LISTVIEW was created.

LISTVIEW SET MODE hDlg, id&, NumrExpr

The display mode of the specified LISTVIEW control is changed to that designated by the value of NumExpr. The possible mode values are 0=icon mode, 1=report mode, 2=small icon mode, 3=list mode.

LISTVIEW SET OVERLAY hDlg, id&, item&, NumExpr

The overlay image specified by NumExpr (1=first, 2=second, etc.) is displayed on top of the image specified by item&. If NumExpr evaluates to zero, or if no IMAGELIST is attached to the LISTVIEW, no overlay is displayed.

LISTVIEW SET STYLEXX hDlg, id&, NumExpr

ListView controls offer a number of optional additional style attributes which are unique and specific to a ListView. This statement allows you to alter the current setting of this special extended style. This special extended style is named STYLEXX to distinguish it from the primary style and extended style specified in CONTROL ADD LISTVIEW. NumExpr defines the new style from any combination of the following extended styles:

%LVS_EX_GRIDLINES	Grid lines added in report mode
%LVS_EX_SUBITEMIMAGES	Icons added to sub-items in report mode
%LVS_EX_CHECKBOXES	Enables checkboxes to items
%LVS_EX_TRACKSELECT	Enables hot track selection
%LVS_EX_HEADERDRAGDROP	Enables drag-drop reordering of columns in report mode
%LVS_EX_FULLROWSELECT	Selection highlights full row in report mode
%LVS_EX_ONECLICKACTIVATE	Notification sent on single click
%LVS_EX_TWOCLICKACTIVATE	Notification sent on double click
%LVS_EX_FLATSB	Enables flat scroll bars
%LVS_EX_REGIONAL	Sets ListView region to icons and text
%LVS_EX_INFOTIP	Listview does InfoTips for you
%LVS_EX_UNDERLINEHOT	Hot items have underlined text
%LVS_EX_UNDERLINECOLD	Non-hot items have underlined text
%LVS_EX_MULTIWORKAREAS	Will not auto-arrange until work areas defined
%LVS_EX_LABELTIP	Listview unfolds partly hidden labels
%LVS_EX_BORDERSELECT	Border selection style instead of highlight
%LVS_EX_DOUBLEBUFFER	Paints via double-buffering and reduces flicker
%LVS_EX_HIDELABELS	Hides labels in Icon and Small Icon mode
%LVS_EX_SINGLEROW	Display a single row
%LVS_EX_SNAPTOGRID	Icons automatically snap to grid
%LVS_EX_SIMPLESELECT	Changes overlay rendering to top right

LISTVIEW SET TEXT hDlg, id&, item&, col&, StrExpr

The text, if any, for the specified data item is replaced by the new text in StrExpr. You must keep in mind that this statement does not create a new item (horizontal row), but changes existing text, if any, to new text. To create a new data item (horizontal row), use LISTVIEW INSERT ITEM instead. The values of item&/col& specify the position of the data item (1=first, 2=second, etc.).

LISTVIEW SET USER hDlg, id&, item&, NumExpr

Each row in a LISTVIEW may have a long integer user value associated with it at the discretion of the programmer. This user value is assigned with LISTVIEW SET USER, and retrieved with LISTVIEW GET USER. The numeric value item& specifies which user value is to be accessed, 1 for the first item, 2 for the second item, etc. The value specified by NumExpr is saved for later retrieval. In addition to these LISTVIEW user values, every DDT control offers an additional eight user values which can be accessed with CONTROL GET USER and CONTROL SET USER.

LISTVIEW SORT hDlg, id&, col& [, options...]

All of the items in a LISTVIEW are sorted, based upon the value of the data in a particular column. The column number (col&) is specified as 1 for the first column, 2 for the second column, etc. The options are one or more comma-delimited parameters which describe the sequence and the nature of the data in the sort-key column:

ASCEND	The items are arranged in ascending sequence.
DESCEND	The items are arranged in descending sequence.
ALPHANUM	The items consist of alphanumeric data. They are sequenced based upon the ASCII value of each byte, so that case is significant. Comparison is limited to the first 255 bytes of each string.
UCASE	The items consist of alphanumeric data. The case of each alphabetic character is not significant. This is accomplished by treating all alphabetic characters as upper case letters. Comparison is limited to the first 255 bytes of each string
NUMERIC	The items start with numeric data, and evaluation is stopped at the first non-numeric character. If numeric characters are not found, the value is assumed to be zero (0). This data may be in any supported PowerBASIC format: integer, floating point, scientific notation, radix format, etc.
MMDDYYYY	A date in the format mm/dd/yyyy which is exactly ten bytes in length. Leading zeros may be replaced by spaces, and delimiters may be any character.
DDMMYYYY	A date in the format dd/mm/yyyy which is exactly ten bytes in length. Leading zeros may be replaced by spaces, and delimiters may be any character.
YYYYMMDD	A date in the format yyyy/mm/dd which is exactly ten bytes in length. Leading zeros may be replaced by spaces, and delimiters may be any character.
YYYYDDMM	A date in the format yyyy/dd/mm which is exactly ten bytes in length. Leading zeros may be replaced by spaces, and delimiters may be any character.

It is important to note that Windows may overwrite USER data when sorting your ListView control. You should avoid the use of the LISTVIEW GET USER and LISTVIEW SET USER statements if you may also execute a LISTVIEW SORT on the same control.

LISTVIEW UNSELECT hDlg, id&, item& [, col&]

The string value specified by item&/col& is set to an unselected state for the LISTVIEW control. The values of item&/col& = 1 for the first item, 2 for the second item, etc. If the optional parameter col& is not given, the default value of 1 is used to unselect the primary data item.

LISTVIEW VISIBLE hDlg, id&, item&

A row is scrolled, if necessary, to ensure that the data specified by item& is visible. The value of item& = 1 for the first row, 2 for the second row, etc.

Restrictions

Under Windows 95/98/ME, a ListView is limited to 32,767 items. In all versions of Windows, the actual string data contained by the ListView is limited only by available memory.