Adding Commands to the Ribbon

From RAD Studio
Jump to: navigation, search

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


Command is a button.


Command displays an Office 2007 style combo box. See the following Note.


Command has a TControl descendant associated with it. An example is dropping a TEdit component onto a ribbon Group.




Command is a gallery or, when selected, it displays a gallery.


Command is a menu item.


Command is a separator with a text description.


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


Size of the button:

TButtonSize = (bsSmall, bsLarge);

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

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


Command appears like an Office 2007 check box.


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 to display when the user selects the drop-down button. These items display in a window like a regular combo box.
The text to display in the combo box.
The width of the spinner control, excluding any caption width.


Reference to the control it is associated with on the ribbon.




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.
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.

Number of items to display on a row.
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.


Set to True to display rich content for the menu item.
The content to be displayed as rich content.
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.)


Command appears like an Office 2007 radio button.


csText and csSeparator share the same CommandProps class, so the available properties are the same.
The alignment of the caption text.
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 to use when drawing the caption text.
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 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