Introduction to Bitmap Buttons

Description

A bitmap button is a command button that displays a small picture and possibly a caption on its body. A bitmap button has its own support for bitmaps. This means that, unlike the regular button, you don't use an intermediary image list to specify the picture of a bitmap button. In fact, as we will see, the VCL's bitmap button already has many predesigned bitmaps you can directly use.

1. Start Embarcadero RAD Studio
2. To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. In the Object Inspector, change the following properties:
   Caption: Cylinder Evaluation
   Name:    frmEvaluation
   Position: poScreenCenter
4. Design the form as follows: 
    
   

   Control Alignment Caption/Text Name Other  TBevel       Style: bsRightLine TImage       Picture: cylinder.bmp  TLabel   Radius:     TEdit taRightJustify 0.00 edtRadius   TLabel   Height:     TEdit taRightJustify 0.00 edtHeight   TLabel   Base Area:     TEdit taRightJustify 0.00 edtBaseArea   TLabel   Lateral Area:     TEdit taRightJustify 0.00 edtLateralArea   TLabel   Total Area:     TEdit taRightJustify 0.00 edtTotalArea   TLabel   Volume:     TEdit taRightJustify 0.00 edtVolume

5. To save the project, on the Standard toolbar, click the Save All button
6. Click the New Folder button
7. Type CylinderEvaluation1 as the name of the folder and press Enter twice to display its content
8. Type Evaluation as the name of the unit and press Enter
9. Type CylinderEvaluation as the name of the project and press Enter
   

To support the bitmap button, the VCL provides the TBitBtn class. The TBitBtn class is derived from TCustomButton.

To visually create a bitmap button, in the Additional section of the Tool Palette, click the TBitBtn button and click the form or container. To programmatically get a bitmap button, create a pointer to TBitBtn. Using its constructor, specify its owner.

1. On the Tool Palette, click Additional
2. Click TBitBtn  and click the form on the right side of the Volume edit control
3. Save all

Because a bitmap button is usually meant to display a bitmap, you may want to provide a bitmap for it. If you want the button to also display a caption, you can proceed as the regular button and use the Caption property, either using the Object Inspector or programmatically writing code.

1. In the Additional section of the Tool Palette, click TBitBtn  and click the form on the right side of the Height edit control
2. In the Object Inspector, change the following properties:
   Caption: Calculate
   Name:    frmCalculate
    
   
3. Save all

There are two primary ways you can provide or add a bitmap to the button. Embarcadero RAD Studio ships with combinations of bitmaps and captions for a bitmap button. To let you use one of these, the TBitBtn class is equipped with a property named Kind, which is of type TBitBtnKind:

__property Buttons::TBitBtnKind Kind = {read=GetKind,write=SetKind};

The TBitBtnKind enumeration has the following members:

enum TBitBtnKind{
	bkCustom,
	bkOK,
	bkCancel,
	bkHelp,
	bkYes,
	bkNo,
	bkClose,
	bkAbort,
	bkRetry,
	bkIgnore,
	bkAll
};

To visually select one of the predesigned pictures, after adding a bitmap button to a container, in the Object Inspector, click Kind and select one of the types of buttons. Some of the buttons you create using one of the Kind types have already been configured to properly respond to the dialog box or form on which they are used. This works only if the form or dialog box is added to an existing form. The possible values of the Kind property and their effect on the application are:

Constant	Picture	Observation	Returns
bkCustom	See Below	No special role	mrNone
bkOK		This value should be used if either it is the only button on a dialog box or the user will need to acknowledge a message after performing some action on the form. In this case the user should either click this button or press Enter. After this Kind value is set, the Default property is automatically set to true, which gives the button a thick border.	mrOk
bkCancel		This value should be used if the user will need the opportunity to dismiss whatever action would have been performed on the form. The button that uses this Kind is usually accompanied by another button labeled OK. After this Kind value is set, the Cancel property is automatically set to true.	mrCancel
bkAbort		Used to display Abort.	mrAbort
bkRetry		Used to display Retry.	mrRetry
bkIgnore		Used to display Ignore.	mrIgnore
bkYes		This value should be used the user will be presented with a Yes/No question. The button should not be used with another button labeled OK on the same container. After this Kind value is set, the Default property is automatically set to true and the button gets equipped with a thick border.	mrYes
bkNo		Used to display No and return the mrAbort value	mrNo
bkHelp		Used to display Help
bkClose
bkAll		Used to display Yes to All and return the mrYesToAll value	mrYesToAll

If none of the default bitmaps is satisfying to you, you can replace it with a bitmap of your choice. If you do not like the caption, you can simply click the Caption field in the Object Inspector and type a string of your choice.

1. On the form, click the button on the right side of the Volume edit control
2. In the Object Inspector, click Kind and select bkClose
3. Save all

The bkCustom value of the Kind property allows you to set both the bitmap and the caption without using the pre-selections. In either case, the bitmap of the button is specified using the Glyph property of the TBitBtn class:

__property Graphics::TBitmap * Glyph = {read=GetGlyph,write=SetGlyph};

To visually change it in the Object Inspector, click the Glyph field and then click its ellipsis button to display the Picture Editor. This allows you to load, select, and open a bitmap of your choice. You can design your own bitmap.

1. On the form, click the button on the right side of the Height edit control
2. In the Object Inspector, click Glyph and click its button
3. In the Picture Editor, click Load
4. From the resources that accompany these lessons, select calculate.bmp and click Open
5. In the Picture Editor, click OK
    
   
6. Double-click the Calculate button to generate its OnClick event
7. Implement the event as follows:

   //---------------------------------------------------------------------------
   
   #include <vcl.h>
   #include <math.h>
   #pragma hdrstop
   
   #include "Evaluation.h"
   //---------------------------------------------------------------------------
   #pragma package(smart_init)
   #pragma resource "*.dfm"
   TForm1 *Form1;
   //---------------------------------------------------------------------------
   __fastcall TForm1::TForm1(TComponent* Owner)
   	: TForm(Owner)
   {
   }
   //---------------------------------------------------------------------------
   void __fastcall TForm1::btnCalculateClick(TObject *Sender)
   {
   	double Radius = 0.00, Height = 0.00;
   	double BaseArea, LateralArea, TotalArea, Volume;
   
   	Radius = StrToFloat(edtRadius->Text);
   	Height = StrToFloat(edtHeight->Text);
   
   	BaseArea = Radius * Radius * M_PI;
   	LateralArea = Radius * Height * 2 * M_PI;
   	TotalArea = BaseArea + LateralArea;
   	Volume = BaseArea * Height;
   
   	edtBaseArea->Text = FloatToStrF(BaseArea, ffFixed, 8, 6);
   	edtLateralArea->Text = FloatToStrF(LateralArea, ffFixed, 8, 6);
   	edtTotalArea->Text = FloatToStrF(TotalArea, ffFixed, 8, 6);
   	edtVolume->Text = FloatToStrF(Volume, ffFixed, 8, 6);
   }
   //---------------------------------------------------------------------------

8. Save all
9. Press F9 to execute
10. Enter a value in the Radius box and another value for the Height
11. Click Calculate
     
    
12. Close the form and return to your programming environment

To position itself, a bitmap uses a margin distance between its location and the button’s borders. This is controlled by the Margin property:

__property int Margin = {read=FMargin,write=SetMargin};

On a bitmap button, you can use only the bitmap, only the caption, or both the bitmap and the caption. If you decide to use both, you have the opportunity to specify how they would appear next to each other. The alignment of the bitmap with regards to the caption is controlled by the Layout property, which is based on the TButtonLayout enumerator:

__property Buttons::TButtonLayout Layout = {read=FLayout,write=SetLayout};

Its possible values are:

Value	Appearance
blGlyphLeft
blGlyphRight
blGlyphTop
blGlyphBottom

If you decide to use both a bitmap and a caption, the distance between them is controlled by the Spacing property whose default value is 4 pixels. You can change it to a reasonable value if you need to.

The bitmap used should/must have at least a 16x16 pixels size. C++Builder allows you to use a bitmap made of more than one glyph. In this case, the bitmap must be created like a single picture image list with a height of 16 pixels at most. If it contains two bitmaps, it should have a size of 32x16. The picture used for a bitmap button should not have more than 3 bitmaps. Otherwise, the fourth and beyond glyphs would be ignored.

After adding the bitmaps, C++Builder would find the number of glyphs that the bitmap contains using the “physical” size of the picture based on the fact that each bitmap has a width of 16 pixels. The number of glyphs is set using the NumGlyphs property and it is automatically set by C++Builder. Based on this, if you add a 16x16 pixels bitmap, its NumGlyphs value would be set to 1. A 32x16 bitmap would have a NumGlyphs value set to 2. A 48x16 bitmap would have the NumGlyph property set to 3. If you think that the number set by C++Builder is not right, you can change it on the Object Inspector.

Here is how the number of glyphs influences the appearance of the bitmap button:

• If the bitmap contains 1 glyph, the single bitmap would always be used except when the button is disabled. The operating system is in charge of painting the face of the button when it is disabled
• If the bitmap contains 2 glyphs, the first glyph would be used both when the button is clicked and not clicked. The second glyph would be used when the button is disabled
• If the bitmap contains 3 glyphs, the first would be used when the button displays normally. The second glyph would display while the button is down when it has been clicked. The third would display when the button is disabled