First: C++Builder

C++Builder programs consist of a project source code file, one or more source code unit files, a unit header file, and other files that you probably won't edit directly. The project source contains the main program, which is created automatically and usually does nothing more than call the application's Initialize(), CreateForm(), and Run() methods. Unit source code files contain the program's functions, procedures, and event handlers. C++Builder's visual environment and class library handle many of the traditional Windows programming details such as setting up the window class, the window procedure, and the message loop.

Here is the C++Builder project source code file for our first example program:

/****************************************************************************\
*                                                                            *
*  First.cpp                                                                 *
*  FirstU.cpp                                                                *
*                                                                            *
*  This is the first Fastgraph for Windows example program. It demonstrates  *
*  tasks common to most Fastgraph for Windows programs and serves as a       *
*  template for building the other examples.                                 *
*                                                                            *
\****************************************************************************/
#include 
#pragma hdrstop
//---------------------------------------------------------------------------
USEFORM("FirstU.cpp", Form1);
USERES("First.res");
USELIB("FGWBC32.LIB");
//---------------------------------------------------------------------------
WINAPI WinMain(HINSTANCE, HINSTANCE, LPSTR, int)
{
   try
   {
      Application->Initialize();
      Application->CreateForm(__classid(TForm1), &Form1);
      Application->Run();
   }
   catch (Exception &exception)
   {
      Application->ShowException(&exception);
   }
   return 0;
}

Note how the project source code file includes a USELIB statement referencing Fastgraph's Borland C++ library (FGWBC32.LIB). This is included automatically when you add the library file to your project in the C++Builder IDE. Also, note the USEFORM statement that references the FirstU.cpp unit source code file, which in turn includes the FirstU.h unit header file. This is likewise added automatically when you create the project.

The FirstU.cpp unit source code file contains an #include directive to include the FirstU.h unit header file. Near the beginning of the unit header file, we add another #include directive referencing Fastgraph's FGwin.h header file. The user declarations section of the unit header file is a good place to define global variables used in the event handlers of the unit source code file. C++Builder automatically creates and maintains the rest of the unit header file for you. The FirstU.h unit header file is shown here:

//---------------------------------------------------------------------------
#ifndef FirstUH
#define FirstUH
//---------------------------------------------------------------------------
#include 
#include 
#include 
#include 
#include <fgwin.h>
//---------------------------------------------------------------------------
class TForm1 : public TForm
{
__published:   // IDE-managed Components
   void __fastcall FormActivate(TObject *Sender);
   void __fastcall FormCreate(TObject *Sender);
   void __fastcall FormPaint(TObject *Sender);
   void __fastcall FormResize(TObject *Sender);
   void __fastcall FormDestroy(TObject *Sender);
private:   // User declarations
   HDC hDC;
   HPALETTE hPal;
   int hVB;
   UINT cxClient, cyClient;
public:      // User declarations
   __fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------
extern TForm1 *Form1;
//---------------------------------------------------------------------------
#endif

And here is the FirstU.cpp unit source code file, which contains our event handlers:

/****************************************************************************\
*                                                                            *
*  First.cpp                                                                 *
*  FirstU.cpp                                                                *
*                                                                            *
*  This is the first Fastgraph for Windows example program. It demonstrates  *
*  tasks common to most Fastgraph for Windows programs and serves as a       *
*  template for building the other examples.                                 *
*                                                                            *
\****************************************************************************/
#include 
#pragma hdrstop
#include "FirstU.h"
//---------------------------------------------------------------------------
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
   : TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormActivate(TObject *Sender)
{
   fg_realize(hPal);
   Invalidate();
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormCreate(TObject *Sender)
{
   hDC = GetDC(Form1->Handle);
   fg_setdc(hDC);
   hPal = fg_defpal();
   fg_realize(hPal);
   fg_vbinit();
   hVB = fg_vballoc(640,480);
   fg_vbopen(hVB);
   fg_vbcolors();
   fg_setcolor(19);
   fg_fillpage();
   Application->OnActivate = OnActivate;
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormPaint(TObject *Sender)
{
   fg_vbscale(0,fg_getmaxx(),0,fg_getmaxy(),0,cxClient-1,0,cyClient-1);
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormResize(TObject *Sender)
{
   cxClient = ClientWidth;
   cyClient = ClientHeight;
   Invalidate();
}
//---------------------------------------------------------------------------
void __fastcall TForm1::FormDestroy(TObject *Sender)
{
   fg_vbclose();
   fg_vbfree(hVB);
   fg_vbfin();
   DeleteObject(hPal);
   ReleaseDC(Form1->Handle,hDC);
}

The FirstU.cpp unit is essentially made up of event-handling procedures that provide our first look at some Fastgraph functions. Note that our program does not explicitly call the event procedures. Instead, they are called by C++Builder's class library in response to Windows events such as creating or resizing the window (these procedures are analogous to the traditional WindowProc() message handlers). Our program includes event handlers for the form's OnCreate, OnActivate, OnPaint, OnResize, and OnDestroy events. You can use C++Builder's Object Inspector to generate code templates for these form event handlers.

An OnCreate event occurs when the form is first created during program execution. This event occurs once per program instance and is analogous to the WM_CREATE Windows message. Hence, it is a good place for any application-specific initialization code. Our OnCreate handler is in the FormCreate() procedure and first calls the Windows API function GetDC() to obtain a device context to the form's client area. It then calls fg_setdc() to make the device context available to other Fastgraph functions:

hDC = GetDC(Form1->Handle);
fg_setdc(hDC);

Next, it creates and realizes the default logical palette:

hPal = fg_defpal();
fg_realize(hPal);

The OnCreate handler then initializes Fastgraph's virtual buffer environment, creates a 640x480 virtual buffer and makes it the active virtual buffer, and assigns the logical palette colors to the virtual buffer:

fg_vbinit();
hVB = fg_vballoc(640,480);
fg_vbopen(hVB);
fg_vbcolors();

Next, we fill the virtual buffer with blue pixels (color 19 is blue when using Fastgraph's default 256-color virtual buffers with the default logical palette):

fg_setcolor(19);
fg_fillpage();

The last thing the OnCreate event handler does is set up the pointer to the application's OnActivate handler:

Application->OnActivate = OnActivate;

The application's OnActivate handler (which has a different purpose than the form's OnActivate handler) executes when the program gains the input focus. This happens when control shifts from another Windows application to our program, so it is thus analogous to the WM_SETFOCUS Windows message. Because we want the application's OnActivate handler to perform the same tasks as the form's OnActivate handler, we simply point the application's handler to the form's handler. The form's OnActivate handler, and hence the application's OnActivate handler, first calls fg_realize() to activate the program's logical palette (in case another program has changed the logical palette colors). It then calls C++Builder's Invalidate() function to force an OnPaint event to redraw the form's client area. This sequence is typical of OnActivate event handlers in Fastgraph programs.

An OnPaint event occurs when the form's client area must be repainted; it is analogous to the WM_PAINT Windows message. Our OnPaint handler is in the FormPaint() procedure and just calls fg_vbscale() to display the contents of the 640x480 virtual buffer scaled to the size of the form's client area. This sequence is typical of OnPaint event handlers in Fastgraph programs.

You can remove the OnActivate event handler by calling fg_realize() before fg_vbscale() in the OnPaint handler. While this eliminates the work of manually creating an application event handler, it introduces overhead in OnPaint because it must realize the logical palette every time the form is repainted. This wouldn't be noticeable in a simple program like our first example. However, in games or other applications where we frequently update the form (and hence frequently execute the OnPaint handler), we recommend using a separate OnActivate handler that realizes the logical palette only when needed.

An OnResize event occurs whenever the size of the form changes, and also upon creation of a form. It is analogous to the WM_SIZE Windows message. Our OnResize handler is in the FormResize() procedure and simply saves the new width and height of the client area (in pixels) in the variables cxClient and cyClient. These quantities are passed to fg_vbscale() in the OnPaint event handler.

An OnDestroy event occurs after removing a form and often signals a program exit; it is analogous to the WM_DESTROY Windows message. Our OnDestroy handler is in the FormDestroy() procedure and first closes the virtual buffer, releases its memory, and terminates virtual buffer processing:

fg_vbclose();
fg_vbfree(hVB);
fg_vbfin();

It then calls two Windows API functions to delete the logical palette created with fg_defpal() and release the device context created with GetDC():

DeleteObject(hPal);
ReleaseDC(Form1->Handle,hDC);

Each C++Builder example supplied with Fastgraph consists of six files comprising a C++Builder project. The unit source code, unit header, and graphical form files will have the same name as the Fastgraph example, but with the letter "U" appended to the file name. For example, the six files for the First example project are:

In general, we'll only be working with the unit source code and header files for each project, as they contain the event handling procedures and their global variables. We'll let C++Builder's visual programming environment handle the maintenance of the other files. For more information about these files, please consult your C++Builder manuals.