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]

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]

$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]

$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]

$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

 
Follow @SAPIENTech
 
             

Tags: Controls, ListView, powershell, PrimalForms 2011, WinForm

This entry was posted on Thursday, April 5th, 2012 at 12:31 pm and is filed under PrimalForms, PrimalForms 2011, Spotlight on Controls, Windows PowerShell. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.