How to: Create a Custom WinForms Ribbon Template

Mar 06, 2026
6 minutes to read

XAF Windows Forms applications implement either the Standard User Interface or the Ribbon User Interface.

To change the user interface type, specify the IModelOptionsWin.FormStyle property of the Application Model’s Options node. For instructions on how to customize a Windows Forms template for the Standard User Interface, see the following topic: How to: Create a Custom WinForms Standard Template.

Note

Ensure that the DevExpress.ExpressApp.Win.Design NuGet package is added to the SolutionName.Win project. This package contains the required design-time functionality based on .NET preview features.

This example demonstrates how to do the following:

Create a custom Windows Forms template for the Ribbon User Interface.
Implement a new Ribbon Page.
Place a custom Action in the new Ribbon Page.

Customize a Detail Form Template

In the Solution Explorer , right-click the YourApplicationName.Win project and choose Add | New Item…. In the invoked dialog, select DevExpress 25.2 Template Kit , specify the item name, and click Add to invoke the Template Kit. Select XAF | XAF WinForms Templates | Detail Ribbon Form Template and click ADD ITEM.
In the invoked Ribbon Form Designer , focus the Ribbon Control, click the smart tag in the top right corner, and click Run Designer.
In the invoked XAF Ribbon Control Designer , choose the Toolbars item in the navigation pane and create a new Ribbon Page Group. You can add it to an existing Ribbon Page or create a custom Page Category, add a new Ribbon Page, and create a new Ribbon Page Group in this Page.
Close the XAF Ribbon Control Designer window. In the Ribbon Form Designer , right-click the new Ribbon Page Group and choose Add Inplace Link Container (BarLinkContainerExItem).
Click the smart tag in the top right corner of the container item. In the displayed property window, set the Caption property to My Actions.
Create an Action Container from the link container. Open the XAF Ribbon Control Designer , choose the XAF Action Controls | Action Containers item in the navigation pane, and drag the My Actions item from the Bar Container Controls list to the Action Containers list.
Select the My Actions item in the Action Containers list and specify the ActionCategory property. For example, set it to MyActionCategory.
Create an Action that is triggered by the button in the Ribbon control. For step-by-step instructions, refer to the following XAF In-Depth .NET WinForms & Blazor UI Tutorial: Add a Simple Action.
Go to the YourApplicationName.Win project and open the Program.cs file. Handle the XafApplication.CreateCustomTemplate event to replace the default template with your custom template.

Tip

To localize a custom Ribbon Template, use the technique described in the following topic: How to: Localize a WinForms Template.

Customize Multiple Templates

This example is based on a default XAF application created with the Template Kit. That application implements the Tabbed View in which every newly invoked View opens as a new tab and all Actions are located in the main window. In this case, XAF merges Detail Ribbon Form and Light Style Main Ribbon Form templates, and it is this merge operation that determines positions of all ribbon elements.

Merging is a complex process. There are times, when merging may position custom Page Groups at the end of the ribbon instead of where you specified in the Ribbon Form Designer. To avoid this behavior, create a custom Light Style Main Ribbon Form template with custom Page Groups identical to those you added to the custom Detail Ribbon Form template.

If your application implements the Multiple or Single Windows SDI View, its Actions can then be located in the main window and in the invoked windows. In such cases, you may need to customize the Light Style Main Ribbon Form template instead of the Detail Ribbon Form template, or you may need to customize both of them at once.

The following code sample shows how to handle the CreateCustomTemplate event when you have to customize both templates:

csharp

winApplication.CreateCustomTemplate += delegate (object sender, CreateCustomTemplateEventArgs e) {
    if (e.Context == TemplateContext.ApplicationWindow) {
        e.Template = new LightStyleMainRibbonForm1();
    }
    else if (e.Context == TemplateContext.View) {
        e.Template = new DetailRibbonForm1();
    }
};

Tip

If your XAF application was created in a version prior to 14.2 and was later upgraded, ensure that the WinApplication.UseOldTemplates property is set to false.