windowsforms-117178-build-an-application-application-skins-add-and-customize-the-ribbon-gallery-skin-selector.md
The Skin List and Skin Gallery allow users to select a skin.
Note
Most applications in the DevExpress Demo Center allow you to select a skin. For example, run the XtraGrid demo and navigate to the Skins ribbon page to change the current skin.
Use the following bar items to add the corresponding UI elements to Ribbon UI: Skin List, Skin Gallery, Skin Palette List, Skin Palette Gallery. Right-click a RibbonPageGroup and invoke the corresponding command to add the Skin List or Skin Gallery at design-time.
A Skin List (SkinDropDownButtonItem) is a drop-down menu that displays application skins.
A Skin Gallery (SkinRibbonGalleryBarItem) is an in-ribbon gallery that displays skins. Skins in the gallery are grouped into categories.
A Skin Palette List (SkinPaletteDropDownButtonItem) allows users to select a color palette for a vector skin.
A Skin Palette Gallery (SkinPaletteRibbonGalleryBarItem) allows users to select a color palette in an embedded or dropdown gallery.
The following code snippet displays skin selectors in the Ribbon UI:
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
namespace DXApplication20 {
public partial class Form1 : RibbonForm {
public Form1() {
InitializeComponent();
skinPageGroup.ItemLinks.Add(new SkinDropDownButtonItem());
skinPageGroup.ItemLinks.Add(new SkinRibbonGalleryBarItem());
colorPalettePageGroup.ItemLinks.Add(new SkinPaletteDropDownButtonItem());
colorPalettePageGroup.ItemLinks.Add(new SkinPaletteRibbonGalleryBarItem());
}
}
}
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Namespace DXApplication20
Partial Public Class Form1
Inherits RibbonForm
Public Sub New()
InitializeComponent()
skinPageGroup.ItemLinks.Add(New SkinDropDownButtonItem())
skinPageGroup.ItemLinks.Add(New SkinRibbonGalleryBarItem())
colorPalettePageGroup.ItemLinks.Add(New SkinPaletteDropDownButtonItem())
colorPalettePageGroup.ItemLinks.Add(New SkinPaletteRibbonGalleryBarItem())
End Sub
End Class
End Namespace
The following code snippet displays pre-designed Ribbon UI commands that correspond to advanced skin settings:
Note
“The Bezier” skin supports the second accent color. Other skins do not support the second accent color
using DevExpress.XtraBars;
using DevExpress.XtraBars.Helpers;
namespace DXRibbonSkinSekector {
public partial class Form1 : DevExpress.XtraBars.Ribbon.RibbonForm {
BarCheckItem bciTrackWindowsAppMode, bciOriginalPalette, bciTrackWindowsAccentColor;
BarButtonItem bbiSystemAccentColor, bbiAccentCustomColor2;
public Form1() {
InitializeComponent();
bciTrackWindowsAppMode = new BarCheckItem();
bciOriginalPalette = new BarCheckItem();
bciTrackWindowsAccentColor = new BarCheckItem();
bbiSystemAccentColor = new BarButtonItem();
bbiAccentCustomColor2 = new BarButtonItem();
advancedOptionsGroup.ItemLinks.Add(bciTrackWindowsAppMode);
advancedOptionsGroup.ItemLinks.Add(bciOriginalPalette);
advancedOptionsGroup.ItemLinks.Add(bciTrackWindowsAccentColor);
advancedOptionsGroup.ItemLinks.Add(bbiSystemAccentColor);
/*
* "The Bezier" skin supports the second accent color.
* Other skins do not support the second accent color.
*/
advancedOptionsGroup.ItemLinks.Add(bbiAccentCustomColor2);
// Initializes corresponding skin settings/selectors.
SkinHelper.InitTrackWindowsAppMode(bciTrackWindowsAppMode);
SkinHelper.InitResetToOriginalPalette(bciOriginalPalette);
SkinHelper.InitTrackWindowsAccentColor(bciTrackWindowsAccentColor);
SkinHelper.InitCustomAccentColor(Ribbon.Manager, bbiSystemAccentColor);
SkinHelper.InitCustomAccentColor2(Ribbon.Manager, bbiAccentCustomColor2);
}
}
}
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Helpers
Namespace DXRibbonSkinSekector
Partial Public Class Form1
Inherits DevExpress.XtraBars.Ribbon.RibbonForm
Private bciTrackWindowsAppMode, bciOriginalPalette, bciTrackWindowsAccentColor As BarCheckItem
Private bbiSystemAccentColor, bbiAccentCustomColor2 As BarButtonItem
Public Sub New()
InitializeComponent()
bciTrackWindowsAppMode = New BarCheckItem()
bciOriginalPalette = New BarCheckItem()
bciTrackWindowsAccentColor = New BarCheckItem()
bbiSystemAccentColor = New BarButtonItem()
bbiAccentCustomColor2 = New BarButtonItem()
advancedOptionsGroup.ItemLinks.Add(bciTrackWindowsAppMode)
advancedOptionsGroup.ItemLinks.Add(bciOriginalPalette)
advancedOptionsGroup.ItemLinks.Add(bciTrackWindowsAccentColor)
advancedOptionsGroup.ItemLinks.Add(bbiSystemAccentColor)
'
' * "The Bezier" skin supports the second accent color.
' * Other skins do not support the second accent color.
'
advancedOptionsGroup.ItemLinks.Add(bbiAccentCustomColor2)
' Initializes corresponding skin settings/selectors.
SkinHelper.InitTrackWindowsAppMode(bciTrackWindowsAppMode)
SkinHelper.InitResetToOriginalPalette(bciOriginalPalette)
SkinHelper.InitTrackWindowsAccentColor(bciTrackWindowsAccentColor)
SkinHelper.InitCustomAccentColor(Ribbon.Manager, bbiSystemAccentColor)
SkinHelper.InitCustomAccentColor2(Ribbon.Manager, bbiAccentCustomColor2)
End Sub
End Class
End Namespace
Do the following to hide individual skins:
Create a string array that contains unwanted skin names. These names can be full (for example, “Office 2016 Colorful”) or partial (for example, “2007”).
Define a custom method that will iterate through skin items and hide unwanted ones.
Use the form or UserControl Load event handler to call your method.
The following code snippet hides the “Bonus Skins” group:
void ucRibbon_Load(object sender, EventArgs e) {
skinRibbonGalleryBarItem1.Gallery.Groups.Remove(skinRibbonGalleryBarItem1.Gallery.Groups.OfType<GalleryItemGroup>()
.First(x => String.Equals(x.Caption, "Bonus Skins")));
}
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
The following code snippet renames and hides gallery groups in SkinDropDownButtonItem:
using System.Linq;
using DevExpress.XtraBars;
using DevExpress.XtraBars.Ribbon;
using DevExpress.XtraBars.Ribbon.Gallery;
using DevExpress.XtraBars.Helpers;
namespace DXApplication20 {
public partial class Form1 : RibbonForm {
SkinDropDownButtonItem skinDropDownButtonItem;
public Form1() {
InitializeComponent();
skinDropDownButtonItem = new SkinDropDownButtonItem(ribbonControl1.Manager);
skinPageGroup.ItemLinks.Add(skinDropDownButtonItem);
}
private void Form1_Load(object sender, System.EventArgs e) {
HideItems(skinDropDownButtonItem);
}
void HideItems(SkinDropDownButtonItem skinItem) {
GalleryControlGallery gallery = ((skinItem.DropDownControl as SkinPopupControlContainer).Controls.OfType<GalleryControl>().FirstOrDefault()).Gallery;
gallery.Groups[0].Caption = "My Custom Caption";
gallery.Groups[1].Visible = false;
gallery.Groups[2].Visible = false;
}
}
}
Imports System.Linq
Imports DevExpress.XtraBars
Imports DevExpress.XtraBars.Ribbon
Imports DevExpress.XtraBars.Ribbon.Gallery
Imports DevExpress.XtraBars.Helpers
Namespace DXApplication20
Partial Public Class Form1
Inherits RibbonForm
Private skinDropDownButtonItem As SkinDropDownButtonItem
Public Sub New()
InitializeComponent()
skinDropDownButtonItem = New SkinDropDownButtonItem(ribbonControl1.Manager)
skinPageGroup.ItemLinks.Add(skinDropDownButtonItem)
End Sub
Private Sub Form1_Load(ByVal sender As Object, ByVal e As System.EventArgs)
HideItems(skinDropDownButtonItem)
End Sub
Private Sub HideItems(ByVal skinItem As SkinDropDownButtonItem)
Dim gallery As GalleryControlGallery = ((TryCast(skinItem.DropDownControl, SkinPopupControlContainer)).Controls.OfType(Of GalleryControl)().FirstOrDefault()).Gallery
gallery.Groups(0).Caption = "My Custom Caption"
gallery.Groups(1).Visible = False
gallery.Groups(2).Visible = False
End Sub
End Class
End Namespace
The following code snippet hides specified groups from SkinPaletteDropDownButtonItem:
void HideSkins2(SkinPaletteDropDownButtonItem skinItem, string[] palettesToHide) {
var groups = (skinItem.DropDownControl as GalleryDropDown).Gallery.Groups;
for(var i = 0; i < groups.Count; i++) {
var group = 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 palette in palettesToHide) {
if(item.Caption.Contains(palette)) {
item.Visible = false;
}
}
if(!group.HasVisibleItems())
group.Visible = false;
}
}
}
Private Sub HideSkins2(ByVal skinItem As SkinPaletteDropDownButtonItem, ByVal palettesToHide() As String)
Dim groups = (TryCast(skinItem.DropDownControl, GalleryDropDown)).Gallery.Groups
For i = 0 To groups.Count - 1
Dim group = 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 palette In palettesToHide
If item.Caption.Contains(palette) Then
item.Visible = False
End If
Next palette
If Not group.HasVisibleItems() Then
group.Visible = False
End If
Next j
Next i
End Sub
To remove item grouping, add a new gallery group and populate it with all existing gallery items. Remove all gallery groups except for your new custom group (see the following code snippet).
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());
}
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
To change captions and glyphs of items within a Ribbon skin gallery, iterate through gallery items and modify the following properties:
GalleryItem.Caption — Gets or sets the item’s caption.
GalleryItem.Hint — Gets a hint associated with the gallery item.
GalleryItem.Description — Gets or sets the item’s description.
GalleryItem.ImageOptions.SvgImage — Gets or sets a vector image. The vector image has priority over the raster image.
GalleryItem.ImageOptions.Image — Gets or sets a raster image. To display a custom raster image, nullify the default vector image.
GalleryItem.ImageOptions.HoverImage — Gets or sets a raster image displayed when the mouse pointer hovers the item.
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";
// We recommend that you use vector images.
item.ImageOptions.SvgImage = SvgImage.FromResources("DXApplication1.Resources.Driving.svg", typeof(Form1).Assembly);
// The vector image has priority over the raster image.
// To assign a raster image, nullify the default vector image.
item.ImageOptions.SvgImage = null;
item.ImageOptions.Image = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_16x16.png");
item.ImageOptions.HoverImage = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_32x32.png");
}
}
}
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"
' We recommend that you use vector images.
item.ImageOptions.SvgImage = SvgImage.FromResources("DXApplication1.Resources.Driving.svg", GetType(Form1).Assembly)
' The vector image has priority over the raster image.
' To assign a raster image, nullify the default vector image.
item.ImageOptions.SvgImage = Nothing
item.ImageOptions.Image = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_16x16.png")
item.ImageOptions.HoverImage = DevExpress.Images.ImageResourceCache.Default.GetImage("office2013/miscellaneous/colors_32x32.png")
End If
Next item
End Sub
The figure below shows the result.
You can use Localizer objects instead of renaming skin items manually. See the Localize Skin Selectors article to learn more.
The following code snippet obtains the active skin name:
string activeSkinName = DevExpress.UserLookAndFeel.Default.ActiveSkinName;
Dim activeSkinName As String = DevExpress.UserLookAndFeel.Default.ActiveSkinName