Skip to end of metadata
Go to start of metadata

This topic discusses the items control model in Intersoft ClientUI controls line up.

An ItemsControl is a type of Control that can contain multiple items. There are generally two types of ItemsControl in Intersoft ClientUI:

The main difference between these two controls is the content model. HeaderedItemsControl contains a header that represents the items while ItemsControl does not contain a header. To learn more about these content model see Content Model Overview.

On this page:

Items and ItemsSource properties

You can use either the Items or the ItemsSource property to define the item collection for your ItemsControl.

ItemsSource

The ItemsSource property of the ItemsControl enables you to use any type that implements IEnumerable as the content of the ItemsControl. ItemsSource is typically used to display a data collection or to bind an ItemsControl to a collection object.

When the ItemsSource property is set, the Items collection is set to read-only and fixed-size. This means that you cannot add items to the collection directly. When ItemsSource is in use, setting the property to null removes the collection and restores usage to Items, which will be an empty ItemCollection.

Items

If you do not want to use an object that implements IEnumerable to populate the ItemsControl, you can add items by using the Items property.

XAML

Item Container types

Each ItemsControl type has a corresponding item container type.

The following table lists the ItemsControl objects in ClientUI controls and their corresponding item containers.

These item container types indicate the control type used as the item of each ItemsControl that you can easily customize using ItemsContainerStyle.To learn more about styling and templating, see Styling and Templating section.

Selection Control

One of the common types of ItemsControl is selection control or selector. This type of control has properties that indicate the current selection such as SelectedIndex, SelectedItem, SelectedValue, SelectedValuePath, SelectedElement which you can bind to a DataContext or using MVVM pattern. To learn more about using MVVM pattern, see MVVM Pattern Overview.

Any changes to one of the properties means that the current selection has changed, and it will synchronize the UI and other related properties automatically.

The base class for selection controls in ClientUI is ISSelectionControl which implements ISelection interface.

The following example shows how these properties working together.

XAML
C#

This sample demonstrates that whenever you change the selection, the SelectedIndex and SelectedItem properties are synchronized automatically and vice versa. When these properties are changed, the UI of the selection control will be updated as well.

Selection Item Control

The item of a selection control is called Selection Item Control. This item control has IsSelected property that indicates whether the particular item is currently selected. Changing this property will also invalidate the whole selection process. This means that it will update the properties of the selection control such as SelectedIndexSelectedItemSelectedValue, etc.

The following example shows how IsSelected property works.

XAML
C#

This sample demonstrates that whenever the selection is changed, the item's IsSelected property is also synchronized. Similar to the previous sample, you can also use IsSelected property to control the selection.

Multiple Selection Control

The base class for multiple selection controls in ClientUI is ISMultipleSelectionControl. This class inherits ISSelectionControl and defines SelectedItems property which you can also bind using MVVM pattern. This property indicates the current selected items and also can be used to define the selected items.

When this property is changed, it means that the current selection has changed. Consequently, it will synchronize all selection related properties, including updating the IsSelected property for each item.

You can change the selection by replacing the SelectedItems property, or adding and removing the items from the current SelectedItems collection.

The following example shows how to work with SelectedItems property.

XAML
C#

This sample demonstrates that when you perform multiple selection, such as by holding Shift or Ctrl key, the SelectedItems property will be updated. You can also change the selected items by changing this SelectedItems property as demonstrated when you click the button.

Dragable ItemsControl

Some of ItemsControl in ClientUI such as UXListBox, UXAccordion, and UXDock, supports built-in drag drop capability thanks to ClientUI Drag-drop Framework.

These controls have similar properties such as implemented in Interactive Panels to enable drag and drop operation. The following are the list of properties that related to drag drop support.

To learn more about this Drag-drop capability, see Drag-drop Framework Overview.

Working with Transformable object

Some of these dragable ItemsControl implements ITransformInfo interface, which allows them to easily transform an object from different ItemsControl to its own type.

Controls that support this transformable object concept are UXListBox, UXAccordion, and UXDock.

The following example shows how transformable object concept works in these controls.

XAML

This example has UXListBoxUXAccordion and UXDock, each of them has an item that can be dragged from one ItemsControl to another. When the item is dropped to another ItemsControl, it will automatically transform those items to underlying item type. The information about the original object remains saved in the items itself which enables the items to convert back to its original type when needed.

Try to move item from UXListBox to UXAccordion and you will see something like the following figure.

The following figure shows the illustration after the item is dropped.

Notice that the text and image are identical, but its not UXListBoxItem control anymore its already transformed into UXAccordionOption control.

If you move the item from UXAccordion to UXDock, you will see something similar to the following figure.

After the item is dropped and the UXDockButton is opened, you can notice that the UXAccordionItem is now transformed to UXDockButton. The items of the UXAccordionItem, which is UXAccordionOption, is appropriately transformed to UXStackItem.

The transformable object concept generally applies the adapter pattern which allows an object to have different kind of presentation based on where the object is placed. This architecture is particularly useful when used together with drag and drop operation. For more information about drag and drop support in ClientUI, see Drag-drop Framework Overview.

Styling and Templating

To perform items styling or templating, the items controls in ClientUI provides several fundamental approaches such as explained in the following sections.

Styling using ItemContainerStyle

Styling using ItemContainerStyle property is the basic way to style the items of ItemsControl. As discussed above each ItemsControl has an item container type, you generally just need to provide the style of the item container type and assign it to ItemContainerStyle property.

The following example shows how to style the item of UXListBox using ItemContainerStyle property.

XAML

Styling using ItemContainerStyleSelector

ItemContainerStyleSelector is used to perform certain validation before applying the style. This approach can be used to alternate style between items, or highlighting certain items based on certain condition and many other scenarios.

To use this approach you need to create a class that inherit from StyleSelector class.

The following example shows how to use StyleSelector to create alternate item style in UXListBox.

XAML
C#

Templating using ItemTemplate

When the ItemsControl is bound to a collection of object, you can use ItemTemplate to control the look and feel of the content.

The following example shows how to perform templating using ItemTemplate property.

XAML

Templating using ItemTemplateSelector

Similar with ItemContainerStyleSelector, you can also create an ItemTemplateSelector by creating a class that inherit from DataTemplateSelector. This template selector allows you to apply different template on different item based on the logic describes in the template selector.

The following example shows how to use DataTemplateSelector to create alternate item template in UXListBox.

XAML
C#