Introduction to Pictures

Description

A picture is an aesthetic graphical object that uses a size and a compination of colors to represent itself. Microsoft Windows supports various types of pictures, including icons, cursors, and commonly known pictures. Win32 as the main library of the the operating provides various functions to deal with pictures but some of its functions could be difficult to use. Fortunately, the VCL provides impressice support for pictures.

Creating a Picture

In the VCL (as well has most, if not all, libraries), a picture is not a control. To support pictures, the VCL provides a class named TPicture. The TPicture class is defined in the Graphics.hpp header file. The TPicture class derives from TInterfacedPersistent. The TInterfacedPersistent class is based on TPersistent:

As you will see, the classes of most controls that need a picture have a property named Picture. This means that most of the time, you will not need to explicitly create a TPicture object, but you can if you want to. To explicitly create a picture, declare a variable of type TPicture and use the new operator to initialize it.

Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	TPicture * pct = new TPicture;
}
//---------------------------------------------------------------------------

The TPicture class primarily supports three types of objects: icons, metafiles, and bitmaps. To represent an icon, the TPicture class is equipped with the Icon property:

__property Graphics::TIcon * Icon = {read=GetIcon,write=SetIcon};

To support metafiles, the TPicture class provides the Metafile property:

__property Graphics::TMetafile * Metafile = {read=GetMetafile,write=SetMetafile};

To support the bitmaps, the TPicture class is equipped with a Bitmap property. You can use one of these properties either to assign a picture or to retrieve the contents of a TPicture object.

Probably the first operation you must perform on a picture is to put a picture in its object. To support this, the TPicture class provides the LoadFromFile() method. Its syntax is:

void __fastcall LoadFromFile(System::UnicodeString Filename);

This method takes one argument that is the name or path of the file that holds the picture. The fife can represent an icon (a file with .ico extension), a metafile (a file with .wmf extension), or a bitmap (a file with .bmp extension). Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	TPicture * pct = new TPicture;

	pct->LoadFromFile(L"C:\\Exercise\\house.bmp");

	Image1->Picture = pct;
}
//---------------------------------------------------------------------------

As an alternative, you can load a picture from a stream, that is, a variable from a class that derives from TStream. To use this scenario, the TPicture class is equipped with the LoadFromStream() method whose syntax is:

void __fastcall LoadFromStream(Classes::TStream * Stream);

If you have a picture created as a TBitmap object, you can assign it to your TPicture. To support this, the TPicture class is equipped with a property named Bitmap:

__property Graphics::TBitmap * Bitmap = {read=GetBitmap,write=SetBitmap};

To load a bitmap to a picture, access this property and assign it to a TPicture object. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnBitmapClick(TObject *Sender)
{
	TPicture * pct = new TPicture;
	Graphics::TBitmap *bmpPicture = new Graphics::TBitmap;

	bmpPicture->LoadFromFile(L"C:\\Exercise\\person.bmp");
	pct->Bitmap = bmpPicture;

	Image1->Picture = pct;
}
//---------------------------------------------------------------------------

As an alternative, the TPicture class provides a property named Graphic:

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

Here is an example of using this property:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnBitmapClick(TObject *Sender)
{
	TPicture * pct = new TPicture;
	Graphics::TBitmap *bmpPicture = new Graphics::TBitmap;

	bmpPicture->LoadFromFile(L"C:\\Exercise\\person.bmp");
	pct->Graphic = bmpPicture;

	Image1->Picture = pct;
}
//---------------------------------------------------------------------------

A picture object has a size. This is usually defined by the picture representation you put in it. To recognize the width of a picture, the TPicture class is equipped with a property named Width:

__property int Width  = {read=GetWidth};

The height of a picture is represented in the TPicture class by a property named Height:

__property int Height = {read=GetHeight};

Besides loading a picture, one of the most valuable operations the picture provides is the ability to save itself as a file. To support this, the TPicture class provides the SaveToFile() method. Its syntax is:

void __fastcall SaveToFile(System::UnicodeString Filename);

When calling this function, pass the file name or its complete path with extension. Alternatively, you can create a stream, that is, a variable from a class that is derived from TStream. In this case, you would use the SaveToStream() method. Its syntax is:

void __fastcall SaveToStream(Classes::TStream * Stream);

Besides text, one of the most common types of objects users usually store in the clipboard is the picture. To assist you with this, the TPicture class provides the SaveToClipboardFormal() method. Its syntax is:

void __fastcall SaveToClipboardFormat(unsigned short & AFormat,
 				      unsigned int & AData,
  				      HPALETTE__ * & APalette);

This method takes three arguments all passed by reference. This means that the methof will return three values. The first argument specifies the type of picture you want to send to the clipboard. The method will return that type. The second argument is a handle that the clipboard will return. The third argument is the color palette that the function will return.

After calling thebe the SaveToClipboardFormat() method, you must update the clipboard. This is done by calling the SetAsHandle() method of the TClipboard class. The syntax of that method is:

void __fastcall SetAsHandle(unsigned short Format, unsigned int Value);

The first argument represents the type of object that the  SaveToClipboardFormat() method returned from its first argument. The second argument represents the clipboard handle that the  SaveToClipboardFormat() method as its second argument.

Here is an example of storing a picture to the clipboard:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnStoreInClipboardClick(TObject *Sender)
{
	TPicture * pct = new TPicture;
	unsigned short Format;
	unsigned int clpHandle;
	HPALETTE hPal;

	pct->LoadFromFile(L"C:\\Exercise\\dress1.bmp");

	pct->SaveToClipboardFormat(Format, clpHandle, hPal);
	Clipboard()->SetAsHandle(Format, clpHandle);
}
//---------------------------------------------------------------------------

As opposed to storing a picture from the clipboard, you may want to retrieve its contents. To support this, the TPicture class provides the SaveToClipboardequipped. Its syntax is: with the

void __fastcall LoadFromClipboardFormat(unsigned short AFormat,
 					unsigned int AData,
  					HPALETTE__ * APalette);

The first argument specifies the type of picture you are trying to get from the clipboard. For a bitmap picture, it can be CF_BITMAP. The second argument is a handle to the clipboard. It can be the returned value of the GetAsHandle() method of the TClipboard class. The syntax of the TClipboard::GetAsHandle() method is:

unsigned int __fastcall GetAsHandle(unsigned short Format);

The third argument represents a color palette that the method will return.

Here is an example of getting a picture from the clipboard (the following code assumes that a bitmap (a file with .bmp extension) is currently stored in the clipboard):

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	TPicture * pct = new TPicture;

	pct->LoadFromClipboardFormat(CF_BITMAP,
	 			     Clipboard()->GetAsHandle(CF_BITMAP),
	  			     0);
}
//---------------------------------------------------------------------------

If you are using an unrecognized format, you should first call the RegisterClipboardFormatA() method of the TPicture class. Its syntax is:

__classmethod void __fastcall RegisterClipboardFormatA(unsigned short AFormat,
 						       System::TMetaClass * AGraphicClass);

This method allows you to initiate the operation of getting something from the clipboard. The AFormat argument represents the type of object you want to retrieve. The AGraphicClass argument is the class that describes the object.