Other Command Types

We will look at some other command types here.

TUICommandBoolean

This command type is used by Toggle Buttons and Check Boxes. This command type has one additional property called Checked which indicates whether the button or check box is currently checked or not. There is also an OnToggle event that is fired when the user toggles the button or check box. For example, the 4 Paragraph Alignment buttons are mutually exclusive toggle buttons. They share the same OnToggle event:

OnToggle event for the Paragraph Alignment Buttons 
procedure TFormMain.AlignToggle(const Args: TUICommandBooleanEventArgs);
var
  ParaFormat: TParaFormat2;
begin
  if (Args.Checked) then
  begin
    ParaFormat := FRichEditEx.ParaFormat;
    case Args.Command.CommandId of
      CmdAlignLeft:
        ParaFormat.wAlignment := PFA_LEFT;
      CmdAlignCenter:
        ParaFormat.wAlignment := PFA_CENTER;
      CmdAlignRight:
        ParaFormat.wAlignment := PFA_RIGHT;
      CmdAlignJustify:
        ParaFormat.wAlignment := PFA_JUSTIFY;
    end;
    ParaFormat.dwMask := PFM_ALIGNMENT;
    FRichEditEx.ParaFormat := ParaFormat;
  end;
  UpdateRibbonControls; { Update Checked state of alignment buttons }
end;

Here, we use the Args.Checked and Args.Command field to check which alignment option is chosen. We modify the paragraph settings accordingly. I will not go into the details of working with Rich Edit controls here since this is a tutorial about working with the Windows Ribbon, not about how to create your own word processor. You can check the source code of the TextPad sample for more details though.

The final line of this method is a call to UpdateRibbonControls. We need to update the Checked property of the 4 alignment buttons. When the paragraph was left-aligned and the user clicks the Center button, then we need to uncheck the Left Alignment button and check the Center button. The Ribbon Framework does not have a concept of mutually exclusive buttons, so it will not do this for you automatically. The UpdateRibbonControls method also sets the Enabled property of some commands that are only available in certain contexts. For example, the Paste button should only be available when there is text on the clipboard. The partial implementation of this method looks like this:

Updating Ribbon Controls 
procedure TFormMain.UpdateRibbonControls;
var
  ParaFormat: TParaFormat2;
begin
  ParaFormat := FRichEditEx.ParaFormat;

  if Assigned(FCmdPaste) then
    FCmdPaste.Enabled := FRichEditEx.CanPaste;

  if Assigned(FCmdAlignLeft) then
    FCmdAlignLeft.Checked := (ParaFormat.wAlignment = PFA_LEFT);

  if Assigned(FCmdAlignCenter) then
    FCmdAlignCenter.Checked := (ParaFormat.wAlignment = PFA_CENTER);

  if Assigned(FCmdAlignRight) then
    FCmdAlignRight.Checked := (ParaFormat.wAlignment = PFA_RIGHT);

  if Assigned(FCmdAlignJustify) then
    FCmdAlignJustify.Checked := (ParaFormat.wAlignment = PFA_JUSTIFY);
end;

Be sure to check a command for nil before you change a property. This is needed because not every command may be available at all times (remember that commands are only created the first time the Ribbon Framework needs to display them).

TUICommandFont

This command type is used exclusively by the Font Controls. It has a Font property which contains the current font settings. This property is of type TUIFont, which is similar to Delphi's TFont, but has more properties. The command also has an OnChanged event which is fired when the user changes one of the font properties. The Args.Font parameter contains the selected font settings:

OnChange event for Font command 
procedure TFormMain.FontChanged(const Args: TUICommandFontEventArgs);
var
  CharFormat: TCharFormat2;
begin
  Args.Font.AssignTo(CharFormat);
  FRichEditEx.CharFormat := CharFormat;
end;

A TUIFont object can be assigned to a TCharFormat2 record, which is the native record used by Rich Edit controls to change font settings. This makes working with the Font Control very simple. You don't have to worry about individual font settings (Font Name, Size, Color, Effects etc), although you can still access those settings if you want to.

TUICommandDecimal

This command type is used exclusively by the Spinner Control. It has the following additional properties:

  • Value: the currently selected value (of type Double).
  • MinValue, MaxValue: the minimum and maximum values the spinner can take.
  • Increment: the amount by which the value increments or decrements when the user clicks a spinner button.
  • DecimalPlaces: the number of decimal places to show in the spinner control.
  • RepresentativeString: this string is used by the Ribbon Framework to query the width of the Spinner control. Set this to the longest string you forecast. The string is never displayed, so it could contain any characters you want. It is just used to calculate the width of the control: the longer the string, the wider the control.
  • FormatString: a string (eg. unit of measurement) that is displayed to the right of the number in the spinner control.

The TUICommandDecimal class also has on OnChange event which is fired when the user changes the value.

TUICommandColorAnchor

This command type is used exclusively by the Drop-Down Color Picker control. It has a number of additional properties:

  • ColorType: the selected color type (ctNoColor, ctAutomatic or ctRgb). When this property equals ctRgb, you can use the Color property to get the actual color.
  • Color: the currently selected color when ColorType=ctRgb. Or clNone when ColorType=ctNoColor, or clDefault when ColorType=ctAutomatic. When setting the color, the ColorType property will be adjusted
    accordingly.
  • StandardColors: an array of colors to use for the Standard Colors section of the drop-down window. Is only used when the ColorTemplate for the color picker contains a StandardColors grid.
  • StandardColorTooltips: an array of strings with the tooltips of the Standard Colors.
  • StandardColorsCategoryLabel: the caption of the "Standard colors" section in the drop-down window.
  • ThemeColors: an array of colors to use for the Theme Colors section of the drop-down window. Is only used when the ColorTemplate for the color picker contains a ThemeColors grid.
  • ThemeColorTooltips: an array of strings with the tooltips of the Theme Colors.
  • ThemeColorsCategoryLabel: the caption of the "Theme colors" section in the drop-down window.
  • RecentColorsCategoryLabel: the caption of the "Recent colors" section in the drop-down window.
  • AutomaticColorLabel: the caption of the "Automatic color" button.
  • NoColorLabel: the caption of the "No color" button.
  • MoreColorsLabel: the caption of the "More colors" button.

There is also an OnExecute event which is fired when the user selects a color.

TUICommandRecentItems

Used for the list of recent items (usually recent files) in the Application Menu. Has a single additional property called Items which is a collection (type TUICollection). You need to add items of type TUIRecentItem (or derived) to this collection. Each item has the following properties:

  • LabelText: a string with the caption of the item (for example, the filename).
  • Description: longer description of the item as it appears in the tooltip for the item (for example, the full path of the file).
  • Pinned: a boolean indicating whether the item is pinned to the Application Menu (if the Application Menu is authored to allow pinning).

Once you add an item to the collection, the collection becomes owner of the item, so you shouldn't free it yourself. We will talk a bit more about collections on the next page.

The TUICommandRecentItems class also has an OnSelect event which is fired when the user selects a recent item from the list.

TUICommandContext

This command is used for Contextual Tab Groups (like the "Table Tools" tab group that appears in Microsoft Word when you edit a table in a document). This command add a single enumerated property called Availability which determines if and how the contextual tab group should be available:

  • caNotAvailable: the tab group will be hidden.
  • caAvailable: the tab group will be shown, but not activated.
  • caActive: the tab group will be shown and activated.

This command type does not expose any events.

We will conclude this tutorial by looking at galleries in more detail.

Next: Working with Galleries