Tutorial: Specify Commands
The Windows Ribbon Framework uses a strict separation between presentation and command logic. This is somewhat similar to how you can separate presentation (Controls) and actions (TActionList and TAction components) in Delphi. The Ribbon Framework takes this a step further: you must specify commands for every action a user can take.
Like Actions in Delphi, Commands can be used by multiple Ribbon controls. For example, in WordPad, the Paste command is used in multiple places:
- On the ribbon, when the top part of the big Paste button is clicked.
- On the ribbon, when the bottom part of the bit Paste button is clicked, and the Paste menu option is selected.
- On the popup menu that appears when you right-click inside the document.
This allows you to reuse the same command in multiple places. In contrast to Actions in Delphi however, you cannot specify captions or images for ribbon controls directly. All captions, images and hints are specified at the Command level. You link commands to one or more ribbon controls to make those captions and images appear on the ribbon. ###Adding and Deleting Commands
Using the Commands toolbar in the Ribbon Designer, you can add and delete commands as well as reorder them:
You can also use the right-click menu or keyboard shortcuts (Shift+Ctrl+Ins, Ctrl+Del, Ctrl+Up and Ctrl+Down). When you delete a command, and one or more controls use this command, you will get a warning. Deleting the command will make those controls unusable.
Each command has the following properties:
- Name: each command must have a unique name, which must be a valid Pascal identifier. This name is later used to connect the command to an equally named VCL action, unless you specify a value for Symbol (see below).
- Caption: this is the caption of the command as it will appear on the ribbon or context popups. You can optionally specify an ID and Symbol for the caption. The ID will be a numeric identifier for the string resource for this caption in the resource file. Similarly, the Symbol will be the name of the constant used for this identifier. For Delphi applications, you usually don't need to specify these values and you can leave them empty.
- Description: a longer description of the command. This description is only used when the command is used in the right side of the application menu:
In this example, the Caption of the highlighted command on the right is "&Rich Text document", and the Description is "Save the document in the Rich Text format.".
-
Tooltip Title: the title of the tooltip (hint) that appear when the user hovers the mouse over the command. This title is displayed in bold at the top of the tooltip:
-
Tooltip Description: the description of the tooltip as it appears below the title.
-
Keytip: the keytip or key sequence that is used to access the command using the Alt key. This keytip appears when the user presses the Alt key to navigate the ribbon:
The Ribbon Framework will automatically apply keytips to every command. However, if you want more control over the keytips used, you can specify them yourself. A keytip is not limited to a single character.
- Symbol: the name of the Delphi action to that this command will be mapped. If you do not specify this, the Name property will be used.
- Comment: this comment is placed in the Pascal file after the constant for this command. It is used for no other purposes.
You can specify up to 4 sets of images for each command. You can specify images for when to command is displayed in Small or in Large mode (for example, as a Small or a Large button on the ribbon). You can also specify additional images for when the Windows is running in High-Contrast mode (again both Small and Large images).
Each image should be a 32-bit BMP image containing an Alpha channel. The Alpha channel is used to make parts of the image partially transparent, for example around the edges or when the image contains a slight shadow. Unfortunately, a lot of image editing applications don't allow you to save images as 32-bit BMP files with Alpha channel. Fortunately, you can use the Ribbon Designer to load PNG files with Alpha channels. Most image editing applications will support this format. The Ribbon Designer will automatically convert the image to a 32-bit BMP file.
Every command should have at least one small and one large image (unless the command is only ever displayed in Large or in Small mode, in which case you can omit one of the images). The small image should be 16x16 pixels in size, and the large image should be 32x32 pixels in size. These images are used when Windows is running at the standard screen resolution of 96 dpi (dots per inch). When a user increases the screen resolution in Windows, these images will be scaled up, which can result in blurry edges and lower quality:
 |
 |
|---|---|
| 96 dpi | 144 dpi (150%) |
To improve the quality at higher dpi settings, you can specify additional images for each command for different dpi settings. Common dpi settings are 96 dpi (default), 120 dpi (125%), 144 dpi (150%) and 192 dpi (200%). The image sizes for small and large images for these resolutions are:
| DPI | Small Image | Large Image |
|---|---|---|
| 96 dpi | 16x16 pixels | 32x32 pixels |
| 120 dpi | 20x20 pixels | 40x40 pixels |
| 144 dpi | 24x24 pixels | 48x48 pixels |
| 192 dpi | 32x32 pixels | 64x64 pixels |
The WordPad template uses additional images for all these resolutions. As a result, the ribbon images will look better (sharper) in higher resolutions:
|
 |
|---|---|
| 144 dpi with scaling | 144 dpi with additional images |
Important: the ribbon will only show the higher resolution images if your Delphi application is High-DPI aware. By default, Delphi applications are not DPI aware. To make them DPI aware, you need to modify the application manifest. The easiest way to do this with the Ribbon Framework for Delphi is like this:
- In Delphi, 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.
Now, when you build you Delphi project, it will be DPI aware and will look better at higher resolutions.
For more information about image guidelines, see the MSDN documentation. ###Specifying Images
For each set of images (Small, Large, High-Contrast), the designer shows the following frame:
You can add, delete and edit the image properties here. When you add an image, you can specify a BMP or PNG file. These should be 32-bit image files with an Alpha channel. The Ribbon Designer will automatically convert a PNG file to a 32-bit BMP file. When you open a file that is not located inside your Ribbon project directory, it will be copied to a "Res" subdirectory under the Ribbon project directory.
Each image has the following properties, which you can open by double-clicking the image or clicking the "Edit" button:
- Image File: the name of the image file, relative to the project directory.
- Minimum target resolution: one of the 4 target resolutions mentioned above, or "auto" for the default resolution.
- ID: an optional ID used to store this image in the resource file. You will usually leave this 0.
- Symbol: the name of the Pascal constant to generate for this image. You usually don't care about this, so leave it empty.
Specifying multiple images for different resolutions can become a bit tedious. That's why the Add button also has a drop-down menu that lets you add multiple images at once:
The will open the File Open dialog box again, but you can select multiple image files now. For Small Images, these should be 16x16, 20x20, 24x24 or 32x32 pixels in size. For Large Images, these should be 32x32, 40x40, 48x48 or 64x64 pixels in size. The Ribbon Designer will automatically set the "Minimum target resolution" of each image, based on the image dimensions. ###Some Tips
We finish this section with some tips:
- You should create a Command for everything you'll see on the ribbon. This includes:
- Ribbon tabs.
- Ribbon groups (a group of controls like the "Clipboard" group in the pictures above).
- Ribbon controls (buttons, menu items, check boxes, combo boxes, font controls, color pickers etc.).
- The application menu.
- The "Recent items" part of the application menu.
- The menu options shown in the application menu.
- The Quick Access Toolbar.
- The Help button at the right of the ribbon.
- Popup and context menu options.
- etc...
- You should also specify small images for ribbon groups. These will be shown when the user reduces the width of the ribbon and the group collapses into a popup:
