KB Article T577264
Visible to All Users

How to migrate a WinForms application to use the Light Style

UPDATED on September 7 2018 (v18.2.1+ is required)

With v18.2, the following controls are used to change a theme in applications with the WinApplication > UseLightStyle property set to True.
IModelOptionsWin > FormStyle = Ribbon:
    * SkinDropDownButtonItem - for a skin selector;
    * SkinPaletteRibbonGalleryBarItem - for a palette selector.
IModelOptionsWin > FormStyle = Standard:
    * SkinDropDownButtonItem - for a skin selector;
    * BarButtonItem with DropDownControl - for a palette selector.

For more information, refer to the Skins (see the "Provide Runtime Skin Selector UI for End-Users"  section) and How to customize Skin Gallery - Remove / rename skins and groups  articles in our WinForms Controls  documentation.

To disable this feature, set the WinApplication.UseSkinSelector property to False.

UPDATED on June 22 2018
Starting with v18.1, the LightStyle feature for DockManager and DocumentManager is enabled by default if the WinApplication.UseLightStyle property is set to true. See the following help articles for details:
    DockManager.Style
    BaseView.Style

Published on Nov 17, 2017
With v17.2, you can use the updated UI in your WinForms applications. The new style layout is much cleaner, as it eliminates excessive borders. Use the WinApplication.UseLightStyle property to enable this feature in existing WinForms apps. If you have custom Nested FrameLookup ControlLookup Form, or Main Form templates, you need to update them to make it possible to use Light Style. If you have a custom FrameTemplateFactory, make sure that it is inherited from DefaultLightStyleFrameTemplateFactory.

This article describes how to manually update custom templates in your existing project. Also, it describes the necessary modification to be introduced in code that sets up properties of controls used in MasterDetailMode = ListViewAndDetailView.
Nested Frame
Add SeparatorControl under the Toolbar and set its properties as shown in the screenshot.

Implement the ISupportBorderStyle and ISeparatorsHolder  interfaces as follows:

C#
using DevExpress.XtraEditors.Controls; using System.Windows.Forms; ... BorderStyles ISupportBorderStyle.BorderStyle { get { return viewSitePanel != null ? viewSitePanel.BorderStyle : BorderStyles.Default; } set { if(viewSitePanel != null) { viewSitePanel.BorderStyle = value; } } } AnchorStyles ISeparatorsHolder.SeparatorAnchors { get { return topSeparatorControl.Visible ? AnchorStyles.Top : AnchorStyles.None; } set { topSeparatorControl.Visible = value.HasFlag(AnchorStyles.Top); } }
Visual Basic
Imports DevExpress.XtraEditors.Controls Imports System.Windows.Forms ... Private Property ViewBorderStyle() As BorderStyles Implements ISupportBorderStyle.BorderStyle Get Return If(viewSitePanel IsNot Nothing, viewSitePanel.BorderStyle, BorderStyles.Default) End Get Set(ByVal value As BorderStyles) If viewSitePanel IsNot Nothing Then viewSitePanel.BorderStyle = value End If End Set End Property Private Property SeparatorAnchors() As AnchorStyles Implements ISeparatorsHolder.SeparatorAnchors Get Return If(topSeparatorControl.Visible, AnchorStyles.Top, AnchorStyles.None) End Get Set(ByVal value As AnchorStyles) topSeparatorControl.Visible = value.HasFlag(AnchorStyles.Top) End Set End Property

Lookup Control
Implement the ILookupPopupFrameTemplateEx interface, which is an extended version of the ILookupPopupFrameTemplateone.

C#
private void OnSearchEnabledChanged() { if(SearchEnabledChanged != null) { SearchEnabledChanged(this, new EventArgs()); } } public event EventHandler<EventArgs> SearchEnabledChanged;
Visual Basic
Private Sub OnSearchEnabledChanged() RaiseEvent SearchEnabledChanged(Me, New EventArgs()) End Sub Public Event SearchEnabledChanged As EventHandler(Of EventArgs) Implements ILookupPopupFrameTemplateEx.SearchEnabledChanged

Call the OnSearchEnabledChanged method at the end of the IsSearchEnabledsetter.

C#
public bool IsSearchEnabled { ... set { ... OnSearchEnabledChanged(); } }
Visual Basic
Public Property IsSearchEnabled() As Boolean Implements ILookupPopupFrameTemplate.IsSearchEnabled ... Set(ByVal value As Boolean) ... OnSearchEnabledChanged() End Set End Property

Lookup Form
Implement the ILookupPopupFrameTemplateEx interface, which is an extended version of the ILookupPopupFrameTemplateone.

C#
private void OnSearchEnabledChanged(object sender, EventArgs e) { if(SearchEnabledChanged != null) { SearchEnabledChanged(this, new EventArgs()); } } public event EventHandler<EventArgs> SearchEnabledChanged;
Visual Basic
Private Sub OnSearchEnabledChanged(ByVal sender As Object, ByVal e As EventArgs) RaiseEvent SearchEnabledChanged(Me, New EventArgs()) End Sub Public Event SearchEnabledChanged As EventHandler(Of EventArgs) Implements ILookupPopupFrameTemplateEx.SearchEnabledChanged

Subscribe to the SearchEnabledChanged event of the Lookup Control in the LookupForm constructor and unsubscribe from it in the LookupForm.Dispose method.

C#
public LookupForm() { ... frameTemplate.SearchEnabledChanged += OnSearchEnabledChanged; } protected override void Dispose(bool disposing) { if(disposing && (components != null)) { ... frameTemplate.SearchEnabledChanged -= OnSearchEnabledChanged; } ... }
Visual Basic
Public Sub New() ... AddHandler _frameTemplate.SearchEnabledChanged, AddressOf OnSearchEnabledChanged End Sub Protected Overrides Sub Dispose(ByVal disposing As Boolean) If disposing AndAlso (components IsNot Nothing) Then ... RemoveHandler _frameTemplate.SearchEnabledChanged, AddressOf OnSearchEnabledChanged End If MyBase.Dispose(disposing) End Sub

Add the SeparatorControl to the top of the form and set its properties as shown in the screenshot.

Implement the ISeparatorsHolder  interface as follows:

C#
AnchorStyles ISeparatorsHolder.SeparatorAnchors { get { return topSeparatorControl.Visible ? AnchorStyles.Top : AnchorStyles.None; } set { topSeparatorControl.Visible = value.HasFlag(AnchorStyles.Top); } }
Visual Basic
Private Property SeparatorAnchors() As AnchorStyles Implements ISeparatorsHolder.SeparatorAnchors Get Return If(topSeparatorControl.Visible, AnchorStyles.Top, AnchorStyles.None) End Get Set(ByVal value As AnchorStyles) topSeparatorControl.Visible = value.HasFlag(AnchorStyles.Top) End Set End Property

Main Form

In the Light Style, the following templates are used for Main Form:
        LightStyleMainForm  - in applications with FormStyle = Standard;
        LightStyleMainRibbonForm  - in applications with FormStyle = Ribbon.
These templates are slightly different from Main Form  and Main Ribbon Form. The main difference is that in the new templates, NavBarControl is added to the Side Panel and the Dock Panel is not used anymore. Create a new custom Light Style template using the Template Gallery and change it according to your needs.

Make the following changes to use updated application theme controls in the custom Main Form template created in v18.1 or earlier.

IModelOptionsWin > FormStyle = Ribbon:
    * Drag the SkinDropDownButtonItem from Toolbox to Ribbon;
    * Drag SkinPaletteRibbonGalleryBarItem from Toolbox to Ribbon;
    * Invoke the Ribbon Designer and click the "XAF Action Controls" -> "Single Choice Action Controls" navigation item;
    * Remove RibbonChooseSkinActionControl;
    * Click the "XAF Action Controls" -> "Simple/Popup Action Controls" navigation item;
    * Drag the SkinDropDownButtonItem to the Action Controls list to create BarConfigureSkinActionControl;
    * Select SkinPaletteRibbonGalleryBarItem for the SkinPaletteBarItem property in the Property Grid;
    * Close the Ribbon Designer and remove RibbonGalleryBarItem from Ribbon.

IModelOptionsWin > FormStyle = Standard:
    * Drag SkinDropDownButtonItem from the Toolbox to Main Menu;
    * Drag BarButtonItem from Toolbox to Main Menu;
    * Invoke the Bar Manager Designer and click the "XAF Action Controls" -> "Single Choice Action Controls" navigation item;
    * Remove BarChooseSkinActionControl;
    * Click the "XAF Action Controls" -> "Simple/Popup Action Controls" navigation item;
    * Drag SkinDropDownButtonItem to the Action Controls list to create BarConfigureSkinActionControl;
    * Select the new BarButtonItem for the SkinPaletteBarItem property in the Property Grid;
    * Close the Bar Manager Designer and remove the old BarButtonItem from Main Menu.

Refer to the following articles for more information:
    How to: Create a Custom WinForms Ribbon Template
    How to: Create a Custom WinForms Standard Template

Layout changes for MasterDetailMode = ListViewAndDetailView
When the WinApplication.UseLightStyle property is set to false, SplitContainerControl is used in ListViewAndDetailView mode. When the WinApplication.UseLightStyle property is set to true, two Side Panels placed inside the Panel are used to display Views in this mode. One SidePanel is used to display the ListView and another to display the Detail View.

Please note that the Flow layout currently is not supported in ListViewAndDetailView mode. Detail Views will be printed and exported using the WYSIWYG approach.

Generally, you don't need to access these controls. To customize the List Editor, use the approach described in the How to: Access the List Editor's Control help article. To customize the Detail View layout, use the approach described in the View Items Layout Customization article.

You can use the following code to set up the minimum and maximum size of the SidePanel:

C#
using DevExpress.ExpressApp; using DevExpress.XtraEditors; using System.Windows.Forms; using System.Linq; using System.Drawing; ... public class CustomizeMasterDetailViewController : ViewController<DevExpress.ExpressApp.ListView> { protected override void OnViewControlsCreated() { base.OnViewControlsCreated(); if(View.Model.MasterDetailMode == MasterDetailMode.ListViewAndDetailView && View.Control is Control) { List<SidePanel> sidePanels = ((Control)View.Control).Controls.OfType<SidePanel>().ToList(); sidePanels[1].MinimumSize = new Size(200, 0); sidePanels[1].MaximumSize = new Size(800, 0); } } }
Visual Basic
Imports DevExpress.ExpressApp Imports DevExpress.XtraEditors Imports System.Windows.Forms Imports System.Linq Imports System.Drawing ... Public Class CustomizeMasterDetailViewController Inherits ViewController(Of DevExpress.ExpressApp.ListView) Protected Overrides Sub OnViewControlsCreated() MyBase.OnViewControlsCreated() If View.Model.MasterDetailMode = MasterDetailMode.ListViewAndDetailView AndAlso TypeOf View.Control Is Control Then Dim sidePanels As List(Of SidePanel) = (CType(View.Control, Control)).Controls.OfType(Of SidePanel)().ToList() sidePanels(1).MinimumSize = New Size(200, 0) sidePanels(1).MaximumSize = New Size(800, 0) End If End Sub End Class

Skins support
The Light Style is not supported in the Flat, Office2003, Style3D, UltraFlat and Windows Theme skins. In these skins, the Layout is not displayed with a minimum of borders on a form.

Comments (2)
MM MM
Maxime MERIAUX 7 years ago

    Hi,

    Using th e WinApplication.UseLightStyle property has a breaking change which is not listed.

    I have a custom controller which is handling the MasterDetailMode.ListViewAndDetailView mode. the View.Control used to be a DevExpress.XtraEditors.SplitContainerControl and has been changed to a Panel…?

    I started to debug but inspecting this object make Visual crash.

    Thanks for your prompt help

    Dennis Garavsky (DevExpress) 7 years ago

      @Maxime: Thanks for your feedback. I've created a separate ticket on your behalf (T578780: Problems when MasterDetailMode = ListViewAndDetailView and UseLightStyle = True). It has been placed in our processing queue and will be answered shortly.

      Disclaimer: The information provided on DevExpress.com and affiliated web properties (including the DevExpress Support Center) is provided "as is" without warranty of any kind. Developer Express Inc disclaims all warranties, either express or implied, including the warranties of merchantability and fitness for a particular purpose. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.

      Confidential Information: Developer Express Inc does not wish to receive, will not act to procure, nor will it solicit, confidential or proprietary materials and information from you through the DevExpress Support Center or its web properties. Any and all materials or information divulged during chats, email communications, online discussions, Support Center tickets, or made available to Developer Express Inc in any manner will be deemed NOT to be confidential by Developer Express Inc. Please refer to the DevExpress.com Website Terms of Use for more information in this regard.