Description
Inserts a master menu item as the first item in the application menu.
Applies to
Syntax
controlname.InsertMasterItemFirst ( { Long ParentIndex, } String Text, String PictureName, String Clicked )controlname.InsertMasterItemFirst ( { Long ParentIndex, } RibbonMenuItem Item )
|
Argument |
Description |
|---|---|
|
controlname |
The RibbonApplicationMenu control in which you want to insert a master menu item as the first item. |
|
ParentIndex |
The index of the master menu item (RibbonMenuItem) into which you want to insert a submenu item. It cannot be an index of a separator (that is RibbonMenuItem with ItemType 1). If not specified, a master menu item will be inserted as the first item; if specified to a valid value, a submenu item will be inserted as the first item under the master menu item (whose index is ParentIndex); if specified to an invalid value, an error would occur and this operation would return -1. |
|
Text |
The text that displays in the master menu item or submenu item. |
|
PictureName |
The name of the file that contains the picture. The image will be displayed in 32*32 pixels. |
|
Clicked |
The name of the Clicked user event to be bound with the master menu item. The Clicked user event for the master menu item (RibbonMenuItem with "Normal(0)" type) must have three long parameters for receiving the handle of the application button and the index numbers of the master menu item and submenu item. For details, see Clicked. |
|
Item |
A RibbonMenuItem item you want to insert. Only RibbonMenuItem with "Normal(0)" or "Separator(1)" ItemType is supported. If RibbonMenuItem is with other ItemType such as "Recent(2)", an error would occur and this operation would return -1. |
Return value
Long.
Returns the position of the item if it succeeds and -1 if an error occurs. If any argument's value is null, returns null.
Usage
Only the menu item with the "Normal" or "Separator" type (that is RibbonMenuItem with ItemType 0 or 1) can be added as a master menu item.
The master menu can have no more than two levels.
The user events to be bound with the master menu item must be defined correctly according to the requirements of RibbonMenuItem. For details, see Clicked and Selected.
Example 1
This example inserts a master menu item "Account" as the first item and a submenu item "Account Settings" as the first item under "Account" and binds the master menu item with the "Ue_AccountMasterItemClicked" user event and the submenu item with the "Ue_AccountSettingsClicked" user event.
Long ll_Return, ll_Index
RibbonApplicationMenu lr_AppMenu
ll_Index = lr_AppMenu.InsertMasterItemFirst ("Account", "AccountBig!", "Ue_AccountMasterItemClicked")
ll_Return = lr_AppMenu.InsertMasterItemFirst (ll_Index, "Account Settings", "AccountSettingsBig!", "Ue_AccountSettingsClicked")
Example 2
This example defines three RibbonMenuItem items (lr_MenuItem1, lr_SubMenuItem1, lr_MenuSeparator1) with various properties (lr_MenuSeparator1 is set to item type 1, which means it will be displayed as a separator line; lr_MenuItem1 is set to bind with the "Ue_AccountMasterItemClicked" user event; lr_SubMenuItem1 is set to bind with the "Ue_SignOutMenuItemClicked" user event), and then inserts lr_MenuItem1 as a master menu item as the first item, lr_SubMenuItem1 as a submenu item as the first item, and lr_MenuSeparator1 as a separator line displayed above the new submenu item.
Long ll_Return, ll_Index RibbonApplicationMenu lr_AppMenu RibbonMenuItem lr_MenuItem1, lr_SubMenuItem1, lr_MenuSeparator1 lr_MenuItem1.Text = "Account" lr_MenuItem1.PictureName = "AccountBig!" lr_MenuItem1.Clicked = "Ue_AccountMasterItemClicked" lr_SubMenuItem1.Text = "Sign Out" lr_SubMenuItem1.PictureName = "SignOutBig!" lr_SubMenuItem1.Clicked = "Ue_SignOutMenuItemClicked" lr_MenuSeparator1.ItemType = 1 ll_Index = lr_AppMenu.InsertMasterItemFirst (lr_MenuItem1) ll_Return = lr_AppMenu.InsertMasterItemFirst (ll_Index, lr_SubMenuItem1) ll_Return = lr_AppMenu.InsertMasterItemFirst (ll_Index, lr_MenuSeparator1)
See also
