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

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