SAPIEN Blog

The “Spotlight on Controls” series focuses on a single WinForms control in PrimalForms 2011 , details the important Properties, Methods, and Events of the control and demonstrates how to utilize the control. Most of the information about the controls is still applicable to previous versions of PrimalForms.

In Part 1 of the Spotlight on the ListView Control we discussed a number of important properties. Here, in Part 2, we complete our look at the control’s properties and we will also cover some of the more important methods and events.

Important Properties Continued:

Items

This property contains a collection of all the items in the ListView. All items in a ListView are represented by a ListViewItem object:

ListViewItem [System.Windows.Forms.ListViewItem]

Property	Description
Checked	This property indicates whether the item is checked.
Text	This property contains the displayed text of the item.
ToolTipText	This property contains the text shown when the mouse pointer rests on the ListViewItem.
Group	This property points to the group to which the item is assigned. Set this property to any existing Group. All items with an unsigned Group will be show in the “Default” Group.
ImageIndex	This property indicates the index of the image that is displayed for the item.
StateImageIndex	This property indicates the index of the state image (an image such as a selected or cleared check box that indicates the state of the item) that is displayed for the item.
SubItems	This property is a collection containing all subitems of the item. Compatible Views: Details, Tile In the Details view the Subitems will be displayed only if Columns are defined. In the Tile view only the first SubItem will be displayed (below the Item’s text).

Adding Items to the ListView:

You can access the Items Collection Editor via the Designer:

Or via the Property Pane:

The ListViewItem Collection Editor allows you to add / remove Item as well set their properties:

Via the Script Editor:

[ListViewItem] Add ([ListViewItem] value)
Adds an existing ListViewItem to the collection.

[ListViewItem] Add ([String] text)
Creates an item with the specified text and adds it to the collection.

[ListViewItem] Add ([String] text, [Int] imageIndex)
Creates an item with the specified text and image and adds it to the collection.

[ListViewItem] Add ([String] text, [String] imageKey)
Creates an item with the specified text and image and adds it to the collection.

[ListViewItem] Add ([String] key, [String] text, [Int] imageIndex)
Creates an item with the specified key, text, and image and adds an item to the collection.

[ListViewItem] Add ([String] key, [String] text, [String] imageKey)
Creates an item with the specified key, text, and image and adds an item to the collection.

Example Use:

$listitem = $listview1.Items.Add(‘PrimalForms’ , 2)

 

Adding SubItems:

In the cases where you wish to add SubItems to the ListView you can add them using:

Via the ListViewItem Collection Editor:

By clicking on the SubItems property in the ListViewItem Collection Editor, you will be presented with a ListViewSubItem Collection Editor.

The only important property you need to set for a ListViewSubItemis the Text property.

Via the Script Editor:

The SubItems property has the following methods to add ListViewSubItems:

[ListViewSubItem] Add ([ListViewSubItem] item)
Adds an existing ListViewItem.ListViewSubItem to the collection.

[ListViewSubItem] Add ([String] text)
Adds a subitem to the collection with specified text.

[ListViewSubItem] Add ([String] text, [Color] foreColor, [Color] backColor, [Font] font)
Adds a subitem to the collection with specified text, foreground color, background color, and font settings.

Example Use:

$subItem = $listitem.SubItems.Add('Installed')

Important Methods:

Clear

This method removes all items and columns from the ListView.

$listview1.Clear()

BeginUpdate

This method prevents the control from drawing until the EndUpdate method is called. Use this method when you are updating or adding a large amount of items.

$listview1.BeginUpdate()

EndUpdate

This method resumes drawing of the list view control after drawing is suspended by the BeginUpdate method.

$listview1.EndUpdate()

Example use of the BeginUpdate and EndUpdate:

$listview1.BeginUpdate() 
$listview1.Items.Clear(); 
foreach($itemin$array) 
{ 
    [void]$listview1.Items.Add($item.Text)
} 
$listview1.EndUpdate();

 

Important Events:

AfterLabelEdit

This event occurs when the label for an item has been edited by the user. Label editing must be enabled for this event to be called (See LabelEdit property).

AfterLabelEdit event uses the following argument, which is accessible via the $_ variable:

[System.Windows.Forms.LabelEditEventHandler]

Properties	Description
CancelEdit	Gets or sets a value indicating whether the edit has been canceled.
Label	Gets the new text assigned to the label of the ListViewItem.
Item	Gets the zero-based index of the ListViewItem containing the label to edit.

Use this event to react to name changes. For example if the represents a file, you can use this event as a trigger for renaming the file. You should also perform any validation and reject the name change if there is a failure.

$listview1_AfterLabelEdit=[System.Windows.Forms.LabelEditEventHandler]{
    #Event Argument: $_ = [System.Windows.Forms.LabelEditEventArgs]
    if(-not (Validate-FileName$_.Label)) 
    { 
        $_.CancelEdit =$true
    } 
    else 
    { 
        #Rename the file 
    } 
}

BeforeLabelEdit

This event occurs when the user starts editing the label of an item.

This event uses the [System.Windows.Forms.LabelEditEventHandler] argument. See AfterLabelEdit for more information about this argument.

Use this event to prevent users from renaming specific items.

$listview1_BeforeLabelEdit=[System.Windows.Forms.LabelEditEventHandler]{ 
    #Event Argument: $_ = [System.Windows.Forms.LabelEditEventArgs]
    if(-not$listview1.Items[$_.Item].Checked) 
    { 
        $_.CancelEdit =$true 
    } 
}

ColumnClick

This event occurs when the user clicks a column header within the list view control. Typically you will use this event to sort the list by the selected column.

ColumnClick event uses the following argument, which is accessible via the $_ variable:

[System.Windows.Forms.ColumnClickEventArgs]

Properties	Description
Column	Gets the zero-based index of the column that is clicked.

$listview1_ColumnClick=[System.Windows.Forms.ColumnClickEventHandler]{ 
    #Event Argument: $_ = [System.Windows.Forms.ColumnClickEventArgs]
    Write-Host ("Column '{0}' was clicked" -f $this.Columns[$_.Column].Text)
}

See Part 3  for how to sort columns.

ItemActivate

This event occurs when an item is activated. One or more items can be activated by the user, depending on the Activate property. Note: Activating an item is not the same as selecting an item. For example, you may want to display a webpage when the user activates an item in the ListView. Use the SelectedItems or SelectedIndices property to referenced the activated item.

$listview1_ItemActivate={ 
    #TODO: Place custom script here
    Write-Host "Activate Item" $listview1.SelectedItems[0].Text 
}

ItemChecked

This event occurs when the checked property of a ListView item changes.

ItemChecked event uses the following argument, which is accessible via the $_ variable:

[System.Windows.Forms.ItemCheckedEventArgs]

Properties	Description
Item	Gets the ListViewItem whose checked state is changing.

$listview1_ItemChecked=[System.Windows.Forms.ItemCheckedEventHandler]{
    #Event Argument: $_ = [System.Windows.Forms.ItemCheckedEventArgs]
    if($_.Item.Checked)
    { 
        Write-Host "Checked Item: $($_.Item.Text)" 
    } 
    else 
    { 
        Write-Host"Unchecked Item: $($_.Item.Text)" 
    } 
}

SelectedIndexChanged

This event occurs when the SelectedIndices collection changes. Use the event when you want to react to a change in the selection.

$listview1_SelectedIndexChanged={ 
    Write-Host "Selection Changed" 
}

ItemSelectionChanged

This event occurs when the selection state of an item changes. Use this event instead of the SelectedIndexChanged when you want to know the which item was selected or unselected.

ItemSelectionChanged event uses the following argument, which is accessible via the $_ variable:

[System.Windows.Forms.ListViewItemSelectionChangedEventArgs]

Properties	Description
Item	Gets the item whose selection state has changed.
IsSelected	Gets a value indicating whether the item’s state has changed to selected.
ItemIndex	Gets the index of the item whose selection state has changed.

$listview1_ItemSelectionChanged=[System.Windows.Forms.ListViewItemSelectionChangedEventHandler]{
    #Event Argument: $_ = [System.Windows.Forms.ListViewItemSelectionChangedEventArgs]
    if($_.IsSelected)
    {
        Write-Host"Selected: $($_.Item.Text)" 
    } 
    else 
    { 
        Write-Host"UnSelected: $($_.Item.Text)" 
    } 
}

Next: Part 3 –  Sorting Columns and Helper Functions