IToolbarPalette.AddItem Method

Adds an item to the ToolbarPalette.

[Visual Basic .NET]
Public Function AddItem ( _
    ByVal item As Object, _
    [ByVal SubType As Integer], _
    [ByVal index As Integer] _
) As Integer

[C#]
public int AddItem (
    object item,
    int SubType,
    int index
);

[C++]
HRESULT AddItem(
  VARIANT item,
  long SubType,
  long index,
  long* insertIndex
);

[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
insertIndex [out, retval]
  insertIndex is a parameter of type long

Product Availability

Description

A ToolbarPalette supplies the implementation of a palette item that can host commands and tools. A ToolbarPalette cannot host ToolbarMenu, ToolControl or MultiItem objects.

Takes the specified command, palette or toolset and creates new items that are appended to the ToolbarPalette with their Command set, and returns the index of the first item added. Specifiy the command, palette or toolset as either a IUid, ProgID, ICommand, IPaletteDef or IToolBarDef. Any items within the IToolBarDef that are not supported will not be added to the ToolbarPalette.

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 ToolbarPalette. 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 ToolbarPalette that the Item will be added to. By default this is -1 and represents the end of the ToolbarPalette.

Errors Returned

1023 800a03ff: The specified index is out of range
1034 800a040a: The supplied command is invalid
1069 800a042d: The specified type is not supported

Remarks

AddItem checks to see if the supplied command or the commands used by the palette already exists in the CommandPool used by the ToolbarPalette. 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 IPaletteDef 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 palette as an ICommand or IPaletteDef 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.

//Get a toolbar item
IToolbarItem2 toolbarItem = (IToolbarItem2) axToolbarControl1.GetItem(0);

//Get the palette from the item  
IToolbarPalette toolbarPalette = toolbarItem.Palette;
if (toolbarPalette == null) return; 

//Add a command to the palette
toolbarPalette.AddItem("esriControlCommands.ControlsMapFullExtentCommand",-1,-1);
//Append a palette to the palette
toolbarPalette.AddItem("esriControls.ControlsInkEraserPalette",-1,-1);

'Get a toolbar item
Dim toolbarItem As IToolbarItem2
toolbarItem = AxToolbarControl1.GetItem(0)

'Get the palette from the item  
Dim toolbarPalette As IToolbarPalette
toolbarPalette = toolbarItem.Palette
If toolbarPalette Is Nothing Then Exit Sub

'Add a command to the palette
toolbarPalette.AddItem("esriControlCommands.ControlsMapFullExtentCommand", -1, -1)
'Append a palette to the palette
toolbarPalette.AddItem("esriControls.ControlsInkEraserPalette", -1, -1)

See Also