Users Guide
Displaying an MDI menu as a ribbon bar

If you have specified the image for the menu item through the ButtonImage property in the RibbonView tab in the menu painter, that image will be displayed in the corresponding ribbon item.

If no image is specified, for the contemporary style menu, the image specified by the MenuImage property of the menu item will be used, otherwise, the system default image will be displayed.

The following is the default image provided by the system.

For the optimal display effect, the ribbon items require the image at the appropriate size: the image for the ribbon panel, small button, and ribbon menu is 16*16 pixels, for large button is 32*32 pixels.

Please make sure the original menu images are at the appropriate size, or prepare new images whenever necessary.

The most recommended approach is to set the ButtonImage property in the menu painter > RibbonView tab for each sub menu item (such as the 2nd-level, 3rd-level, and 4th-level menu items).

If you have not set the ButtonImage property in the RibbonView tab, then if the menu item has an image specified by the MenuImage property, that image will be used as the default, otherwise, a system image will be automatically displayed in RibbonView.

When the DisplayMenuAsRibbonBar feature is enabled, internal system icons from the original menu do not display in the RibbonView.

Cause: The naming conventions for internal system icons in PowerBuilder 2017 were inconsistent -- some names included spaces and hyphens while others did not. In PowerBuilder 2019 R2 (build 2323), these icons were renamed to a standardized format, removing spaces and hyphens. Consequently, the original names cannot be found in the Select Image dialog any more. However, although the original names cannot be located, they remain compatible and visible when used in the application; the only exception is the RibbonView.

Solution: To ensure system icons display in the RibbonView, use either of the following methods:

QuickAccessToolbar is an internal sub-control of the RibbonView and cannot be used independently as a standalone control. It can only be used in the RibbonView. When a menu contains a toolbar, the ribbon bar automatically adds a corresponding QuickAccessToolbar. You can use the ShowQuickAccessToolbar property to determine whether to show the QuickAccessToolbar.

In addition to display the shortcut icons of menu items, it also provides a dropdown list to conveniently control the visibility of each shortcut icon and offer simple customization options. For instance, you can control whether a shortcut icon displays in the QuickAccessToolbar by selecting its checkbox , or use the "Show below the Ribbon" option to display the QuickAccessToolbar at the top or bottom of the ribbon bar.

The following is a description of the general rules when displaying the menu toolbar as QuickAccessToolbar:

The following features are not supported in the QuickAccessToolbar:

The "Customize Quick Access Toolbar" dropdown menu in the QuickAccessToolbar only records manual status changes made by users at runtime.

Currently, the following Toolbar properties can be supported by QuickAccessToolbar:

Usages are consistent with the Toolbar property settings. (Properties not listed are not supported)

The following pictures show the effect before and after displaying in RibbonView.

The Clear icon is originally at the last position in the drop-down list, but because its ToolbarITemOrder is set to 2, it is displayed as the second item in the drop-down list.

QuickAccessToolbar supports custom theme.

You can configure the settings under the "quickaccesstoolbar" node (as shown below) in the theme file to customize the display and style of QuickAccessToolbar. QuickAccessToolbar follows the same customization rules of the RibbonBar control. For more information, refer to Theme.

Note: Please make sure that your theme folder has been updated to the latest version. Otherwise, users who have upgraded will find that the QuickAccessToolbar position is displayed in black.

The "quickaccesstoolbar" node contains the following settings:

"quickaccesstoolbar": 
  {
   "background-color": "#FFFFFF",
   "moreitem-image": { "file": "moreitem.png" },
   "allitemvisible-image": { "file": "allitemvisible.png" },
   "item": 
   {
    "separator-color": "#A0A0A0",
    "groupseparator-image": { "file": "groupseparator.png" },
    "arrow-image": { "file": "dropdown-arrow.png" },
    "normal-state": 
    {
     "background-color": "#FFFFFF",
     "border-color": "#FFFFFF"
    },
    "hover-state": 
    {
     "background-color": "#F9E4D2",
     "border-color": "#F9E4D2"
    },
    "pressed-state": 
    {
     "background-color": "#F9D2B0",
     "border-color": "#F9D2B0"
    },
    "disabled-state": 
    {
     "background-color": "#FFFFFF",
     "border-color": "#FFFFFF"
    }
   },
   "menu": 
   {
    "border-color": "#D9D9D9",
    "background-color": "#FFFFFF",
    "separator-color": "#D9D9D9",
    "item-custom-qat": 
    {
     "normal-state": 
     {
      "background-color": "#F8EADF",
      "text-font": { "color": "#333333" }
     }
    },
    "item": 
    {
     "checked-image": { "file": "menucheck.png" },
     "normal-state": 
     {
       "border-color": "#FFFFFF",
       "background-color": "#FFFFFF",
       "text-font": { "color": "#333333" }
     },
     "hover-state": 
     {
       "border-color": "#F9E4D2",
       "background-color": "#F9E4D2",
       "text-font": { "color": "#333333" }
     },
     "disabled-state": 
     {
       "border-color": "#FFFFFF",
       "background-color": "#FFFFFF",
       "text-font": { "color": "#999999" }
     }
    },
    "scroll-spinner": 
    {
     "normal-state": 
     {
       "border-color": "#FFFFFF",
       "background-color": "#FFFFFF",
       "up-arrow-image": { "file": "scroll-spinner-up.png" },
       "down-arrow-image": { "file": "scroll-spinner-down.png" }
     },
     "hover-state": 
     {
       "border-color": "#F9E4D2",
       "background-color": "#F9E4D2",
       "up-arrow-image": { "file": "scroll-spinner-up.png" },
       "down-arrow-image": { "file": "scroll-spinner-down.png" }
     },
     "pressed-state": 
     {
       "border-color": "#F9D2B0",
       "background-color": "#F9D2B0",
       "up-arrow-image": { "file": "scroll-spinner-up.png" },
       "down-arrow-image": { "file": "scroll-spinner-down.png" }
     }
    }
   }
  }

The functions and events of the original menu will be supported in RibbonView.

The MenuChanged event of the MDI window is triggered automatically when the ribbon bar is initialized.

Long MenuChanged (string oldmenu, string newmenu)

The oldname parameter indicates the name of the menu for the MDI frame and the newname parameter indicates the name of the menu associated with the active sheet (the currently opened sheet), because several sheets can be open at the same time, and the menu associated with the active sheet will display as the menu of the frame. Whenever the sheet switches to another one, the menu and its corresponding ribbon bar of the frame will be initialized again.

If you want to add scripts to customize the ribbon bar, it is highly recommended to place the scripts in the MenuChanged event. If you place the scripts in the other events such as the MDI window Open event, the scripts may not be executed when the sheet switches to another one.

The following Menu properties can be supported in RibbonView:

Usages are consistent with the property settings of Menu. (Properties not listed are not supported)