A button on a toolbar can be made to display text, just as done on a menu item. In order to prepare its buttons to show text, a toolbar must allow it. To support this, the TToolBar class is equipped with the AllowTextButtons property:

__property bool AllowTextButtons =
{
    read=FAllowTextButtons,
    write=SetAllowTextButtons
};

To configure this visually, access the Object Inspector for the toolbar and set its AllowTextButtons field to True. In the same way, you can programmatically set this property. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->AllowTextButtons = True;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
}
//---------------------------------------------------------------------------

After allowing text buttons, when creating a button, assign text to its Caption property. Of course, you can do this visually in the Object Inspector or programmatically. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->AllowTextButtons = True;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "New";
}
//---------------------------------------------------------------------------

Besides, or instead of, text, a button can be made to show a picture or else. This characteristic is handled by the Style property of the TToolButton class:

__property Comctrls::TToolButtonStyle Style = {read=FStyle,write=SetStyle};

The style of a button is based on the TToolButtonStyle enumeration. To indicate that you want a button to appear with text (only), specify its Style property as tbsTextButton. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->AllowTextButtons = True;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "New";
	btnToolbar->Style = tbsTextButton;
}
//---------------------------------------------------------------------------

In the same way, you can add as many buttons as you want.

On a toolbar, a separator that appears with | as its caption. To help you create a separator, create a new button and set its Style to tbsSeparator. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->AllowTextButtons = True;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "New";
	btnToolbar->Style = tbsTextButton;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "Open";
	btnToolbar->Style = tbsTextButton;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Style = tbsSeparator;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "Print";
	btnToolbar->Style = tbsTextButton;
}
//---------------------------------------------------------------------------

Instead of (or besides) text, a button can display (only) a picture. To start, you must create an image list and assign it to the toolbar. To support bitmaps on a button, the TToolBar class is equipped with the Images property that is of type TCustomImageList:

__property Imglist::TCustomImageList * Images = {read=FImages,write=SetImages};

To property a toolbar to have its buttons display bitmaps, assign a TImageList collection to its Images property. You can do this visually or programmatically. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TImageList * lstImages = new TImageList(this);
	Graphics::TBitmap *bmpImage = new Graphics::TBitmap;

	bmpImage->LoadFromFile(L"C:\\buttons\\new.bmp");
	lstImages->Add(bmpImage, NULL);
	bmpImage->LoadFromFile(L"C:\\buttons\\open.bmp");
	lstImages->Add(bmpImage, NULL);

	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->Images = lstImages;
}
//---------------------------------------------------------------------------

To support bitmaps, the TToolButton class is equipped with an indexed property named ImageIndex:

__property int ImageIndex = {read=FImageIndex,write=SetImageIndex};

To visually specify the index of a button, click it on the form and select the number in the ImageIndex field of its Object Inspector. To do this programmatically, assign the desired number to the ImageIndex proeprty. Here are examples:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TImageList * lstImages = new TImageList(this);
	Graphics::TBitmap *bmpImage = new Graphics::TBitmap;

	bmpImage->LoadFromFile(L"C:\\buttons\\new.bmp");
	lstImages->Add(bmpImage, NULL);
	bmpImage->LoadFromFile(L"C:\\buttons\\open.bmp");
	lstImages->Add(bmpImage, NULL);

	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->Images = lstImages;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->ImageIndex = 0;

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->ImageIndex = 1;
}
//---------------------------------------------------------------------------

1. On the Tool Palette, click Win32
2. Click TImageList and click the form
3. On the form, double-click ImageList1
4. Click Add and add the following images: new.bmp, open.bmp, save.bmp, and print.bmp
5. Click OK
6. On the form, click the toolbar
7. In the Object Inspector, click Images and select ImageList1
8. On the form, right-click the toolbar and click New Button
9. Right-click the right side of the first button and click New Button
10. Right-click the empty area on the toolbar and click New Button
11. Right-click the empty area on toolbar click New Separator
12. Right-click the empty area on the toolbar and click New Button
13. On the toolbar, click the second button from the left
14. In the Object Inspector, click Events
15. Click OnClick, click the arrow of the field and select Open1Click
16. In the Object Inspector, click Properties
17. Press F9 to test the project
18. On the form, click the second button from left, select a picture, and click Open
19. Close the application and return to your programming environment

You can make a button behave like a check box. That is, when the button is clicked, it gets down. If the button was down, when it is clicked, it becomes up. To support this, the Style of the TToolButton class has a member named tbsCheck. Therefore, to get this behavior, first set the Style to tbsCheck.

To support the scenario of being up or down, the TToolButton class is equipped with a Boolean property named Down:

__property bool Down = {read=FDown,write=SetDown};

To set a button down, set this property to True. To set it up, change this property to False. Since this is a read-write property, at any time, to get its state, check the value of the Down property. Here is an example that changes the down-up state and vice versa:

//---------------------------------------------------------------------------
void __fastcall TForm1::ToolButton1Click(TObject *Sender)
{
	ToolButton1->Down != ToolButton1->Down;
}
//---------------------------------------------------------------------------

You can make a group of button behave in mutual exclusion. That is, when one of the buttons in the same group is clicks, it gets down and the other buttons become up. To support this, the TToolButton class is equipped with the Grouped Boolean property.

To implement the mutual exclusive scenario:

1. Create a separator to group the buttons
2. For each button in the group:
   • Set the Grouped property to True
   • Set the Style to tbsCheck

You can create a button that is made of two parts. The regular part is on the left side and the right side has a down-pointint arrow. When the user clicks the down-pointing arrow, a menu would display.

To create menu-equipped button, first create a popup menu. To implement this functionality, set the Style of the TToolButton to tbsDropDown. To let you apply a menu on a button, the TToolButton class is equipped with a property named DropDownMenu:

__property Menus::TPopupMenu * DropdownMenu = {read=FDropdownMenu,
					       write=SetDropdownMenu};

After creating a popup menu, assign it to the DropDownMenu property. You can do this using the Object Inspector or with code. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TToolButton *btnToolbar = NULL;
	TToolBar *tbrStandard = new TToolBar(this);
	tbrStandard->Parent = this;
	tbrStandard->ShowCaptions = True;

	TPopupMenu *mnuPopup = new TPopupMenu(this);
	TMenuItem *mnuItem = new TMenuItem(this);
	mnuItem->Caption = "First";
	mnuPopup->Items->Add(mnuItem);
	mnuItem = new TMenuItem(this);
	mnuItem->Caption = "Second";
	mnuPopup->Items->Add(mnuItem);
	mnuItem = new TMenuItem(this);
	mnuItem->Caption = "Third";
	mnuPopup->Items->Add(mnuItem);

	btnToolbar = new TToolButton(tbrStandard);
	btnToolbar->Parent = tbrStandard;
	btnToolbar->Caption = "New";
	btnToolbar->Style = tbsDropDown;
	btnToolbar->DropdownMenu = mnuPopup;
}
//---------------------------------------------------------------------------

This would produce:

Of course, you can use a button that shows only text, only a bitmap, or both.

When you add a toolbar to a form, it automatically positions itself to the top section of the form and uses the same width as the form. This means that the default Align value of a toolbar is alTop.

Besides its width, a toolbar is caterized by its height. When newly added to a form, a toolbar receives a default height of 29. You can change it if you want, by assigning a new value to its Height property.

To hold its collection of objects, the TToolBar class is equipped with a property named Buttons:

__property Comctrls::TToolButton * Buttons = {read=GetButton};

The TToolBar::Buttons property is a read-only collection. This means that it can only give you information about buttons that already exist on the toolbar. You cannot use it to create buttons.

To keep track of the buttons positioned on it, a toolbar provides other pieces of information such as

• The number of buttons on it, represented by the ButtonCount read-only property:

  __property int ButtonCount = {read=GetButtonCount};

• The width of each button, represented by the ButtonWidth property:

  __property int ButtonWidth = {read=FButtonWidth,write=SetButtonWidth};

• The height of each button, represented by the ButtonHeight property:

  __property int ButtonHeight = {read=FButtonHeight,write=SetButtonHeight};

You can create a toolbar that either share the items with a main menu or acts itself as a main menu. To start, create a TMainMenu object with all the necessary options. If you don't want the form to display it, delete the value of its Menu property. To make a toolbar hold the main menu, the TToolBar class has a property named Menu:

__property Menus::TMainMenu * Menu = {read=FMenu,write=SetMenu};

Assign a TMainMenu object to the Menu property of your TToolBar object.

If you create a form that display a menu, whether it is a main menu or a popup menu, to make some menu items appealing, you can add pitures to them. Here are examples:

To keep up with this tendency, the VCL makes it very easy to add pictures to menu items; all this without writing a single line of code.

To display a pictue on a menu item, you have two primary options.

The TMenuItem class is equipped with a property named Bitmap, which is of type TBitmap:

__property Graphics::TBitmap * Bitmap = {read=GetBitmap,write=SetBitmap};

After visually creating a menu, to apply a bitmap to a menu item, in the Menu Designer, click that item. In the Object Inspector, click Bitmap and click its button. In the Picture Editor, click Load. Locate a bitmap, select it, and click Open. In the Picture Editor, click OK.

To programmatically specify the picture to apply to a menu, access its Bitmap propert and assign an initialized TBitmap object to it. Here are examples:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	Graphics::TBitmap *bmpImage = new Graphics::TBitmap;
	TMainMenu *mnuMain = new TMainMenu(this);

	TMenuItem *mnuFile = new TMenuItem(this);
	mnuFile->Caption = L"&File";

	bmpImage->LoadFromFile(L"C:\\Some Images\\new.bmp");

	TMenuItem *mnuFileNew = new TMenuItem(this);
	mnuFileNew->Caption = L"&New";
	mnuFileNew->Bitmap = bmpImage;
	mnuFile->Add(mnuFileNew);

	bmpImage->LoadFromFile(L"C:\\Some Images\\open.bmp");

	TMenuItem *mnuFileOpen = new TMenuItem(this);
	mnuFileOpen->Caption = L"&Open";
	mnuFileOpen->Bitmap = bmpImage;
	mnuFile->Add(mnuFileOpen);

	mnuMain->Items->Add(mnuFile);
}
//---------------------------------------------------------------------------

An alternative to show pictures on menu items consists of using an image list. To prepare pictures to display on a menu item, first create an image list. Using the Image List Editor, add the necessary pictures. Normally, the picture can be of any type but it is better to use icons.

To support this solution, the TMenu class, which is the parent of TMainMenu, has a property named Images:

__property Imglist::TCustomImageList * Images = {read=FImages,write=SetImages};

As you can see, the TMenu::Images property is an object of type TCustomImageList, which is the parent of the TImageList class. After creating an image list, to visually specify that you want to use its pictures on a menu, on the form, click the main menu. In the Object Inspector, set the value of the Images field to the image list control. To do this programmatically, after creating a TMainMenu object, assign a TImageList value to its Images property. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TImageList * lstImages = new TImageList(this);
	
	. . . Add images to the image list

	TMainMenu *mnuMain = new TMainMenu(this);
	mnuMain->Images = lstImages;
}
//---------------------------------------------------------------------------

To support this solution, the TMenuItem class is equipped with a property named ImageIndex. After assigning an image list to a main menu, to visually apply a picture to a menu item, in the Menu Designer, click a menu item. In the Object Inspector, select a value in the ImageIndex field. To do this programmatically, assign the integer index to the menu item. Here are examples:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	TImageList * lstImages = new TImageList(this);
	Graphics::TBitmap *bmpImage = new Graphics::TBitmap;

	bmpImage->LoadFromFile(L"C:\\Some Images\\new.bmp");
	lstImages->Add(bmpImage, NULL);
	bmpImage->LoadFromFile(L"C:\\Some Images\\open.bmp");
	lstImages->Add(bmpImage, NULL);
	bmpImage->LoadFromFile(L"C:\\Some Images\\save.bmp");
	lstImages->Add(bmpImage, NULL);
	bmpImage->LoadFromFile(L"C:\\Some Images\\print.bmp");
	lstImages->Add(bmpImage, NULL);

	TMainMenu *mnuMain = new TMainMenu(this);
	mnuMain->Images = lstImages;

	TMenuItem *mnuFile = new TMenuItem(this);
	TMenuItem *mnuFileNew = new TMenuItem(this);
	TMenuItem *mnuFileOpen = new TMenuItem(this);

	mnuFile->Caption = L"&File";

	mnuFileNew->Caption = L"&New";
	mnuFileNew->ImageIndex = 0;
	mnuFile->Add(mnuFileNew);

	mnuFileOpen->Caption = L"&Open";
	mnuFileOpen->ImageIndex = 1;
	mnuFile->Add(mnuFileOpen);

	mnuMain->Items->Add(mnuFile);
}
//---------------------------------------------------------------------------

1. On the form, click MainMenu1
2. In the Object Inspector, click Images and select ImageList1
3. On the form, right-click MainMenu1 and click Menu Designer...
4. In the Menu Designer, under File, click New
5. In the Object Inspector, click ImageIndex, click the arrow of its combo box and select 0
6. In the Menu Designer, under File, click Open
7. In the Object Inspector, click ImageIndex, click the arrow of its combo box and select 1
8. In the Menu Designer, under File, click Save
9. In the Object Inspector, click ImageIndex, click the arrow of its combo box and select 2
10. In the Menu Designer, under File, click Print...
11. In the Object Inspector, click ImageIndex, click the arrow of its combo box and select 0
12. Close the Menu Designer
13. Press F9 to test the project
14. On the form, click File and see the pictures on the menu items
15. Close the form and return to your programming environment