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
|
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. |
|
User-defined. |
|
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
|
TButtonSize = (bsSmall, bsLarge);
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
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. |
|
TGalleryResize = (grNone, grVertical, grBoth);
// grNone - do not allow resizing
// grVertical - only allow vertical resizing
// grBoth - allow both vertical and horizontal resizing
|
csControl |
|
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. 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
|
csMenu |
ShowRichContent |
|
Command appears like an Office 2007 radio button. |
csSeparator |
csText and csSeparator share the same CommandProps class, so the available properties are the same. |
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.