ArcObjects Library Reference (Controls)  

IToolbarMenu.AddItem Method

Adds an item to the ToolbarMenu.

ERROR: Syntax information about IToolbarMenu.AddItem may not be in D:\ArcGIS\DotNet\ESRI.ArcGIS.Controls.dll

[C++]
HRESULT AddItem(
  VARIANT item,
  long SubType,
  long index,
  VARIANT_BOOL beginGroup,
  esriCommandStyles Style,
  long* itemIndex
);
[C++]

Parameters

item [in]   item is a parameter of type VARIANT SubType [in, optional, defaultvalue(0)]   SubType is a parameter of type long 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

A ToolbarMenu supplies the implementation of a menu item that can host commands, menus, palettes and multi-items.

Takes the specified command, menu or palette 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 command, menu or palette as either a IUid, ProgID, ICommand , IMenuDef or IPaletteDef. To add a sub menu use the AddSubMenu method. To add a MultiItem use the IToolbarMenu2::AddMultiItem method. Note a palette object will be automatically added as a sub menu.

Supply a subType when passing an ICommandSubType. If no subType is supplied and the command is passed as a IUid or ProgID then ICommandSubType::GetCount determines the number of item's to be added to the ToolbarMenu. A subType must be supplied when passing an ICommandSubType as an ICommand, or the method will fail. By default subType is 0.

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

1035 800A040B: The subtype specified for the command (possibly in a UID object) is invalid or out of range 

1038: Tool control is already on a ToolbarControl, only one instance of a tool control can be added

1049 800A0419 The supplied style is not valid for this Toolbar item 

1050 800A041A: The item being added is  invalid -Tools and ToolControls may not be added to menus 

1064 800A0428: A command or a toolbar cannot be added as a menu item. 

1068: A subtype must be specified when adding an ICommandSubType object

Remarks

AddItem checks to see if the supplied command or the commands used by the menu 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 commands and menus as either Uid objects or ProgID's. Only supply commands as ICommand or IMenuDef 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 command or menu as an ICommand or IMenuDef object has the following limitation: Multiple instances of the same command 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 a the menu from the item  
IToolbarMenu toolbarMenu = toolbarItem.Menu;
if (toolbarMenu == null) return; 

//Add a command to the menu
IUID uID = new UIDClass();
uID.Value = "esriControlCommands.ControlsMapFullExtentCommand";
toolbarMenu.AddItem(uID,-1,-1,false,esriCommandStyles.esriCommandStyleIconAndText);

//Append a menu to the menu
string progID = "esriControlCommands.ControlsMapViewMenu";
toolbarMenu.AddItem(progID,-1,-1,false,esriCommandStyles.esriCommandStyleIconAndText);
[Visual Basic .NET]
'Get a toolbar item
Dim pToolbarItem As IToolbarItem
pToolbarItem = AxToolbarControl1.GetItem(0)

'Get a the menu from the item  
Dim pToolbarMenu As IToolbarMenu
pToolbarMenu = pToolbarItem.Menu
If pToolbarMenu Is Nothing Then Exit Sub

'Add a command to the menu
Dim pUid As New UIDClass
pUid.Value = "esriControlCommands.ControlsMapFullExtentCommand"
pToolbarMenu.AddItem(pUid)

'Append a menu to the menu
Dim sProgID As String
sProgID = "esriControlCommands.ControlsMapViewMenu"
pToolbarMenu.AddItem(sProgID)

See Also

IToolbarMenu Interface

.NET Snippets

Add Editing Commands to ToolbarControl

.NET Samples

Creating toolbar menus that work with the ToolbarControl (Code Files: ToolbarMenu) | Cut polygons without selection edit task (Code Files: EditingForm) | Custom reshape polyline edit task (Code Files: EditingForm) | Network Analyst Engine application (Code Files: frmMain) | Displaying a TOCControl context menu (Code Files: TOCContextMenuForm) | Add a custom bookmarks MultiItem to the ToolbarControl (Code Files: MultiItemBookmarks) | Managing snap agents (Code Files: EditingForm) | Using HookActions in custom commands (Code Files: HookActions) | Custom vertex editing commands (Code Files: EditingForm) | Building a MapViewer application using the ArcGIS Engine controls (Code Files: MapViewer) | Implementing a property page for an ArcGIS Engine application (Code Files: TocContextMenuClass) | Save a layer file in a MapControl application (Code Files: ContextMenuClass) | Edit event listener (Code Files: EditingForm) | Schematics Engine application (Code Files: MainForm) | Feature editing with the control commands (Code Files: FeatureEditing)

.NET Related Topics

Enabling menu tracking on the ToolbarControl