Pin and Close

With the R2 2019 version of our controls, the RadTabControl now allows further customization of its items by providing pinning and closing its tab items out of the box. Every RadTabItem now can be pinned or close with a click of a button.

The purpose of this article is to get you familiar with these functionalities.

Pin/Unpin

The pin button of the RadTabItem is collapsed by default. Pin functionality can be enabled by setting the PinButtonVisibility Visibility property to Visible. To check if given tab item is pinned you can use its IsPinned property. To get the current pinned tab items you can use the PinnedItems collection.

The PinnedItems collection of the RadTabControl is ReadOnlyCollection so no items can be added or removed. You can only use this collection for iteration or to get the current number of the pinned tabs by using its Count() method.

Example 1: Show the Pin button

<Style TargetType="telerik:RadTabItem" > 
    <Setter Property="PinButtonVisibility" Value="Visible"/> 
</Style>

When an item is pinned it will be moved to the lowest index which is not occupied. For example, when no items are pinned, the first pinned item will move it to index 0 of PinnedItems collection. If there are 3 pinned items, they will be in indices: 0,1,2. Pinning another item will move it to position 3.

Similar behavior is observed when an item is unpinned. Unpinning an item will move it to the first index possible which is not pinned. For example if items 0 1 2 are pinned. If you unpin 1 it will go to index 2. Unpinning removes the item from the PinnedItems collection.

The pinned/unpinned item will be brought into the view.

WPF RadTabControl Pinned Unpinned Items

Close

The close button of the RadTabItem is collapsed by default. The button can be shown by setting the CloseButtonVisibility property of the RadTabItem to Visible.

RadTabItem can be close by pressing the mouse middle button while the mouse is over it.

Example 2: Show the Close button

<Style TargetType="telerik:RadTabItem" > 
    <Setter Property="CloseButtonVisibility" Value="Visible"/> 
</Style>

WPF RadTabControl Tab Items with Close Button

To prevent the tab from closing when the middle mouse button is pressed, set the CloseTabsOnMouseMiddleButtonDown property of RadTabControl to False.

Example 3: Disable closing the tabs when the middle mouse button is pressed

<telerik:RadTabControl CloseTabsOnMouseMiddleButtonDown="False" />

Events

RadTabControl provides several events in regards to its pinning and closing functionalities:

Close events

PreviewTabClosed: Occurs before the tab item is closed. The type of the passed event arguments is PreviewTabChangedEventArgs. Closing the tab can be canceled by setting the Cancel property from the event arguments.
TabClosed: Occurs after the tab item is closed. The type of the passed event arguments is TabChangedEventArgs. You can get the current closed tab and its DataContext from the TabItem and DataContext properties from the event arguments.

Pin events

PreviewTabPinned: Occurs before the tab item is pinned. The type of the passed event arguments is PreviewTabChangedEventArgs. Pinning the tab can be canceled by setting the Cancel property from the event arguments.
TabPinned: Occurs after the tab item is pinned. The type of the passed event arguments is TabChangedEventArgs. You can get the currently pinned tab and its DataContext from the TabItem and DataContext properties from the event arguments.
PreviewTabUnpinned: Occurs before the tab item is unpinned. The type of the passed event arguments is PreviewTabChangedEventArgs. Unpinning the tab can be canceled by setting the Cancel property from the event arguments.
TabUnpinned: Occurs after the tab item is unpinned. The type of the passed event arguments is TabChangedEventArgs. You can get the current unpinned tab and its DataContext from the TabItem and DataContext properties from the event arguments.

Commands

RadTabControl exposes its pinned/unpinned functionality through two commands that can be executed on its behalf. These two commands are placed in the static class TabItemCommands.

TogglePin command

When executing the command on a given RadTabItem the item will be pinned/unpinned depending on its current state.

Example 4: Execute the TogglePin command

TabItemCommands.TogglePin.Execute(null,myRadTabItem);

Close command

When executing the command on a given RadTabItem the item will be close.

Example 5: Execute the Close command

TabItemCommands.Close.Execute(null,myRadTabItem);

Notes

Multi-line Tabs with ReorderTabRows (True by default): Pinning items rules are not followed when multiline tabs occur and ReorderTabRows is TRUE (default value). ReorderTabRows makes the selected tab always on the last row so that content is as close as possible. So please consider Pinning items not supported in this case. If you need multiline tabs and pinning please set ReorderTabRows to False.
Drag and Drop for pinned/unpinned items: When the AllowDragReorder property is set to True the user will be able to rearrange the tabs while dragging them. When there are pinned/unpinned tab items this behavior is slightly different. You could rearrange the pinned or unpinned items while performing a dragging operation. Dragging a pinned tab item between unpinned tabs are not allowed.