Home

VCL Controls: The Category Buttons Control

 

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.

 

Practical LearningPractical Learning: Introducing Category Buttons

  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 Save All
  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:
     
    Circle Ellipse
    Right Triangle Equilateral Triangle
    Isosceles Triangle Irregular Triangle
    Square Rectangle
    Parallelogram Trapezoid
    Rhombus  
  11. Return to your programming environment

Creating a Category Buttons Control

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:

TCategoryButtons Inheritance

To visually create a category buttons control, in the Additional section of the Tool Palette, click the TCategoryButtons icon TCategoryButtons 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;
}
//---------------------------------------------------------------------------

Practical LearningPractical Learning: Creating a Category Buttons Control

  1. Design the form as follows: 
     
    Geometric Shapes
    Control Align Center Color Name Kind 
    TCategoryButtons TCategoryButtons       cbtGeometry  
    TPanel TPanel     clWhite    
    TImage TLabel alClient True   imgShape  
    TBitBtn TBitBtn         bkClose
     
  2. Save all

Characteristics of the Category Buttons Control

 

Introduction

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;
}
//---------------------------------------------------------------------------

Creating the Categories

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:

 

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

This would open the Editing Category Buttons Category window:

Editing CategoryButtons Category

 
 

To create a category:

  • Click the New button New Category
  • 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.

Practical LearningPractical Learning: Creating the Categories

  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 Add New

Introduction to the Buttons of a Category

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 New Category
  • 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.

Practical LearningPractical Learning: Creating the Buttons of a Category

  1. In the Editing Category Buttons Category window, click 0 - TButtonCategory
  2. In the Object Inspector, click Items and click its ellipsis button Ellipsis Button
  3. On the Editing Category Buttons Items window, the New button Add New
  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 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 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

The Border Style

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;
}
//---------------------------------------------------------------------------

Introduction to Button Options

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
};

Rearranging the Buttons' Orders

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.

The Buttons' Captions

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 Common Size of the Buttons

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.

Practical LearningPractical Learning: Setting the Size of Buttons

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

Collapsing or Expanding a Category

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:

Collapsing or Expanding a Category

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

Collapsing or Expanding a Category

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.

The Background Color of a Category

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};

Practical LearningPractical Learning: Setting the Background Color of Buttons

  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

The Gradient Color of a Category

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.

Practical LearningPractical Learning: Setting the Gradient Color of Buttons

  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

The Caption of a Category

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.

Practical LearningPractical Learning: Specifying the Captions of Categories

  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

The Caption Color

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};

Images on Buttons

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.

Practical LearningPractical Learning: Using Images on Buttons

  1. In the Tool Palette, click Win32
  2. Click TImageList 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
     
    Geometric Shapes
     
    Geometric Shapes
     
    Geometric Shapes
  70. Close the form and return to your programming environment
 
 
 
 

Home Copyright © 2010-2011 FunctionX, Inc.