Skip to content

Tutorial: Integrating with Delphi

Jump to bottom Edit New page
Joachim Marder edited this page Mar 27, 2018 · 16 revisions

Integrating with Delphi

Now that we have designed the Ribbon User Interface, it is time to integrate it into a Delphi application. You can start a new Delphi application from scratch using this tutorial, or you can follow along with the medium-level TextPad sample application that comes with the library.

Starting a new Delphi project

You should follow these steps when you create a new Delphi project that uses a Windows Ribbon.

  1. Make sure you have Build (Ctrl+F9) or Previewed (F9) the ribbon in the Ribbon Designer. This will make sure that all the necessary resource files are up-to-date.

  • In Delphi, create a new VCL Forms Application as you normally would. Save it in the project directory that you created when you designed the Ribbon. In our case, we saved the ribbon files in the directory "C:\Projects\TextPad\Ribbon", so we need to save our Delphi project in "C:\Projects\TextPad".

  • If you haven't set the Delphi Library Path to include the Ribbon Framework directory, then make sure you add the Lib directory from the download to the project's search path (using Project | Options | Delphi Compiler | Search Path).

  • Make the application High-DPI aware, so it will look better when the user increases the resolution in Windows. This will make sure that text stays sharp and that the additional high-resolution images we provided with the Ribbon will be used when needed. This step is optional but recommended for RAD Studio XE3 - XE8:

    1. Go to "Project | Options".
    • Go the the Application page.
    • Uncheck "Enable runtime themes". Don't worry, your application will still be theme-aware because we will use a custom manifest.
    • Choose "Project | Add to project...".
    • In the File Open dialog box, choose the "Resource file (*.rc)" file type.
    • Open the file "UIRibbon.rc" in the Lib directory of the Ribbon Framework.

    In Delphi 10 Seattle and higher, use the integrated support for high dpi awareness at "Project | Options | Application"

  • Drop the TUIRibbon control from your RAD Studio toolbox on your main form.

  • Add the .PAS file created by the Ribbon Designed to the uses of your form. It is named equally to the XML file in which you saved the ribbon design.

You should now be able to compile and run the application. If you followed the steps above, the main form will show the ribbon at the top:

Screenshot

TUIRibbon

The TUIRibbon control can be dropped on any VCL form. It works as a placeholder for the ribbon, it cannot show a preview for technical reasons. This control has the following properties:

  • ResourceName: the name of the Ribbon resource as it is stored in the resource file. If you use the Ribbon Designer to design the ribbon, then you don't need to override this method. If you use Microsoft's Ribbon Compiler and specify a custom resource name, then you need to override this method and return that resource name.
  • Available: whether the UI Ribbon Framework is available on the system. If not (because the application is running on an older Windows version), then you will need to provide an alternative user interface.
  • Height: the current visible height of the Ribbon. You can use this property for laying out controls on the ribbon form. However, it is usually easier to place a single control (like a TPanel) on the form and setting its Align property to alClient. Place your other controls on this panel, and the layout will automatically be taken care of.
  • Visible: whether the Ribbon is currently visible. You can hide the Ribbon by setting this property to False.
  • Minimized: whether the Ribbon is currently minimized (or collapsed). When the Ribbon is in a minimized state, only the tab headers will be visible. The user can also minimize the ribbon by double clicking on a ribbon tab.
  • QuickAccessToolbarPosition: whether the Quick Access Toolbar is displayed above or below the Ribbon.
  • Commands: all the currently created commands for the Ribbon. This is detailed in the next page.
  • BackgroundColor: the background color of the Ribbon. This is the main color that the Ribbon Framework will use to colorize the ribbon. You can change it to create a different color theme.
  • HighlightColor: the highlight color of the Ribbon. This is the color that is used for highlighted buttons.
  • TextColor: the color that is used for text items on the ribbon.
  • BackgroundHsbColor, HighlightHsbColor, TextHsbColor: the same 3 colors, but in HSB (Hue, Saturation, Brightness) format. This color format might be easier to use if you want to individually adjust the Hue, Saturation or Brightness value of the color.
  • Framework: a handle to the low-level IUIFramework interface for direct access to the Ribbon API. You usually don't need to use this property if you use the Delphi Ribbon Class Library.
  • OnLoaded: this event is fired right after the ribbon has been loaded from the resource. You can perform some initialization that depends on the ribbon in this method.
  • OnCommandCreated: every time the Ribbon Framework creates a command, this event is fired. You can use this event to customize the command or set the event that is fired when the command is executed. We will discuss this in detail in the next page of this tutorial.

The TextPad sample application uses the BackgroundColor property to set the background color of the entire form to a slightly darker version of the ribbon background color: ###Using TUIRibbon.BackgroundColor

1	procedure TFormMain.RibbonLoaded;
2	begin
3	  inherited;
4	  Color := ColorAdjustLuma(Ribbon.BackgroundColor, -25, False);
5	end;

We have overridden the RibbonLoaded method to do this, because we know that at this point, the ribbon properties have been loaded and are available. (BTW: The ColorAdjustLuma function is available in Delphi's GraphUtil unit).

The TUIRibbon class also has a couple of methods that may be of interest:

  • Load: to manually load a ribbon resource. You don't need this if you use TUIRibbonForm.
  • ShowContextPopup: to display a context popup that you have defined for the Ribbon. You need to pass the identifier of the popup command (that is, the name of the command you have used for this popup in the Ribbon Designer). You can optionally specify a location if you don't want it to popup at the mouse position.
  • SetApplicationModes: as discussed before, the Ribbon Framework supports up to 32 application modes. Call this method with an array of integer values to enable those application modes. For example, to enable regular mode (0) in TextPad, you would call SetApplicationModes([0]) to display the Home and View tabs. When you call SetApplicationModes([1]), the Print preview tab will be displayed. If, for some reason, you want to display all 3 tabs, you would call SetApplicationModes([0,1]).
  • SaveSettings: to save the user-customizable settings to a stream or file. Settings that a user can customize are the state of the Ribbon (Visible and Minimized), the location of the Quick Access Toolbar (above or below the Ribbon) and the items pinned to the Quick Access Toolbar.
  • LoadSettings: to load the user-customizable settings previously saved with SaveSettings.

Command Line

For command line usage in makefiles and on build servers you may call RibbonDesigner.EXE with an XML file as first parameter and /BUILD as second parameter:

RibbonDesigner.exe "Path\To\Ribbon.xml" /BUILD

If you need even more control, we provide a PowerShell script which performs the build process.

powershell -f "Generate.Ribbon.Markup.pas.ps1" "My.Ribbon.Markup.xml"

As a second optional parameter you can supply the resource name of the ribbon in the RES-file. If omitted, the name will be APPLICATION_RIBBON. The PowerShell script requires the Windows 7 or Windows 8 SDK to be installed or the UICC.EXE and UICCDLL.DLL in the same folder as the PowerShell script or part of the PATH environment variable. Alternatively you may pass the path to the Folder containing UICC.EXE and RC.EXE as third parameter, but this is optional.

Next: Executing Commands

VCL Styles

VCL styles do not work well with the Windows Ribbon Framework, see issue #86. The Windows Ribbon framework is basically an embedded ActiveX control that does some additional magic in the window title, we don't think it can be themed, currently it is themed according to the Windows version on which it is started. With a light theme you may get acceptable results, in any case you should set StyleElements.seBorderto False.

Add a custom footer
Add a custom sidebar
Clone this wiki locally