Introduction to the Clipboard

Description

The clipboard is an operating system object that is used to temporarily hold an object other that can be copied or moved from one source to a target. To store an object to the clipboard, the user must first copy it. The user has the option of copying or moving.

By default, the clipboard in Microsoft Windows can hold only one object. Normally, the size and type of the object doesn't matter. The object can be a letter, a word, a sentence, a paragraph, a page, or even a whole book. The object can also be a small icon, a picture, or even a whole video. There is a common clipboard that all applications share and use.

To support the clipboard, the VCL provides a class named TClipboard. The TClipboard class is derived is derived from TPersistent. The TClipboard class is defined in the Clipbrd.hpp header file.

As mentioned already, all applications that are currently running on the computer share a clipboard. To let you use that common clipboard, when you start an application, the compiler automatically creates a global TClipboard object. This means that you will hardly, if ever, have any reason to explicitly declare a TClipboard variable. The global clipboard variable created by the compiler is a function named Clipboard.

Some controls already have complete built-in support for the clipboard. That's the case for text-based controls. For the other controls, you will have to write code.

The clipboard is an operating system object that is available to all applications. To support it, it is represented in the Win32 library as a handle. To let you get this handle in a VCL application, the TClipboard class is equipped with a Handle property:

__property HWND__ * Handle = {read=GetClipboardWindow};

As you can see, the clipboard is an HWND object.

There are almost no restrictions on the types and sizes of objects that the clipboard can hold. When storing something in the clipboard, probably the first decision you must make is about the type of object you want to keep. The most common type of object used by the clipboard is text. To let you indicate that you are storing text in the clipboard, the TClipboard class is equipped with the AsText property:

__property System::UnicodeString AsText = {read=GetAsText,write=SetAsText};

In the same, to get the text stored in the clipboard, you can access the value of this property.

As mentioned already, the clipboard is configured to hold various types of objects. These types are referred to as formats. If you decide to put something in the clipboard, you must specify the format of that object.  The available formats are:

To let find out what type of format the clipboard currently has, the TClipboard class provides the HasFormat() method. Its syntax is:

bool __fastcall HasFormat(unsigned short Format);

When calling this method, pass a format to it. If the method returns True, it means that the clipboard is currently holds the type of value you passed.

The other characteristics of the clipboard are connected to text-based and picture-based controls. These will be addressed in other lessons.

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

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

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.