Skip to content

Tutorial: Integrating with Delphi

Jump to bottom Edit New page
Joachim Marder edited this page Jul 1, 2015 · 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:

    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.

  • 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

##The Ribbon Form

By deriving your main form from TUIRibbonForm, it will automatically take care of loading the ribbon from the resource file and displaying it. TUIRibbonForm has 4 virtual methods you may want to override:

  • RibbonResourceName: 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.
  • RibbonInstance: the module instance from which to load the Ribbon resource. If you link the resource to the executable (as you usually would), then you don't need to override this method. However, if you compile the Ribbon resource to a separate (resource) DLL, then you need to return the DLL instance from this method. In that case, you must make sure that the DLL instance is valid for the entire duration of the application (that is, do not unload the DLL until you shut down the application).
  • RibbonLoaded: this method is called right after the ribbon has been loaded from the resource. You can perform some initialization that depends on the ribbon in this method.
  • CommandCreated: every time the Ribbon Framework creates a command, it calls this method. You can override this method 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.

##TUIRibbon

The ribbon form also has a property names Ribbon of type TUIRibbon that provides access to the ribbon. This object has the following properties:

  • 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.

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.

Now we come to the meat of the application, which is how to access and execute the commands that are available on the Ribbon.

Next: Executing Commands

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