<< Click to Display Table of Contents >> Navigation:  Printing Functions > SetupPrinter

[Windows platform only; not supported by PHP and the Community Edition]

This is a very central function for controlling the printer. You can create a setup for the printer separate from printing. The settings for the printer can be stored/retrieved in/from a file (optional), so the settings can be used permanently.

The method is very flexible, as your end-user may make individual printer-setups for each kind of document. So the user can not only specify an individual printer for each different type of document, but also the printer's properties, like the number of copies, collation, output paper bin and everything else. Just let the user make these definitions in an extra part of your application and store the different settings into different files. This will give you the best control possible, and you can easily implement a "Printer Setup" function in your applications menu using this method.

The setup and storage into a file is done with a single call to SetupPrinter(), where you provide the file name as parameter and set the parameter DialogControl = PRINTDLG_ALWAYS.

For example with the call: SetupPrinter("document_type_1.prs", PRINTDLG_ALWAYS)
VPE will try to read the file "document_type_1", and load it, if it exists. Next, a dialog with the settings stored in the file (or default settings, if no file is found) will appear and your user can make all settings available in the dialog(s). If the user then pushes the OK button, the settings are stored in the file "document_type_1.prs".

Later, when printing the document of "type 1", you call OpenDoc() and then SetupPrinter( "document_type_1.prs", PRINTDLG_ONFAIL). The flag PRINTDLG_ONFAIL will let the setup-dialog only come up, if the file "document_type_1.prs" is not found. For example if your user hasn't done the setup yet (the specified file is not found), it will be done then and only once! Otherwise, if the file is found, no dialog is shown and the printer setup - using all previously stored settings from the file - is performed "silently".

Important: VPE saves all settings to the setup file: name of the printer, driver, port and in addition all other driver-specific private data. The private printer-driver data includes every special option a printer-driver provides, even those which can not be accessed through the standard Windows API. This means that your users can set, store and use just any option of the printer!

method integer VPE.SetupPrinter(

string FileName,

PrintDialogControl [integer] DialogControl

)

string FileName

(path and) file name of the file where to restore or store the setup or ""

PrintDialogControl [integer] DialogControl

possible values are:

Returns:

Remarks:

For standardization, Printer Setup Files created with VPE should have the suffix ".PRS".

 

Beside using SetupPrinter(), you can read Printer Setup Files into VPE by using ReadPrinterSetup() and you can write them using WritePrinterSetup().

 

If there is a problem in the printing system, for example the printer used in the setup file is no longer installed in the system, SetupPrinter() will try to select the default printer. If this is not possible, SetupPrinter() will return the value "4".

 

VPE is not using the settings of a printer for the document (otherwise it wouldn't be printer-independent). In order to reflect the settings of the printer, let the user make a printer setup - or read an existing setup from a PRS file - and assign the Device Control Propertieslike DevPaperFormat and DevOrientation, etc. to the current VPE Document (see PageFormat and PageOrientation). For an example, see below.

 

The page range is not written to a PRS File:

It does not make sense to store the page range within a generic setup file, which is intended to be used for different documents.

 

The settings in the PRS file for the page orientation and page format are ignored:

The PageOrientation (Landscape / Portrait) chosen in the Printer Setup Dialog is ignored by VPE: this is by design, because VPE gives you - the developer - the control over the printout. That means: because you can set in a VPE Document the page orientation for each page separately by code, the printer setting for the orientation will be overridden by the settings in the VPE document during printing.

 

The same rule applies to the PageFormat (or individual page dimensions): since you can specify different page formats for each page in a VPE Document separately, VPE ignores the settings in a PRS file and uses the settings of the document. This has the advantage, that VPE instructs the printer at each newly printed page, to use the page dimensions of the currently printed page. Many printers can react on this and choose automatically the right paper from a different paper input bin. If you want to stop VPE from this automatism, or if you need to retrieve the page format from the PRS file, you can specify the flag PRINT_NO_AUTO_PAGE_DIMS for the property PrintOptions.

 

Example:

ActiveX / VCL:

VPE.OpenDoc

// use PRINT_NO_AUTO_PAGE_DIMS, in order to be able to retrieve the

// values for the page dimensions from the PRS file:

VPE.PrintOptions = PRINT_ALL + PRINT_NO_AUTO_PAGE_DIMS

VPE.SetupPrinter "personal settings.prs", PRINTDLG_ONFAIL

VPE.PageWidth = VPE.DevPaperWidth

VPE.PageHeight = VPE.DevPaperHeight

VPE.PageOrientation = VPE.DevOrientation

 

// switch PrintOptions back and let VPE control the printer's page

// dimensions, i.e. clear the flag PRINT_NO_AUTO_PAGE_DIMS

VPE.PrintOptions = PRINT_ALL

 

.NET:

VPE.OpenDoc

// use NoAutoPageDims, in order to be able to retrieve the values

// for the page dimensions from the PRS file:

VB: VPE.PrintOptions = PrintOptions.PrintAll + PrintOptions.NoAutoPageDims

C#: VPE.PrintOptions = PrintOptions.PrintAll | PrintOptions.NoAutoPageDims

VPE.SetupPrinter "personal settings.prs", PrintDialogControl.OnFail

VPE.PageWidth = VPE.DevPaperWidth

VPE.PageHeight = VPE.DevPaperHeight

VPE.PageOrientation = VPE.DevOrientation

 

// switch PrintOptions back and let VPE control the printer's page

// dimensions, i.e. clear the flag PRINT_NO_AUTO_PAGE_DIMS

VPE.PrintOptions = PrintOptions.PrintAll

 

You will notice that we are using PageWidth and PageHeight in the example above. The reason is, that this circumvents a bug in many printer drivers, which return wrong values for DevPaperFormat in case a user defined format has been assigned to the printer. Because of this, the construction "VPE.PageFormat = VPE.DevPaperFormat" can not be used reliably. Instead, use the code from the example above.

 

Printing to a tractor printer using endless paper / labels:

The Windows operating system always generates a Form Feed after a page has been printed. In order to print on endless paper or labels with a tractor printer, set the PageFormat or PageWidth and PageHeight of the VPE Document correspondingly to the dimensions of the paper / label. Since VPE will instruct the printer to use the document's page format, this will force the printer to position exactly on the next page/label after a single page/label has been printed.