Introduction to the Category Buttons Control

Description

A category button is a control container that uses one or more sections. Each section holds one (rectangular) button or a group of (rectangular) buttons. In fact, each section is constructed like a button group. Besides being able to hold more than one group of buttons, one of the differences between a button group and a category button is that the group of buttons in a category button can be minimized or collapsed. That is, the user can hide the buttons of a particular group and keep the button(s) of the other series visible.

1. To start a new application, on the main menu, click File -> New -> VCL Forms Application - C++Builder
2. In the Object Inspector, change the properties of the form as follows:
   Caption: Geometric Shapes
   Name:    frmGeometry
   Position: poScreenCenter
3. To save the project, on the Standard toolbar, click the Save All button
4. Click the New Folder button
5. Type GeometricShapes1 as the name of the folder and press Enter twice to display its content
6. Type Geometry as the name of the unit and press Enter
7. Type GeometricShapes as the name of the project and press Enter
8. Press F9 to test the project
9. Close the form
10. Copy each one of these images and paste it in the Debug folder of this project:
     
11. Return to your programming environment

The category buttons control is available from a class named TCategoryButtons, which is defined in the CategoryButtons.hpp header file. The TCategoryButtons class is derived from TCustomControl that is based on TWinControl:

To visually create a category buttons control, in the Additional section of the Tool Palette, click the TCategoryButtons icon and click the form. To programmatically create a category buttons control, declare a variable of type TCategoryButtons. Use the new operator to initialize it and specify its owner. Also make sure you specify its parent. Here is an example:

//---------------------------------------------------------------------------

#include <vcl.h>
#include <CategoryButtons.hpp>

#pragma hdrstop

#include "Unit1.h"
//---------------------------------------------------------------------------
#pragma package(smart_init)
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
	: TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
	TCategoryButtons * SeriesOfButtons = new TCategoryButtons(Form1);
	SeriesOfButtons->Parent = Form1;
}
//---------------------------------------------------------------------------

1. Design the form as follows: 
    
   

   Control Align Center Color Name Kind  TCategoryButtons       cbtGeometry   TPanel     clWhite     TImage alClient True   imgShape   TBitBtn         bkClose

2. Save all

A category buttons control is a Windows control. It gets its foundational characteristics from the TWinControl and the TControl classes. For this reason, in must have a name, a location, and a size. Here is an example of applying some of these features:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
	TCategoryButtons * SeriesOfButtons = new TCategoryButtons (Form1);
	SeriesOfButtons->Parent = Form1;

	SeriesOfButtons->Left = 8;
	SeriesOfButtons->Top  = 40;
}
//---------------------------------------------------------------------------

A category buttons controls if primarily one button group or a series of button groups. This means that, to make a buttons group control available in your application, the first thing you must do is to create one or more button groups.

To visually create a category, right-click the category buttons control and click Category Editor:

This would open the Editing Category Buttons Category window:

To create a category:

• Click the New button
• Right-click the window and click Add
• Press Ins

This would create one category. In the same way, you can create as many categories as necessary. By default, each new category appears a horizontal bar that uses the whole width of the category buttons control.

To hold its series, the TCategoryButtons class is equipped with a property named Categories. The TCategoryButtons::Categories property is an indexed property based on a class named TButtonCategories:

__property Categorybuttons::TButtonCategories * Categories = 
{
    read=FButtonCategories,
    write=SetButtonCategories
};

The TButtonCategories class is derived from TItemCollection that itself is based on the TCollection class.

Each member of the TButtonCategories class is of type TButtonCategory. The TButtonCategory class is derived from TBaseItem, which is the parent of the TCollectionItem class. Based on this, to programmatically create a category, you can call the Add() method that the TCategoryButtons class inherits from TCollection. The TButtonCategories::Add() method returns a TButtonCategory object. When calling the Add() method, you should make sure you get this returned value so you can use it later. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
	TCategoryButtons * SeriesOfButtons = new TCategoryButtons (Form1);
	SeriesOfButtons->Parent = Form1;

	SeriesOfButtons->Left = 8;
	SeriesOfButtons->Top  = 40;

	TButtonCategory *Category = SeriesOfButtons->Categories->Add();
}
//---------------------------------------------------------------------------

In the same way, you can create as many categories as you want.

1. On the form, right-click the category buttons control and click Categories Editor...
2. Right-click inside the Editing Category Buttons Category window and click Add
3. To create another category, press Ins
4. On the Editing Category Buttons Category window, the New button

Normally, a category appears as an empty colored bar. To make it useful, it must contain one or more buttons. To visually create the buttons of a category, in the Editing Category Buttons Categories, click the category. Then, in the Object Inspector, click Items and click its button. This would open the Editing Category Buttons Items window. To visually create a button:

• Click the New button
• Right-click the window and click Add
• Press Ins

Any of these actions would create a new button.

As mentioned already, a/each category should contain at least one button. The buttons of a category are represented in the TButtonCategory class by a property named Items, which is an indexed property that contains TButtonCollection items:

__property Categorybuttons::TButtonCollection * Items = 
{
    read=FItems,
    write=SetItems
};

Each button of a category is of type TButtonItem. To programmatically create a button, you can call the Add() method. This method returns a TButtonItem object. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
	TCategoryButtons * SeriesOfButtons = new TCategoryButtons (Form1);
	SeriesOfButtons->Parent = Form1;

	SeriesOfButtons->Left = 8;
	SeriesOfButtons->Top  = 40;

	TButtonCategory *Category = SeriesOfButtons->Categories->Add();
	TButtonItem * btn = Category->Items->Add();
}
//---------------------------------------------------------------------------

Getting the result of the Add() method, you can set the desired properties of the button.

1. In the Editing Category Buttons Category window, click 0 - TButtonCategory
2. In the Object Inspector, click Items and click its ellipsis button
3. On the Editing Category Buttons Items window, the New button
4. Click it again to get a second buttons
5. In the Editing Category Buttons Category window, click 1 - TButtonCategory
6. In the Object Inspector, click Items and click its ellipsis button
7. While the Editing Category Buttons Items window has focus, press Ins four times to get four buttons
8. In the Editing Category Buttons Category window, click 2 - TButtonCategory
9. In the Object Inspector, click Items and click its ellipsis button
10. Right-click inside the Editing Category Buttons Items window and click Add
11. Right-click the Editing Category Buttons Items window and click Add 4 times to get 5 buttons
12. Save all

A category buttons control uses some of the same characteristics as the button group. A category buttons control appears with a 3-D border. This characteristic is set by the BorderStyle property that is of type TFormBorderStyle:

__property Forms::TFormBorderStyle BorderStyle = 
{
    read=FBorderStyle,
    write=SetBorderStyle
};

If you want the control to appear flat, set this property to bsNone. You can do it programmatically as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
    TCategoryButtons * SeriesOfButtons = new TCategoryButtons (Form1);
    SeriesOfButtons->Parent = Form1;

    SeriesOfButtons->Left = 8;
    SeriesOfButtons->Top  = 40;
    SeriesOfButtons->BorderStyle = bsNone;
}
//---------------------------------------------------------------------------

To enhance its usefulness, a category buttons control uses various options that are controlled by its ButtonOptions property:

__property System::Set ButtonOptions = 
{
    read=FButtonOptions,
    write=SetCatButtonOptions
};

The ButtonOptions set uses the following members:

enum Categorybuttons__2{
	boAllowReorder,
	boAllowCopyingButtons,
	boFullSize,
	boGradientFill,
	boShowCaptions,
	boVerticalCategoryCaptions,
	boBoldCaptions,
	boUsePlusMinus,
	boCaptionOnlyBorder
};

If you want the user to be able to modify the order of the buttons in the categories, set the gboAllowReorder member of the ButtonOptions value to True. Then, to order the buttons, the user can click and drag a button to drop it in a different position.

A button can be made to show a caption. This is possible because each button has a Caption property. To make sure the buttons can show captions, you must set the gboShowCaptions member of the ButtonOptions value to True. Then, assign the desired caption to a button. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnCategoryButtonsClick(TObject *Sender)
{
	TCategoryButtons * SeriesOfButtons = new TCategoryButtons (Form1);
	SeriesOfButtons->Parent = Form1;

	SeriesOfButtons->Left = 8;
	SeriesOfButtons->Top  = 40;

	TButtonCategory *Category = SeriesOfButtons->Categories->Add();
	TButtonItem * btn = Category->Items->Add();

	btn->Caption = L"Set";
}
//---------------------------------------------------------------------------

Not all buttons have to have captions. You will decide what button should have a caption and which one doesn't need one.

The buttons of a category use a common size. They can have the same width and/or the same height. To set a common size to all buttons, set the gboFullSize member of the ButtonOptions value to True. Then set the common width using the ButtonWidth property:

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

In the same way, to apply the same height to all buttons, assign the desired value to the ButtonHeight property:

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

These values are independent.

1. On the form, click the category buttons control
2. In the Object Inspector, click ButtonWidth, type 28, and press Enter
    
   
3. Save all

When a category has just been created, it is empty and shows only a gradient color. If you add at least one button to a category, that category becomes equipped with a chevron:

To show the contents of a category, the user can click the chevron:

This is referred to as collapsing a category. To support this operation, the TButtonCategory class is equipped with a Boolean property named Collapse:

__property bool Collapsed = {read=FCollapsed,write=SetCollapsed};

To visually collapse a category, access its Object Inspector, and set the Collapse property to True. To do this programmatically, set the value of Collapse to True. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TfrmGeometry::FormCreate(TObject *Sender)
{
	cbtGeometry->Categories[0][3]->Collapsed = True;
}
//---------------------------------------------------------------------------

When a category's content is hidden, to reveal it, the user can click the category itself (or its chevron). This is referred to expanding the category. To expand a category, set its Collapse property to False.

To enhance its appearance, a category can be painted with a specific color. This is done using the Color property:

__property Graphics::TColor Color = {read=FColor,write=SetColor};

1. In the Editing Category Buttons Category window, click 0 - TButtonCategory
2. In the Object Inspector, click Color, click the arrow of its box, and select clSkyBlue
3. Double-click an unoccupied area of the form to generate its OnCreate event
4. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TfrmGeometry::FormCreate(TObject *Sender)
   {
   	cbtGeometry->Categories[0][1]->Color = RGB(115, 185, 255);
   	cbtGeometry->Categories[0][2]->Color = RGB(35, 145, 255);
   }
   //---------------------------------------------------------------------------

5. Save all
6. Press F12 to display the form

Another feature used for aesthetic reasons on a category is to paint it with a fading color. This is done through the GradientColor property:

__property Graphics::TColor GradientColor = 
{
    read=FGradientColor,
    write=SetGradientColor
};

Each category uses its own gradient color.

1. In the Editing Category Buttons Category window, click 0 - TButtonCategory
2. In the Object Inspector, click GradientColor, click the arrow of its box, and select clCream
3. In the Editing Category Buttons Category window, click 1 - TButtonCategory
4. In the Object Inspector, click GradientColor, click the arrow of its box, and select clWhite
5. In the Editing Category Buttons Category window, click 1 - TButtonCategory
6. In the Object Inspector, click GradientColor, click the arrow of its box, and select clWindow
7. Save all

By default, when a category is collapsed, it shows an empty bar. If you want, you can make it display a string. This is possible because the TButtonCategory class is equipped with a Caption property. If you set a value to this property, when the category is expanded, the caption or part of it would show under the chevron. If the caption is made of a letter or a symbol, it would appear fine. If the caption is too long for the height, only part of it would show. If you want the whole caption to show, you can change the ButtonHeight value.

When the category is collapsed, the caption would show on the right side of the chevron.

1. In the Editing Category Buttons Category window, click 0 - TButtonCategory
2. In the Object Inspector, click Caption and type Round Shapes
3. In the Editing Category Buttons Category window, click 1 - TButtonCategory
4. In the Object Inspector, click Caption and type Triangles
5. In the Editing Category Buttons Category window, click 2 - TButtonCategory
6. In the Object Inspector, click Caption and type Quadrilaterals
7. Close the Editing Category Buttons Category window but leave the other windows open
8. Save all

If the color of the captions is close to, or the same as, the background color of the categories, the caption may be difficult to see. To let you change the caption color, you can use the TextColor property:

__property Graphics::TColor TextColor = {read=FTextColor,write=SetTextColor};

Instead of showing captions on button, you can use pictures. To support them, the TCategoryButtons class is equipped with a property named Images :

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

Create an image list that contains the necessary pictures. If you want to use pictures that are larger and/or taller that 16 pixels, you should programmatically create the image list.

After creating the image list, assign it to the category buttons control. To specify the image to show on a button, specify its position using the ImageIndex property.

1. In the Tool Palette, click Win32
2. Click TImageList and click the form
3. Double-click ImageList1 to open the image list editor
4. From the image list editor, click Add
5. From the resources that accompany these lessons, select circle2.bmp, ellipse2.bmp, righttriangle2.bmp, equilateral2.bmp, isosceles2.bmp, iregtriangle2.bmp, square2.bmp, rectangle2.bmp, trapezoid2.bmp, parallelogram2.bmp, and rhombus2.bmp
6. Click OK
7. On the form, click the category buttons control
8. In the Object Inspector, click Images and select ImageList1
9. In the Editing Category Buttons Items window that has 2 items, click 0 - TButtonItem
10. In the Object Inspector, click Hint and type Circle
11. Click ImageIndex and select 0
12. In the same Editing Category Buttons Items window that has 2 items, click 1 - TButtonItem
13. In the Object Inspector, click Hint and type Ellipse
14. Click ImageIndex and select 1
15. In the Editing Category Buttons Items window that has 4 items, click 0 - TButtonItem
16. In the Object Inspector, click Hint and type Right Triangle
17. Click ImageIndex and select 2
18. In the same Editing Category Buttons Items window that has 4 items, click 1 - TButtonItem
19. In the Object Inspector, click Hint and type Equilateral Triangle
20. Click ImageIndex and select 3
21. In the same Editing Category Buttons Items window that has 4 items, click 2 - TButtonItem
22. In the Object Inspector, click Hint and type Isosceles
23. Click ImageIndex and select 4
24. In the same Editing Category Buttons Items window that has 4 items, click 3 - TButtonItem
25. In the Object Inspector, click Hint and type Irregular Triangle
26. Click ImageIndex and select 5
27. In the Editing Category Buttons Items window that has 5 items, click 0 - TButtonItem
28. In the Object Inspector, click Hint and type Square
29. Click ImageIndex and select 6
30. In the same Editing Category Buttons Items window that has 5 items, click 1 - TButtonItem
31. In the Object Inspector, click Hint and type Rectangle
32. Click ImageIndex and select 7
33. In the same Editing Category Buttons Items window that has 5 items, click 2 - TButtonItem
34. In the Object Inspector, click Hint and type Parallelogram
35. Click ImageIndex and select 8
36. In the same Editing Category Buttons Items window that has 5 items, click 3 - TButtonItem
37. In the Object Inspector, click Hint and type Isosceles Trapezoid
38. Click ImageIndex and select 9
39. In the same Editing Category Buttons Items window that has 5 items, click 3 - TButtonItem
40. In the Object Inspector, click Hint and type Rhombus
41. Click ImageIndex and select 10
42. In the Object Inspector, click Events
43. In the Editing Category Buttons Items window that has 2 items, click 0 - TButtonItem
44. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories0Items0Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Circle.bmp");
    }
    //---------------------------------------------------------------------------

45. In the Editing Category Buttons Items window that has 2 items, click 1 - TButtonItem
46. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories0Items1Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Ellipse.bmp");
    }
    //---------------------------------------------------------------------------

47. Close the Editing Category Buttons Items window that has 2 items
48. In the Editing Category Buttons Items window that has 4 items, click 0 - TButtonItem
49. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories1Items0Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("RightTriangle.bmp");
    }
    //---------------------------------------------------------------------------

50. In the same Editing Category Buttons Items window that has 4 items, click 1 - TButtonItem
51. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories1Items1Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Equilateral.bmp");
    }
    //---------------------------------------------------------------------------

52. In the same Editing Category Buttons Items window that has 4 items, click 2 - TButtonItem
53. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories1Items2Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Isosceles.bmp");
    }
    //---------------------------------------------------------------------------

54. In the same Editing Category Buttons Items window that has 4 items, click 3 - TButtonItem
55. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories1Items3Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("IrregularTriangle.bmp");
    }
    //---------------------------------------------------------------------------

56. Close the Editing Category Buttons Items window that has 4 items
57. In the Editing Category Buttons Items window that has 5 items, click 0 - TButtonItem
58. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories2Items0Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Square.bmp");
    }
    //---------------------------------------------------------------------------

59. In the same Editing Category Buttons Items window that has 5 items, click 1 - TButtonItem
60. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories2Items1Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Rectangle.bmp");
    }
    //---------------------------------------------------------------------------

61. In the same Editing Category Buttons Items window that has 5 items, click 2 - TButtonItem
62. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories2Items2Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Parallelogram.bmp");
    }
    //---------------------------------------------------------------------------

63. In the same Editing Category Buttons Items window that has 5 items, click 3 - TButtonItem
64. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories2Items3Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Trapezoid.bmp");
    }
    //---------------------------------------------------------------------------

65. In the same Editing Category Buttons Items window that has 5 items, click 3 - TButtonItem
66. In the Events section of the Object Inspector, double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmGeometry::cbtGeometryCategories2Items4Click(TObject *Sender)
    {
    	imgShape->Picture->LoadFromFile("Rhombus.bmp");
    }
    //---------------------------------------------------------------------------

67. Close the Editing Category Buttons Items window that has 5 items
68. Save all
69. Press F9 to test the application
     
    
     
    
     
    
70. Close the form and return to your programming environment