Not logged in▾
Log In Register
Forgot Password Resend Validation E-mail
In This Article

Columns (TreeListView)

The TreeListView control supports one or more columns of cells that can be displayed within each item (row). Columns can be resized, reordered, hidden, frozen, and much more.

Columns are created by adding TreeListViewColumn instances to the TreeListView.Columns collection. Properties set on the column instance affect all cells within that column.

Header and Cell Appearance

Header Appearance

For a basic text column header, simply set the TreeListViewColumn.Header property to a text value.

If you need to display additional content such as images, you can set the HeaderTemplate property to a custom DataTemplate. The HeaderTemplateSelector property can be used if you have a DataTemplateSelector instance for multiple columns that is responsible for supplying a DataTemplate for each column based on the column's Header content.

The TreeListViewColumnHeader control that is used to render the chrome of a column header can have an additional style applied via the HeaderContainerStyle property. This allows you to customize the appearance of the header chrome.

The HeaderHorizontalAlignment property lets you set the horizontal alignment of content within the header cell. This is useful in cases such as numeric columns where you may wish to right-align text.

The HeaderCellPadding property controls the amount of padding between the header cell's border and its content.

The HeaderCellBorderThickness property sets the thickness of the border around the header cell.

Cell Appearance

Each column has TreeListViewColumn.CellTemplate and CellTemplateSelector properties that can be set to generate templated content for each cell within that column. See the Getting Started topic for some examples of setting the cell template properties.

The CellHorizontalAlignment and CellVerticalAlignment properties let you set the horizontal and vertical alignments of content within the item cells. This is useful in cases such as numeric columns where you may wish to right-align text. The default horizontal alignment is Stretch and the default vertical alignment is Center.

The CellPadding property controls the amount of padding between each item cell's border and its content.

The CellBorderThickness property sets the thickness of the border around each item cell.

Widths

A column's width is specified via the TreeListViewColumn.Width property. This property accepts a GridLength value and effectively works the same as a Grid panel's column width specification where a value can be a specific pixel length, "Auto", or can be a star (*) sized length.

In the case of auto and star-sized columns, the MinWidth and MaxWidth values are also examined. These properties set minimum and maximum values for any calculated widths.

The current pixel width of the column is returned by the ActualWidth property.

Pixel Width

Pixel width columns will always render at the specified width value.

Here's an example of specifying a pixel width for a column:

<grids:TreeListView>
	<grids:TreeListView.Columns>
		<grids:TreeListViewColumn Header="Name" Width="150" />
		<grids:TreeListViewColumn Header="Description" Width="250" />
	</grids:TreeListView.Columns>
</grids:TreeListView>

Auto Width

Auto width columns will auto-size to their content. The AutoWidthMode property governs whether the auto-size includes header-only, items-only, or both (the default). It can be set to another TreeListViewColumnAutoWidthMode value to alter this behavior. It is common to set minimum and/or maximum width values on these sorts of columns.

Here's an example of specifying an auto width (which is also the default) for a column, ensuring it is at least 50px, and indicating that only item cells should be used for auto-width calculation:

<grids:TreeListView>
	<grids:TreeListView.Columns>
		<grids:TreeListViewColumn Header="Name" Width="Auto" MinWidth="50" AutoWidthMode="ItemsOnly" />
		<grids:TreeListViewColumn Header="Description" Width="250" />
	</grids:TreeListView.Columns>
</grids:TreeListView>

Star Width

Star-sized columns fill the remaining available space. It is generally a good idea to set minimum and/or maximum width values on these sorts of columns.

Here's an example of specifying star-sized widths for columns (the second column will be twice as wide as the first):

<grids:TreeListView>
	<grids:TreeListView.Columns>
		<grids:TreeListViewColumn Header="Name" Width="*" MinWidth="50" />
		<grids:TreeListViewColumn Header="Description" Width="2*" MinWidth="50" />
	</grids:TreeListView.Columns>
</grids:TreeListView>

Resizing

The TreeListView.CanColumnsResize property (defaults to true) is a global property that indicates whether columns can resize by default. This value can be overridden on an instance basis by setting the TreeListViewColumn.CanResize property to a non-null value.

When a column is allowed to resize, the end user can click and drag a gripper on the right side of the column's header to resize it. Note that this feature is only available for star-sized columns when there is another visible star-sized column after it in the same control.

The SizeToFitCommand property returns a command that can be wired up to menu items to size the column to fit its visible contents.

The TreeListView.ColumnsResized event is raised after the end user resizes columns.

Reordering

The TreeListView.CanColumnsReorder property (defaults to false) is a global property that indicates whether columns can be reordered by default. This value can be overridden on an instance basis by setting the TreeListViewColumn.CanReorder property to a non-null value.

When a column is allowed to be reordered, the end user can click and drag the column header to a new location. Drop indicators will show where the drop will occur.

The TreeListView.ColumnReordered event is raised after the end user reorders a column.

Visibility

A column's visibility can be controlled via the TreeListViewColumn.IsVisible property. The TreeListView.ColumnIsVisibleChanged event is raised after a column's visibility changes.

The TreeListView.CanColumnsToggleVisibility property (defaults to false) is a global property that indicates whether columns can toggle their visibility by default. This value can be overridden on an instance basis by setting the TreeListViewColumn.CanToggleVisibility property to a non-null value.

When a column is allowed to have its visibility toggled, the end user can right-click the column header to show a context menu (see a section below for more on column header context menus) and the default context menu provides an option for toggling visibility.

The ToggleVisibilityCommand property returns a command that can be wired up to menu items to toggle the visibility of the column.

Frozen Columns

Frozen columns are one or more columns that appear fixed to the left side of the TreeListView control and are outside of the scrollable portion of the control.

Set the TreeListView.FrozenColumnCount to a value larger than zero to indicate the number of columns to freeze. Make sure the columns you intend to freeze are the first columns in the Columns collection. The count doesn't examine the current visibility state of the columns, only their index in the collection.

Specifying the Expansion Column

Set the TreeListView.ExpansionColumnIndex property to the index of the column that should contain the expander buttons and be indented based on nesting level. This property defaults to 0, meaning use the first column.

The index doesn't examine the current visibility state of the columns, so it is possible to hide the expansion column. It's good practice to set the CanToggleVisibility to false on the expansion column index if you are enabling column visibility toggling in general.

Handling Column Header Taps

When a column header is tapped and is not being dragged at the time, the TreeListView.ColumnHeaderTapped event is raised. Handle this event to take some appropriate action, such as sorting items by the values presented in that column.

Column Header Context Menus

When the TreeListView.IsDefaultColumnHeaderContextMenuEnabled property is set to true (the default), a default context menu will be generated when a column header is right-clicked. The default context menus has size-to-fit options and column visibility options, all based on if the related features are enabled.

If you are using column header templates instead of setting the TreeListViewColumn.Header properties to string values, be sure to set the Title property to a string that describes the column title. This string will be used in the default column header context menu and/or other UI.

The TreeListView.ColumnHeaderMenuRequested event is raised immediately before the menu is displayed. This allows you to customize the menu as needed with custom logic or prevent it from showing at all.

Size-to-Fit

The TreeListViewColumn.SizeToFit method can be called to size a column to its visible contents based on the AutoWidthMode setting.

A companion SizeToFitCommand property is available, returning a command that can be used in menu items to call the SizeToFit method.

Grid Lines

While column headers have grid lines by default due to the TreeListViewColumn.HeaderCellBorderThickness property being "0,0,1,1", item cells don't have grid lines by default.

Set the TreeListViewColumn.CellBorderThickness property to "0,0,1,1" to enable grid lines around the item cells too.

Column Index

The index of the column within its owner control can be retrieved via the TreeListViewColumn.Index property.

Sort Direction

If a custom external sorting mechanism is used, the TreeListViewColumn.SortDirection property can display a glyph indicating ascending or descending sorting is active for the column. The property is nullable and can be set to a null reference to remove the sort glyph.

Handle the TreeListView.ColumnHeaderTapped event to know when a column header is clicked, so that you can programmatically alter the SortDirection property, which updates the sort arrow glyph.

The column's Tag property can store custom data, such as the name of the property to use when sorting the column. Then tell the item adapter about how to sort items so that its TreeListBoxItemAdapter.GetChildren returns items in appropriate sorted order. Finally, call TreeListView.InvalidateChildren on the control's RootItem to refresh the tree with the same items source.

Alternatively, set the TreeListView.ItemsSource property to a new collection that has its items already sorted appropriately.

Important Note on Data Bindings in Column Properties

Since the TreeListViewColumn class isn't a UI element, bindings specified in its properties may fail with a data error. Please see the Troubleshooting topic for more information on the problem, including an example and a workaround.