Adding Commands to the Ribbon

Go Up to How To Build an Application that Uses Ribbon Controls

This topic follows in sequence the creation of a ribbon application using either the Ribbon Application Wizard or the manual steps described in Creating an Application that Uses Ribbon Controls.

This topic assumes that you are familiar with the TActionManager component and the components associated with its use. Numerous new properties have been added to help support the ribbon requirements. Many existing properties have no effect when modified on a command that is displayed on the ribbon.

For instance:

• Small buttons always display their glyph to the left of the caption.
• Large buttons always display their glyph at the top.
• A Large button must have a caption. The caption can be a maximum of two lines, and the button width is resized accordingly. A large button's height is fixed to cover the height of the group where the command is displayed.
• Only small buttons with no caption can be displayed in groups.

New Properties

CommandStyle: The CommandStyle determines the type of control that is used to represent this command on the ribbon. The default style is csButton. CommandStyle is used extensively for determining the control type that is used for the command except under one exception.

type TCommandStyle = (csButton, csMenu, csSeparator, csText, csGallery, csComboBox, csControl, csCustom);

Style of the Command on the Ribbon Group

csButton	Command is a button.
csComboBox	Command displays an Office 2007 style combo box. See the following Note.
csControl	Command has a TControl descendant associated with it. An example is dropping a TEdit component onto a ribbon Group.
csCustom	User-defined.
csGallery	Command is a gallery or, when selected, it displays a gallery.
csMenu	Command is a menu item.
csSeparator	Command is a separator with a text description.
csText	Command only displays text and has no associated control.

Note: You can only use the csComboBox CommandStyle if you first place a TRibbonComboBox from the tool palette onto your ribbon Group.

CommandProperties: CommandProperties is a dynamic property class. The published properties of this property (it is a TPersistent descendant) vary depending on the CommandStyle that has been selected. If you select the csButton CommandStyle, the CommandProperties class used is called TButtonProperties. This property class publishes properties that are specific to the csButton CommandStyle.

An example is ButtonSize, which allows you to indicate if the button is a large button or a small button. There is no need for a csMenu command to have a ButtonSize property because the menu does not react to a size variance.

All CommandProperties classes descend from TCommandProperties. If you are using the csCustom CommandStyle, you must descend from the TCommandProperties class.

Properties that can be available in the CommandProperties property depending on your selected CommandStyle

csButton	ButtonSize Size of the button: TButtonSize = (bsSmall, bsLarge); ButtonType Special types of buttons allowed: TButtonType = (btNone, btDropDown, btSplit, btGallery); // btNone - normal button // btDropdown - button displays a drop-down menu // btSplit - button has drop-down menu and a default action // btGallery - button displays a gallery as a drop-down menu GroupPosition Position of this command in a group of commands: TGroupPosition = (gpNone, gpStart, gpMiddle, gpEnd, gpSingle); // Determines whether a border is drawn around a button // gpNone - no border drawn // gpStart - the right edge of a border is not drawn // gpMiddle - top and bottom of border is drawn // gpEnd - the left edge is not drawn // gpSingle - the full border is drawn
csCheckBox	Command appears like an Office 2007 check box.
csComboBox	AllowResize Controls whether the pop-up menu associated with the combo box can be resized: TGalleryResize = (grNone, grVertical, grBoth); // grNone - do not allow resizing // grVertical - only allow vertical resizing // grBoth - allow both vertical and horizontal resizing Items Items to display when the user selects the drop-down button. These items display in a window like a regular combo box. Text The text to display in the combo box. Width The width of the spinner control, excluding any caption width.
csControl	ContainedControl Reference to the control it is associated with on the ribbon.
csCustom	User-defined.
csGallery	The csGallery CommandProperties class descends from the csButton CommandProperties class. This means that all of the csButton properties are also available for csGallery commands, as well as the following gallery ones. GalleryType Type of gallery to be displayed: TGalleryType = (gtDropDown, gtGrid, gtRibbon); // gtDropDown - Gallery is in the form of a drop-down menu. // gtGrid - Gallery is a grid layout, meaning it can be more than one item across. // ItemsPerRow controls the number of items across. // gtRibbon - Gallery is in Ribbon. ItemsPerRow Number of items to display on a row. ShowRichContent Set to True to display rich content for the gallery items. Note: Using csGallery CommandStyle with gtRibbon TGalleryType is not supported in the current version, but you can use the other two TGalleryTypes.
csMenu	ShowRichContent Set to True to display rich content for the menu item. Content The content to be displayed as rich content. Font Use a custom font when displaying the rich content. Rich content menu items are limited to two lines. Depending on the content, the menu items might be wider and are not changed to be taller, and some menu items therefore display additional lines (beyond the two permitted.)
csRadioButton	Command appears like an Office 2007 radio button.
csSeparator	csText and csSeparator share the same CommandProps class, so the available properties are the same. Alignment The alignment of the caption text. EllipsisPosition Position of any ellipsis if caption text is too wide for the menu width. It is only possible for menu items to be displayed in the Application menu. Font Font to use when drawing the caption text. Width Force the width of the created control to be a specific size. Leave as -1 for csSeparator CommandStyle and modify as required for csText CommandStyle.
csText	csText and csSeparator share the same CommandProps class, so the available properties are the same.

Additional Ribbon Component Properties

KeyTip: The key that can be pressed to activate the command when using the keyboard. To activate KeyTips, press either the ALT or F10 key.

NewCol: Setting NewCol for a command forces the control to be displayed in a new column of the ribbon group. This property is only effective when the ribbon group alignment is gaVertical.

NewRow: Setting NewRow for a command forces the control to be displayed in a new row of the ribbon group. This property is only effective when the ribbon group alignment is gaHorizontal.

Default: Set to True to force a menu items caption to be bolded. Only effective for menu items.

See Also

• VCL Overview
• How To Build a VCL Forms Application with Graphics
• Creating an Application that Uses Ribbon Controls
• Windows Ribbon Framework (MDSN)