The RibbonBar Converter exports the menu structure to an XML file, allowing users to perform advanced customizations far beyond what RibbonView offers.
With this approach, you have full control over the design and behavior of the RibbonBar, making it ideal for complex projects with specific UI/UX requirements.
You can export the menu into an XML file in the following way:
-
If you right-click the top-level menu object and then select Export to RibbonBar XML, the entire menu will be exported as a ribbon bar in the XML format.
The XML file (or string) can be loaded by the ImportFromXMLFile (or ImportXML) function.
Note
It is unsupported to export a menu that is created dynamically at runtime.
It is unsupported to export the toolbar, therefore the file will not include the QuickAccessToolbar.
The export rules are the same as the RibbonView rules.
-
If you right-click the 1st-level menu item and then select Export to RibbonBar XML, that menu item (including its sub-menus) will be exported as a ribbon category in the XML format.
This file can be loaded by the ReplaceCategoryByXML function.
Note
It is unsupported to export the 2nd-level, 3rd-level, or 4th-level menu item only to the XML file.
After you export the menu to the XML file, you can customize the file in the RibbonBar Builder and then load this customized ribbon bar via the ImportFromXMLFile or ImportXML function.
Here are complete steps for how to do that:
-
Export the menu to an XML file by right-clicking the menu object or the 1st-level menu item in the menu treeview, and then selecting Export To RibbonBar XML.
-
Open the RibbonBar Builder by selecting the Tools > RibbonBar Builder menu from the PowerBuilder IDE, and then load the exported XML file to the RibbonBar Builder by selecting the Open File menu.
-
In the RibbonBar Builder, customize the ribbon bar by changing the contents of the XML file and previewing the result. Save the XML file or as an XML string when finishing customization.
The ribbon items: category, panel, large button, small button, and ribbon menu exported from the menu are automatically mapped and bound to the corresponding standard ribbon item controls: RibbonCategoryItem, RibbonPanelItem, RibbonLargeButton, RibbonSmallButton, and RibbonMenuItem.
You can customize the ribbon items through the properties, events, and functions of these controls.
Note
During the manual modification of XML, ensure that the original MenuItemName values are not altered. Otherwise, the mapping relationship will be broken, leading to the inability to trigger the corresponding events for the MenuItem when the relevant button is clicked.
-
Load the XML file or string via the ImportFromXMLFile, ImportXML or ReplaceCategoryByXML function in the MenuChanged event of the MDI window.
Code example 1:
li_rtn = mdirbb_1.ImportFromXMLFile ("Export2.xml")Code example 2:
li_rtn = mdirbb_1.importxml(ls_xml)
Code example 3:
ls_tag ="Edit" li_return = mdirbb_1.getitembytag(ls_tag, lr_Category) If li_Return = 1 Then li_return = mdirbb_1.replacecategorybyxml(lr_Category.itemhandle, ls_xml) End If
Note
In order for the MenuChanged event to be triggered successfully, the DisplayMenuAsRibbonBar property must be enabled.
The mdirbb_1 object represents the ribbon bar displayed from the menu. For more information about mdirbb_1, refer to the next section.
Each MDI/MDIHelp window defines an mdirbb_1 object by default in the window's source code (similar to mdi_1 and mditbb_1).
When a menu is converted and displayed as a ribbon bar, that ribbon bar will be bound with the mdirbb_1 object.
The definition of the mdirbb_1 object in the MDI window is like below:
(Note that the mdirbb_1 object inherits from the RibbonBar control, therefore it has the properties, functions and events of the RibbonBar control.)
The ribbon items: category, panel, large button, small button, and ribbon menu exported from the menu are all standard ribbon item controls: RibbonCategoryItem, RibbonPanelItem, RibbonLargeButton, RibbonSmallButton, and RibbonMenuItem.
And the properties, functions, and events of the menu item are automatically mapped and bound to the corresponding standard ribbon item control.
The following Menu properties are mapped to the corresponding ribbon XML elements (properties not listed are not supported):
|
Properties of Traditional Style Menu |
Properties of Contemporary Style Menu |
XML Element of Ribbon Control |
|
Name |
Name |
MenuItemName |
|
Text |
Text |
Text |
|
MicroHelp |
MicroHelp |
PowerTipDescription |
|
Tag |
Tag |
Tag |
|
Visible |
Visible |
Visible |
|
Enabled |
Enabled |
Enabled |
|
Checked |
Checked |
Checked |
|
Default |
Default |
DefaultCommand |
|
Shortcut |
Shortcut |
Shortcut |
|
-- |
MenuImage |
PictureName |
|
-- |
FaceName |
Font |
|
-- |
TextSize |
TextSize |
-
Name vs. MenuItemName
MenuItemName -- The unique identifier of the ribbon item that is converted from the menu item. It is by default the same value as the Name property of the original menu item. This property value associates the ribbon item with the menu item, so that the events of the menu item will be triggered successfully after conversion. You might want to use this property value only when you want to associate a ribbon item with a menu item, for example, when you create a new ribbon item and want to trigger the event of a menu item, you can associate the menu item with the new ribbon item by setting the Name property value of the menu item as the value of the MenuItemName property of the ribbon item.
The MenuItemName XML element is available for the RibbonCategoryItem, RibbonSmallButtonItem, RibbonLargeButtonItem, and RibbonMenuItem control.
-
MicroHelp vs. PowerTipDescription
The text value of the MicroHelp property of the original menu item will be synchronized to the PowerTipDescription property value of the corresponding ribbon item control (such as RibbonCategoryItem, RibbonSmallButtonItem, RibbonLargeButtonItem, and RibbonMenuItem).
The text will display in the status area at the bottom of the frame as well as in the pop-up (if PowerTipText is set, PowerTipDescription shows below the PowerTipText) when the user moves a cursor over the control.
-
The traditional-style menu does not have properties such as MenuImage, FaceName, and TextSize, therefore, the default font name and text size of the RibbonBar control (Tahoma 12) will be used, and the corresponding XML element PictureName (if set) will be used as the default image.
Other than that, the MDI frame window has added a new event to help developers customize the ribbon bar:
-
MenuChanged event -- Occurs when the ribbon bar is initialized. The DisplayMenuAsRibbonBar property must be enabled in order for this event to be triggered successfully. The
oldnameparameter indicates the name of the menu for the MDI frame and thenewnameparameter 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, and whenever the sheet switches to another one, the menu (and the corresponding ribbon bar) of the frame will be initialized again.To ensure the scripts that customize the ribbon bar are executed whenever the sheet switches to another one, it is 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.
The RibbonBar control has added two new functions:
-
ReplaceCategoryByXML -- Replaces an existing category with the category from an XML file.
-
ReplaceCategoryByJSON -- Replaces an existing category with the category from a JSON file.
One-way conversion means:
-
The menu properties that are dynamically set will be reflected in the ribbon bar.
-
However, the ribbon bar properties that are dynamically set will not be reflected back in the original menu.
Following uses an example to show how one-way conversion may affect the code logic and the developer should take this into consideration.
Phenomenon:
After enabling a menu item via the ReplaceCategoryByXml or ReplaceCategoryByJSON method, it is found that the Clicked event of the menu item in the ribbon bar cannot be triggered.
Reason:
If the menu item is disabled by default, even by customizing and setting the enabled property to true, its clicked event still cannot be triggered in the ribbon bar.
For example:
When the first sheet window or the default MDI Frame window is opened, the enabled property of the Undo menu item (m_undo) is set to false by default.
When you open the third sheet window and use the ReplaceCategoryByXML or ReplaceCategoryByJSON method to customize a category (such as Edit), and set the enabled property of the Undo button to true, although the Undo button in the ribbon bar is enabled, the enabled property of the original Undo menu item (m_undo) is still false. Therefore, the Clicked event of the original Undo menu item (m_undo) cannot be triggered.
Solution:
-
#1: Set the enabled property of the original Undo menu item (m_undo) to true in the script. This ensures that the clicked event of the Undo button in the RibbonBar control can be triggered normally.
-
#2: When using the ReplaceCategoryByXml or ReplaceCategoryByJSON method to customize the corresponding Undo button, define a clicked event for the button at the same time.
