Skip to main content
.NET 6.0+

How to: Create a Custom WinForms Standard Template

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

    Template Gallery, DevExpress

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

    Add a Bar Menu, DevExpress

    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.

    Bar Menu Properties, DevExpress

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

    Add a Bar Link Container, DevExpress

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

    Bar Link Container Properties, DevExpress

    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.

    Run XAF BarManager Designer, DevExpress

  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.

    Create an Action Container, DevExpress

    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:

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

    Alternatively, you can do the following:

  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.

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

    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.

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

    The following image illustrates the result.

    Windows Forms Application with Customized Standard Template, DevExpress

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:

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();
    }
};

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.

See Also