Copyright © 2012 by CODE4SALE, LLC All Rights Reserved -
Contact CODE4SALE, LLC.
CODE4SALE, LLC - TExcellent home page
TExcellent documentation home page!
Try TExcellentFormPrinter!
Buy TExcellentFormPrinter!
Try TExcellentImagePrinter!
Buy TExcellentImagePrinter!
Product names, trademarks, and servicemarks mentioned are owned by their respective owners.
Installation
PrintForm
PrintFormXY
PrintFormEx
PrintFormXYEx
PrintTCustomForm
PrintTScrollingWinControl
PrintTScrollingWinControlEx
HasClass
TPrintFormData
VirtualClientSize
VirtualClientScrolledOffset
PrnFormSetDebugMsg
PrnFormSetAbortDialogHandle
PrnFormSetDebugDoBlt
PrnFormSetDebugUseDDB
PrnFormSetDebugAutoUseDDB
PrnFormSetDebugFrames
PrnFormSetSleepValue
PrnFormSetOutputScaleFactor
PrnFormSetDoWinScale
If you are using the trail version of TExcellentFormPrinter, to compile the units into your project, you will need to:
1) unzip the .obj and .dfm files and place them in your project directory.
2) If you are not using CBuilder 5, go to the BCB menu, and select Project->Add to Project, and select the PrnUtils.obj and PrnForm.obj files.
3) Add the following #include and #pragma statements to the unit that you are using TExcellentFormPrinter from:
#include "Printers.hpp"
#include "PrnUtils.h"
#include "PrnForm.h"
#pragma link "PrnUtils"
#pragma link "PrnForm"
If you are using the registered version of TExcellentFormPrinter, to compile the units into your project, you will need to:
1) unzip the .cpp, .h, and .dfm files and place them in a directory that has a common path with your other CBuilder components. Delete any trial version .dfm, .h, and .obj files you might have installed.Back to Functions and Structures
BOOL __fastcall PrintForm(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
BOOL Centered,
BOOL UsePerfectMargins);
Location: PrnForm.h
Prints a form (or other TScrollingWinControl) to the Windows dc (Canvas.Handle) given, stretched proportionally to fit the page. If Centered is TRUE, then the printout will be centered on the device, else the printout will start at the top left corner of the device. If UsePerfectMargins is TRUE, then the print margin will be adjusted to accommodate devices that have uneven page margins. Note that the dc passed in should not be a DIBSECTION, and must be a true windows device or memory dc. Returns TRUE if successful.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
}
Back to Functions and Structures
BOOL __fastcall PrintFormXY(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
int x,
int y,
int Width,
int Height);
Location: PrnForm.h
Prints a form (or other TScrollingWinControl) to the Windows dc
(Canvas.Handle) given. The output starts at x,y, and the image is
stretched to width, height.
Note: The dc passed in should not be a DIBSECTION, and must be a true windows
device or memory dc. Returns TRUE if successful.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
SIZE TheVirtualClientSize;
TheVirtualClientSize = VirtualClientSize(this);
Printer()->BeginDoc();
PrintFormXY(this,
Printer()->Canvas->Handle,
0,
0,
TheVirtualClientSize.cx,
TheVirtualClientSize.cy);
Printer()->EndDoc();
}
Back to Functions and Structures
BOOL __fastcall PrintFormEx(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
BOOL Centered,
BOOL UsePerfectMargins,
TPrintFormData * lpPrintFormData);
Location: PrnForm.h
Prints a form (or other TScrollingWinControl) to the Windows dc given, stretched proportionally to fit the page. Note that the dc (Canvas.Handle) passed in should not be a DIBSECTION, and must be a true windows device or memory dc. If Centered is TRUE, then the printout will be centered on the device, else the printout will start at the top left corner of the device. If UsePerfectMargins is TRUE, then the print margin will be adjusted to accomodate devices that have uneven page margins. Additional options are set by passing a pointer to a TPrintFormData structure in the lpPrintFormData parameter. Returns TRUE if successful.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
TPrintFormData PrintFormData;
memset(&PrintFormData,
0,
sizeof(PrintFormData));
PrintFormData.StrucSize = sizeof(PrintFormData);
//Set the PrintFormData options you wish to set
PrintFormData.UseAbortDialog = TRUE;
Printer()->BeginDoc();
PrintFormEx(this,
Printer()->Canvas->Handle,
TRUE,
TRUE,
&PrintFormData);
Printer()->EndDoc();
}
Back to Functions and Structures
BOOL __fastcall PrintFormXYEx(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
int x,
int y,
int Width,
int Height,
TPrintFormData * lpPrintFormData);
Location: PrnForm.h
Prints a form (or other TScrollingWinControl) to the Windows dc (Canvas.Handle) given. The output starts at x,y, and the image is stretched to width, height. Note that the dc passed in should not be a DIBSECTION, and must be a true windows device or memory dc. Additional options are set by passing a pointer to a TPrintFormData structure in the lpPrintFormData parameter. Returns TRUE if successful.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
TPrintFormData PrintFormData;
SIZE TheVirtualClientSize;
memset(&PrintFormData,
0,
sizeof(PrintFormData));
PrintFormData.StrucSize = sizeof(PrintFormData);
//Set the PrintFormData options you wish to set
PrintFormData.UseAbortDialog = TRUE;
TheVirtualClientSize = VirtualClientSize(this);
Printer()->BeginDoc();
PrintFormXYEx(this,
Printer()->Canvas->Handle,
0,
0,
TheVirtualClientSize.cx,
TheVirtualClientSize.cy,
&PrintFormData);
Printer()->EndDoc();
}
Back to Functions and Structures
BOOL __fastcall PrintTScrollingWinControl(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
int x,
int y,
int Width,
int Height,
const RECT &ClipRect,
BOOL TrueColor,
TAppCallbackFn OnAppCallbackFn,
DWORD OnAppCallbackData,
TOnPaintCallbackEvent OnPaintCallbackEvent,
TOnPaintControlCallbackEvent OnPaintControlCallbackEvent);
Location: PrnForm.h
Special Note: This function is provided for backwards compatibility. We recommend you upgrade your code to use the new PrintTScrollingWinControlEx() function, as this function is now a simple wrapper to the new PrintTScrollingWinControlEx() function. The wrapper ignores the TrueColor parameter, as the print engine has been enhanced, and this parameter is no longer useful. Documentation for this function's parameters can be found in the documentation for PrintTScrollingWinControlEx() function.
Back to Functions and Structures
BOOL __fastcall PrintTCustomForm(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
int x,
int y,
int Width,
int Height,
const RECT &ClipRect,
TPrinterAbortDialog* AbortDialog,
TOnPaintCallbackEvent OnPaintCallbackEvent,
TOnPaintControlCallbackEvent OnPaintControlCallbackEvent);
Location: PrnForm.h
Special Note: This function is provided for backwards compatibility. We recommend you upgrade your code to use the new PrintTScrollingWinControlEx() function, as this function now a simple wrapper to the new PrintTScrollingWinControlEx() function. Documentation for this functions parameters can be found in the docuemtation for PrintTScrollingWinControlEx() function.
Back to Functions and Structures
BOOL __fastcall PrintTScrollingWinControlEx(Forms::TScrollingWinControl* TheScrollingWinControl,
HDC dc,
int x,
int y,
int Width,
int Height,
const RECT &ClipRect,
TAppCallbackFn OnAppCallbackFn,
DWORD OnAppCallbackData,
TOnPaintCallbackEvent OnPaintCallbackEvent,
TOnPaintControlCallbackEvent OnPaintControlCallbackEvent,
TPrintFormData * lpPrintFormData);
Location: PrnForm.h
Prints a form (or other TScrollingWinControl) to the Windows dc
(Canvas.Handle) given. The output starts at x,y, and the image is
stretched to width, height. Note that the dc passed in should not be a
DIBSECTION, and must be a true windows device or memory dc.
The ClipRect parameter specifies the area of the device to clip output
to, and should be no larger than the device surface. The ClipRect
parameter is useful in stretching the output to span across multiple pages (up
to 2 billion pixels high and wide), and allows the PrintForm engine to optimize
output by processing only the stretched data contained in the ClipRect area.
This also allows the engine to overcome Windows 9x GDI limitations of a 32000
pixel high/wide output.
The OnAppCallbackFn is an optional callback function that you may
install to track the progess of the print job and optionally provide real time
status updates to your user (perhaps by using a progress meter) as well as
allowing you to cancel the print job. If you do not install a callback
function, simply pass nil in this parameter. If you do install a callback
function, you would pass the address of your callback function, and during the
printjob, you will be passed the original value you passed in the
OnAppCallbackData parameter each time your callback function is called.
If you do not install a callback function, you simply pass zero in the
OnAppCallbackData parameter. The callback fuction is passed the number
of "UnitsDone" (the amount completed), the "TotalUnits"
(the total number of units that will be processed) and the
OnAppCallbackData that you originally passed to the
PrintTScrollingWinControlEx()
function. Note that while the OnAppCallbackData parameter is prototyped
as a DWORD, any 32 value can be passed by using typecasting. In other words,
you could pass a pointer or object reference (such as a form reference or a
reference to a TMemo) by using typecasting. This is demonstrated in the example
given below for the PrintTScrollingWinControlEx() function.
Note that this function may be called several times with the same value for
"UnitsDone". Please also note that this is a pure stand alone
callback function and not a TEvent or a method. The prototype for the callback
function looks like this:
BOOL __stdcall AppPrintingCallbackFn(DWORD UnitsDone,
DWORD TotalUnits,
DWORD UserData) {
//Return TRUE to continue the printjob or FALSE to abort the the printjob
return(TRUE);
}
The OnPaintCallbackEvent is an optional event that allows your application to trap (or hook) the rendering of the contols OnPaint event during the print job, and optionally paint the area yourself. This can be useful should you wish to take over the OnPaint event during the print job and paint something different (or perhaps nothing at all). If you do not care to install this hook, simply pass nil for this paramter. The prototype for the callback event looks like this:
BOOL __fastcall TForm1::OnPaintCallbackEvent(HDC dc)
{
//handle the painting yourself here and return TRUE, or return FALSE
//and TExcellentFormPrinter will handle the call!
return(FALSE);
}
The OnPaintControlCallbackEvent is an optional event that allows your application to trap (or hook) the rendering of each control that gets printed during the print job, and optionally paint the control yourself. This can be useful should you wish to take over the rendering of a problematic control. From time to time, we publish hook code for printing third party problematic controls to our registered users. If you do not care to install this hook, simply pass nil for this parameter. The prototype for the callback event looks like this:
BOOL __fastcall TForm1::OnPaintControlCallbackEvent(Controls::TControl* TheControl,
HDC dc)
{
//You may test to see what kind of contol "TheControl" is by using the VCL
//class methods or the PrintForms "HasClass" function, and selectively
//handle the painting yourself and return TRUE, or you may return FALSE and
//TExcellentFormPrinter will handle the call for you! The coordinates to
//paint to are (0,0), as the dc's offset has been already been adjusted to
//account for the left,top of the control.
return(FALSE);
}
Additional options are set by passing a pointer to a
TPrintFormData structure in the lpPrintFormData
parameter.
Returns TRUE if successful.
Example notes: This complete (and intimidating) example prints a form,
stretched across multiple pages. This example uses functions from the PrnUtils
unit. Please refer to the PrnUtils documentation for additional information.
Example:
--unit1.h--------------------------------------------------------------------
class TForm1 : public TForm
{
__published: // IDE-managed Components
TButton *Button1;
void __fastcall Button1Click(TObject *Sender);
private: // User declarations
protected:
public: // User declarations
void virtual __fastcall WMShowWindow(TMessage& Msg);
BEGIN_MESSAGE_MAP
MESSAGE_HANDLER(WM_SHOWWINDOW,TMessage,WMShowWindow)
END_MESSAGE_MAP(TForm)
BOOL __fastcall OnPaintCallbackEvent(HDC dc);
BOOL __fastcall OnPaintControlCallbackEvent(Controls::TControl* TheControl,
HDC dc);
__fastcall TForm1(TComponent* Owner);
};
//---------------------------------------------------------------------------
extern TForm1 *Form1;
//---------------------------------------------------------------------------
#endif
//---------------------------------------------------------------------------
--unit1.cpp -----------------------------------------------------------------
//---------------------------------------------------------------------------
#include "unit1.h"
#include "PrnUtils.h"
#include "PrnForm.h"
//---------------------------------------------------------------------------
#pragma resource "*.dfm"
TForm1 *Form1;
//---------------------------------------------------------------------------
__fastcall TForm1::TForm1(TComponent* Owner)
: TForm(Owner)
{
}
//---------------------------------------------------------------------------
void __fastcall TForm1::WMShowWindow(TMessage& M) {
if ((M.WParam == 0) &&
(Printer()->Printing)) {
M.Result = 1;
return;
}
TForm::Dispatch(&M);
}
//---------------------------------------------------------------------------
BOOL __fastcall TForm1::OnPaintCallbackEvent(HDC dc)
{
//Optional callback event!
//handle the painting yourself here and return TRUE, or return FALSE
//and TExcellentFormPrinter will handle the call!
return(FALSE);
}
//---------------------------------------------------------------------------
BOOL __fastcall TForm1::OnPaintControlCallbackEvent(Controls::TControl* TheControl,
HDC dc)
{
//Optional callback event!
//You can test to see what kind of control "TheControl" is, and
//handle the painting yourself and return TRUE, or return FALSE
//and TExcellentFormPrinter will handle the call!
return(FALSE);
}
//---------------------------------------------------------------------------
//define a data type we will use during a callback
//to update an abort dialog with a status update
#pragma pack(push, 1)
typedef struct _AppCallbackData
{
TAbortDialog * AbortDialog; //The abort dialog
int PageAcross; //The current page printing across
int PageDown; //The current page printing down
} TAppCallbackData, *PAppCallbackData;
#pragma pack(pop)
//---------------------------------------------------------------------------
//Our optional status update callback event
BOOL __stdcall AppPrintingCallbackFn(DWORD UnitsDone,
DWORD TotalUnits,
DWORD UserData) {
System::AnsiString s;
TAppCallbackData * TheData;
//cast UserData to a usable form
TheData = (TAppCallbackData *) UserData;
//update the abort dialogs caption to give a status update.
s = "Printing Page " +
IntToStr(TheData->PageAcross) +
":" +
IntToStr(TheData->PageDown) +
" - " +
IntToStr(INT((((float)UnitsDone / (float)TotalUnits) * 100))) +
"%";
AbortDialogSetCaption(TheData->AbortDialog,
s.c_str());
//return if the user has canceled the print job.
return(! AbortDialogUserHasCanceled(TheData->AbortDialog));
}
//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
int PagesWide; //How many pages wide you want.
int PagesHigh; //How many pages high you want.
BOOL CenterFormOnPage; //Center on the page or print at the top left corner?
TAbortDialog* AbortDialog; //The Abort Dialog.
TAppCallbackData AppCallbackData; //Our callback data structure.
TPrnPageInfo PrnPageInfo; //Info about the page to be printed.
SIZE VirtualFormSize; //Size of the form (including non visible scrolled areas.
int TotalImageWidth; //Total width of the printout (including multiple pages).
int TotalImageHeight; //Total height of the printout (including multiple pages).
double ScaleX; //How much the form gets stretched in the x direction.
double ScaleY; //How much the form gets stretched in the y direction.
int PrintedFormWidth; //Total printed width of the form (including multiple pages).
int PrintedFormHeight; //Total printed height of the form (including multiple pages).
POINT PrintedFormOffset; //How much to offset the form to print it centered on the page(s).
int i; //Loop variable (for i := 1 to PagesHigh do).
int j; //Loop variable (for j := 1 to PagesWide do).
int SaveIndex; //Used to save the state of the printer.
System::AnsiString APageCaption; //Used to print a caption on the page.
System::AnsiString AnAbortCaption; //Used to update the abort dialog caption.
RECT PageRect; //The clipping rectangle for the page.
TPrintFormData PrintFormData;
//how many pages to print across and down
PagesWide = 2;
PagesHigh = 2;
//center the output on the page? (FALSE prints the form at the top left of the page).
CenterFormOnPage = TRUE;
memset(&PrintFormData,
0,
sizeof(PrintFormData));
PrintFormData.StrucSize = sizeof(PrintFormData);
//Note: we are done with configurable print choices!
//disable the window so the user cannot click on anything while we are printing.
EnableWindow(this->Handle,
FALSE);
//try to fire up the printjob!
try {
Printer()->BeginDoc();
} catch ( ... ) {
//error! clean up and bail out!
EnableWindow(this->Handle,
TRUE);
ShowMessage("Printer corrupt or not installed!");
return;
}
//create our abort dialog
AbortDialog = CreatePrinterAbortDialog(Application->Handle,
this);
//Set our callback information
AppCallbackData.AbortDialog = AbortDialog;
//get the page information
GetPrnPageInfo(Printer()->Handle,
&PrnPageInfo);
// do some calculations to stretch and position
// the form to fit the page (or pages).
PageRect.left = 0;
PageRect.top = 0;
PageRect.right = PrnPageInfo.AdjustedPageArea.x;
PageRect.bottom = PrnPageInfo.AdjustedPageArea.y;
VirtualFormSize = VirtualClientSize(this);
TotalImageWidth = PagesWide * PrnPageInfo.AdjustedPageArea.x;
TotalImageHeight = PagesHigh * PrnPageInfo.AdjustedPageArea.y;
ScaleX = (double)TotalImageWidth / (double)VirtualFormSize.cx;
ScaleY = (double)TotalImageHeight / (double)VirtualFormSize.cy;
if (ScaleX < ScaleY) {
PrintedFormWidth = TotalImageWidth;
PrintedFormHeight = VirtualFormSize.cy * ScaleX;
PrintedFormOffset.x = 0;
PrintedFormOffset.y = (TotalImageHeight / 2) - (PrintedFormHeight / 2);
} else {
PrintedFormHeight = TotalImageHeight;
PrintedFormWidth = VirtualFormSize.cx * ScaleY;
PrintedFormOffset.x = (TotalImageWidth / 2) - (PrintedFormWidth / 2);
PrintedFormOffset.y = 0;
}
if (! CenterFormOnPage) {
PrintedFormOffset.x = 0;
PrintedFormOffset.y = 0;
}
//loop through and print the pages!
for (i = 1; i <= PagesHigh; i++) {
for (j = 1; j <= PagesWide; j++) {
//set our callback information
AppCallbackData.PageAcross = j;
AppCallbackData.PageDown = i;
//construct a caption to print at the top of each page.
APageCaption = "Page " +
IntToStr(j) +
" : " +
IntToStr(i);
//construct a caption for the abort dialog.
AnAbortCaption = "Printing " + APageCaption;
//set the abort dialog's caption to give the user a status update
PrinterAbortDialogSetCaption(AbortDialog,
AnAbortCaption.c_str());
//test to see if the user canceled the print job
if (PrinterAbortDialogAborted(AbortDialog)) {
//user canceled the print job - clean up and bail out!
Printer()->Abort();
FreePrinterAbortDialog(AbortDialog);
EnableWindow(this->Handle,
TRUE);
ShowMessage("Printing Aborted!");
return;
}
//save the printer state
SaveIndex = SaveDC(Printer()->Canvas->Handle);
//move our origin to account for a perfect printing margin
MoveWindowOrg(Printer()->Canvas->Handle,
PrnPageInfo.AdjustedMarginOffset.x,
PrnPageInfo.AdjustedMarginOffset.y);
//allow drawing only within our perfect margins
IntersectClipRect(Printer()->Canvas->Handle,
0,
0,
PrnPageInfo.AdjustedPageArea.x,
PrnPageInfo.AdjustedPageArea.y);
//print the form! We will need to "back up" the offset of where we print
//the form to account for printing across multiple pages. No need to fear,
//TExcellentPrinter will allow us to print up to 2 billion pixels high
//and wide, even under Windows 95 and 98!
if (! PrintTScrollingWinControlEx(this,
Printer()->Canvas->Handle,
-((j - 1) * PrnPageInfo.AdjustedPageArea.x) + PrintedFormOffset.x,
-((i - 1) * PrnPageInfo.AdjustedPageArea.y) + PrintedFormOffset.y,
PrintedFormWidth,
PrintedFormHeight,
PageRect,
(TAppCallbackFn)AppPrintingCallbackFn,
(DWORD)&AppCallbackData,
OnPaintCallbackEvent,
OnPaintControlCallbackEvent,
&PrintFormData)) {
//this will happen if the user has canceled the print job
//(or a error occured). Clean up and bail out!
RestoreDC(Printer()->Canvas->Handle,
SaveIndex);
FreePrinterAbortDialog(AbortDialog);
Printer()->Abort();
EnableWindow(this->Handle,
TRUE);
ShowMessage("Printing Aborted!");
return;
}
//we can print those lovely page captions here (or anything else we care to print)!
Printer()->Canvas->Font->Name = "Arial";
//fix a VCL issue that pops up sometimes with font scaling!
Printer()->Canvas->Font->PixelsPerInch = PrnPageInfo.DPI.y;
Printer()->Canvas->Font->Size = 10;
Printer()->Canvas->TextOut(0,
0,
APageCaption.c_str());
//we are done printing on this page, restore the printer state!
RestoreDC(Printer()->Canvas->Handle,
SaveIndex);
//if not the last page, we need to call NewPage!
if (! ((j == PagesWide) &&
(i == PagesHigh))) {
Printer()->NewPage();
}
}
}
//We are done! Time to clean up!
FreePrinterAbortDialog(AbortDialog);
Printer()->EndDoc();
EnableWindow(this->Handle,
TRUE);
ShowMessage("Printing Completed!");
}
Back to Functions and Structures
A VCL Class that many Windows components (such as a Form or TScrollBox) descend from.
Back to Functions and Structures
#pragma pack(push, 1)
typedef struct _TPrintFormData
{
DWORD StrucSize;
BOOL UseAbortDialog;
BOOL DoNotFlushGDICalls;
BOOL Use24BitOutputOnly;
} TPrintFormData, *PPrintFormData;
#pragma pack(pop)
Location: PrnForm.h
The TPrintFormData structure is used with the PrintFormEx()
functions, and allows us to add additional functionality in future releases
without requiring you to make changes to your code (unless you wish to take
advantage of the additional functionality). The only member of this structure
that is required to be initialized is the StrucSize member. All other members
are designed to default to zero values. The TPrintFormData members are
currently defined as:
StrucSize : The size of the TPrintFormData structure. Required.
UseAbortDialog : If TRUE, an Abort/Status dialog is displayed while the
form is being printed, and allows the user to cancel the print job.
DoNotFlushGDICalls : The PrintForm engine makes frequent calls to the
Windows API GDIFlush() function. If this member is TRUE, we will not call the
GDIFlush(). This is intended for experienced users who are writing
multi-threaded printing applications.
Use24BitOutputOnly : The PrintForm engine prints in sections, and
automatically analyzes each output section to obtain the minimum color depth
required for that section, and outputs a bitmap for that section using the
minimum number of colors required. This can substantially reduce the printing,
transmission and resource overhead for the print job. If this member is set to
TRUE, then this optimization is turned off, and all sections are sent as 24 bit
True Color bitmaps.
Back to Functions and Structures
BOOL __fastcall HasClass(Controls::TControl* AObject,
const System::AnsiString AClassName);
Location: PrnForm.h
Returns TRUE if the given control descends from a given class. AClassName is case sensitive. This function works in a similar manner as the VCL class type operators, however may be safer to use when working in a DLL environment.
Back to Functions and Structures
SIZE __fastcall VirtualClientSize(Controls::TControl* AControl);
Location: PrnForm.h
Returns the total size of a controls client area, including any area that
may be scrolled out of view (if the control descends from a
TScrollingWinControl).
Note: A SIZE structure is equivalent to a TPoint structure where the x and y
members are named .cx and .cy.
Back to Functions and Structures
POINT __fastcall VirtualClientScrolledOffset(Controls::TControl* AControl);
Location: PrnForm.h
Returns the current offset of a controls client area (the amount the control is scrolled) if the control descends from a TScrollingWinControl, otherwise returns (0,0).
Back to Functions and Structures
void __fastcall PrnFormSetDebugMsg(BOOL value);
Location: PrnForm.h and PrnForm.cpp
This function (when set to TRUE) causes a Windows messagebox
to be displayed in the event that the Windows StretchDIBits,
BitBlt, MoveTo, or LineTo functions fail. Should you use this
function, you should also call the
PrnFormSetAbortDialogHandle()
to set the parent window of any messageboxes that are displayed,
else the messageboxes may not appear on the screen, but may in fact
show up on the taskbar. Should any messageboxes appear, this indicates
that the problem is most likely downstream from TExcellentFormPrinter,
but can be also caused by memory corruption in the VCL or your application,
especially in multi-threaded applications.
The default value is FALSE.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugMsg(TRUE);
PrnFormSetAbortDialogHandle(this->Handle);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
PrnPrnFormSetAbortDialogHandle
HWND __fastcall PrnPrnFormSetAbortDialogHandle(HWND value);
Location: PrnForm.h and PrnForm.cpp
This function informs the TExcellentFormPrinter engine of the handle
of a status window you may be displaying during the print job, allowing
any error messageboxes to display on top of your status window. Failure
to set this value may cause any error messageboxes to be shown with the
Windows desktop as the owner.
This value only has meaning when
PrnFormSetDebugMsg() is set to TRUE.
The default value is 0.
Returns:
The previous window handle.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugMsg(TRUE);
PrnFormSetAbortDialogHandle(this->Handle);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetDebugDoBlt(BOOL value);
Location: PrnForm.h and PrnForm.cpp
This function (when set to FALSE) causes
TExcellentFormPrinter to go through its normal code
except it does not actually transfer the bitmap
to the GDI (ie, you will get a blank sheet of paper,
unless the PrnFormSetDebugFrames
is set to TRUE.
If you get a crash in the TExcellentFormPrinter unit
(using the standard supported list of controls) in a
simple test app, then it is likely you have exposed a
problem in the TExcellentFormPrinter code. Please
alert us as soon as possible so that we may
take steps to correct the problem and publish a fix (if
it can be determined that TExcellentFormPrinter actually
caused the problem).
The default value is TRUE.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugDoBlt(FALSE);
PrnFormSetDebugFrames(TRUE);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetDebugUseDDB(BOOL value);
Location: PrnForm.h and PrnForm.cpp
This function (when set to TRUE) causes
TExcellentFormPrinter to internally use a Device Dependent Bitmap
(as opposed to a Device Independent Bitmap), and transfers
those bitmaps using the Windows API function BitBlt(),
(as opposed to using the Windows API function StretchDIBits().
Please note that if a call to StretchDIBits() fails, the TExcellentFormPrinter
default recovery plan is to switch to using device dependent bitmaps
and transfer the bitmap using the Windows API function BitBlt(). This
automatic recovery logic can be controlled by the use of the
PrnFormSetDebugAutoUseDDB()
function. A word of warning: Some printers will claim that StretchDIBits()
was successful, even though the call actually failed. For those
printers, your application should still provide a way for the user
to force the use of device dependent bitmaps using a call to
the PrnFormSetDebugUseDDB() function.
We have found that some printers report that they support
the Windows StretchDIBits() function, however, calls to the
StretchDIBits() function will sometimes fail on some printers.
This function provides a workaround for buggy print drivers.
Note that for printers that do not support the Windows
StretchDIBits() function, it is still safe to call the
StretchDIBits() function, as Windows should automatically
simulate the call using lower level driver calls.
Note that the Device Dependent Bitmap that is created is
based on the context of the output device. This implies
that the bitmap created will most likly be a monochrome
bitmap with one bit of color depth. Note that most devices
do not provide for reasonable dithering of colors to a
monochrome bitmap, so color translation may be lost.
The default value is FALSE.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugUseDDB(TRUE);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetDebugAutoUseDDB(BOOL value);
Location: PrnForm.h and PrnForm.cpp
Normally, TExcellentFormPrinter uses Device Independent Bitmaps
and the Windows API function StretchDIBits() to transfer images.
This function (when set to TRUE) causes TExcellentFormPrinter
to first try using Device Independent Bitmaps and the StretchDIBits()
function. If the StretchDIBits() function fails, then TExcellentFormPrinter
will automatically switch to using device dependent bitmaps and attempt
to transfer bitmaps using the Windows API function BitBlt().
Please note that some printers will claim that StretchDIBits()
was successfull, even though the call actually failed. For those
printers, your application should provide a way for the user
to force the use of device dependent bitmaps using a call to
the PrnFormSetDebugUseDDB()
function.
We have found that some printers report that they support
the Windows StretchDIBits() function, however, calls to the
StretchDIBits() function will sometimes fail on some printers.
This function provides a workaround for buggy print drivers.
Note that for printers that do not support the Windows
StretchDIBits() function, it is still safe to call the
StretchDIBits() function, as Windows should automatically
simulate the call using lower level driver calls.
Note that the Device Dependent Bitmap that is created is
based on the context of the output device. This implies
that the bitmap created will most likly be a monochrome
bitmap with one bit of color depth. Note that most devices
do not provide for reasonable dithering of colors to a
monochrome bitmap, so color translation may be lost.
The default value is TRUE.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugAutoUseDDB(FALSE);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetDebugFrames(BOOL value);
Location: PrnForm.h and PrnForm.cpp
This function (when set to TRUE) causes
TExcellentFormPrinter to print cross-hairs through
each "chunk" that is printed. This is useful
for testing where the image chunks would be printed, and is
often used with the
PrnFormSetDebugDoBlt(FALSE)
setting for debugging purposes.
The default value is FALSE in the registered versions of the product,
and is automatically set to TRUE in the trial versions.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDebugFrames(TRUE);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetSleepValue(int value);
Location: PrnForm.h and PrnForm.cpp
This function (when set a value of zero or greater) causes
TExcellentFormPrinter call the Windows API function Sleep(value)
between each image transfer call, and may provide some relief
for buggy 3rd party spooler software that may be installed with
some printer drivers, by allowing the spooler to catch up with the
image data that is sent.
The default value is -1.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetSleepValue(1000);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetOutputScaleFactor(int x,
int y);
Location: PrnForm.h and PrnForm.cpp
The TExcellentFormPrinter default behavior is output form images pre-scaled to the
full resolution of the printer. This can produce large print jobs.
This function reduces the resolution of the output by the scale
factor given, and asks the print driver to enlarge the output
by the same amount. In other words, a scale factor of 2 reduces
the resolution of the output by 2, and the print driver will
enlarge the output by 2. Reducing the resolution by a factor
of 2 should provide a four times reduction in the amount
of data spooled, and reducing the resolution by a factor
of 4 should provide a sixteen times reduction in the amount
of data spooled. For reliablity, the scale factor should always
be less than 8. A scale factor of (1,1) (the default value) outputs
form images at the full resolution of the device. Note that printing
systems with intellegent pre-processors may not actually reduce
the amount of output generated, as the pre-processor may compress
image data at the full resolution of the printer, however, some
systems may greatly benefit from resolution reduction, and the
gains measured may actually be double the expected amount.
On high resolution printers, a scaling factor of (2,2) often
provides output that appears identical to using the full resolution
of the device.
The default value is (1,1).
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetOutputScaleFactor(2, 2);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures
void __fastcall PrnFormSetDoWinScale(BOOL value);
Location: PrnForm.h and PrnForm.cpp
The TExcellentFormPrinter default behavior is output form images pre-scaled to the
full resolution of the printer. This can produce large print jobs.
This function (when set to true) causes "form image chunks"
to be sent to the printer for re-scaling. If the form you are
printing is to be enlarged, this can amount to a significant
savings in print job size. If the form you are printing is
to be reduced, this can amount to a significant enlargement
in print job size. This function responds to scaling factors
introduced by the
PrnFormSetOutputScaleFactor()
function.
The default value is FALSE.
Example:
void __fastcall TForm1::Menu1Click(TObject *Sender)
{
Printer()->BeginDoc();
PrnFormSetDoWinScale(TRUE);
PrintForm(this,
Printer()->Canvas->Handle,
TRUE,
TRUE);
Printer()->EndDoc();
end;
Back to Functions and Structures