Add and Customize the Ribbon Gallery Skin Selector

• Jan 23, 2019
• 4 minutes to read

This article explains how to allow end-users to select skins at runtime using the embedded Toolbar and Menu Skin Selector.

Add the Ribbon Gallery Skin Selector

A Ribbon provides an In-Ribbon gallery (SkinRibbonGalleryBarItem objects) to allow end-users to change application skins at runtime. In this gallery, skin items are grouped into “Standard Skins”, “Bonus Skins” and “Theme Skins” categories.

To add a Ribbon skin gallery, right-click a RibbonPageGroup and select “Add Skin Gallery (SkinRibbonGalleryBarItem)”.

Once you add a required skin item, there is no need to manually implement its functionality. Click a gallery item to automatically apply the corresponding skin.

Since a Ribbon skin gallery is an automatically populated in-Ribbon gallery, you can easily access its items and groups to modify them – as explained below.

Hide Specific Items And Groups

The steps below describe how to hide individual skins.

1. Create a string array that contains unwanted skin names. These names can be full (e.g., “Office 2016 Colorful”) or partial (e.g., “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. Define a custom method that will iterate through skin items and hide unwanted ones.

   C#

   
   private void HideSkins(string[] skinsToHide) {
       for(var i = 0; i < skinRibbonGalleryBarItem1.Gallery.Groups.Count; i++) {
           var group = skinRibbonGalleryBarItem1.Gallery.Groups[i];
           if(group == null) {
               continue;
           }
           for(var j = 0; j < group.Items.Count; j++) {
               var item = group.Items[j];
               if(item == null) {
                   continue;
               }
               foreach(var skin in skinsToHide) {
                   if(item.Caption.Contains(skin)) {
                       item.Visible = false;
                   }
               }
           }
       }
   }
   

   VB.NET

   
   Private Sub HideSkins(ByVal skinsToHide() As String)
       For i = 0 To skinRibbonGalleryBarItem1.Gallery.Groups.Count - 1
           Dim group = skinRibbonGalleryBarItem1.Gallery.Groups(i)
           If group Is Nothing Then
               Continue For
           End If
           For j = 0 To group.Items.Count - 1
               Dim item = group.Items(j)
               If item Is Nothing Then
                   Continue For
               End If
               For Each skin In skinsToHide
                   If item.Caption.Contains(skin) Then
                       item.Visible = False
                   End If
               Next skin
           Next j
       Next i
   End Sub
   

3. Use the form or UserControl Load event handler to call your method.

   C#

   
   this.Load += ucRibbon_Load;
   
   void ucRibbon_Load(object sender, EventArgs e) {
       HideSkins(skinsToHide);
   }
   

   VB.NET

   
   Private Me.Load += AddressOf ucRibbon_Load
   
   Private Sub ucRibbon_Load(ByVal sender As Object, ByVal e As EventArgs)
       HideSkins(skinsToHide)
   End Sub
   

To hide an entire skin group, use the code sample below.

C#

void ucRibbon_Load(object sender, EventArgs e) {
    skinRibbonGalleryBarItem1.Gallery.Groups.Remove(skinRibbonGalleryBarItem1.Gallery.Groups.OfType<GalleryItemGroup>()
            .First(x => String.Equals(x.Caption, "Bonus Skins")));
}

VB.NET

Private Sub ucRibbon_Load(ByVal sender As Object, ByVal e As EventArgs)
    skinRibbonGalleryBarItem1.Gallery.Groups.Remove(skinRibbonGalleryBarItem1.Gallery.Groups.OfType(Of GalleryItemGroup)().First(Function(x) String.Equals(x.Caption, "Bonus Skins")))
End Sub

Remove Item Grouping

To remove item grouping, add a new gallery group and populate it with all existing gallery items. Then, you can remove all gallery groups except for your new custom group – as illustrated in the code sample below.

C#

void ucRibbon_Load(object sender, EventArgs e) {
    RemoveGrouping();
}

void RemoveGrouping() {
    GalleryItemGroup group = new GalleryItemGroup() { Caption = "Available Skins" };
    skinRibbonGalleryBarItem1.Gallery.Groups.Insert(0, group);
    foreach(var item in skinRibbonGalleryBarItem1.Gallery.GetAllItems()) {
        skinRibbonGalleryBarItem1.Gallery.Groups[0].Items.Add(item);
    }
    while(skinRibbonGalleryBarItem1.Gallery.Groups.Count > 1)
        skinRibbonGalleryBarItem1.Gallery.Groups.Remove(skinRibbonGalleryBarItem1.Gallery.Groups.Last());
}

VB.NET

Private Sub ucRibbon_Load(ByVal sender As Object, ByVal e As EventArgs)
    RemoveGrouping()
End Sub

Private Sub RemoveGrouping()
    Dim group As New GalleryItemGroup() With {.Caption = "Available Skins"}
    skinRibbonGalleryBarItem1.Gallery.Groups.Insert(0, group)
    For Each item In skinRibbonGalleryBarItem1.Gallery.GetAllItems()
        skinRibbonGalleryBarItem1.Gallery.Groups(0).Items.Add(item)
    Next item
    Do While skinRibbonGalleryBarItem1.Gallery.Groups.Count > 1
        skinRibbonGalleryBarItem1.Gallery.Groups.Remove(skinRibbonGalleryBarItem1.Gallery.Groups.Last())
    Loop
End Sub

Change Captions and Icons Manually

To change captions and glyphs of items within a Ribbon skin gallery, iterate through gallery items and modify GalleryItem.Caption, GalleryItem.Hint, GalleryItem.Image and GalleryItem.HoverImage properties. Optionally, specify the GalleryItem.Description property to set the item subtitle string.

C#

void ucRibbon_Load(object sender, EventArgs e) {
    CustomizeItems(skinRibbonGalleryBarItem1);
}
void CustomizeItems(SkinRibbonGalleryBarItem target) {
    foreach(var item in target.Gallery.GetAllItems()) {
        if(item.Caption == "DevExpress Dark Style") {
            item.Caption = item.Hint = "Default Skin";
            item.Description = "The default skin";
            item.Image = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_16x16.png");
            item.HoverImage = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_32x32.png");
        }
    }
}

VB.NET

Private Sub ucRibbon_Load(ByVal sender As Object, ByVal e As EventArgs)
    CustomizeItems(skinRibbonGalleryBarItem1)
End Sub

Private Sub CustomizeItems(ByVal target As SkinRibbonGalleryBarItem)
    For Each item In target.Gallery.GetAllItems()
        If item.Caption = "DevExpress Style" Then
            item.Caption = "Default Skin"
            item.Image = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_16x16.png")
            item.HoverImage = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_32x32.png")
        End If
    Next item
End Sub

The figure below shows the result.

Change Skin Captions Using a Localizer

You can use Localizer objects instead of renaming skin items manually. See the How To: Localize Bar and Ribbon Skin Items article to learn more.