Command Manager

This page describes the use of commands and the command manager.

Using command objects makes it easier to construct general components that need to delegate, sequence or execute method calls at a time of their choosing without the need to know the owner of the method or the method parameters.

A command is a component instance that separates the logic from the visual commanders. Commanders or visualizers are all the buttons, menu items, link labels and other controls that the user interact with to execute an action. The command holds the events for execute and inquire.  Commanders that are attached to the commands are required to update their visual state depending on the command state. When a commander is invoked, for example when a push button is pressed the, it is the command that will fire the execute event.

Multiple commanders can be connected to one command. For example a menu item and a button can both be driven by the same command.

Contents

• Command Manager
• Command Manager Designer
• Create a Command
• Subscribe to command events
  • Handle Execute Events
  • Handle Inquire Events
  • Change Trigger for Inquire Events
• Create a Commander
• Create a Commander from a Command

Command Manager

For a command to function it must be child to a Command Manager. It is the command manager that is responsible for inquiring its' child commands when an application event is raised. The Command Manager also enables and disables commands during server calls etc.

Commands are designed through the Command Manager Designer. All top level window classes expose a Command Manager instance.

Command Manager Designer

In the Command Manager Designer you can create commands and commanders. In the left pane of the editor you create commands and on the right side commanders are created.

Figure 1:The Command Manager Designer

Note: Commanders can be created directly on the form design surface and later edited in this editor. It is normally quite convenient to create the command and the commanders at the same time in the editor. 

Create a Command

1. From the Visual Studio Solution Explorer, open the window that should be designed.
2. Open the Command Manager Designer
   In the Components Pane, select the commandManager
   From the context menu, select Designer
3. In the available commands view, press the Add New command button, .
4. Update the name of the command as command<action>.
   Example: commandListOrders
5. Set the Caption property. This caption will be displayed on connected commanders. 
   Example: List Orders
6. Attach and implement event handlers

Subscribe to command events

The command publishes the Inquire and Execute events that normally should be implemented in order to add the correct logic for the command.

1. Use Visual Studio designer view on the form where you want to add a visualizer, e.g. a button.
2. Open the context menu for the commandManager in the components pane and select the menu item Designer....
3. Select the created command in the list of commands.
4. In the property sheet, click the Events button .
5. Click the name of the event you want to handle
6. In the value section next to the event name, click the drop-down button to display a list of existing event handlers.
7. Select the appropriate event handler from the list
8. Press the Close button.

Tip: If the required event handler does not exist, double click the event in the property dialog and Visual Studio will generate the handler.

Handle Execute Events

The command's Execute event is fired when the button is clicked. When the event is fired, the callback method created when subscribing to the Execute event will be called. The callback method should perform the action appropriate for the button.

private void commandPopulate_Execute(object sender, Ifs.Fnd.Windows.Forms.FndCommandExecuteEventArgs e)
{
    Sys.hWndForm.SendMessage(Const.PM_DataSourcePopulate, Const.METHOD_Execute, 0);
}

Figure 2: Example of a command execute event handler

Handle Inquire Events

A Command has an Inquire event that is fired when the command needs to update its state. This could be e.g. when a user selects a new record or edits a field.

The Inquire event callback methods are used by the application to set the state of commands to reflect the state of the application. The code in Fig. 3. shows how the populate command Enabled state is set according to if the current form can be populated at the current time.  This is done by changing the Enabled property on the Command. That property change on the command will be reflected on all the connected commanders.

private void commandPopulate_Inquire(object sender, Ifs.Fnd.Windows.Forms.FndCommandInquireEventArgs e)
{
    ((FndCommand)sender).Enabled = Sys.hWndForm.SendMessage(Const.PM_DataSourcePopulate, Const.METHOD_Inquire, 0);
}

Figure 3: Example of a command inquire event handler

Change Trigger for Inquire Events

The default behavior for the command Inquire is that the Command Manager will request an inquire whenever some data source, contextual or edit change happens. This is for example when a data source is populated, when a new record is created, when the data record is saved, when the user switches window etc. In some situations there is a need for a commander to update with much greater frequency. An LOV button for example needs to change every time focus is moved from one field to another. The overall performance of the application would however not benefit from all commanders to update their state that often.

This is what the EventCategory property solves. If you have a command that has special needs, you can set the command's EventCategory property to a specific category. Only commands with the property EventCategory set will be inquired for such a category.

Create a Commander

The action tree displays the existing commanders on the underlying form. An existing button can be connected to a created command directly, but if there is a need for a new commander you create one like this.

1. In the action tree, select the node for which you want to create a commander.

   Example: If you want to create a button, select the Buttons node.

2. Click the Add New commander button.
3. In the tree, select the created commander
4. In the property dialog assign the Command property to the desired command.

Create a Commander from a Command

It is possible to create a commander directly from a command.

1. In the list of available commands, select a command.
2. With the mouse, drag the command and drop it on a node in the Action Tree.

When a command is dropped like this, a commander is generated with a name corresponding to the command and with the command assigned.