Add an Action with Option Selection

• Apr 07, 2021
• 4 minutes to read

This lesson explains how to create an Action that supports an option selection.

In this lesson, you will implement a new View Controller with a SingleChoiceAction. This action will allow users to select values for the Task.Priority and Task.Status properties.

Note

Before you proceed, take a moment to review the following lessons.

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

Step-by-Step Instructions

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

2. Open the MySolution.Module | Controllers | TaskActionsController.cs file and set the controller TargetObjectType:

   C#

   using MySolution.Module.BusinessObjects;
   // ...
   public partial class TaskActionsController : ViewController {
       public TaskActionsController() {
           InitializeComponent();
           TargetObjectType = typeof(DemoTask);
       }
       // ...
   }
   

3. Add a SingleChoiceAction and specify its properties.

   C#

   public partial class TaskActionsController : ViewController {
       public TaskActionsController() {
           InitializeComponent();
           TargetObjectType = typeof(DemoTask);
   
           SingleChoiceAction SetTaskAction = new SingleChoiceAction(this, "SetTaskAction", PredefinedCategory.Edit) {
               Caption = "Set Task",
               ItemType = SingleChoiceActionItemType.ItemIsOperation,
               SelectionDependencyType = SelectionDependencyType.RequireMultipleObjects
           };
       }
       // ...
   }
   

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

   C#

   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() {
         // ...
         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));
         SetTaskAction.Execute += SetTaskAction_Execute;
      }
      private void FillItemWithEnumValues(ChoiceActionItem parentItem, Type enumType) {
           EnumDescriptor ed = new EnumDescriptor(enumType);
           foreach(object current in ed.Values) {
               ChoiceActionItem item = new ChoiceActionItem(ed.GetCaption(current), current);
               item.ImageName = ImageLoader.Instance.GetEnumValueImageName(current);
               parentItem.Items.Add(item);
           }
       }
   }
   

5. Open the DemoTask.cs file and assign images to the Priority enumeration value, like in the code sample below.

   C#

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

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

   C#

   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;
           }
       }
       objectSpace.CommitChanges();
       View.ObjectSpace.Refresh();
   }
   

7. Run the application. Select the Task item in the navigation control. After you select a task, the Set Task Action is displayed.

   To change the Priority or Status property of the selected Task objects, select an item in the Action’s drop-down list.

   

   

Detailed Explanation

SingleChoiceAction Options

The SingleChoiceAction.ItemType property specifies a display mode for the Action’s items. In this lesson, you perform an operation against selected records, which is why the property value is set to “ItemIsOperation”.

Populate Action Items

The code sample in step 4 organizes items from the Action’s Items collection as a tree:

• The root level contains items whose captions correspond to the DemoTask.Priority and DemoTask.Status property names. Item captions are returned by the CaptionHelper object.
• The nested level contains the Priority and Status enumeration values. Item captions are returned by an EnumDescriptor object.

This is useful when the Priority and Status properties, and corresponding enumeration values, are localized with the Application Model.

When you populate the ChoiceActionBase.Items collection in a Controller’s constructor as shown in the code above, you can set an image name, a shortcut and a localized caption for the added items using the Model Editor‘s ActionDesign | Actions | <Action> | ChoiceActionItems node.

If you populate the Items collection in a Controller’s Controller.Activated event handler, items are not loaded into the Model Editor.

Access Action Items

To access a selected action item, we use the event handler’s SingleChoiceActionExecuteEventArgs.SelectedChoiceActionItem parameter.

Selection Dependent Action

In this tutorial, the Action is available within the Task List View when a user selects at least one object. To do this, the Action’s ActionBase.SelectionDependencyType property is set to RequireMultipleObjects.

Custom Images for Enumeration Values in UI

In this tutorial, you decorate enumeration values with the ImageNameAttribute attribute to set images for these values in the UI.

XAF ships with the standard image library. The library includes the State_Priority_Low, State_Priority_Normal and State_Priority_High images used in this lesson.

Operations on Sets

The code displayed in step 6 uses the XafApplication.CreateObjectSpace method to create a new ObjectSpace when the Action is used in a List View. This ObjectSpace helps manipulate the View’s selected objects.

Create a separate Object Space to edit multiple objects that are currently displayed. This approach improves performance, as the grid control’s events do not trigger on each object change.

Next Lesson

Add a Simple Action using an Attribute