Description

Represents a Windows list view control, which displays a collection of items that can be displayed using one of four different views.

Overview

A ListView allows you to quickly display tabular data. It has four modes of operation:

Structure

The general logical layout of the list view is as follows:

A list view is composed of columns and items. Items are composed of the main subject item and a collection of associated subitems (details) - one for each column defined. Item 0 (zero) can also be referred to as subitem 0. Items are analagous to Rows in a spreadsheet, and SubItems are analagous to Cells although the analogy is not perfect it can be usefull to think of a list view in those terms.

Keyboard Interface

If there is a selected row, the arrow keys will move the selection up or down. PgUp and PgDn down have their usual meanings. If MultiSelect is enabled, holding down the shift key and using the up and down arrow results in multiple rows of data being selected. Holding down the CTRL key while using the arrow keys results in moving the focus bar (dotted rectangle) during a selection and is used to select non-adjacent items. Hitting the space bar while in this mode selects the item. Holding down shift while using PgUp or PgDn down is a convienent way to select large amounts of data.

Mouse Interface

Left click on a row moves the focus and the selection to that row. Left click on a column header automatically sorts the column in reverse alphabetical order (that is to say reverse to how it is currently sorted). Placing the mouse cursor between column headers and left-click-drag allows one to dynamically drag and resize the column. Double click between column headers automatically resizes the header to fit the largest item or subitem in that column.Use the mouse and scrollbars to access columns that may be out of view.

Creating a ListView

The list view is accessed as a regular COM object and inherits most of the properties, methods and behaviors supported by all other Kixforms objects. The following example creates an initially empty listview positioned in the top left corner of the form (0,0) with a width and height of approx. 200 pixels. These are arbitrary default values and should be customized after construction:

$ListView = $Form.Controls.ListView

Working with Columns

A newly created listview has no columns. Use the Columns property to return a reference to the Columns collection. The following example displays the count of the number of columns in the listview.

? "Count = " $ListView.Columns.Count

Use the Add method to create a new column and add it to the collection. The following example creates a new column labeled "Name" that is 50 pixels wide a left aligned.

$= $ListView.Columns.Add("Name",50,0)

The first optional parameter is the heading text that will appear inside the column header. The second parameter is the width (in pixels) of the column. The last optional parameter is the text alignment of the column and is specified as 0=Right 1=Left and 2=Centered. One can also construct a new column and set these attributes later. The following example hangs on to the handle returned from the Columns.Add method and uses it to specify each column property seperately.

$Column = $ListView.Columns.Add $Column.Text = "Name" $Column.Width = 100 $Column.Alignment = 2 ; Centered

Use the Insert method to create a new column and insert it at a specified index. Use the remove method to remove a column. The following example removes the last column in the collection.

$ListView.Columns.Remove($ListView.Columns.Count-1)

Working with Items

A listview control displays a list of items that are defined by the Item class. Use the Items property to return a reference to the Items collection. Use the Add method to create a new item and add it to the collection. The following example adds an item at the next available index. The first optional parameter is the text to display for the item. It returns a handle to the newly created item.

$Item = $ListView.Items.Add("John Doe")

Use the Insert method to create a new item and insert it at a specified index. The following example creates a new item and inserts it at the beginning of the list:

$Item = $ListView.Items.Insert(0,"John Doe")

Use Items(index), where index is the item index number, to return a single item from the collection. The following example sets the item text at index position 5 to a new value.

$ListView.Items(5).Text = "John Doe"

To remove an item from the collection, use the Remove method. To clear all items from the collection, use the Clear method. The following example removes all items from the listview.

$ListView.Items.Clear

Working with SubItems

Each Item can store subitem objects that are defined by the SubItem class. Subitems are displayed when there are columns defined in the listview, and when the View property of the ListView control is set to Details. Typically, subitems contain information that is related to their parent item. For example, if a ListView control displays items that represent orders, each item could display the order number. Subitems could be used to display information such as the product ordered, the quantity of items ordered, and the total price of the items ordered. Unlike Item objects, SubItem objects cannot be edited directly by the user (the user can edit Item objects if the LabelEdit property of the ListView control is set to true).

Use the SubItems collection to access individual subitem data within an item. SubItem(0) refers to the data displayed in the first column, SubItem(1) to the second column, and so on. Use the SubItems property to return a reference to the SubItems collection. The following example creates a ListView with three columns and adds 100 items and populates each with data.

$ListView = $Form.Controls.ListView $ListView.Location = 0,0 $ListView.Size = $Form.ClientSize $= $ListView.Columns.Add("Name") $= $ListView.Columns.Add("Address") $= $ListView.Columns.Add("Phone") For $i = 1 to 100 $Item = $ListView.Items.Add $Item.SubItems(0).Text = "John Doe" $Item.SubItems(1).Text = "74 Maple Drive" $Item.SubItems(2).Text = "905-555-1234" Next

Note that SubItems(0) actually refers back to the main subject item itself, for example, the following two statements produce the exact same result. They both set the text value of $Item to "John Doe".

$Item.Text = "John Doe" $Item.SubItems(0).Text = "John Doe"

Use SubItems(index), where index is the subitem index number, to return a single subitem from the collection. The following example gets the text value of second subitem of the first item in the listview.

$Value = $ListView.Items(0).SubItems(1).Text

Working with SelectedItems

The SelectedItems collection contains all the items in the control that are currently selected. Use the SelectedItems property to return a reference to the SelectedItems collection. If there are no selected items, the SelectedItems property returns an empty collection. The following example dumps the text of each selected item to the console.

If $ListView.SelectedItems.Count > 0 For Each $Item In $ListView.SelectedItems ? "Text = " $Item.Text Next EndIf

This example removes all the SelectedItems from the control.

For Each $Item In $ListView.SelectedItems $Item.Remove Next

Working with the FocusedItem

Use the FocusedItem property to return a reference to the item in the control that currently has the focus. If no item in the control has the focus, FocusedItem returns an empty reference. The following example checks to see if the currently focused item is selected. If it is, a message is displayed to the console.

If $ListView.FocusedItem If $ListView.FocusedItem.Selected ?"The focused item is selected." EndIf EndIf




The CHM file was converted to HTML by chm2web software.