Static Text-Based Controls

Labels

Introduction

Borland C++ Builder ships with many string-oriented classes for most of the controls used to perform any necessary string manipulation. AnsiString is the main string classes used by those controls as it provides the caption property of all controls that need to set or control their caption. The label is one of those controls.

A label is a control that serves as a guide to the user. It provides static text that the user cannot change but can read to get information on the form. The programmer can also use it to display simple information to the user. Most controls on the form are not explicit at first glance and the user would not know what they are. Therefore, you can assign a label to a control as a help to the user.

To add a label to a container, click the Label button from the Standard section of the Tool Palette and click on the object that would host it. You can also dynamically create a label.

A label is based on the TLabel class that is a child of the TCustomLabel class which itself is derived from the TGraphicControl class.

1. Start Borland C++ Builder with its default form
2. To create a form ready for the database, on the main menu, click Database -> Form Wizard...
3. In the first page of the wizard, accept all defaults and click Next
4. In the second page of the wizard, in the Drive Or Alias Name combo box, select CPAS. In the Table Name combo box, select WorkOrders.db and click Next
    
   
5. In the third page, click the select all fields button
    
   
6. Click Next
7. In the fourth page of the wizard, click the Vertically option and click Next
8. In the fifth page, accept the Left default option and click Next
9. In the sixth page, click the Generate A Main Form check box and click Finish
    
   
10. On the main menu, click Project -> Remove From Project...
11. In the Remove From Project dialog box, select Unit1.cpp
     
    
12. Click OK
13. To save the project, on the Standard toolbar, click the Save All button
14. Locate the main folder where you will save the project and display it in the Save In combo box
15. Click the Create New Folder button
16. Type CPAS2 and press Enter twice to display it in the Save In combo box
17. Change Unit1.cpp to WorkOrders and press Enter
18. Change the Project file to CPAS and press Enter
19. Change the form's Caption with College Park Auto-Shop
20. Click the WorkOrderID label
     
    
21. Press Delete
22. In the same way, click each label and press Delete to remove all labels from the form
23. Click the area on the left side of the Table1 icon
     
    
24. In the Object Inspector, change the Align property to alBottom

The most important characteristic of a label control is the text it displays. This is what the user would read. The text of a label is its Caption property and is its default. To set a label’s caption, after adding the control to a container, click Caption in the Object Inspector and type the desired value. As we mentioned when studying controls characteristics, at design time, the text you type in the Caption is considered “as is”. If you want to create a more elaborate and formatted string, you would have to do it programmatically.

When you type the caption of a label, it is continually resized to accommodate its string. If you edit the label, as you delete or add characters, the label resizes itself. If you want to fix the size of the label regardless of its caption, set the Boolean property AutoResize to false. By default, this property is set to false on most controls that use it; but on a label, it is set to true. Once you have set AutoResize to true, if you change the text of the label, only the portion that fits in the allocated space would be seen. Of course, you can resize it manually.

Before or after typing the caption of a label, you can resize its allocated space to your liking. This is because a string occupies a rectangular area. Here is an example:

By default, the caption of a label is positioned starting on the left side of its allocated rectangle. Alternatively, you can position it to the center or the right side inside of its rectangle. This positioning is controlled by the Alignment property which is based on the TAlignment enumerator. It can have the following values:

taLeftJustify	taCenter	taRightJustify

Because the caption of a label is confined to a rectangle, you can increase the height of that rectangle and align text to the top, the middle or the bottom side of that allocated rectangle. The vertical alignment of a label is controlled by the Layout property which is based on the TTextLayout enumerator and defined as follows:

enum TTextLayout { tlTop, tlCenter, tlBottom };

The effects of the Alignment and the Layout properties are as follows:

Alignment taLeftJustify Alignment taLeftJustify Alignment taLeftJustify Layout tlTop Layout tlCenter Layout tlBottom Alignment taCenter  Alignment taCenter  Alignment taCenter Layout tlTop Layout tlCenter Layout tlBottom Alignment taRightJustify  Alignment taRightJustify  Alignment taRightJustify  Layout tlTop Layout tlCenter Layout tlBottom

If you have allocated a rectangular area wider and taller than the actual string of the label, you can display it on more than one line. This ability is controlled by the WordWrap Boolean property. Its default value is false, which makes the label display on a single line. When the value of the WordWrap property is set to true, the text of the label can span multiple lines.

If you want to create a shadow effect on a label, you can place one label on top of another. Using the Transparent property, which is a Boolean value, you should make the top label transparent.

Other fancy characteristics you can apply to a label include its font and color. The Label control is also equipped with a Canvas property. This allows you to display a bitmap or to perform any needed drawing in the allocated rectangle of the label. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormDblClick(TObject *Sender)
{
	Label2->Canvas->Pen->Color = clBlue;
	Label2->Canvas->Brush->Color = clSkyBlue;
	Label2->Canvas->Brush->Style = bsDiagCross;
	ClientToScreen(Point(Label2->Left, Label2->Top));
	Label2->Canvas->Rectangle(Label2->ClientRect);
}
//---------------------------------------------------------------------------

1. From the Standard section of the Tool Palette, click the Label control 
2. Click on the left side of the edtWorkOrderID control on the form
    
   
3. As the new label is still selected, on the Object Inspector, click Caption and type &Work Order ID:
4. To move the new label, click and drag it up and down
5. In the combo box on top of the Object Inspector, select Panel2
    
   
6. (Make sure the panel, and not the ScrollBox control, is selected)
   To add a panel, on the Standard section, double-click the Panel control 
7. While the new panel is still selected, in the Object Inspector, set its Align property to alTop
8. Click Caption and press Delete to remove the caption
9. To add a new label, on the Standard section of the Tool Palette, click the Label and click the top panel
10. In the Object Inspector, click Caption and type College Park Auto-Shop
11. Click the gray box on the right side of the Font field
12. Click the ellipsis button to open the Font dialog
13. Change the font to Times New Roman
14. In the Font Style combo box, click Bold.
15. In the Font Size combo box, select 24
16. Click the arrow of the Color combo box and select Blue
     
    
17. Click OK
18. On the Object Inspector, click the Name field and type lblMainTitle
19. Double-click the box on the right side of the Transparent field. Instead of false, it should now display true
20. On the form, click the College Park Auto-Shop label to select it
21. On the main menu, click Edit -> Copy
22. Click the top panel on which the College Park label is positioned
23. On the main menu, click Edit -> Paste
24. As the new label is still selected, click the + on the Font field
25. Under the Font field, click Color to reveal its combo box and select clGray
26. Click the – on the Font field
27. Click the Name field and type lblTitleShadow
28. Click the arrow on the top section of the Object Inspector and select lblMainTitle
29. Set following properties
    Left: 16
    Top: 8
30. Click the arrow on the top section of the Object Inspector and select lblTitleShadow
31. Set its properties as follows:
    Left: 19
    Top: 11
32. Right-click on the group of those big labels. One of them will be selected. On the context menu, click Bring To Front. If the blue label does not come in front, right-click again and click Bring To Front until the blue label is on top of the white label
33. Drag the lower border of the panel to make sure it includes both labels
34. Add a label for each corresponding text control on the form and complete the design to make it more user-friendly:
     
    
35. In the combo box on top of the Object Inspector, select Form2
36. Change the following properties:
    Name: frmWorkOrders
    ShowHint: true
37. To save the project, on the Standard toolbar, click Save All

The Label is based on the TLabel class and does not have any methods per se, only a constructor and a destructor. You should never directly call either the TLabel constructor or the ~TLabel destructor. These are only used if you want to dynamically create a label.

To dynamically create a label locally, in a function or an event, declare a pointer to TLabel object and use the new operator, specify the component that owns the instance of the control. To initiate the control, you must specify its container or parent. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	TLabel* Lbl = new TLabel(Form1);
	Lbl->Parent = Form1;
	Lbl->Caption = "LaFace, Inc.";
	Lbl->Left = 75;
	Lbl->Top = 32;
}
//---------------------------------------------------------------------------

The Label control has various events that are part of its repertoire, although they are hardly used. You can configure a label to behave like a (web) link using its OnClick event. For example the Win32 ShellExecute() function can be used to perform an operation on a file. The following OnClick event on a label would launch WordPad:

//---------------------------------------------------------------------------
void __fastcall TForm1::lblWordPadClick(TObject *Sender)
{
	ShellExecute(NULL,
		     NULL,
		     "C:\\Program Files\\Windows NT\\Accessories\\wordpad.exe",
		     NULL,
		     NULL,
		     SW_SHOWNORMAL);
}
//---------------------------------------------------------------------------

The label inherits two valuable events from its parent the TCustomLabel class. Although the label cannot receive focus, when the mouse is positioned over it, it fires the OnMouseEnter() event, which is a TNotifyType. When the mouse is taken away from the top of the label, it fires the OnMouseLeave() event, which also is a TNotifyEvent type.

The label control we used earlier is a completely native VCL object and not particularly related to Win32. The Win32 library provides its own support to labeled text through a window class named STATIC. To support the Win32 STATIC control, the VCL provides the StaticText control. Over all, the VCL’s Label and StaticText controls are very similar. The biggest difference is that StaticText is a Windows control, like the STATIC class of the Win32 API while the VCL’s Label control is not.

To create a static text, at design time, from the Additional tab of the Tool Palette, you can click the StaticText button and click the container that would host it.

As stated already, the static text provides the same functionality as the label control. Its text is aligned using the Alignment property. It also has the following properties similar to those of the label: AutoSize, FocusControl, and ShowAccelChar.

Among the differences between both controls, the StaticText does not have a Canvas property because you cannot draw into it. The StaticText control has a “physical” and identifiable border, unlike the label. This characteristic is controlled by the BorderStyle property which is an enumerator called TStaticBorderStyle and defined as follows:

enum TStaticBorderStyle { sbsNone, sbsSingle, sbsSunken };

Its effects are as follows:

sbsNone sbsSingle sbsSunken

Probably the biggest difference for us is that the StaticText, which is a descendent of TWinControl’s has a Handle property. This allows you to access the properties of the Win32’s STATIC class and apply them to the VCL’s StaticText control. For example, you can draw an etched border around the static text control as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
	LONG GWL = GetWindowLong(StaticText1->Handle, GWL_STYLE);
	GWL |= SS_ETCHEDFRAME;
	SetWindowLong(StaticText1->Handle, GWL_STYLE, GWL);
}
//---------------------------------------------------------------------------

In the same way, you can use the rectangular area of the StaticText control to draw, display an icon or a bitmap, or perform any other complicated task allowed by the Win32’s STATIC class.

This example demonstrates that through one or another control, the VCL provides most , if not any, of the functionality you need from Windows controls. For example, instead of writing so many lines of code to get the above look, you could have used either a panel, a group box, a radio group, or a bevel controls, to get the above frame.

If you try using the regular label control in a database application, you will find out that it has no built-in support for a database field. To all a label to be able to connect to a database field, the VCL provides the DBText control, which is implemented through the TDBText class defined in the DBCtrls.hpp library. Like the label, the DBText control derives from the TCustomLabel class. Because the DBText control is primarily a label, the user cannot directly edit its value: you can only do this programmatically.

To use a DBText control in your application, click it in the Data Controls tab of the Tool Palette and click the control that would hold it.

As implied above, the DBText control is meant to connect to a table's field. To make this possible, this control is equipped with a DataSource property that allows you to indicate the list that holds the data for the table. After specifying the source of data, you can use the DataField property to specify the particular field whose data would be displayed on this DBText control.

If you want more detailed information about the DBText control, you can access its Field property, which is of type TField.

While you can use the regular label control on a form, it cannot function in a report. If you want to display a label in a report, you can use the QRLabel control implemented through the TQRLabel class of the QuickRpt.hpp library. The primary purpose of this control is to display static text. It doesn't connect to a database field.

The Quick Report label is based on the TCustomLabel class. As such, it uses the following characteristics in the same way we described them for the label control:

• Alignment: this property allows you to align the QRLabel's text to the left, the center, or the right side of its bounding rectangle. The default value of this property is taLeftJustify
• AutoSize: This lets the control know whether or not it must automatically resize itself based on the length of its string
• Caption: This is the string that the control displays. Remember that the QRLabel control doesn't connect to a database field. This means that you must manually (or programmatically) specify the text that the control will display
• Font: The Font property can be very valuable on a report as it allows you to emphasize the face, color, size, or style applied on the QRLabel control
• Transparent: This lets the control know whether or not it should allow the user to see through it, possibly to know if there is a control or another object behind the QRLabel control
• WordWrap: If you allow this control to display its text on multiple lines, you can use this property to let the control know if it should continue the text on the next line when its string is too long for the current line

To make report design easier, the QRLabel provides the AlignToBand Boolean property. This specifies whether the control will use its containing band as reference for its alignment.

Another characteristic that can help you enhance the appearance of a QRLabel control is its Frame property. It allows you to specify the borders of the control.

The only event that the QRLabel control can claim is OnPrint. This event fires when you decide to print the report that this control belongs to. This event holds an AnsiString string as argument that allows you to specify what string to print when the printer reaches this control.