PrintDialogBox

(Engine-Level Function)

Description:	Displays a threaded system common printer selection dialog box.
Returns:	Nothing
Usage:	Script Only.
Function Groups:	Graphics,  Printer
Related to:	FontDialog | FileDialogBox | FileStream
Format:	PrintDialogBox(PrinterName, PrinterDevice, MinPage, MaxPage, FirstPage, LastPage, NumCopies, Result [, AllowSelection])
Parameters:

PrinterName

Required. Any text expression giving the initial printer name to display as selected. If this is not a valid text value, the default printer (as configured under Windows) will initially be selected. If PrinterName refers to a variable and the user clicks the "Print" button on the dialog, thereby closing it, the variable will be set to the name of the selected printer. If the user cancels the dialog box, the variable is unchanged.

PrinterDevice

Required. Any variable that will be set to the device name for the selected printer when the user clicks the "Print" button on the dialog. If the user cancels the dialog box, the variable is unchanged. The text expression returned here can be supplied to a FileStream statement to open a stream to the selected printer.

MinPage

Required. Any positive integer expression specifying the minimum page number in the printed output (see Comments section for further details).

MaxPage

Required. Any positive integer expression specifying the maximum page number in the printed output (see Comments section for further details).

FirstPage

Required. Any integer expression specifying the first page to be printed (see Comments section for further details).

LastPage

Required. Any integer expression specifying the last page to be printed (see Comments section for further details).

NumCopies

Required. Any integer expression specifying the number of copies to be printed (see Comments section for further details).

Result

Required. A variable that will be set to one of the following values: Invalid when this statement is run, Zero (0) to indicate that the user has canceled the dialog, or One (1) to indicate that the user has clicked the "Print" button.

AllowSelection

An optional parameter. If provided, it must be a non-constant variable. This enables and controls the "Selection" radio button in the print dialog box. See the Comments section for further details.

Comments:

This function creates a printer selection dialog that runs in its own thread, thereby avoiding blocking the calling code. The calling code can use the Result parameter to determine when the user has completed the dialog box (see Result above). In addition to the Result parameter, the function itself will return an error code to indicate whether the dialog was successfully opened. A "1" indicates failure to open while a "0" indicates success. The caller of this function is expected to supply the MinPage and MaxPage parameters, representing the minimum and maximum page number from which the user may select. FirstPage and LastPage can be initially set to any values between MinPage and MaxPage. If the combination of the four values is not logical (e.g. LastPage is smaller than FirstPage), VTScada will force logical values for the dialog. When Result is set to one, FirstPage and LastPage will contain the page range that the user selected. If Result is set to zero (i.e. the user has canceled the dialog), FirstPage and LastPage are left at their initial values. Setting MinPage and MaxPage to Invalid or to equal values will disable the page range field. NumCopies can likewise contain an initial value, and will be set to the user-selected number of copies if Result returns a value of one. The initial value of the Selection radio button is controlled by the value of the variable provided for the AllowSelection parameter: If the variable's value evaluates to a non-zero positive number, the Selection radio button will be selected. If the variable's value is zero, the radio-button will initially be unselected. When the Print button on the print dialog box is clicked, this variable receives a zero if the Selection radio-button was not selected and one if it was selected. Within an Anywhere Client session, this function does nothing.

Example:

If ZButton(10, 90, 110, 120, "Browse Print", 1, System.DefFont);
[
  PrintDialogBox(PrinterName, PrinterDevice, MinPage, MaxPage,
                 FirstPage, LastPage, NumCopies, Result);
]
ZText(120, 112,
      Concat("Printer chosen: ", PickValid(PrinterName, "Invalid"),
             " (", PickValid(PrinterDevice, "Invalid"), ") Page ",
             PickValid(FirstPage, "Invalid"), " to ",
             PickValid(LastPage, "Invalid"), " Copies: ",
             PickValid(NumCopies, "Invalid")),
      0, System.DefFont);