# Toolbar_InsertItem

int Toolbar_InsertItem (ToolbarType toolbar, int position, int itemType, int active, const char *description, int callbackType, int menuItem, CtrlCallbackPtr controlCallbackFunction, void *callbackData, const char *imageFile);

## Purpose

Inserts a new item onto a toolbar.

## Parameters

Input
Name | Type | Description
toolbar | ToolbarType | The specifier for the toolbar to add an item to. Obtain this handle from the Toolbar_New or Toolbar_Duplicate functions.
position | integer | The position on the toolbar where the item is to be inserted. Valid positions are from 1 to one more than the number of items on the toolbar (as returned by Toolbar_GetNumItems). You may also use FRONT_OF_LIST or END_OF_LIST to specify the beginning or the end of the list, respectively.
> itemType | integer | The control type of the item. You can specify the following values:
> kCommandButton | : Command Button
> kToggleButton | : Toggle Button
> kExclusiveToggleButton | : Exclusive Toggle Button
> kSeparator | : Separator (no control)
> kRing | : Ring
> kString | : String
> kPicturePulldownMenu | : Picture Pulldown Menu
> kTextPulldownMenu | : Text Pulldown Menu
> kMoveHandle | : Move Handle
> kColorNumeric | : Color Numeric
Exclusive toggle buttons: Use exclusive toggle buttons when you have a set of toggle options in which one and only one button is selected at a time. For example, in the File Manager, you can sort files by name, type, size, or date. Each of these options has a toggle button, but only one can be selected at a time. So, when you press one of the toggle buttons, all of the other toggle buttons are turned off automatically and return to the up position. A "set" of exclusive toggle buttons is defined entirely by the order of the buttons on the toolbar. Any group of consecutive exclusive toggle buttons will be considered a set, and any command button, ordinary toggle button, or separator item ends an exclusive toggle button set. If you insert a new exclusive toggle item where no exclusive items existed before, the item will be turned on. As you add more items to the set, the new items will be off when they are inserted. The result is that if you add a series of exclusive toggle buttons, the first one will always be on by default. You might want to use Toolbar_SetItemVal before displaying the toolbar to set a different item to the on position. If your exclusive toggle buttons are associated with menu items, then the menu item will be checkmarked whenever the button is pressed, and the checkmark will be cleared when the button is not pressed.
active | integer | Specifies whether the item is active. An active item appears on the toolbar when the toolbar is displayed, while an inactive item does not. This is useful if you want to keep a large number of items on the toolbar but selectively choose which ones are active in different situations.
description | const char * | The description of the item. Item descriptions are not normally visible, but they appear when you use the toolbar help.
callbackType | integer | The type of callback function associated with the item. This parameter is ignored if the item is a separator. You can specify the following values:
kControlCallback | : Control callback function
kMenuCallback | : Menu callback function
kNoCallback | : The item has no callback function
| Note For kControlCallback, the panel callback parameter is the ToolbarType for the associated toolbar. The control callback parameter is the item index of the pressed/operated item. For kMenuCallback, the panel callback parameter is the parent panel of the toolbar or zero if the toolbar is detached.
menuItem | integer | The menu item associated with the toolbar item. This parameter is ignored if the item is a separator or the callback type is not kMenuCallback. The menu item must specify a valid menu item on the menu bar asociated with the toolbar. Specify the toolbar menu bar in Toolbar_New. If the menu item has a callback function, the toolbar item also will use the same callback function and will pass the correct parameters, exactly as if the user had selected the menu item rather than pressing the toolbar button.
controlCallbackFunction | CtrlCallbackPtr | The callback function to be called when the item receives an event. This parameter is ignored if the item is a separator or the callback type is not kControlCallback. When using the callback function, cast the toolbar parameter to ToolbarType. The toolbar parameter represents the owning toolbar of the item that initiated the event. Likewise, toolbarItemIndex is the index of the toolbar item (the index that you would pass to any of the toolbar item functions). This event function (type CtrlCallbackPtr) takes the form: int CVICALLBACK ToolbarItemCallback(int toolbar, int toolbarItemIndex, int event, void *callbackData, int eventData1, int eventData2);
callbackData | void * | The callback data to be passed to the callback function when the item receives an event. This parameter is ignored if the item is a separator or the callback type is not kControlCallback.
imageFile | const char * | The image file that contains the image for the toolbar button. By default, images are 16 x 16 pixels. You can specify the size of all images in the toolbar with the Toolbar_SetAttribute function and the TOOLBAR_ATTR_BUTTON_IMAGE_SIZE attribute. You can use a complete pathname or a simple filename. If the name is a simple filename (that is, contains no directory path) and the file is listed in the project, then the file is loaded using the pathname from the project. If the name is a simple filename and the file is not listed in the project, then the file is loaded from the directory containing the project. The following image types are supported: PCX, BMP, DIB, RLE, ICO, JPG, PNG, WMF, and EMF. You also can specify an image for a toolbar item with the Toolbar_SetItemAttribute function and the TOOLBAR_ATTR_BUTTON_BITMAP attribute. If you specify an image for a toolbar item with the Toolbar_SetItemAttribute function, you can pass NULL for this parameter.

## Return Value

Name | Type | Description
status | integer | Return value indicating whether the function was successful. A negative number indicates that an error occurred.