## 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);

# See also

wb_set_text
wb_create_items
wb_delete_items
Control classes