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]
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)" } }
2 comments on “Spotlight on the ListView Control – Part 2”
Comments are closed.