Skip to main content

Add and Customize Toolbar Skin Selectors

  • 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.

Skins - Add Skin Items Design-Time - Bars

The following skin selectors are available:

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

    SkinBarSubItem

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

    SkinDropDownButtonItem

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

    SkinPaletteDropDownButtonItem

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.

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

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”).

    string[] skinsToHide = { "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.

    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;
            }
        }
    }
    
  3. Call the HideSkins method from the Load event handler.

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

Change Captions and Icons

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

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";
        }
    }
}

The figure below shows the result:

Skins - Custom Bar Skin Subitem 1

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.