Introduction to the Image Control

Description

To support the ability to display pictures, the VCL provides an Image control. By default, the Image control appears as a dotted rectangle:

To take advantage of it, you have to add a picutre to it. You can then manipulate it as you see fit.

1. Start Embarcadero RAD Studio
2. To create a new project, on the main menu, click File -> New -> VCL Forms Application - C++Builder
3. Change the Caption of the form to Picture Loader

To support the display of a picture, the VCL provides the TImage class. To visually create an Image control, in the Additional section page of the Tool Palette, click the TImage button and click its container.

 TImage is derived from a class named TGraphicControl:

Both classes are members of the ExtCtrls library. Based on this, to create an Image control, create a pointer to TImage. When initializing it, use its constructor to specify its own and access its Parent proeprty to determine its parent. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormPaint(TObject *Sender)
{
    TImage * imgHolder = new TImage(Form1);
    imgHolder->Parent = Form1;
}
///---------------------------------------------------------------------------

1. In the Tool Palette, click Additional
2. Click the TImage button and click the form
3. In the Object Inspector, change its Name to imgPictureViewer
   

The Image control is probably the favorite object used to display a picture. It supports all the popular picture formats (jpeg, bmp, gif, ico, etc). After adding an Image control to a container, its borders display as dash lines to indicate that they will not display when the picture comes up. Like any other visual control, you can resize the Image object using the handles on its borders and/or corners.

The most important piece of information the control needs is probably a picture. This can be specified using the Picture property of the Object Inspector.

The Picture property is of type TPicture:

__property Graphics::TPicture * Picture = {read=FPicture,write=SetPicture};

The TPicture class derives from the TInterfacedPersistent class. The  TPicture class is equipped with a property named Graphic that is of type TGraphic:

__property Graphics::TGraphic * Graphic = {read=FGraphic,write=SetGraphic};

Based on this, to specify the picture of an Image control, you can create a TGraphic-descendant object and assign it to the Graphic property of the Picture member of the TImage object. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::FormPaint(TObject *Sender)
{
    TImage * imgHolder = new TImage(Form1);
    imgHolder->Parent = Form1;

    Graphics::TBitmap * bmpPicture = new Graphics::TBitmap;

    bmpPicture->LoadFromFile("C:\\Exercise\\flower.bmp");
    imgHolder->Picture->Graphic = bmpPicture;
}
//---------------------------------------------------------------------------

1. While the image control is still selected on the form, in the Object Inspector, click Picture and click its ellipsis button
2. In the Picture Editor, click Load...
3. Locate the Pictures sub-folder from the Documents folder or locate the resources that accompany these lessons
4. Select a picture file and click Open
    
   
5. In the Picture Editor, click OK

After specifying the picture for the Image control, you may find out that your image is smaller or bigger than the rectangle drawn on the form when you added the Image control. You have many options to solve this. If you want to use the whole actual size of the picture, you can manually resize the border of the Image control to accommodate the picture. Since the border of the Image control will not appear when the picture displays on the form at run time, you can enlarge the size of the Image control to be greater than the picture itself:

If you want to keep the size of the Image, you can instead resize the picture itself to fit in the Image control’s rectangle. This is taken care of by the Stretch Boolean property

__property bool Stretch = {read=FStretch,write=SetStretch};

The default value of the Stretch property is false, which means that you decide how to deal with the difference between the size of the Image control and the actual size of the picture. If you set the Stretch property to True (whether visually in the Object or programmatically), the picture would be automatically resized to use the whole size of the Image control.

If you set the Stretch property’s value to true, and if you resize the image by dragging one of the borders, the picture may become distorted:

If you want to keep the ratio between the length and the height of the picture balanced during resizing, you can use the Proportional Boolean property:

__property bool Proportional = {read=FProportional,write=SetProportional};

The default value of the TImage::Proportional property is false, in which case the picture can be resized "as is". To respect the ratio of the dimensions, set the Proportional property to true:

You can combine the Stretch and the Proportioal properties to get some dramatic effects such as zooming.

After adding a picture to an Image control, if the picture is smaller than the size of the Image control, the picture would be positioned in the top-left corner of the control. The positioning of the picture inside an Image is controlled by the Center Boolean property:

__property bool Center = {read=FCenter,write=SetCenter};

Its default value is false, which means the top-left corner of the picture coincides with the top-left corner of the Image rectangular border. If the picture you are using is smaller than the size of the Image control but want to keep the size of the Image control, which could be valid during design, you can position the picture in the horizontal center and vertical middle of the borders of the Image. This is done by setting the Center Boolean property to true:

When it comes to resizing a picture, the image contriol inherits the AutoSize property of the TControl class. If you apply this property to an image control, the control resizes itself to get the size of the picture.

1. While the image control is still selected on the form, in the Object Inspector, click the AutSize check box to make it True
2. In the top combo box of the Object Inspector, select Form1
3. Click Events and double-click OnCreate
4. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TForm1::FormCreate(TObject *Sender)
   {
   	// Move the image control to somewhere in the top-left section,
   	// 8 measures from the left border of the form ...
   	this->imgPictureViewer->Left = 8;
   	// and 8 measures from the top border of the form ...
   	this->imgPictureViewer->Top = 8;
   
   	// Resize the form according to the image control,
   	// add some margins to the right and the bottom borders
   	ClientWidth = this->imgPictureViewer->Width + 16;
   	ClientHeight = this->imgPictureViewer->Height + 16;
   }
   //---------------------------------------------------------------------------

5. Press F9 to execute the application and see the result
    
   
6. Close the form and return to your programming environment