ListView class

A ListView is a control that displays data arranged as a rectangular grid of rows and columns. Each row is a selectable item. Each element in the row is called a cell.

Actions

The following actions are possible with list views:

Create one or more titles to identify each column using wb_set_text(), optionally setting their width and alignment.
Clear all column titles calling wb_set_text() with text equal to NULL and item as FALSE or blank.
Create one or more titles to identify each column using wb_set_text().
Clear all items by calling wb_set_text() with text equal to NULL and item as TRUE.
Create one or more rows with one or more cells each, using wb_create_items().
Set the width of one or more columns with wb_set_size().
Assign an icon to a selected cell with wb_set_item_image().
Select a row and get the index of the currently selected row with wb_get_selected().
Delete one or more rows with wb_delete_items().
Change the text of a row or selected cells using wb_set_text().
Retrieve the string value of a cell using wb_get_text().
Show or hide grid lines with wb_set_style() and the WBC_LINES style.

Using list views

The function used to create rows and cells is wb_create_items(). This function can create one or more rows at once by passing an array of arrays as the items parameter. Each element of the second-level array is the value of a cell to be inserted. The function returns the index of the lastly inserted row.

Function wb_set_text() can be used to change the text of a single cell or row or to set the column titles. Use the table below:

text	item	subitem	What it does
string	integer	integer	Sets the text of the cell indexed by item (the row) and subitem (the column).
array of arrays	empty	empty	Sets the text, width and alignment of all columns
array of strings	integer	empty	Sets the text of all cells in the row indexed by item. A NULL element will skip a cell.
`NULL`	`FALSE`	empty	Clears all column titles
`NULL`	`TRUE`	empty	Clears all cells

To set the width and alignment of a ListView column, each element of the array text must be an array. The first parameter is the column title, the second one its width in pixels, and the third is one of the following: WBC_LEFT (the default), WBC_RIGHT or WBC_CENTER. The first column is always right-aligned. If the width is set to -1 (the default), the actual width will be calculated automatically according to the column title length. Please note that zero is a valid width.

To retrieve the text of a cell, row or the whole ListView, use wb_get_text(). If no cells are selected, the function will return a two-dimensional array containing the text of all cells in the control, and the array will end when it reaches the first blank line. If one or more cells are selected, the function will return a two-dimensional array containing the text of the selected cells in the control. Use the following table:

item	subitem	What it retrieves
integer	integer	The text of the cell indexed by item (the row) and subitem (the column).
integer	empty	An array containing the text of all cells in the row indexed by item.
empty	empty	A two-dimensional array containing the text of all cells of the control.

You may assign an image to a cell using function wb_set_item_image(). The parameter item specifies the row index and subitem is the column index.

Example

The code below shows how to create a list view and add some data to it.

// Create a ListView

$list = wb_create_control($mainwin, ListView, "", 5, 30, 540, 200, ID_ITEMLIST,
   WBC_VISIBLE | WBC_ENABLED | WBC_SORT | WBC_LINES | WBC_CHECKBOXES);

// Set the column titles, widths and alignments

wb_set_text($list, array(
   array("Description"),
   array(null, 80),
   array("Cat", 40, WBC_CENTER),
   array("Value", 100, WBC_RIGHT),
));

// Create rows of data

wb_create_items($list, array(
	array("1,000", "Bob", "John", "Peter"),
	array(0, "Sue", "Paul", "Mary"),
	array("200", null, 300/2, pi()),
));

// Set list view images

wb_set_image($list, PATH_RES . "toolbar.bmp", GREEN, 32);
wb_set_item_image($list, 5, 0, 1);
wb_set_item_image($list, 2, 2, 3);

ListView class

Actions

Using list views

Example

See also