CommandOverride.zip
4 KB
S21 Basics: Overriding Standard Commands
Every action that can be triggered by the user via menu, toolbar, or shortcut are implementations of the _3S.CoDeSys.Core.Commands.ICommand interface. Using Automation Platform, you can create new implementations of commands within your own plug-ins. However, sometimes it is desired to override the behavior of an already existing command instead of creating a new one. This article shows how to solve this task.
Idea
Currently, there are four derived interfaces of ICommand (implementations never implement ICommand directly, but one of the sub-interfaces in order to define the general behavior of the command):
- IStandardCommand: A command that simply executes an action when clicked. Example: File::Save as...
- IToggleCommand: A command with an additional "checked" state that can be switched on and off. Example: Online::Simulation
- IListCommand: A command that drops down additional items when clicked. Example: File::Recent Projects (Note: do not mix this up with popup menus which are user-definable groups of commands. Edit::Find & Replace > for instance is not a list command.)
- ITextCommand: A command that requires a text input for execution. Currently, there is no implementation of that kind of command because it is not fully implemented in the CoDeSys frame.
For each interface exists a corresponding customization interface that can be used to override the standard behavior:
ICommand | ICustomizedCommand |
IStandardCommand | ICustomizedStandardCommand |
IToggleCommand | ICustomizedToggleCommand |
IListCommand | ICustomizedListCommand |
ITextCommand | ICustomizedTextCommand |
When we take a closer look to one of those customization interfaces and compare it with the corresponding command interface, then the idea becomes obvious:
ICommand method/property | ICustomizedCommand method |
AddedToUI() | AddedToUI(ICommand originalCommand) |
RemovedFromUI() | RemovedFromUI(ICommand originalCommand) |
Category { get; } | GetCategory(ICommand originalCommand) |
Name { get; } | GetName(ICommand originalCommand) |
Description { get; } | GetDescription(ICommand originalCommand) |
ToolTipText { get; } | GetToolTipText(ICommand originalCommand) |
SmallIcon { get; } | GetSmallIcon(ICommand originalCommand) |
LargeIcon { get; } | GetLargeIcon(ICommand originalCommand) |
Enabled { get; } | GetEnabled(ICommand originalCommand) |
IsVisible(bool bContextMenu) | IsVisible(bool bContextMenu, ICommand originalCommand) |
BatchCommand { get; } | GetBatchCommand(ICommand originalCommand) |
ExecuteBatch(string[] arguments) | ExecuteBatch(string[] arguments, ICommand originalCommand) |
Each method and property of the command interface has got a corresponding method for customization, which has got an extra argument where a reference to the original implementation is passed to your implementation. That means that you are not only able to influence the execution of the command, but any other aspect like name, icons, etc. as well! For all aspects which you do not want to change, simply call the corresponding method on the originalCommand parameter.
The ICustomizedCommand interface has got one additional property OriginalCommandGuid which returns the type GUID of that command that should be overwritten.
Running the sample
- Download the attached sources.
- If not already done, set the environment variable %APCOMMON% to the Common directory of your CoDeSys installation. (This is the directory where CoDeSys.exe, IPMCLI.exe, and IPM.exe are installed.)
- Start Visual Studio and open the solution CommandOverride.sln.
- Depending on your installation, you must correct some references to interface components, so that they point into the Interface Binaries folder in your Automation Platform SDK installation.
- Build the sample. The plug-in will be automatically installed.
- Use IPM.exe in order to add the plug-in Sample: Command Override to one of your version profiles.
- Start CoDeSys and ignore the message about the missing plug-in key.
The sample implementation overrides the File::Save command in two aspects:
- The name of the command is changed to My customized Save.
- When executed, it first prompts the user whether s/he wants to save the project. Then the original implementation is called. After that, a message box appears where the resulting project file size is reported.
Best practices
- When using the sample code in any serious development, please make sure that you exchange all type GUIDs and the plug-in GUID by GUIDs generated on your machine.
- Just as with your own command implementations, most of the methods in the customized interface are called very often, so they must perform very fast!
