Spotlight on the ListView Control – Part 1

April 4th, 2012 by David Corrales
Last updated on February 25th, 2013

 

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.

Last time we took a look at the ContextMenuStrip . This time we will look at the ListView control:

ListView [System.Windows.Forms.ListView]

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

ListView Toolbox Item

Default Event: SelectedIndexChanged

Why use a ListView control?

The ListView is a hybrid display. It is more complex then a ListBox, but also can display data similar to a grid. A ListView control allows you to display a list of items with item text and, optionally, an icon to identify the type of item. For example, you could use the ListView to display icons in a similar fashion to the Window’s File Explorer.

Note: Requires PrimalForms 2011 v2.0.20 and above to utilize some of the following ListView features.

Important Properties:

View

This property indicates how items are displayed in the control. Use this property to set the style or view of the ListView control.

Select from the following views:

LargeIcon
Each item appears as a full-sized icon with a label below it.

LargeIcon View

Details
Each item appears on a separate line with further information about each item arranged in columns. The left-most column contains a small icon and label, and subsequent columns contain sub items as specified by the application. A column displays a header which can display a caption for the column. The user can resize each column at run time.

Details View

SmallIcon
Each item appears as a small icon with a label to its right.

SmallIcon View

List
Each item appears as a small icon with a label to its right. Items are arranged in columns with no column headers.

List View

Tile
Each item appears as a full-sized icon with the item label and subitem information to the right of it. The subitem information that appears is specified by the application. This view is available only on Windows XP and the Windows Server 2003 family. On earlier operating systems, this value is ignored and the ListView control displays in the LargeIcon view.

Tile View

Note: Some properties only pertain to particular views. The compatible views will be listed in each property’s description.

 

Alignment

This property indicates how items are aligned within the ListView.

Compatible Views: SmallIcon, LargeIcon

Default Value: Top

Default
When the user moves an item, it remains where it is dropped.

Top
Items are aligned to the top of the ListView control.

Left
Items are aligned to the left of the ListView control.

SnapToGrid
Items are aligned to an invisible grid in the control. When the user moves an item, it moves to the closest juncture in the grid.

AllowColumnReorder

This property indicates whether the user can reorder column headers in the Details view. Set this property to True, the users the order of the column header, by dragging the header to the desired location.

Compatible Views: Details

Default Value: False

CheckBoxes

This property indicates whether a check box appears next to each item in the control.

Compatible Views: All except Tile

Default Value: False

When CheckBoxes is set to True, use the ItemChecked event to respond to an item’s checked state changes.

CheckBoxes

Columns

This property contains a collection of column headers that are displayed in the Details view.

Compatible Views: Details

You can access the ColumnHeader Collection Editor via the designer:

Edit Columns Designer

Or you can access the ColumnHeader Collection Editor via the Property Pane:

Edit Columns Property Pane

The ColumnHeader Collection Editor allows you to add / remove Column as well as modify their properties:

ColumnHeader Collection Editor

The Columns collection is made up of the following object:

ColumnHeader [System.Windows.Forms.ColumnHeader ]

Property Description
DisplayIndex This property indicates the display order of the column relative to the currently displayed columns
ImageIndex This property indicates the index of the image displayed in the ColumnHeader.
Text This property contains the text displayed in the column header.
TextAlign This property determines the horizontal alignment of the text displayed in the ColumnHeader.
Values (Default: Left):
Left
The object or text is aligned on the left of the control element.

Right
The object or text is aligned on the right of the control element.

Center
The object or text is aligned in the center of the control element.

Width This property determines the width of the column.

Set Width = -1, to adjust the width of the longest item in the column.
Set Width = -2, to auto size to the width of the column heading.
Note: When setting these special values, the control will automatically replace the Width with the calculated value.

You can use the Column’s Add method to add Columns via the script editor:

Add Methods:

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


[ColumnHeader] Add ([String] text)
Creates and adds a column with the specified text to the collection.


[ColumnHeader] Add ([String] text, [int] width)
Creates and adds a column with the specified text and width to the collection.


[ColumnHeader] Add ([String] key, [String] text)
Creates and adds a column with the specified text and key to the collection.


[ColumnHeader] Add ([String] text, [int] width, [HorizontalAlignment] textAlign)
Adds a column header to the collection with specified text, width, and alignment settings.


[ColumnHeader] Add ([String] key, [String] text, [int] width)
Creates and adds a  column with the specified text, key, and width to the collection.


[ColumnHeader] Add ([String] key, [String] text, [int] width, [HorizontalAlignment] textAlign, [int] imageIndex)
Creates and adds a column with the specified key, aligned text, width, and image index to the collection.


[ColumnHeader] Add ([String] key, [String] text, [int] width, [HorizontalAlignment] textAlign, [String] imageKey)
Creates and add s a column with the specified key, aligned text, width, and image key to the collection.

Example Use:

$columnApplication = $listview1.Columns.Add("Application") 
$columnInstalled = $listview1.Columns.Add("Installed")

 

FullRowSelect

This property indicates whether all sub items are highlighted along with the item when selected.

Compatible Views: Details

Default Value: False

Selection without FullRowSelect:

FullRowSelect False

Selection with FullRowSelect:

FullRowSelect True

 

GridLines

This property indicates whether grid lines appear between the rows and columns containing the items and sub items in the control. The grid lines are only shown when in Details view.

Compatible Views: Details

 Gridlines

Groups

This property contains a collection of ListViewGroup objects that are used by the control. Groups are very useful to display items in categories within the ListView.

Note: If there are groups defined and a item has no group set, it will go into the “Default” group.

Compatible Views: All except the List

You can access the Group Collection Editor via the Designer:

 Edit Columns Designer

Or via the Property Pane:

Groups via Property Pane

 

The ListViewGroup Collection Editor allows you to add / remove groups:

ListViewGroup Editor

The Group collection is made up of the following object:

ListViewGroup [System.Windows.Forms.ListViewGroup]

Property Description
Header This property sets the header text for the group.
HeaderAlignment This property sets the alignment of the group header text.

Values (Default: Left):

Left
The object or text is aligned on the left of the control element.

Group Alignment Left

Right
The object or text is aligned on the right of the control element.

Group Alignment Right

Center
The object or text is aligned in the center of the control element.

Group Alignment Center

Adding groups via the Script Editor:

[int] Add ([ListViewGroup] group)
Adds the specified ListViewGroup to the collection.

[ListViewGroup] Add ([String] key, [String] headerText)
Adds a new ListViewGroup to the collection using the specified values to initialize the Name and Header properties

Example Use:

$listview1.Groups.Add("InstallGroup", "Installed")

ShowGroups

This property indicates whether items are displayed in groups.

Compatible Views: Details, LargeIcon, SmallIcon, Tile

Default Value: True

ListView with Groups

HeaderStyle

This property indicated the style of the column headers in the Details view. Use this property when you want to prevent the users from having the option to click on the headers. Typically you would want to sort the items when a user clicks on the header. You can respond to a header click by using the ListView’s ColumnClick event.

Compatible Views: Details

Values (Default: Clickable):

None
The column header is not displayed in report view.

Nonclickable
The column headers do not respond to the click of a mouse.

Clickable
The column headers function like buttons and can carry out an action, such as sorting, when clicked.

HideSelection

This property indicates whether the selected item in the control remains highlighted when the control loses focus.

Compatible Views: All

HotTracking

This property indicates whether the text of an item or subitem has the appearance of a hyperlink when the mouse pointer passes over it.

Enabling hot tracking will cause the Activation property to be set to OneClick and the HoverSelection property to be set to true. In addition, run-time label editing is not allowed when hot tracking is enabled.

Compatible Views: All

Default Value: False

LabelEdit

This property indicates whether the user can edit the labels of items in the control.  Use the BeforeEditLabel and AfterEditLabel events in order react to when a user changes a label.

Compatible Views: All

Default Value: False

LargeImageList

This property contains the ImageList control used by the ListView for images in Large Icon view.  See the Spotlight on the ImageList Control blog article for more information on the ImageList.

Note: The index of the corresponding SmallImageList should be the same as the LargeImageList.

Compatible Views: LargeIcon

SmallImageList

This property contains the ImageList control used by the ListView for images in all views except for the Large Icon view.

Compatible Views: SmallIcon, Detail, List, Tile

 

StateImageList

This property contains the ImageList control used by the ListView for custom states.

Note: If an ImageList is specified in the StateImageList property and the CheckBoxes property is set to true, the images at index positions 0 and 1 in the ImageList are displayed instead of the check box. The image at index position 0 is displayed instead of the unchecked check box, and the image at index position 1 is displayed instead of the checked check box.

Compatible Views: All

 

MultiSelect

This property indicating whether multiple items can be selected. If this property is set to true, use the SelectedItems property to determine which items are selected.

Compatible Views: All

Default Value: True

ShowItemToolTips

This property indicates whether ToolTips are shown for the ListViewItem objects contained in the ListView.

Compatible Views: All

Default Value: False

Sorting

This property indicates the manner in which items are to be sorted.

Default Value: None

None
The items are not sorted.

Ascending
The items are sorted in ascending order.

Descending
The items are sorted in descending order.

Compatible Views: All

SelectedItems

This property contains all the items that are selected in the ListView. Note: Each item is a ListViewItem object, so you will have to use the Text property to display the name. The ListViewItem will be addressed in Part 2.

#Display Selected Items
foreach($itemin$listview1.SelectedItems)
{
Write-Host $item.Text
}

 

Next: Part 2 – Adding Items, Methods and Events

 

 
[Google+]   [Facebook]   [LinkedIn]   [StumbleUpon]   [Digg]   [Reddit]   [Google Bookmark]  

Tags: , , , ,