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 and control 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.
