Add an Action with Option Selection 添加具有选项选择的按钮

In this lesson, you will learn how to create an Action with support for option selection. A new View Controller will be implemented and a SingleChoiceAction will be added to it. Via this Action, the Task.Priority and Task.Status properties will be set to the value selected by an end-user.

在本课中，您将学习如何创建支持选项选择的按钮。将实现一个新的视图控制器，并将向其添加一个单选按钮。通过此操作，"任务.优先级"和"任务.状态"属性将设置为最终用户选择的值。

Note 注意

Before proceeding, take a moment to review the following lessons.

在继续之前，请花点时间复习以下课程。

• Add a Simple Action
• Add an Action that Displays a Pop-up Window

• Add a new View Controller to the MySolution.Module project, as described in the Add a Simple Action lesson. Name it TaskActionsController.

• Right-click the MySolution.Module | Controllers | TaskActionsController.cs (TaskActionsController.vb) file and choose View Designer to invoke the Designer. Within the DX.19.2: XAF Actions Toolbox tab, navigate to SingleChoiceAction and drag it to the Designer. In the SingleChoiceAction's Properties window, set the Name and ID properties to "SetTaskAction", the Caption property to "Set Task" and the Category property to "Edit". Set the ItemType property to "ItemIsOperation".

• 添加简单按钮

• 添加显示弹出窗口的操作

• 向 MySolution.Module 项目添加新的视图控制器，如"添加简单操作"一课中所述。将其命名为任务操作控制器。

• 右键单击"我的解决方案"模块 |控制器 |TaskActionsController.cs（TaskActions控制器.vb）文件，然后选择视图设计器来调用设计器。在 DX.19.2：XAF 操作工具箱选项卡中，导航到"单选操作"并将其拖动到设计器。在"单选操作的属性"窗口中，将"名称"和"ID"属性设置为"SetTaskAction"，将"标题"属性设置为"设置任务"，将"类别"属性设置为"编辑"。将 ItemType 属性设置为"ItemIs 操作"。。

  

  Note 注意

  • The ActionBase.Category property specifies the Action group to which the current Action belongs. All Actions within a single group are displayed together in a UI.
  • The SingleChoiceAction.ItemType property specifies a display mode for the Action's items. With the "ItemIsOperation" value set to this property, the Action's items will not be displayed by check box items, as they would be if you set the "ItemIsMode" value.
  • ActionBase.Category 属性指定当前操作所属的操作组。单个组中的所有操作都显示在 UI 中。
  • "单选择操作.ItemType"属性指定操作项的显示模式。将"ItemIsAction"值设置为此属性后，操作项将不会按复选框项显示，就像设置"ItemIsMode" 值时一样。

   

• To activate the TaskActionsController for DemoTask objects only, set the Controller's ViewController.TargetObjectType property to MySolution.Module.BusinessObjects.DemoTask.

• 要仅激活演示任务对象的任务操作控制器，请将控制器的视图控制器.TargetObjectType 属性设置为 MySolution.module.BusinessObjects.DemoTask。

  

• To populate the Action with items, fill the Action's ChoiceActionBase.Items collection in the Controller's constructor.

• 要用项填充操作，请填充控制器构造函数中的操作选择操作Base.项集合。

using DevExpress.ExpressApp.Utils;
using DevExpress.Persistent.Base.General;
using MySolution.Module.BusinessObjects;
//...
public partial class TaskActionsController : ViewController {
   private ChoiceActionItem setPriorityItem;
   private ChoiceActionItem setStatusItem;
   public TaskActionsController() {
      InitializeComponent();
      SetTaskAction.Items.Clear();
      setPriorityItem = 
         new ChoiceActionItem(CaptionHelper.GetMemberCaption(typeof(DemoTask), "Priority"), null);
      SetTaskAction.Items.Add(setPriorityItem);
      FillItemWithEnumValues(setPriorityItem, typeof(Priority));
      setStatusItem = 
         new ChoiceActionItem(CaptionHelper.GetMemberCaption(typeof(DemoTask), "Status"), null);
      SetTaskAction.Items.Add(setStatusItem);
      FillItemWithEnumValues(setStatusItem, typeof(TaskStatus));
   }
   private void FillItemWithEnumValues(ChoiceActionItem parentItem, Type enumType) {
      foreach(object current in Enum.GetValues(enumType)) {
         EnumDescriptor ed = new EnumDescriptor(enumType);
         ChoiceActionItem item = new ChoiceActionItem(ed.GetCaption(current), current);
         item.ImageName = ImageLoader.Instance.GetEnumValueImageName(current);
         parentItem.Items.Add(item);
      }
   }
}

• The code above organizes items from the Action's Items collection as a tree. The first level is formed from the items whose captions correspond to the DemoTask.Priority and DemoTask.Status property names. The second level is formed from the Priority and Status enumeration values. The first-level item captions are returned by the CaptionHelper object; and the second-level item captions are returned by an EnumDescriptor object. This is useful when the Priority and Status properties and corresponding enumeration values are localized via the Application Model.

• 上面的代码将操作的"项"集合中的项组织为树。第一个级别由标题对应于 DemoTask.优先级和演示任务.状态属性名称的项目组成。第二个级别由"优先级"和"状态"枚举值组成。第一级项目标题由标题帮助器对象返回;第二级项目标题由枚举描述器对象返回。当通过应用程序模型本地化优先级和状态属性和相应的枚举值时，这非常有用。

• Note 注意

  If you create an Action's Items in the controller's constructor, they will be created once for each Window. This may be advantageous, for example, if the window's View is often changed (e.g., if this is the main window and the Multiple Document Interface (MDI) mode is not turned on). Alternatively, you can add Items in the overridden OnActivated method. In this instance, Items will not be created until the required View is shown, but will be created each time this View is displayed.

  如果在控制器的构造函数中创建操作项，则每个窗口将创建它们一次。例如，如果窗口的视图经常更改（例如，如果这是主窗口，并且多文档接口 （MDI） 模式未打开，则这可能更有利。或者，您可以在重写的 On 已激活方法中添加项目。在这种情况下，在显示所需的视图之前不会创建项目，但每次显示此视图时都会创建项目。

  The code snippet below sets the images associated with the Priority and TaskStatus enumeration values for the SetTask Action's items. Note that the TaskStatus enumeration is declared in the Business Class Library, and already has images assigned to its values. To assign images to the Priority enumeration values you declared in the DemoTask.cs (DemoTask.vb) file, decorate them with the ImageNameAttribute attribute.

         下面的代码段设置与 SetTask Action 项的优先级和任务状态枚举值关联的图像。请注意，任务状态枚举在业务类库中声明，并且已经具有分配给其值的图像。要将图像分配给在DemoTask.cs （DemoTask.vb） 文件中声明的"优先级枚举"值，请使用 ImageName属性属性对其进行修饰。

public enum Priority {
    [ImageName("State_Priority_Low")]
    Low = 0,
    [ImageName("State_Priority_Normal")]
    Normal = 1,
    [ImageName("State_Priority_High")]
    High = 2
}

Note 注意

The State_Priority_Low, State_Priority_Normal and State_Priority_High images are included in the standard image library supplied with XAF. To learn how to use custom images, see the Assign a Custom Image lesson.

xAF 随附的标准图像库中包含State_Priority_Low、State_Priority_Normal和State_Priority_High图像。要了解如何使用自定义图像，请参阅分配自定义图像课程。

When you populate the ChoiceActionBase.Items collection in a Controller's constructor as shown in the code above, you can set an image name, shortcut and a localized caption for the added items using the Model Editor's ActionDesign | Actions | <Action> | ChoiceActionItems node. To learn how to invoke and use the Model Editor, refer to the first lesson in the UI Customization section. However, you may have to populate the Items collection in a Controller's Controller.Activated event handler, where you can access the current Application, View, etc. In this instance, the items added to the collection will not be loaded into the Model Editor.

当您在控制器的构造函数中填充 ChoiceActionBase.Items 集合时，如上面的代码所示，您可以使用模型编辑器的操作设计为添加的项目设置图像名称、快捷方式和本地化标题 |操作 |<Action>*选择操作项节点。要了解如何调用和使用模型编辑器，请参阅 UI 自定义部分中的第一课。但是，您可能必须填充控制器控制器中的"项目"集合。在这种情况下，添加到集合中的项将不会加载到模型编辑器中。

• To implement the code that must be executed when an end-user chooses the Action's item, handle the SingleChoiceAction.Execute event as shown below.

• 要实现最终用户选择操作项时必须执行的代码，请处理单选操作.Execute 事件，如下所示。

using DevExpress.ExpressApp.Editors;
using System.Collections;
using MySolution.Module.BusinessObjects;
//...
private void SetTaskAction_Execute(object sender, SingleChoiceActionExecuteEventArgs e) {
    IObjectSpace objectSpace = View is ListView ? 
        Application.CreateObjectSpace(typeof(DemoTask)) : View.ObjectSpace;
    ArrayList objectsToProcess = new ArrayList(e.SelectedObjects);
    if(e.SelectedChoiceActionItem.ParentItem == setPriorityItem) {
        foreach(Object obj in objectsToProcess) {
            DemoTask objInNewObjectSpace = (DemoTask)objectSpace.GetObject(obj);
            objInNewObjectSpace.Priority = (Priority)e.SelectedChoiceActionItem.Data;
        }
    }
    else
        if(e.SelectedChoiceActionItem.ParentItem == setStatusItem) {
            foreach(Object obj in objectsToProcess) {
                DemoTask objInNewObjectSpace = (DemoTask)objectSpace.GetObject(obj);
                objInNewObjectSpace.Status = (TaskStatus)e.SelectedChoiceActionItem.Data;
            }
        }
    if(View is DetailView && ((DetailView)View).ViewEditMode == ViewEditMode.View) {
        objectSpace.CommitChanges();
    }
    if(View is ListView) {
        objectSpace.CommitChanges();
        View.ObjectSpace.Refresh();
    }
}

• As you can see in the code above, the item currently selected in the drop-down list of the SetTaskAction is accessed via the event handler's SingleChoiceActionExecuteEventArgs.SelectedChoiceActionItem parameter. To assign a chosen value to a property of an object selected in the current View, you can use an Object Space. When the SetTaskAction is used in a Detail View, the View's Object Space is used to manipulate the current object. When the Action is used in a List View, a new ObjectSpace is created via the XafApplication.CreateObjectSpace method. This ObjectSpace helps manipulate the View's selected objects.

• 如上述代码所示，当前在 SetTaskAction 的下拉列表中选择的项将通过事件处理程序的"单选操作执行事件"参数进行访问。要将所选值分配给当前视图中选择的对象的属性，可以使用对象空间。在详细视图中使用 SetTaskAction 时，视图的对象空间用于操作当前对象。在列表视图中使用操作时，将通过 XafApplication.CreateObjectSpace 方法创建新的对象空间。此对象空间有助于操作视图的选定对象。

Note 注意

• Create a separate Object Space when you are going to modify multiple objects that are currently displayed. This approach improves performance, as the grid control's events do not trigger on each object change. In the code above, a new Object Space is created when the current View is the List View.
• 要修改当前显示的多个对象时，请创建单独的对象空间。此方法可提高性能，因为网格控件的事件不会触发每个对象更改。在上面的代码中，当当前视图是列表视图时，将创建新的对象空间。

• In ASP.NET Web applications, Detail Views are displayed in View and Edit modes. When SetTaskAction is activated for a DemoTask Detail View in View mode, the changes made to the DemoTask.Priority property should be saved to the database. For this purpose, the BaseObjectSpace.CommitChanges method of the current View's View.ObjectSpace is called. The same technique is used when the SetTaskAction is activated for a DemoTask List View. However, when you use the SetTaskAction in a DemoTask Detail View in Edit mode, the changes can be saved or rolled back via corresponding built-in Actions.

• 在ASP.NET Web 应用程序中，详细信息视图显示在"查看"和"编辑"模式下。在视图模式下为演示任务详细信息视图激活 SetTaskAction 时，对 DemoTask.Priority 属性所做的更改应保存到数据库中。为此，调用当前视图的视图.ObjectSpace 的 BaseObjectSpace.CommitChanges 方法。当为演示任务列表视图激活 SetTaskAction 时，将使用相同的技术。但是，当您在编辑模式下的"演示任务详细信息"视图中使用 SetTaskAction 时，可以通过相应的内置操作保存或回滚更改。

• The Priority or Status property will be changed for the currently selected objects. However, the grid editor used in ASP.NET Web applications does not have selected objects until an end-user selects an object manually. So, disable the Action when no objects are selected. To do this, set the Action's ActionBase.SelectionDependencyType property to RequireMultipleObjects. The Action will be available only when one or more objects are selected. To specify this property, use the Properties window.
• 将更改当前选定对象的"优先级"或"状态"属性。但是，在最终用户手动选择对象之前，ASP.NET Web 应用程序中使用的网格编辑器没有选择对象。因此，在未选择任何对象时禁用操作。为此，将操作的操作基础。仅当选择一个或多个对象时，操作才可用。要指定此属性，请使用"属性"窗口。

• Run the Windows Forms or ASP.NET application. Select the Task item in the navigation control. The Set Task Action will be displayed. Select one or more Task objects in the Task List View and select an item in the Action's drop-down list. The Priority or Status property of the selected Task objects will be modified.

• 运行 Windows 窗体或ASP.NET应用程序。在导航控件中选择"任务"项。将显示"设置任务"操作。在"任务列表"视图中选择一个或多个"任务"对象，然后选择"操作"的下拉列表中的项目。将修改所选任务对象的"优先级"或"状态"属性。

  

  

You can see the code demonstrated here in the MySolution.Module | Controllers | TaskActionsController.cs (TaskActionsController.vb) file of the Main Demo installed with XAF. The MainDemo application is installed in %PUBLIC%DocumentsDevExpress Demos 19.2ComponentseXpressApp FrameworkMainDemo by default. The ASP.NET version is available online at http://demos.devexpress.com/XAF/MainDemo/

您可以在 MySolution.模块 |控制器 |TaskActionsController.cs（任务操作控制器.vb）文件的主要演示安装与XAF。主演示应用程序安装在%PUBLIC%DocumentsDevExpress Demos 19.2ComponentseXpressApp FrameworkMainDemo by default. The ASP.NET version is available online at http://demos.devexpress.com/XAF/MainDemo/

.