How to: Create a Custom WinForms Ribbon Template
- 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
If you use .NET 6+, make sure that the DevExpress.ExpressApp.Win.Design NuGet package is added to the YourSolutionName.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 DevExpress Item | New Item… to invoke the Template Gallery. Select the XAF WinFormsTemplates | Detail Ribbon Form Template item. 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.
Note
XAF Ribbon Control Designer is an XAF-specific extension of the Ribbon Control Designer. Refer to the following topic to learn how to manage ribbon items, ribbon pages, and page groups: Toolbars 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).
Tip
You can also add a Link Container to the status bar. In the Status Bar Menu of the Ribbon Form Designer, right-click StatusMessages 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.
Tip
To create an Action Container from a Link Container in the status bar, drag the corresponding item from the Bar Container Controls list to Action Containers.
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 6+ WinForms & Blazor UI Tutorial: Add a Simple Action.
If your Action is created in code, pass the name of the Action Category specified in the previous step to the Action’s constructor as displayed in the code sample below:
public class MyViewController : ViewController { public MyViewController() { SimpleAction myAction = new SimpleAction(this, "MyAction", "MyActionCategory"); myAction.ImageName = "Action_SimpleAction"; } }Alternatively, you can:
- Specify the ActionBase.Category property in code or in the Controller Designer.
- Customize the ActionDesign | ActionToContainerMapping node in the Model Editor. For more information about this technique, refer to the following topic: How to: Place an Action in a Different Location.
Go to the YourApplicationName.Win project and open the Program.cs (Program.vb) file. Handle the XafApplication.CreateCustomTemplate event to replace the default template with your custom template.
[STAThread] static void Main() { // ... winApplication.CreateCustomTemplate += delegate(object sender, CreateCustomTemplateEventArgs e) { if (e.Context == TemplateContext.View) e.Template = new DetailRibbonForm1(); }; // ... }If your application implements both the Ribbon User Interface and the Standard User Interface, you need to check the IModelOptionsWin.FormStyle property value in the CreateCustomTemplate event handler before you specify your custom template.
When you access the Application Model, ensure that it is not set to
null. For details, refer to the following breaking change description: WinApplication.Setup method runs in a separate thread.[STAThread] static void Main() { // ... winApplication.CreateCustomTemplate += delegate(object sender, CreateCustomTemplateEventArgs e) { if(e.Application.Model != null){ if (((IModelOptionsWin)winApplication.Model.Options).FormStyle == RibbonFormStyle.Ribbon) { // ... } } }; // ... }The following image illustrates the result:
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 Solution Wizard. 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:
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.