Site Map / Register

Feature Articles

Using Commands

Introduction

For many medium and larger-scale applications, it is essential to provide a consistent and unified way of developing and supporting the user interface. In Elegant Ribbon this is achieved by using the time-proven concept of command-oriented interface, when user-interface controls are separated from the code that implements user actions. For example, you have a button that itself does nothing and you have a non-visual command object, whose methods do something. You can now set a link between the button and the command object so that when clicking the button, a method of the command object is called and you can execute some custom code (for instance, save a file to disk). Such a separation allows you to make the application more extensible and scalable. Besides, you can put the code for all commands into a separate file, which makes your code more reusable and maintainable.

The overall advantage of this approach is that the developer can focus on the application design rather than on implementation details.

Commands in Elegant Ribbon

Every action that the user requests in the application is represented by a command. For example, you can define commands like OpenFile, SaveFile, StartBuild, etc. Any UI control can be linked to one command and any command can be linked to more than one control. That is, a command can be considered as a server and controls as clients. For example, you can have one command that opens a file (OpenFile) and two UI controls that are linked to this command: OpenFileButton in a ribbon group and OpenFileContextMenuButton in a context menu. By clicking any of these two buttons, the user invokes the same code, which opens a file.

In Elegant Ribbon every command is represented by an object that has its properties (Name, Enabled and Data), method (Execute) and events (DataChanged and Executed). The Execute method is called for all controls associated with the command and if you put some code into the SomeCommand.Executed handler, this code will always be executed when you click any button linked to this command.

If you set SomeCommand.Enabled property to false, all controls associated with this command will get disabled. Please note that the Enabled property set for one of the controls is properly reflected in all the other controls linked to the same command. In other words, making one control disabled, you automatically disable all other controls linked to the same control and vice versa.

The Data property can be handy when you need to store some data associated with the command. The command cannot always be considered only as being associated with buttons for executing some code. You can link a text box to a command so that the logical content of the text box can be reflected in the Data property of this command. When the Data property changes, the DataChanged event occurs. This can be useful, for instance, when you are using a text box in conjunction with a combo box: you can link both controls to a same command in order to make the data synchronized when the user selects a new item in the combo box.

This mechanism of synchronizing data between controls via commands is also used when some controls need to be customizable. If you do not assign a command to a control, the user will not be able to add a copy of such a control to the Quick Access Toolbar because the only way of synchronizing content between controls in Elegant Ribbon is via commands.

Programming Commands

Elegant Ribbon offers a simple and flexible API for interacting with command-related features programmatically. The most significant parts of the Command class interface are shown below.

[C#]
public class Command
{
   public Command(string name);

   public string Name
   {
      get;
   }

   public object Data
   {
      get;
      set;
   }

   public bool Enabled
   {
      get;
      set;
   }

   public void Execute();

      public event CommandEventHandler Executed;
      public event CommandDataEventHandler DataChanged;
}

Each command, when created, registers itself in the static command manager (CommandManager), which is used as global storage for all commands. You can enumerate the commands using the following code:

[C#]
foreach (Command command in CommandManager.Commands)
{
   Console.WriteLine(command.Name);
}

[VB.NET]
For Each command As Command In CommandManager.Commands
   Console.WriteLine(command.Name)
Next command

The Control class contains the Command property of Command type, which allows you to get or set the command associated with the control. That is all. The power of using commands is based on using them consistently rather than on the complexity of the concept itself.

Commands at Design Time

One of the distinguishing features of Elegant Ribbon is that you can do a considerable part of the work using the Windows Forms designer. Adding, removing and assigning commands is not an exception. Select a control (e.g. Button) on the form, find the Command property in the Properties pane and click the ellipsis button in order to invoke the Commands Designer dialog. You can now add and remove commands at the application level. You can also select a command for the control. Please note that the commands are stored in application scope rather than serialized to the form you are working with. After you added one or more commands, an Elegant Ribbon's extensibility component creates an ApplicationCommands static class in a separate file. This allows you to work with commands by using auto-generated static variable names (like with forms in Windows Forms or with ADO.NET data sets). Here is the sample of an ApplicationCommands.cs file:

//------------------------------------------------------------------------------
// 
//    This code was generated by a tool.
//    Runtime Version:2.0.50727.42
//
//    Changes to this file may cause incorrect behavior and will be lost if
//    the code is regenerated.
// 
//------------------------------------------------------------------------------

[C#]
[assembly: Elegant.Ui.CommandSource("Elegant.Ui.Tests.RibbonUiTest.ApplicationCommands")]

namespace WindowsApplication1
{
   //  This class is required for commands support.
   // Do not modify the code inside the editor

   public class ApplicationCommands
   {
   public static Command CloseFile = new Elegant.Ui.Command("CloseFile");
   public static Command SaveFile = new Elegant.Ui.Command("SaveFile");
   public static Command OpenFile = new Elegant.Ui.Command("OpenFile");
   }
}

[VB.NET]
<Assembly: Elegant.Ui.CommandSource("Elegant.Ui.Tests.RibbonUiTest.ApplicationCommands")>

Namespace WindowsApplication1
   '  This class is required for commands support.
   ' Do not modify the code inside the editor

   Public Class ApplicationCommands
   Public Shared CloseFile As Command = New Elegant.Ui.Command("CloseFile")
   Public Shared SaveFile As Command = New Elegant.Ui.Command("SaveFile")
   Public Shared OpenFile As Command = New Elegant.Ui.Command("OpenFile")
   End Class
End Namespace

Short Tutorial

Open Visual Studio and create a new Windows Forms application project.
Add a ribbon control.
Add some tabs, groups and controls to the ribbon.
Select some control (for example, a button).
In the Properties pane, find the Command property and invoke the Commands Designer dialog.
Add a few new commands, select a command click OK.
Notice that the selected command is now associated with the control.
Go to the ApplicationCommands class that was generated for added commands.
In your form code, add an event handler for the selected command from the ApplicationCommands class. Write some code in it.
Run the application and see the results.