Introduction to the Command Link Button

Description

A command link appears with a picture on the left, followed by a caption in regular size (and font). Under the main caption, it can display another smaller caption that serves as hint to provide more information. Here are two examples from the Add Printer dialog box:

 

Practical Learning: Introducing Command Link Buttons

1. To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
2. In the Object Inspector, change the following properties:
   Caption: Trigonometric Calculations
   Name:    frmCalculations
   Position: poScreenCenter
3. To save the project, on the Standard toolbar, click the Save All button
4. Click the New Folder button
5. Type TrigonometricCalculations1 as the name of the folder and press Enter twice to select it
6. Type Calculations as the name of the unit and click Save
7. Type TrigonometricCalculations as the name of the project and click Save
8. Design the form as follows:
   
   

   Control Caption Name Text Other Properties TButton Angle Evaluations btnAngleEvaluations     TButton Right Triangle Calculations btnRightTriangle     TButton Close btnClose     TPanel   pnlAngleEvaluations     TLabel Value:       TEdit   edtAngleValue 0.00 Alignment: taRightJustify TButton Calculate btnCalculateAngle     TPanel   pnlRightTriangle     TImage   imgShape   Picture: TLabeledEdit a: ledA 0.00 Alignment: taRightJustify LabelPosition: lpLeft TLabeledEdit b: ledB 0.00 Alignment: taRightJustify LabelPosition: lpLeft TLabeledEdit c: ledC 0.00 Alignment: taRightJustify LabelPosition: lpLeft TButton Alpha btnAlpha     TButton Theta btnTheta     TPanel         TLabeledEdit sin: ledAngleSine 0.00 Alignment: taRightJustify TLabeledEdit cos: ledAngleCosine 0.00 Alignment: taRightJustify TLabeledEdit tan: ledAngleTangent 0.00 Alignment: taRightJustify TLabeledEdit csc: ledAngleCosecant 0.00 Alignment: taRightJustify TLabeledEdit sec: ledAngleSecant 0.00 Alignment: taRightJustify TLabeledEdit cot: ledAngleCotangent 0.00 Alignment: taRightJustify TGroupBox Alpha grpAlpha     TLabeledEdit sin: ledAlphaSine 0.00 Alignment: taRightJustify TLabeledEdit cos: ledAlphaCosine 0.00 Alignment: taRightJustify TLabeledEdit tan: ledAlphaTangent 0.00 Alignment: taRightJustify TLabeledEdit csc: ledAlphaCosecant 0.00 Alignment: taRightJustify TLabeledEdit sec: ledAlphaSecant 0.00 Alignment: taRightJustify TLabeledEdit cot: ledAlphaCotangent 0.00 Alignment: taRightJustify TGroupBox Theta grpTheta     TLabeledEdit sin: ledThetaSine 0.00 Alignment: taRightJustify TLabeledEdit cos: ledThetaCosine 0.00 Alignment: taRightJustify TLabeledEdit tan: ledThetaTangent 0.00 Alignment: taRightJustify TLabeledEdit csc: ledThetaCosecant 0.00 Alignment: taRightJustify TLabeledEdit sec: ledThetaSecant 0.00 Alignment: taRightJustify TLabeledEdit cot: ledThetaCotangent 0.00 Alignment: taRightJustify

9. Change the positions of the top panels so that one is positions one on top of the other
10. Change the positions of the bottom group box and the panel so that they are positions one on top of the other
     
    
11. Save all

To create a command link, set the Style of the button to bsCommandLink. Once you do this, the button becomes equipped with a right-pointing green button on the left side of the caption:

Like a normal button, the command link can display a caption. Of course, you can visually specify it using the Caption field in the Object Inspector. You can also change it programmatically. The caption appears in bold characters on the right side of the picture. By Microsoft Windows standards, you cannot change the alignment of the picture.

1. Click the Angle Evaluations button
2. In the Object Inspector, change the Style property to bsCommandLink
3. In the same way, change the style of the Right Triangle Calculations and the Close buttons to bsCommandLink
4. Save all

Besides the regular caption, you can add a sentence under it. To support this, the TCustomButton class provides the CommandLinkHint property, which is a string:

__property System::UnicodeString CommandLinkHint = 
{
	read=FCommandLinkHint,
	write=SetCommandLinkHint
};

To visually specify the hint, access the Object Inspector for the button and type the desired string in the CommandLinkHint field:

This would produce:

When a command link has focus, it shows some borders. This is also the case if the button appears by itself in a form. When there are more than one button, the button that has focus shows some borders and the other button does not. When the mouse passes over the button that doesn't have focus, its borders are raised.

1. Click the Angle Evaluations button
2. In the Object Inspector, click CommandHitLink, type Find the trigonometric values of a known constant and press Enter
3. In the same way, change the CommandHitLink property of the Right Triangle Calculations button to Knowing the 3 sides of a right triangle, find the values of both acute angles
4. In the same way, change the CommandHitLink property of the Close button to Close the application
   
   
5. Double-click the Angle Evaluations button and implement its event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TfrmCalculations::btnAngleEvaluationsClick(TObject *Sender)
   {
   	pnlAngleEvaluations->Visible = True;
   	grpAlpha->Visible = True;
   
   	pnlRightTriangle->Visible = False;
   	grpTheta->Visible = False;
   	pnlValue->Visible = False;
   }
   //---------------------------------------------------------------------------

6. Return to the form and double-click an unoccupied area of its body
7. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TfrmCalculations::FormCreate(TObject *Sender)
   {
   	btnAngleEvaluationsClick(Sender);
   }
   //---------------------------------------------------------------------------

8. In the top combo box of the Object Inspector, select btnCalculateAngle
9. Click Events
10. Double-click OnClick and implement its event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmCalculations::btnCalculateAngleClick(TObject *Sender)
    {
    	double Value = 0.00,
    		   Sine = 0.00, Cosine = 0.00, Tangent = 0.00;
    
    	// Retrieve the value
    	Value   = StrToFloat(edtAngleValue->Text);
    
    	// Calculate
    	Sine    = sin(Value);
    	Cosine  = cos(Value);
    	Tangent = tan(Value);
    
    	// Display the values
    	this->ledAngleSine->Text      = FloatToStr(Sine);
    	this->ledAngleCosine->Text    = FloatToStr(Cosine);
    	this->ledAngleTangent->Text   = FloatToStr(Tangent);
    
    	if( Value != 0.00 )
    		this->ledAngleSecant->Text    = FloatToStr(1 / Sine);
    
    	this->ledAngleCosecant->Text  = FloatToStr(1 / Cosine);
    
    	if( Value != 0.00 )
    		this->ledAngleCotangent->Text = FloatToStr(1 / Tangent);
    }
    //---------------------------------------------------------------------------

11. Return to the form
12. Double-click the Right Triangle Calculations button and implement its event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmCalculations::btnRightTriangleClick(TObject *Sender)
    {
    	pnlRightTriangle->Visible = True;
    	pnlAngleEvaluations->Visible = False;
    
    	grpAlpha->Visible = True;
    	pnlAngleValues->Visible = False;
    	grpTheta->Visible = False;
    }
    //---------------------------------------------------------------------------

13. In the top combo box of the Object Inspector, select btnAlpha
14. Double-click OnClick and implement its event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmCalculations::btnAlphaClick(TObject *Sender)
    {
    	double a = 0.00, b = 0.00, c = 0.00;
    	double Alpha = 0.00;
    	double Theta = 0.00;
    
    	a = StrToFloat(ledA->Text);
    	b = StrToFloat(ledB->Text);
    	c = StrToFloat(ledC->Text);
    
    	this->grpAlpha->Visible = True;
    	this->grpTheta->Visible = False;
    
    	this->ledAlphaSine->Text      = FloatToStr(b / c);
    	this->ledAlphaCosine->Text    = FloatToStr(a / c);
    	this->ledAlphaTangent->Text   = FloatToStr(b / a);
    	this->ledAlphaCosecant->Text  = FloatToStr(c / b);
    	this->ledAlphaSecant->Text    = FloatToStr(c / a);
    	this->ledAlphaCotangent->Text = FloatToStr(a / b);
    }
    //---------------------------------------------------------------------------

15. In the top combo box of the Object Inspector, select btnTheta
16. Double-click OnClick and implement the event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmCalculations::btnThetaClick(TObject *Sender)
    {
    	double a = 0.00, b = 0.00, c = 0.00;
    	double Alpha = 0.00;
    	double Theta = 0.00;
    
    	a = StrToFloat(ledA->Text);
    	b = StrToFloat(ledB->Text);
    	c = StrToFloat(ledC->Text);
    
    	this->grpTheta->Visible = True;
    	this->grpAlpha->Visible = False;
    
    	this->ledThetaSine->Text      = FloatToStr(a / c);
    	this->ledThetaCosine->Text    = FloatToStr(b / c);
    	this->ledThetaTangent->Text   = FloatToStr(a / b);
    	this->ledThetaCosecant->Text  = FloatToStr(c / a);
    	this->ledThetaSecant->Text    = FloatToStr(c / b);
    	this->ledThetaCotangent->Text = FloatToStr(b / a);
    }
    //---------------------------------------------------------------------------

17. Press F12 to display the form
18. Double-click the Close button and implement its event as follows:

    //---------------------------------------------------------------------------
    void __fastcall TfrmCalculations::btnCloseClick(TObject *Sender)
    {
    	Close();
    }
    //---------------------------------------------------------------------------

19. Save all
20. Press F9 to execute the application
21. Enter a position value in the edit control and click Calculate:
     
    
22. Click the Right Triangle button
23. Enter some values in the a, the b, and the c edit boxes
24. Click Alpha
     
    
25. Enter new values in the a, the b, and the c edit boxes
26. Click Theta
     
    
27. Close the form and return to your programming environment

The defualt picture of a command link button appears as a green right-pointing icon. If you want to change it, first create an image list and assign it to the Images property of the button. To specify what picture to use, assign the index to the ImageIndex property. That image would appear on the button when the control doesn't have focus or when it looses focus. One of the options you have it to display a different picture when the button has focus but without being clicked. To support this, the TCustomButton class provides the SelectedImageIndex property:

__property int SelectedImageIndex = 
{
	read=FSelectedImageIndex,
	write=SetSelectedImageIndex
};

This property is of type int. To specify its value assign the desired index from the image list. Another option is to specify what picture to show when the button is pressed. This is done using the PressedImageIndex proeprty:

__property int PressedImageIndex = {read=FPressedImageIndex,write=SetPressedImageIndex};

This property also uses an index from the image list.