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
csComboBoxCommandStyle 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
csGalleryCommandStyle withgtRibbonTGalleryType 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.