Purpose |
Manipulate a LISTVIEW control in order to set/retrieve data. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Syntax |
LISTVIEW DELETE COLUMN hDlg,
id&, col& | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hDlg |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
hLst |
Handle of the ImageList to be used for graphical items. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
id& |
The control identifier assigned with CONTROL ADD LISTVIEW. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
row& |
A horizontal row number. First=1, second=2... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
col& |
A vertical column number. First=1, second=2... | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
NumExpr |
A
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
StrExpr |
A string expression passed as a parameter. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
txtv$ |
A
| ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
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 row (or sub-item) is referenced by a combination of its row number (row&) 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 row numbers (row&) and 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.). LISTVIEW DELETE ITEM hDlg, id&, row& The data item specified by row& is deleted from the LISTVIEW control. The row number (row&) is indexed to 1 (1=first, 2=second, etc.). LISTVIEW FIND hDlg, id&, row&, StrExpr TO datav& Strings in the 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 row&, and ending with the last string in the LISTVIEW. Searching does not wrap to the beginning of the list. The row number (row&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTVIEW starting with the first string, row& 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&, row&, StrExpr TO datav& Strings in the 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 row&, and ending with the last string in the LISTVIEW. Searching does not wrap to the beginning of the list. The row number (row&) is indexed to 1 (1=first, 2=second, etc.). To search the entire LISTVIEW starting with the first string, row& 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 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 number of selected items in the LISTVIEW is retrieved, and assigned to the long integer variable specified by datav&. LISTVIEW GET STATE hDlg, id&, row&, col& TO datav& A data item is tested to see if it is currently selected. The values of row&/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 STYLE 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 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 STYLE. LISTVIEW GET TEXT hDlg, id&, row&, 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 row&/col& specify the position of the data item (1=first, 2=second, etc.). LISTVIEW GET USER hDlg, id&, row& 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 row& 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, width&, 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 width& 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. LISTVIEW INSERT ITEM hDlg, id&, row&, image&, StrExpr A new row is added to this LISTVIEW control. The value row& 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&, row&, col& The string data item specified by row&/col& is chosen as selected text for the LISTVIEW control, and the selected text is scrolled into a visible position. The values of row&/col& = 1 for the first item, 2 for the second item, etc. 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&, row&, NumExpr The image specified by NumExpr (1=first, 2=second, etc.) is displayed next to the item specified by row&. If no IMAGELIST is attached to the LISTVIEW, nothing is displayed. LISTVIEW SET IMAGE2 hDlg, id&, row&, 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:
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&, row&, NumExpr The overlay image specified by NumExpr (1=first, 2=second, etc.) is displayed on top of the image specified by row&. If NumExpr evaluates to zero, or if no IMAGELIST is attached to the LISTVIEW, no overlay is displayed. LISTVIEW SET STYLE 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 extended style. NumExpr defines the new style from any combination of the following extended styles:
LISTVIEW SET TEXT hDlg, id&, row&, 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 row&/col& specify the position of the data item (1=first, 2=second, etc.). LISTVIEW SET USER hDlg, id&, row&, 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 row& 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:
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&, row&, col& The string value specified by row&/col& is set to an unselected state for the LISTVIEW control. The values of row&/col& = 1 for the first item, 2 for the second item, etc. LISTVIEW VISIBLE hDlg, id&, row& A row is scrolled, if necessary, to ensure that the data specified by row& is visible. The value of row& = 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. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
See also |
Dynamic Dialog Tools, CONTROL ADD LISTVIEW, CONTROL SET COLOR, CONTROL SET FONT, IMAGELIST |