The functionality of a menu item and a toolbar button is very similar in C1Command. The menu item or toolbar button is split between two components: a command and a command link.

Functionality of a C1Command Component

The command (an object of type C1Command or derived types, see Class Hierarchy for a list) is used to hold properties and event handlers related to the actual action which the command represents. Commands themselves are not contained in C1Commands menus and toolbars. Instead, all commands on a form are stored as a single collection in a component of type C1CommandHolder, a single instance of which is automatically created on the form when you add the first C1Commands menu or toolbar to it.

For more information on how to use C1CommandHolder, please see C1CommandHolder Component. To represent commands in menus and toolbars, command links (components of type C1CommandLink) are used.

Functionality of a C1CommandLink Component

A command link is a small and quite simple component. Its most important property is Command, which points to the actual command object associated with this command link. Aside from this, a command link allows you to override some of the properties of the linked command, such as text. The visual representation of a command link depends on two factors: the command it links to and whether the link is contained in a main menu, a popup menu, or a toolbar.

Properties used to show the command link are taken from the command, for example text or image, whereas the way they are shown is determined by the container. In a main menu, only the command’s text is shown and in a popup menu the image and the shortcut are also shown, and so on. Multiple command links can point to the same command, which is one of the main reasons why commands and command links are separate items.

Relationships Among Commands, Command Links, Menus and Toolbars, and Command Holder

To sum it up, the following relationships exist between commands, command links, menus and toolbars, and the command holder on a form:

• Commands (class C1Command and derived classes) are automatically stored in the form’s command holder (object of type C1CommandHolder).
• Menus and toolbars (objects of type C1MainMenu, C1CommandMenu, C1ContextMenu, C1ToolBar) contain command links (type C1CommandLink) which represent menu items or toolbar buttons. Each command link points to the actual command in the command holder. Command links are stored in the CommandLinks collection of a menu or a toolbar. Command links can be edited via this collection or using the designer.
• Multiple command links can point to the same command. And command links pointing to the same command can be inside different containers. For example, a link from the File menu and another from the File Operations toolbar can point to the same file open command.
• Most properties of a command link visible to the user (text, image, and so on.) are normally taken from the linked command. The shown state of the command link (enabled/disabled, checked/unchecked and so on.) is also determined by the corresponding state of the linked command (command links do not have state properties).
• Most importantly, event handlers that actually perform user-defined actions (for example, opening a file or copying to the clipboard) are associated only with commands and never with command links. When a menu item is selected or a toolbar button is clicked by the user, the click event handler of the linked command is invoked.
• To enumerate all commands defined on a form, use the Commands collection of the command holder (which shows up in the component tray of the form). You can also use the collection editor to add or remove commands (although an easier approach is probably to use the menu or toolbar designer, accessing commands via their links).