ArcObjects Library Reference (Controls)

IToolbarMenu2.AddMultiItem Method

Adds a multi-item to the ToolbarMenu.

[Visual Basic .NET]
Public Function AddMultiItem ( _
    ByVal MultiItem As Object, _
    [ByVal index As Integer], _
    [ByVal beginGroup As Boolean], _
    [ByVal Style As esriCommandStyles] _
) As Integer

[C#]
public int AddMultiItem (
    object MultiItem,
    int index,
    bool beginGroup,
    esriCommandStyles Style
);

[C#]

Optional Values

index Supply -1 as a default value.

beginGroup Supply false as a default value.

Style Supply esriCommandStyleIconAndText as a default value.

[C++]
HRESULT AddMultiItem(
  VARIANT MultiItem,
  long index,
  VARIANT_BOOL beginGroup,
  esriCommandStyles Style,
  long* itemIndex
);

[C++]
Parameters
MultiItem [in]
  MultiItem is a parameter of type VARIANT
index [in, optional, defaultvalue(-1)]
  index is a parameter of type long
beginGroup [in, optional, defaultvalue(VARIANT_FALSE)]
  beginGroup is a parameter of type VARIANT_BOOL
Style [in, optional, defaultvalue(2)]
  Style is a parameter of type esriCommandStyles
itemIndex [out, retval]
  itemIndex is a parameter of type long

Product Availability

Available with ArcGIS Engine.

Description

Takes the specified multi-item and creates new items that are appended to the ToolbarMenu with their Command set, and returns the index of the first item added. Specifiy the multi-item as either a IUID, ProgID, or IMultiItem. To add a sub menu use the AddSubMenu method.

Index determines the position on the ToolbarMenu that the item will be added to. By default this is -1 and represents the end of the ToolbarMenu.

beginGroup determines whether a separator will appear before the item. By default beginGroup is false.

Style determines the style of the item.

Errors Returned

1023 800a03FF: The specified index is out of range
1073 800a0431: The specified item is not a valid multi-item

Remarks

AddMultiItem checks to see if the supplied command already exists in the CommandPool used by the ToolbarMenu. If the command does not already exist, it is created and added to the CommandPool with a ICommandPool::UsageCount of 1, and is set as the IToolbarItem::Command. If the command already exists in the CommandPool its ICommandPool::UsageCount is incremented by 1 and the command is set as the IToolbarItem::Command. The ICommand::OnCreate method will be called the first time a command is added to the CommandPool .

Where possible always supply multi-items as either Uid objects or ProgID's. Only supply multi-items as IMultiItem objects when a IUID or ProgID does not exist, and the class is compiled as part of the same project using the ToolbarControl. Passing a multi-item as IMultiItem object has the following limitation: Multiple instances of the same multi-item can be added to the CommandPool, and each IToolbarItem::Command will point to a different command object.

[C#]

//Get a toolbar item
IToolbarItem toolbarItem = axToolbarControl1.GetItem(0);
//Get the menu from the item  
IToolbarMenu2 toolbarMenu= (IToolbarMenu2) toolbarItem.Menu;
if (toolbarMenu is NullReferenceException) return; 
//Add the multi-item to the menu
toolbarMenu.AddMultiItem("esriControls.ControlsMapBookmarksMultiItem",-1,false,esriCommandStyles.esriCommandStyleIconAndText);

[Visual Basic .NET]

'Get a toolbar item
Dim toolbarItem As IToolbarItem = AxToolbarControl1.GetItem(0)
'Get the menu from the item  
Dim toolbarMenu As IToolbarMenu2 = toolbarItem.Menu
If toolbarMenu Is Nothing Then Exit Sub
'Add the multi-item to the menu
toolbarMenu.AddMultiItem("esriControls.ControlsMapBookmarksMultiItem", -1, False, esriCommandStyles.esriCommandStyleIconAndText)

.NET Samples