Introduction to the Paint Box

Description

As its name suggests, a paint box is a control whose main purpose is to provide a platform for painting. The user never sees a paint box as it does not have borders and it is accessible only to the programmer. Like many other controls, the paint box provides a canvas object that receives and manages the painting assignments performed on this control.

1. To create a new project, on the Tool Palette, click C++Builder Projects and double-click VCL Forms Application
2. In the Object Inspector, click Caption and type Picture Viewer
3. Click Name and type frmViewer
4. Under the Code Editor, click Unit1.h
5. Change the file as follows:
   

   //---------------------------------------------------------------------------
   
   #ifndef Unit1H
   #define Unit1H
   //---------------------------------------------------------------------------
   #include <Classes.hpp>
   #include <Controls.hpp>
   #include <StdCtrls.hpp>
   #include <Forms.hpp>
   //---------------------------------------------------------------------------
   class TfrmViewer : public TForm
   {
   __published:	// IDE-managed Components
   	TPaintBox *pbxViewer;
   	void __fastcall pbxViewerPaint(TObject *Sender);
   	void __fastcall FormCreate(TObject *Sender);
   private:	// User declarations
       UnicodeString strFilename;
       void __fastcall WMDropFiles(TWMDropFiles &Message);
   
   public:		// User declarations
   	__fastcall TfrmViewer(TComponent* Owner);
   
   BEGIN_MESSAGE_MAP
       MESSAGE_HANDLER(WM_DROPFILES, TWMDropFiles, WMDropFiles)
   END_MESSAGE_MAP(TForm)
   };
   //---------------------------------------------------------------------------
   extern PACKAGE TfrmViewer *frmViewer;
   //---------------------------------------------------------------------------
   #endif

6. Press F12 to display the form
7.  Double-click the middle of the form te generate its OnCreate event
8. Change the file as follows:

   //---------------------------------------------------------------------------
   
   #include <vcl.h>
   #pragma hdrstop
   
   #include "Unit1.h"
   //---------------------------------------------------------------------------
   #pragma package(smart_init)
   #pragma resource "*.dfm"
   TfrmViewer *frmViewer;
   //---------------------------------------------------------------------------
   __fastcall TfrmViewer::TfrmViewer(TComponent* Owner)
   	: TForm(Owner)
   {
   	strFilename = "";
   }
   //---------------------------------------------------------------------------
   void __fastcall TfrmViewer::FormCreate(TObject *Sender)
   {
   	DragAcceptFiles(Handle, True);
   }
   //---------------------------------------------------------------------------
   void __fastcall TfrmViewer::WMDropFiles(TWMDropFiles &Message)
   {
   	int iLength;
   
   	strFilename.SetLength(255);
   	iLength = DragQueryFile((HDROP)Message.Drop, 0,
   				strFilename.t_str(),
   				strFilename.Length());
   
   	strFilename.SetLength(iLength);
   }
   //---------------------------------------------------------------------------

9. Press F12 to display the form

To support paint boxes, the VCL provides a class named TPaintBox. The TPaintBox class is derived from the TGraphicControl class:

To visually add a paint box to your application, in the System section of the Tool Palette, click the TPaintBox button and click the container that will own it. To programmatically create a paint box, declare a variable of type TPaintBox and specify its owner in the constructor.

1. In the Tool Palette, click System
2. Double-click TPaintBox button
3. In the Object Inspector, click Name and type pbxViewer

The paint box is not a visual control, at least not to the user. After you have visually added it to a form or container, the paint box draws a dotted square. This means that it has a location. Because a paint box is used to paint or display a graphic, you can set the location of your choice to specify from where the graphic would appear. If you plan to use the whole area of the owner of the paint box, make sure you use the Align property to specify this.

• In the Object Inspector, click Align and select alClient

Because a paint box’ main purpose is to provide an area for painting, the only inherent characteristic it has is a rectangular area which makes available a Canvas property. The paint box inherits this property from the TGraphicControl class. This Canvas member gives access to all necessary tools used to paint, including access to bitmaps, etc.

Besides the canvas, another important characteristic of a paint box is the ability to paint itself. To provide this functionality, the paint box inherits the OnPaint event from its parent.

1. In the form, make sure the paint box is still selected.
   In the Object Inspector, click Events and double-click OnPaint
2. Implement the event as follows:

   //---------------------------------------------------------------------------
   void __fastcall TfrmViewer::WMDropFiles(TWMDropFiles &Message)
   {
   	int iLength;
   
   	strFilename.SetLength(255);
   	iLength = DragQueryFile((HDROP)Message.Drop, 0,
   				strFilename.t_str(),
   				strFilename.Length());
   
   	strFilename.SetLength(iLength);
   	Invalidate();
   }
   //---------------------------------------------------------------------------
   void __fastcall TfrmViewer::pbxViewerPaint(TObject *Sender)
   {
   	if( strFilename != L"" )
   	{
   		Graphics::TBitmap * picture = new Graphics::TBitmap;
   		picture->LoadFromFile(strFilename);
   		pbxViewer->Canvas->Draw(0, 0, picture);
   	}
   }
   //---------------------------------------------------------------------------

3. Press F9 to execute the application
4. Open a file utility such as Windows Explorer and open a folder that contains bitmaps (we wrote code only for bitmaps, which are files with .bmp extension)
5. Drag a file from the file utility and drop it on the form to display it