Add and Customize Toolbar Skin Selectors

• Aug 01, 2023
• 4 minutes to read

You can add skin selectors to a toolbar (BarManager) and Ribbon Control to allow users to choose skins at runtime.

Add a Skin Selector to a Toolbar

At design time, click the [Add] button in the toolbar, and select a skin selector from the Skin Item sub-menu.

The following skin selectors are available:

• Skin Menu (SkinBarSubItem) — Displays skin names as a menu.

  

• Skin List (SkinDropDownButtonItem) — Displays skin names as a scrollable list with a built-in search box to locate skins by name.

  

• Skin Palette List (SkinPaletteDropDownButtonItem) — Displays palettes for the currently selected vector skin.

  

You can modify skin selectors in code. To do this, use a skin selector’s BarCustomContainerItem.ItemLinks collection.

When you create skin selectors (SkinBarSubItem, SkinDropDownButtonItem, SkinPaletteDropDownButtonItem, SkinRibbonGalleryBarItem, and SkinPaletteRibbonGalleryBarItem) and add them to a toolbar or Ribbon control in code, ensure that you call the skin selector’s Initialize method.

C#

SkinBarSubItem skinBarSubItem1 = new SkinBarSubItem();
barManager1.Items.Add(skinBarSubItem1);
bar1.ItemLinks.Add(skinBarSubItem1);
skinBarSubItem1.Initialize();

VB.NET

Dim skinBarSubItem1 As New SkinBarSubItem()
BarManager1.Items.Add(skinBarSubItem1)
Bar1.ItemLinks.Add(skinBarSubItem1)
skinBarSubItem1.Initialize()

Tip

Read the following topic for information on how to display pre-designed Ribbon UI commands that correspond to advanced skin settings: Add and Customize the Ribbon Skin List and Skin Gallery.

Hide Skins and Skin Groups

You can hide individual items in a skin selector as follows:

1. Create a string array of skin names to exclude. You can use the full name (for example, “Office 2016 Colorful”) or partial name (for example, “2007”).

   C#

   string[] skinsToHide = { "Seven Classic", "DevExpress Style", "Dark", "2010", "2007", "Sharp" }; 
   

   VB.NET

   Dim skinsToHide() As String = { "Seven Classic", "DevExpress Style", "Dark", "2010", "2007", "Sharp" }
   

2. Create a custom method (HideSkins) that iterates through the skin selector’s items, and remove skins that match values in the array.

   C#

   private void HideSkins(string[] skinsToHide) {
       for(var i = 0; i < skinBarSubItem1.ItemLinks.Count; i++) {
           //Check regular button items
           if(skinBarSubItem1.ItemLinks[i] is BarButtonItemLink) {
               var item = skinBarSubItem1.ItemLinks[i];
               foreach(var skin in skinsToHide) {
                   if(item.Caption.Contains(skin)) {
                       item.Visible = false;
                   }
               }
           }
           //Check buttons nested in the "Bonus Skins" sub-menu
           if(skinBarSubItem1.ItemLinks[i] is BarSubItemLink && skinBarSubItem1.ItemLinks[i].Caption == "Bonus Skins") {
               BarSubItemLink group = (BarSubItemLink)skinBarSubItem1.ItemLinks[i];
               for(var j = 0; j < group.Item.ItemLinks.Count; j++) {
                   var item = group.Item.ItemLinks[j];
                   foreach(var skin in skinsToHide) {
                       if(item.Caption.Contains(skin)) {
                           item.Visible = false;
                       }
                   }
               }
           }
           //Hide theme skins
           if(skinBarSubItem1.ItemLinks[i] is BarSubItemLink && skinBarSubItem1.ItemLinks[i].Caption == "Theme Skins") {
               skinBarSubItem1.ItemLinks[i].Visible = false;
           }
       }
   }
   

   VB.NET

   Private Sub HideSkins(ByVal skinsToHide() As String)
       For i = 0 To skinBarSubItem1.ItemLinks.Count - 1
           'Check Items
           If TypeOf skinBarSubItem1.ItemLinks(i) Is BarButtonItemLink Then
               Dim item = skinBarSubItem1.ItemLinks(i)
               For Each skin In skinsToHide
                   If item.Caption.Contains(skin) Then
                       item.Visible = False
                   End If
               Next skin
           End If
           'Check bonus skins
           If TypeOf skinBarSubItem1.ItemLinks(i) Is BarSubItemLink AndAlso skinBarSubItem1.ItemLinks(i).Caption <> "Theme Skins" Then
               Dim group As BarSubItemLink = CType(skinBarSubItem1.ItemLinks(i), BarSubItemLink)
               For j = 0 To group.Item.ItemLinks.Count - 1
                   Dim item = group.Item.ItemLinks(j)
                   For Each skin In skinsToHide
                       If item.Caption.Contains(skin) Then
                           item.Visible = False
                       End If
                   Next skin
               Next j
           End If
           'Hide theme skins
           If TypeOf skinBarSubItem1.ItemLinks(i) Is BarSubItemLink AndAlso skinBarSubItem1.ItemLinks(i).Caption = "Theme Skins" Then
               skinBarSubItem1.ItemLinks(i).Visible = False
           End If
       Next i
   End Sub
   

3. Call the HideSkins method from the Load event handler.

   C#

   void ucBar_Load(object sender, EventArgs e) {
       HideSkins(skinsToHide);
   }
   

   VB.NET

   Private Sub ucBar_Load(ByVal sender As Object, ByVal e As EventArgs)
       HideSkins(skinsToHide)
   End Sub
   

Change Captions and Icons

Iterate through the skin selector’s ItemLinks collection to change an item caption or glyph.

C#

void ucBar_Load(object sender, EventArgs e) {
    RenameSkins();
}
private void RenameSkins() {
    for(var i = 0; i < skinBarSubItem1.ItemLinks.Count; i++) {
        if(skinBarSubItem1.ItemLinks[i].Caption == "DevExpress Style") {
            BarButtonItem parentItem = (BarButtonItem)skinBarSubItem1.ItemLinks[i].Item;
            parentItem.Caption = "Default Skin";
            parentItem.ImageUri.Uri = "Apply";
        }
    }
}

VB.NET

Private Sub ucBar_Load(ByVal sender As Object, ByVal e As EventArgs)
    RenameSkins()
End Sub
Private Sub RenameSkins()
    For i = 0 To skinBarSubItem1.ItemLinks.Count - 1
        If skinBarSubItem1.ItemLinks(i).Caption = "DevExpress Style" Then
            Dim parentItem As BarButtonItem = CType(skinBarSubItem1.ItemLinks(i).Item, BarButtonItem)
            parentItem.Caption = "Default Skin"
            parentItem.ImageUri.Uri = "Apply"
        End If
    Next i
End Sub

The figure below shows the result:

Change Skin Captions Using a Localizer

You can also use a Localizer object to rename skin items. See the following article to learn more: How To: Localize Bar and Ribbon Skin Items.