VCL Controls: The Label

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 tab of the Component 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.

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

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.