How to: Create a Custom WinForms Standard Template

• Oct 19, 2023
• 6 minutes to read

XAF Windows Forms applications implement either the Standard or 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 Ribbon User Interface, see the following topic: How to: Create a Custom WinForms Ribbon Template.

Note

If you use .NET, 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 Standard User Interface.
• Implement a new menu.
• Place a custom Action in the new menu.

Customize a Detail Form Template

1. 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 WinForms Templates | Detail Form Template item. Click Add Item.

   

2. In the invoked Detail Form Designer, click the [Add] button in the Main Menu bar and choose Menu (BarSubItem).

   

   Tip

   You can create a complex hierarchy of sub-menus with nested bar sub-items.

3. In the Main Menu bar, focus the newly added barSubItem1 and click the smart tag in the top right corner. In the displayed property window, set the Caption property to My Actions.

   

4. Click the My Actions item and click [Add] in the displayed menu. Choose Inplace Link Container (BarLinkContainerExItem) in the invoked pop-up menu.

   

5. Focus the newly added Link Container. In the Properties window, set the Caption property to My Actions.

   

   Tip

   You can also add a Link Container to the status bar. In the Status Bar Menu of the Detail Form Designer, click [Add] and select Inplace Link Container (BarLinkContainerExItem).

6. Create an Action Container from the Link Container. In the bottom pane of the Detail Form Designer, focus the barManager control and click the smart tag in the top right corner. In the displayed menu, click Run Designer.

   

7. In the invoked XAF BarManager Designer (an XAF-specific extension of the Bar Manager 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.

8. If your Action is created in code, pass the name of the Action Container to the Action’s constructor as displayed in the code sample below:

   C#

   public class MyViewController : ViewController {
       public MyViewController() {
           SimpleAction myAction = new SimpleAction(this, "MyAction", "My Actions");
           myAction.ImageName = "Action_SimpleAction";
       }
   }
   

   VB.NET

   Public Class MyViewController
       Inherits ViewController
       Public Sub New()
           Dim myAction As New SimpleAction(Me, "MyAction", "My Actions")
           myAction.ImageName = "Action_SimpleAction"
       End Sub
   End Class
   

   Alternatively, you can do the following:

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

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

   C#

   [STAThread]
   static void Main() {
       // ...
       winApplication.CreateCustomTemplate += delegate(object sender, CreateCustomTemplateEventArgs e) {
           if (e.Context == TemplateContext.View) e.Template = new DetailForm1();
       };
       // ...
   }
   

   VB.NET

   <STAThread> _
   Shared Sub Main()
       ' ...
       AddHandler winApplication.CreateCustomTemplate, Sub(sender As Object, e As CreateCustomTemplateEventArgs)
           If e.Context = TemplateContext.View Then
               e.Template = New DetailForm1()
           End If
       End Sub
       ' ...
   End Sub
   

   If your application implements both the Ribbon and the Standard User Interfaces, 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.

   C#

   winApplication.CreateCustomTemplate += delegate(object sender, CreateCustomTemplateEventArgs e) {
       if (e.Application.Model != null){
           if (((IModelOptionsWin)winApplication.Model.Options).FormStyle == RibbonFormStyle.Standard) {
               // ...
           }
       }
   };
   

   VB.NET

   AddHandler winApplication.CreateCustomTemplate, Sub(sender As Object, e As CreateCustomTemplateEventArgs)
       If e.Application.Model IsNot Nothing Then
           If DirectCast(winApplication.Model.Options, IModelOptionsWin).FormStyle = RibbonFormStyle.Standard Then
               ' ...
           End If
       End If
   End Sub
   

   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 invoked View opens in a new tab and all Actions are located in the main window. In this case, XAF merges the Detail and Main Form templates, and it is this merge operation that determines positions for all Main Menu bar elements.

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

If your application implements the Multiple or Single Window SDI View, its menus can be located in the main window and the invoked windows. In such cases, you may need to customize the Light Style Main Form template instead of the Detail Form template, or you may need to customize both templates.

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

C#

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

VB.NET

AddHandler winApplication.CreateCustomTemplate, Sub(sender As Object, e As CreateCustomTemplateEventArgs)
    If e.Context = TemplateContext.ApplicationWindow Then
        e.Template = New MainForm1()
    ElseIf e.Context = TemplateContext.View Then
        e.Template = New DetailForm1()
    End If
End Sub

Tip

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