Copyright © 2012 by CODE4SALE, LLC All Rights Reserved -
Contact Sales.
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
GetPrnPageInfo
TPrnPageInfo
TScaleInfo
ScaleToFitX
ScaleToFitY
ScaleToBestFit
TPixelSizeInfo
GetPixelSizeInfo
GetNumPagesRequired
GetMemEx
FreeMemEx
LoadDIBFromStream
LoadDIBFromFile
LoadDIBFromTBitmap
TAbortDialog
TPrinterAbortDialog
CreateAbortDialog
FreeAbortDialog
AbortDialogSetCaption
AbortDialogUserHasCanceled
CreatePrinterAbortDialog
FreePrinterAbortDialog
PrinterAbortDialogSetCaption
PrinterAbortDialogAborted
Back to Functions and Structures
BOOL __stdcall GetPrnPageInfo(HDC dc,
TPrnPageInfo * lpPrnPageInfo);
Location: PrnUtils.h and PrnUtils.cpp
This function is usefull for retrieving page information from a given device context. It accepts a dc (Canvas.Handle) and a pointer to a TPrnPageInfo structure. Retruns TRUE if successful.
Example:
{
TPrnPageInfo PrnPageInfo;
GetPrnPageInfo(Printer()->Handle,
&PrnPageInfo);
}
Back to Functions and Structures
#pragma pack(push, 1)
typedef struct _TPrnPageInfo
{
RECT Margin; //normal margins to printing area
POINT PageSize; //normal page (paper) size
POINT PageArea; //normal page image size
RECT AdjustedMargin; //adjusted margins (equal on all sizes)
POINT AdjustedPageArea; //page image size adjusted for equal margins
POINT AdjustedMarginOffset; //amount to offset output for adjusted margins
POINT DPI; //pixels per inch
} TPrnPageInfo, *PPrnPageInfo;
#pragma pack(pop)
Location: PrnUtils.h and PrnUtils.cpp
Note: Not all devices have equal margins on all sides. This function is
used with the GetPrnPageInfo() function and
retrieves margin and page information and calculates the "adjusted
margins" for the device allowing you to offset either the device context,
or offset your drawing operations, to obtain page output that is equally
centered on the page. All values are returned in pixel coordinates. The Margin
and AdjustedMargin members are the distances from the edge of the device to the
edge of the corrisponding rect. In other words, given that the margins are:
Margin.Left = 150;
Margin.Top = 100;
Margin.Right = 25;
Margin.Bottom = 50;
The Adjusted margins would be:
AdjustedMargin.Left = 150;
AdjustedMargin.Top = 150;
AdjustedMargin.Right = 150;
AdjustedMargin.Bottom = 150;
This structures "Adjusted" members also adjusts for super high
resolution devices that have a page area that exceed 32000 pixels wide or high.
Under Win9x platforms, it is an error condition when output coordinates exceed
32000 pixels. The adjusted page size accounts for this limitation, allowing you
a safe working area under all Windows platforms on all devices.
Back to Functions and Structures
#pragma pack(push, 1)
typedef struct _TScaleInfo
{
double OriginalSize_X;
double OriginalSize_Y;
double ScaledSize_X;
double ScaledSize_Y;
double ScaleFactor_X;
double ScaleFactor_Y;
} TScaleInfo, *PScaleInfo;
#pragma pack(pop)
Location: PrnUtils.h and PrnUtils.cpp
This structure is used with many of the scaling functions included in the PrnUtils unit.
Back to Functions and Structures
BOOL __stdcall ScaleToFitX(TScaleInfo * lpScaleInfo);
Location: PrnUtils.h and PrnUtils.cpp
This function accepts a pointer to a TScaleInfo structure. Given an Original(X,Y) and an X size to fit, this function calculates the scaled Y size (in proportion to X), and the scale factors used. Returns TRUE if successful.
TScaleInfo On Input: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : Horizontal size to fit. ScaledSize_Y : Not filled in. ScaleFactor_X : Not filled in. ScaleFactor_Y : Not filled in. TScaleInfo On Output: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : Horizontal size to fit. ScaledSize_Y : OriginalSize_Y scaled in proportion to X. ScaleFactor_X : Horizontal scaling factor. ScaleFactor_Y : Vertical scaling factor.
Example:
{
TScaleInfo ScaleInfo;
ScaleInfo.OriginalSize_X = 100;
ScaleInfo.OriginalSize_Y = 200;
ScaleInfo.ScaledSize_X = 1000;
ScaleToFitX(&ScaleInfo);
//Note:
//ScaledSize_X now equals 1000
//ScaledSize_Y now equals 2000
//ScaleFactor_X now equals 10
//ScaleFactor_Y now equals 10
}
Back to Functions and Structures
BOOL __stdcall ScaleToFitY(TScaleInfo * lpScaleInfo);
Location: PrnUtils.h and PrnUtils.cpp
This function accepts a pointer to a TScaleInfo structure. Given an Original(X,Y) and any Y size to fit, this function calculates the scaled X size (in proportion to Y), and the scale factors used. Returns TRUE if successful.
TScaleInfo On Input: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : Not filled in. ScaledSize_Y : Vertical size to fit. ScaleFactor_X : Not filled in. ScaleFactor_Y : Not filled in. TScaleInfo On Output: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : OriginalSize_X scaled in proportion to Y. ScaledSize_Y : Vertical size to fit. ScaleFactor_X : Horizontal scaling factor. ScaleFactor_Y : Vertical scaling factor.
Example:
{
TScaleInfo ScaleInfo;
ScaleInfo.OriginalSize_X = 100;
ScaleInfo.OriginalSize_Y = 200;
ScaleInfo.ScaledSize_Y = 1000;
ScaleToFitY(&ScaleInfo);
//Note:
//ScaledSize_X now equals 500
//ScaledSize_Y now equals 1000
//ScaleFactor_X now equals 5
//ScaleFactor_Y now equals 5
}
Back to Functions and Structures
BOOL __stdcall ScaleToBestFit(TScaleInfo * lpScaleInfo);
Location: PrnUtils.h and PrnUtils.cpp
This function accepts a pointer to a TScaleInfo structure. Given an Original(X,Y) and an (X,Y) size to fit, this function calculates the "best fit" scaled X and Y size and the scale factors used. The scaling is done in proportion, and *either* the ScaledSize X or Y will fit in the maximum area allowed, and the other "side" will be scaled for a "best fit". If you wish to use the returned scaling factors to stetch drawing coordinates, always multiply *both* the x and y coordinates you wish to scale using the *smaller* of the ScaleFactor_X or ScaleFactor_X value returned from the function. Returns TRUE if successful.
TScaleInfo On Input: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : Maximum horizontal size to fit. ScaledSize_Y : Maximum vertical size to fit. ScaleFactor_X : Not filled in. ScaleFactor_Y : Not filled in. TScaleInfo On Output: OriginalSize_X : Horizontal size of the original. OriginalSize_Y : Vertical size of the original. ScaledSize_X : OriginalSize_X scaled to best fit. ScaledSize_Y : OriginalSize_Y scaled to best fit. ScaleFactor_X : Horizontal scaling factor. ScaleFactor_Y : Vertical scaling factor.
Example:
{
TScaleInfo ScaleInfo;
double SmallestScaleFactor;
ScaleInfo.OriginalSize_X = 100;
ScaleInfo.OriginalSize_Y = 200;
ScaleInfo.ScaledSize_Y = 1000;
ScaleInfo.ScaledSize_Y = 1000;
ScaleToFitY(&ScaleInfo);
//Note:
//ScaledSize_X now equals 500
//ScaledSize_Y now equals 1000
//ScaleFactor_X now equals 10
//ScaleFactor_Y now equals 5
if (ScaleInfo.ScaleFactor_X < ScaleInfo.ScaleFactor_Y) {
SmallestScaleFactor = ScaleInfo.ScaleFactor_X;
} else {
SmallestScaleFactor = ScaleInfo.ScaleFactor_Y;
}
Canvas->MoveTo(0, 0);
Canvas->LineTo((double)(SmallestScaleFactor) * 100,
(double)(SmallestScaleFactor) * 200);
}
Back to Functions and Structures
#pragma pack(push, 1)
typedef struct _TPixelSizeInfo
{
double DotsPerInch_X;
double DotsPerInch_Y;
double DotsPerMillimeter_X;
double DotsPerMillimeter_Y;
double DotsPerPoint_X;
double DotsPerPoint_Y;
} TPixelSizeInfo, *PPixelSizeInfo;
#pragma pack(pop)
Location: PrnUtils.h and PrnUtils.cpp
This structure is used with the GetPixelSizeInfo() function and returns information pixel measurements in several popular measuring units. Note that the DotsPerPoint member is a "Printers Point" where their 72 points equal one inch. Additional information: 12 points equal one pica, and 6 picas equals one inch.
Back to Functions and Structures
BOOL __stdcall GetPixelSizeInfo(HDC,
TPixelSizeInfo * lpPixelSizeInfo);
Location: PrnUtils.h and PrnUtils.cpp
This function accepts a given device context (Canvas.Handle), and a pointer to a TPixelSizeInfo structure, and correctly fills out the TPixelSizeInfo structure. If dc value passed in is zero, then information returned is from the screen dc. Returns TRUE if successful.
Example:
{
TPixelSizeInfo PixelSizeInfo;
GetPixelSizeInfo(Printer()->Canvas->Handle,
&PixelSizeInfo);
}
Back to Functions and Structures
DWORD __stdcall GetNumPagesRequired(DWORD PrinterPageSize,
DWORD ImageSize);
Location: PrnUtils.h and PrnUtils.cpp
Given the page size of a device (x or y), and an image size you wish to print (x or y), returns the number of pages (across or down) required to print image size in the direction given.
Example:
{
DWORD NumberOfPagesToPrintAcross;
DWORD NumberOfPagesToPrintDown;
NumberOfPagesToPrintAcross = GetNumPagesRequired(Printer()->PageWidth,
20000);
NumberOfPagesToPrintDown = GetNumPagesRequired(Printer()->PageHeight,
10000);
}
Back to Functions and Structures
void * __stdcall GetMemEx(DWORD size);
Location: PrnUtils.h and PrnUtils.cpp
Allocates a memory block and zeros out the memory block. Returns null on failure. This function is preferable over the RTL memory functions when allocating memory for graphics used in a threaded enviroment. Please use the FreeMemEx() function to free the memory block allocated.
Example:
{
BITMAPINFO * bmiOut;
bmiOut = (BITMAPINFO*) GetMemEx(1024);
bmiOut = (BITMAPINFO*) FreeMemEx(bmiOut);
}
Back to Functions and Structures
void * __stdcall FreeMemEx(void * p);
Location: PrnUtils.h and PrnUtils.cpp
Frees a memory block allocated using the GetMemEx() function. Returns nill on success or returns the original pointer on failure.
Example:
{
BITMAPINFO * bmiOut;
bmiOut = (BITMAPINFO*) GetMemEx(1024);
bmiOut = (BITMAPINFO*) FreeMemEx(bmiOut);
}
Back to Functions and Structures
BOOL __stdcall LoadDIBFromStream(TStream * TheStream,
void * lpBitmapInfo,
void * lpBits,
int * BitmapWidth,
int * BitmapHeight);
Location: PrnUtils.h and PrnUtils.cpp
This function loads a DIB (device independent bitmap from a TStream object.
The function allocates the neccessary memory for the DIBInfoHeader and the DIB
Bits using the GetMemEx() function, and fills in the
lpBitmapInfo, lpBits, BitmapWidth, and BitmapHeight
parameters. You must use the FreeMemEx() function to
free the memory for the lpBitmapInfo and lpBits when you are
finished using them.
Note: The stream objects current position is advanced. In the case of a failure
(the bitmap is not valid), the stream objects current position may be invalid.
If you are storing multiple DIB images in a stream, it is recommended that you
either create a table of StreamOffsets for each DIB, or use a header for each
bitmap indicating the exact size that the DIB occupies, there may be times when
a given DIB may report an invalid size (or the size must be calculated and the
DIB Header may be invalid). Using this method will allow you to recover from a
read of an inproperly formatted DIB image.
Returns TRUE if successful, else returns FALSE.
Example:
{
BITMAPINFO * BitmapInfo;
void * Bits;
int BitmapWidth;
int BitmapHeight;
TFileStream * TheStream;
TheStream = new TFileStream("test.bmp",
fmOpenRead |
fmShareDenyWrite);
if (!LoadDIBFromStream(TheStream,
(PVOID*)&BitmapInfo,
&Bits,
&BitmapWidth,
&BitmapHeight)){
TheStream->Free();
ShowMessage("Bitmap load error");
return;
}
TheStream->Free();
Printer()->BeginDoc();
//A function from out TExcellentImagePrinter product!
PrintDIBitmap(Printer()->Canvas->Handle,
BitmapInfo,
Bits,
FALSE,
FALSE);
Printer()->EndDoc();
FreeMemEx(BitmapInfo);
FreeMemEx(Bits);
ShowMessage("Printing Completed!");
}
Back to Functions and Structures
BOOL __stdcall LoadDIBFromFile(const char * lpFileName,
void * lpBitmapInfo,
void * lpBits,
int * BitmapWidth,
int * BitmapHeight);
Location: PrnUtils.h and PrnUtils.cpp
This function loads a DIB (device independent bitmap) from a file. The function allocates the neccessary memory for the DIBInfoHeader and the DIB Bits using the GetMemEx() function, and fills in the lpBitmapInfo, lpBits, BitmapWidth, and BitmapHeight parameters. You must use the FreeMemEx() function to free the memory for the lpBitmapInfo and lpBits when you are finished using them. Returns TRUE if successful, else returns FALSE.
Example:
{
BITMAPINFO * BitmapInfo;
void * Bits;
int BitmapWidth;
int BitmapHeight;
if (!LoadDIBFromFile("test.bmp",
(PVOID*)&BitmapInfo,
&Bits,
&BitmapWidth,
&BitmapHeight)){
ShowMessage("Bitmap load error");
return;
}
Printer()->BeginDoc();
//A function from out TExcellentImagePrinter product!
PrintDIBitmap(Printer()->Canvas->Handle,
BitmapInfo,
Bits,
FALSE,
FALSE);
Printer()->EndDoc();
FreeMemEx(BitmapInfo);
FreeMemEx(Bits);
ShowMessage("Printing Completed!");
}
BOOL __stdcall LoadDIBFromTBitmap(Graphics::TBitmap * ABitmap,
void * lpBitmapInfo,
void * lpBits,
int * BitmapWidth,
int * BitmapHeight);
Location: PrnUtils.h and PrnUtils.cpp
This function loads a DIB (device independent bitmap) from a VCL TBitmap. The
function allocates the neccessary memory for the DIBInfoHeader and the DIB Bits
using the GetMemEx() function, and fills in the
lpBitmapInfo, lpBits, BitmapWidth, and BitmapHeight
parameters. You must use the FreeMemEx() function to
free the memory for the lpBitmapInfo and lpBits when you are
finished using them.
Note: This function is only as accurate as the VCL in its ability to save a
bitmap to a stream. We simply ask the VCL to save the TBitmap to a stream, then
we load it from the stream. In some versions of the VCL, the bitmap format may
change in the process. Note that LoadDIBFromTBitmap() has proven to be much
more reliable than the VCL's GetDibSizes() and GetDIBBits() functions, where we
have seen many real world failures (even though the VCL may use these functions
internally to save the same bitmap to a stream). This is especially true in a
threaded enviroment.
Returns TRUE if successful, else returns FALSE.
Example:
{
BITMAPINFO * BitmapInfo;
void * Bits;
int BitmapWidth;
int BitmapHeight;
if (!LoadDIBFromTBitmap(Image1->Picture->Bitmap,
(PVOID*)&BitmapInfo,
&Bits,
&BitmapWidth,
&BitmapHeight)){
ShowMessage("Bitmap load error");
return;
}
Printer()->BeginDoc();
//A function from out TExcellentImagePrinter product!
PrintDIBitmap(Printer()->Canvas->Handle,
BitmapInfo,
Bits,
FALSE,
FALSE);
Printer()->EndDoc();
FreeMemEx(BitmapInfo);
FreeMemEx(Bits);
ShowMessage("Printing Completed!");
}
Back to Functions and Structures
class TAbortDialog : public TForm
{
__published: // IDE-managed Components
TButton *btnCancel;
void __fastcall btnCancelClick(TObject *Sender);
private: // User declarations
BOOL Canceled;
public: // User declarations
__fastcall TAbortDialog(TComponent* Owner);
__fastcall BOOL Aborted();
};
Location: PrnUtils.h and PrnUtils.cpp
An abort dialog box used by the TExcellentPrinter family of products. We have designed wrapper functions to create, query, and free this dialog class. While you are free to use the class directly, we discourage this practice, as it may not be upwardly compatible with updates to the TExcellentPrinter family of products. In addition, by using the wrapper functions, we can assure compatibility with many of our products when used from other non-VCL languages, as we plan to offer many of our products in a DLL format where the wrapper functions can be called.
Back to Functions and Structures
typedef TAbortDialog TPrinterAbortDialog;
Location: PrnUtils.h and PrnUtils.cpp
A backwards compatible Abort Dialog prototype for use with code that was written for earlier versions of our products.
Back to Functions and Structures
TAbortDialog* __stdcall CreateAbortDialog(HANDLE ApplicationHandle,
Classes::TComponent* AOwner);
Location: PrnUtils.h and PrnUtils.cpp
Creates and shows an abort dialog. ApplicationHandle should be set to Application.Handle when called from an executable, and should be set to the Application.Handle of the calling executable when used from a Dynamic Link Library. Returns a 32bit object reference to an TAbortDialog if successful, or nil on failure.
Example:
{
TAbortDialog* AbortDialog; //any 32 bit type will so if calling from a non VCL language
AbortDialog = CreateAbortDialog(Application->Handle,
this);
AbortDialogSetCaption(AbortDialog,
"Printing");
//Do some lengthy operation
if (AbortDialogUserHasCanceled(AbortDialog)) {
//Abort the process
}
FreeAbortDialog(AbortDialog);
}
Back to Functions and Structures
void __stdcall FreeAbortDialog(TAbortDialog* AbortDialog);
Location: PrnUtils.h and PrnUtils.cpp
Frees an abort dialog.
Example:
{
TAbortDialog* AbortDialog; //any 32 bit type will so if calling from a non VCL language
AbortDialog = CreateAbortDialog(Application->Handle,
this);
AbortDialogSetCaption(AbortDialog,
"Printing");
//Do some lengthy operation
if (AbortDialogUserHasCanceled(AbortDialog)) {
//Abort the process
}
FreeAbortDialog(AbortDialog);
}
Back to Functions and Structures
void __stdcall AbortDialogSetCaption(TAbortDialog* AbortDialog,
char *s);
Location: PrnUtils.h and PrnUtils.cpp
Sets the caption of an abort dialog.
Example:
{
TAbortDialog* AbortDialog; //any 32 bit type will so if calling from a non VCL language
AbortDialog = CreateAbortDialog(Application->Handle,
this);
AbortDialogSetCaption(AbortDialog,
"Printing");
//Do some lengthy operation
if (AbortDialogUserHasCanceled(AbortDialog)) {
//Abort the process
}
FreeAbortDialog(AbortDialog);
}
Back to Functions and Structures
BOOL __stdcall AbortDialogUserHasCanceled(TAbortDialog* AbortDialog);
Location: PrnUtils.h and PrnUtils.cpp
Returns TRUE if the user has pressed the cancel button of an abort dialog.
Example:
{
TAbortDialog* AbortDialog; //any 32 bit type will so if calling from a non VCL language
AbortDialog = CreateAbortDialog(Application->Handle,
this);
AbortDialogSetCaption(AbortDialog,
"Printing");
//Do some lengthy operation
if (AbortDialogUserHasCanceled(AbortDialog)) {
//Abort the process
}
FreeAbortDialog(AbortDialog);
}
Back to Functions and Structures
TPrinterAbortDialog* __stdcall CreatePrinterAbortDialog(HANDLE ApplicationHandle,
Classes::TComponent* AOwner);
Location: PrnUtils.h and PrnUtils.cpp
This is a backwards compatible wrapper function for code that was written for earlier versions of our products. We now encourage you to use the newer CreateAbortDialog() function where possible. The documentation for this function is the same as the CreateAbortDialog() function.
Back to Functions and Structures
void __stdcall FreePrinterAbortDialog(TPrinterAbortDialog* AbortDialog);
Location: PrnUtils.h and PrnUtils.cpp
This is a backwards compatible wrapper function for code that was written for earlier versions of our products. We now encourage you to use the newer FreeAbortDialog() function where possible. The documentation for this function is the same as the FreeAbortDialog() function.
Back to Functions and Structures
void __stdcall PrinterAbortDialogSetCaption(TPrinterAbortDialog* AbortDialog,
char *s);
Location: PrnUtils.h and PrnUtils.cpp
This is a backwards compatible wrapper function for code that was written for earlier versions of our products. We now encourage you to use the newer AbortDialogSetCaption() function where possible. The documentation for this function is the same as the AbortDialogSetCaption() function.
Back to Functions and Structures
BOOL __stdcall PrinterAbortDialogAborted(TPrinterAbortDialog* AbortDialog);
Location: PrnUtils.h and PrnUtils.cpp
This is a backwards compatible wrapper function for code that was written for earlier versions of our products. We now encourage you to use the newer AbortDialogUserHasCanceled() function where possible. The documentation for this function is the same as the AbortDialogUserHasCanceled() function.
Back to Functions and Structures