How to: Create a Custom WinForms Standard Template 如何：创建自定义 WinForms 标准模板

XAF provides two form styles of WinForms applications: Standard and Ribbon. Your application's form style can be selected using the IModelOptionsWin.FormStyle property of the Options node. This example demonstrates how to modify the default template of the Standard form style - create a main menu item and place an Action into it. If your FormStyle is Ribbon, please refer to the How to: Create a Custom WinForms Ribbon Template article instead.

XAF 提供了 WinForms 应用程序的两种形式样式：标准和功能区。可以使用选项节点的 IModelOptionsWin.FormStyle 属性选择应用程序的窗体样式。此示例演示如何修改标准窗体样式的默认模板 - 创建主菜单项并将其放入操作。如果您的 FormStyle 是功能区，请参阅"如何：创建自定义 WinForms 功能区模板"一文。

 

Tip 提示

A complete sample project is available in the DevExpress Code Examples database at http://www.devexpress.com/example=T196002

完整的示例项目可在 DevExpress 代码示例数据库中找到，http://www.devexpress.com/example=T196002

.

Consider the following Action located on the View menu:

请考虑"视图"菜单上的以下操作：

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

 

By default, you can place an Action into an existing predefined menu only. The steps below demonstrate how you can place this Action into a custom location within the menu bar.

默认情况下，只能将 Action 放入现有的预定义菜单中。以下步骤演示如何将此操作放置在菜单栏中的自定义位置。

 

1. Open the Template Gallery for the WinForms application project and add the XAF WinForms Templates | Detail Form Template project item.

2. In the Main Menu bar of the detail form designer, click the [Add] button and choose Menu (BarSubItem). Then, give a name for the new menu, for example, "My Actions".

1. 打开 WinForms 应用程序项目的模板库并添加 XAF WinForms 模板 |详细说明表单模板项目项。
2. 在详细信息窗体设计器的主菜单栏中，单击 [添加] 按钮并选择菜单（订阅项）。然后，为新菜单指定一个名称，例如"我的操作"。

 

Tip 提示

You can create a complex hierarchy of sub-menus using nested BarSubItem items.

您可以使用嵌套的 BarSubItem 项创建子菜单的复杂层次结构。

 

3. Open the newly created menu, click the [Add] button and select Inplace LinkContainer (BarLinkContainerExItem). Name the link container. The primary container is usually named after its menu. Name it "My Actions".

3. 打开新创建的菜单，单击 [添加] 按钮并选择"就地链接容器"（BarLinkContainerExItem）。命名链接容器。主容器通常以其菜单命名。将其命名为"我的操作"。

Tip 提示

You can also add an Action Container to the status bar. In the Status Bar Menu of the detail form designer, click the [Add] button and select Inplace Link Container (BarLinkContainerExItem). Then, specify the caption for the new link container, for example, "My Status Actions".

您还可以将操作容器添加到状态栏。在详细信息窗体设计器的状态栏菜单中，单击 [添加] 按钮并选择"放置链接容器（BarLinkContainerExItem）。"。然后，指定新链接容器的标题，例如"我的状态操作"。

 

 

4. At the bottom part of the designer, focus the barManager control, click its smart tag, then select Run Designer.

4. 在设计器的底部，聚焦 barManager 控件，单击其智能标记，然后选择"运行设计器"。

 

5. As a result, the XAF BarManager Designer (an XAF-specific extension of the Bar Manager Designer) is invoked. In the navigation panel at the left part of the designer, select the XAF Action Controls | Action Containers page. To make an action container from a link container, drag "My Actions" item from the Bar Container Controls list to Action Containers. After that, close the designer.

5. 因此，将调用 XAF BarManager 设计器（条形管理器设计器特定于 XAF 的扩展）。在设计器左侧的导航面板中，选择 XAF 操作控件 |操作容器页。要从链接容器创建操作容器，请将"我的操作"项从"条形容器控件"列表拖动到操作容器。之后，关闭设计器。

Tip 提示

If you want to additionally place an action container to a status bar, drag the "My Status Actions" item from the Bar Container Controls list to Action Containers.

如果要另外将操作容器放置到状态栏，请将"我的状态操作"项从"条形容器控件"列表拖动到操作容器。

 

6. Change the category of the Action that you want to place into the created menu. Use the same value that was specified in step 3 (e.g., My Actions). If your Action is created in code, you can pass the category to the Action's constructor.

6. 更改要放入已创建的菜单中的操作的类别。使用步骤 3 中指定的相同值（例如"我的操作"）。如果操作是在代码中创建的，则可以将类别传递给操作的构造函数。

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

 

Alternatively, you can use the ActionBase.Category property in code or in the Controller designer, or the IModelAction.Category property or the ActionsDesign | Actions | MyAction node in the Model Editor.

或者，您可以在代码或控制器设计器中使用 ActionBase.Category 属性，或者使用 IModelAction.Category 属性或"操作设计"|操作 |模型编辑器中的 MyAction 节点。

Finally, you should replace the default Template with the custom Template. Edit the application project's Program.cs (Program.vb) file and handle the XafApplication.CreateCustomTemplate event.

最后，应将默认模板替换为自定义模板。编辑应用程序项目的Program.cs（程序.vb）文件并处理 Xaf 应用程序.创建自定义模板事件。

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

 

The following image illustrates the result.

下图说明了结果。

Tip 提示

You can localize this custom Template using the approach described in the How to: Localize a WinForms Template topic.

您可以使用"如何：本地化 WinForms 模板"主题中介绍的方法本地化此自定义模板。

 

Note the following when implementing this approach:

• In this example, it is assumed that you use the Tabbed MDI mode MdiShowViewStrategy, which is the default for any XAF solution created from the Solution Wizard. In this mode, the visible bar menu elements are merged from the Detail Form and Main Form templates. In other modes, it may be required to customize the Main Form instead of the Detail Form, or both these templates, depending on your particular scenario. To create a custom Main Form, use the Deprecated Templates | Main Form Template template to create the MainForm1 (the process is similar to the one described above). Then, use the following code of the CreateCustomTemplate event handler.

实现此方法时请注意以下事项：

• 在此示例中，假定您使用 Tabbed MDI 模式 MdiShowView 策略，这是从解决方案向导创建的任何 XAF 解决方案的默认值。在此模式下，可见条形菜单元素从"详细信息窗体"和"主窗体"模板合并。在其他模式下，可能需要自定义主窗体而不是"详细信息窗体"，或者同时自定义这两个模板，具体取决于您的特定方案。要创建自定义主窗体，请使用已弃用模板 |主表单模板模板，用于创建 MainForm1（该过程与上述模板类似）。然后，使用创建自定义模板事件处理程序的以下代码。

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

 

• If users of your application can choose between theRibbon andStandard form styles using the IModelOptionsWin.FormStyle property, then you may need to check this property value in the CreateCustomTemplate event handler before specifying a custom ribbon template. Note that if you access the Application Model, you need to ensure that it is not set to null. For details, refer to the WinApplication.Setup method runs in a separate thread breaking change description.
• 如果应用程序的用户可以使用 IModelOptionsWin.FormStyle 属性在功能区和标准窗体样式之间进行选择，则可能需要在"创建自定义模板"事件处理程序中选中此属性值，然后再指定自定义功能区模板.请注意，如果您访问应用程序模型，则需要确保它不设置为 null。有关详细信息，请参阅 WinApplication.Setup 方法在单独的线程中断更改说明中运行。

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

 

• If your XAF application was created in a version prior to 14.2, and then upgraded, please ensure that the WinApplication.UseOldTemplates property is set to false.
• 如果您的 XAF 应用程序是在 14.2 之前的版本中创建的，然后进行了升级，请确保 WinApplication.UseOldTemplates 属性设置为 false。