InsertMasterItem

PowerScript function

Description

Inserts a master menu item at the specified position in the
application menu.

Applies to

Syntax

controlname.InsertMasterItem ( { Long ParentIndex, } Long Index, String Text, String PictureName, String Clicked )

1	controlname.InsertMasterItem ( { Long ParentIndex, } Long Index, String Text, String PictureName, String Clicked )

controlname.InsertMasterItem ( { Long ParentIndex, } Long Index, RibbonMenuItem Item )

1	controlname.InsertMasterItem ( { Long ParentIndex, } Long Index, RibbonMenuItem Item )

Argument	Description
controlname	The name of the RibbonApplicationMenu control.
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 at the specified position; if specified to a valid value, a submenu item will be inserted at the specified position 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.
Index	The index number of the master menu item or submenu item before which you are inserting a master menu item. If index is invalid, 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 is 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 in PowerScript Reference.
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 in PowerScript Reference and Selected in PowerScript Reference.

Example 1

This example inserts a master menu item “Account” and a submenu item
“Account Settings” 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.InsertMasterItem (1,"Account", "AccountBig!", "Ue_AccountMasterItemClicked")
ll_Return = lr_AppMenu.InsertMasterItem (ll_Index, 1, "Account Settings", "AccountSettingsBig!", "Ue_AccountSettingsClicked")

Long ll_Return, ll_Index

RibbonApplicationMenu lr_AppMenu

ll_Index = lr_AppMenu.InsertMasterItem (1,"Account", "AccountBig!", "Ue_AccountMasterItemClicked")

ll_Return = lr_AppMenu.InsertMasterItem (ll_Index, 1, "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), and then inserts lr_MenuItem1
as a master menu item, lr_SubMenuItem1 as a submenu item, and
lr_MenuSeparator1 as a separator line displayed below both the new submenu
item and the new master menu 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 = "Account Settings"
lr_MenuSeparator1.ItemType = 1
ll_Index = lr_AppMenu.InsertMasterItem (1, lr_MenuItem1)
ll_Return = lr_AppMenu.InsertMasterItem (ll_Index, 1, lr_SubMenuItem1)
ll_Return = lr_AppMenu.InsertMasterItem (ll_Index, 2, lr_MenuSeparator1)
ll_Index = lr_AppMenu.InsertMasterItem (2, lr_MenuSeparator1)