How to: Create a Custom WinForms Ribbon Template 如何：创建自定义 WinForms 功能区模板

This example demonstrates how to modify the default ribbon template - create a ribbon page group and place an Action into it.

此示例演示如何修改默认功能区模板 - 创建功能区页面组并将 Action 放入其中。

 

XAF provides two form styles of WinForms applications: Ribbon and Standard. 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 ribbon template - create a ribbon page group and place an Action into it. If your FormStyle is Standard, please refer to the How to: Create a Custom WinForms Standard Template article instead.

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

Tip 提示

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

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

.

Consider the following Action located in the View category:

请考虑位于"视图"类别中的以下操作：

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

RibbonTemplate_01

    

 

By default, you can place this Action into existing predefined categories only. The steps below demonstrate how you can place this Action into a custom location within the ribbon control.

默认情况下，只能将此操作放入现有的预定义类别中。以下步骤演示如何将此操作放置在功能区控件中的自定义位置。

 

1. In the Solution Explorer, right-click the WinForms application project and choose Add DevExpress Item | New Item... to invoke Template Gallery. Then select the XAF WinForms Templates | Detail Ribbon Form Template project item and press Add Item.

1. 在解决方案资源管理器中，右键单击 WinForms 应用程序项目并选择"添加 DevExpress 项目 |新项目...以调用模板库。然后选择 XAF WinForms 模板 |详细说明功能区表单模板项目项目，然后按"添加项"。

 

2. In the ribbon form designer, focus the ribbon control, click the smart tag in the top right corner and then click Run Designer.

2. 在功能区窗体设计器中，聚焦功能区控件，单击右上角的智能标记，然后单击"运行设计器"。

 

3. In the invoked XAF Ribbon Control Designer, create a Ribbon Page Group. You can add it into an existing Ribbon Page, or add a new page to the default or custom Page Category.

3. 在调用的 XAF 功能区控制设计器中，创建功能区页面组。您可以将其添加到现有功能区页面，或将新页面添加到默认或自定义页面类别。

 

Note 注意

XAF Ribbon Control Designer is an XAF-specific extension of the Ribbon Control Designer. Refer to the Ribbon Items Page topic to learn how to manage ribbon items, ribbon pages and page groups.

XAF 功能区控制设计器是功能区控制设计器的 XAF 特定扩展。请参阅功能区项目页面主题，了解如何管理功能区项目、功能区页面和页面组。

 

4. Close the XAF Ribbon Control Designer window. In the ribbon form designer, right-click the newly created Ribbon Page Group and select Inplace Link Container (BarLinkContainerExItem).

4. 关闭 XAF 功能区控制设计器窗口。在功能区窗体设计器中，右键单击新创建的功能区页面组并选择"就地链接容器（BarLinkContainerExItem）。"。

 

Tip 提示

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

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

 

5. Set the link container's Caption to My Actions.

5. 将链接容器的标题设置为"我的操作"。

 

6. Open XAF Ribbon Control Designer again. Choose XAF Action Controls | Action Containers in the navigation panel. To make an action container from a link container, drag "My Actions" item from the Bar Container Controls list to Action Containers.

6. 再次打开 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.

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

 

7. In the property grid to the right, specify the ActionCategory for the created Action Container. For example, set it to MyActionCategory.

7. 在右侧的属性网格中，为创建的操作容器指定操作类别。例如，将其设置为"我的操作类别"。

 

8. Change the category of the Action that you want to place into the created ribbon page group. Use the same value that was specified in the previous step (e.g., MyActionCategory). If your Action is created in code, you can pass the category to the Action's constructor

8. 更改要放入已创建的功能区页面组中的操作的类别。使用上一步中指定的相同值（例如，MyActionCategory）。如果操作是在代码中创建的，则可以将类别传递给操作的构造函数

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

 

Alternatively, you can use the ActionBase.Category property in code or in the Controller designer, or customize the ActionDesign | ActionToContainerMapping node in the Model Editor (see Place an Action in a Different Location).

或者，您可以在代码或控制器设计器中使用 ActionBase.Category 属性，或者自定义 ActionDesign |在模型编辑器中操作到容器映射节点（请参阅将操作放在其他位置）。

 

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

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

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

 

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 ribbon elements are merged from the Detail Ribbon Form and Main Ribbon Form templates. In other modes, it may be required to customize the Main Ribbon Form instead of the Detail Ribbon Form, or both these templates, depending on your particular scenario. Here is the code of the CreateCustomTemplate event handler for a case when you customize both templates.

 

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

 

• 在此示例中，假定您使用 Tabbed MDI 模式 MdiShowView 策略，这是从解决方案向导创建的任何 XAF 解决方案的默认值。在此模式下，可见功能区元素从"详细信息功能区窗体"和"主功能区窗体"模板合并。在其他模式下，可能需要自定义主功能区窗体，而不是"详细信息功能区窗体"，或同时自定义这两个模板，具体取决于您的特定方案。下面是自定义两个模板时案例的 CreateCustomTemplate 事件处理程序的代码。

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

 

• If users of your application can choose between the Ribbon and Standard 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.

• 如果应用程序的用户可以使用 IModelOptionsWin.FormStyle 属性在功能区和标准窗体样式之间进行选择，则可能需要在"创建自定义模板"事件处理程序中选中此属性值，然后再指定自定义功能区模板.

 

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.

请注意，如果您访问应用程序模型，则需要确保它不设置为 null。有关详细信息，请参阅 WinApplication.Setup 方法在单独的线程中断更改说明中运行。

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

 

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