%WPR_EXECUTE

Execute printing

return = %WPR_EXECUTE(report_handle, operation[, arguments])

Return value

return

Defined by the specified operation. See the Discussion below.

Arguments

report_handle

The report handle returned by the DWP_GETPRINTER subfunction of %WPR_INFO. (n)

operation

One of the following printer operations: (n)

DWP_PRINT = Print the metafile

DWP_PREVIEW = Preview the metafile

arguments

(optional) Any arguments used by the specified operation.

Discussion

If an invalid report_handle, filename, or printer name is passed, the runtime generates a trappable error. If the routine returns false or generates a trappable error such as $ERR_IOFAIL or $ERR_WNFNCERR, %SYSERR returns the status code from the last system call. (A status code of 1223 means the user canceled the print operation.) Refer to the Windows winerror.h file or check MSDN for more error codes.

DWP_PRINT

DWP_PRINT, [filename][, keep_file]

Plays the metafile to the printer selected in DWP_GETPRINTER. If filename is not a Synergy metafile, an error is returned.

Filename is passed to reprint an existing metafile. If filename is passed and the report handle points to a current print job, filename is verified against the current print job value. If filename is not passed, the current print job value is used.

Keep_file is passed as true to save the file after printing. The default is false, which deletes the metafile.

DWP_PRINT returns true if successful and false if unsuccessful.

DWP_PREVIEW

DWP_PREVIEW, [filename], [previewer_title], [flags][, help_routine]

Opens a preview window displaying the metafile. (See Print previewer.) If filename is not a Synergy metafile, an error is returned.

Previewer_title is the text that is displayed on the preview window’s title bar. The default value is “Synergy Print Preview.” The maximum length of previewer_title is 128 characters, including the “ - page n of n” appended trailing text.

If specified, flags is one or more of the following values:

DWP_PREVIEW_TOOLBAR

The toolbar is displayed in the preview window.

DWP_PREVIEW_PRINTDLG

The Print dialog box is available to the user from the preview window via the Print entry on the File menu.

Help_routine is the name of a Synergy DBL routine to handle the user’s request for Help. If help_routine is not passed or is blank, the Help menu item does not appear. If Help is invoked, the previewer remains visible on the screen. Any windows placed by help_routine must also be removed by the help routine. (Help_routine is ignored in Synergy .NET.)

DWP_PREVIEW returns one of the following:

DWP_PREVIEW_PRINT

The user opted to print the job by selecting File > Print now, by clicking the Print button on the toolbar, or by selecting File > Print and then clicking the Print button in the Print dialog.

DWP_PREVIEW_CANCEL

The user closed the print previewer without printing the job by closing the window, pressing Esc, or selecting File > Exit.

DWP_PREVIEW_REGEN

The user opted to print the job, but the metafile for the document should be regenerated prior to printing, because the user selected a printer with different resolution or modified the page characteristics in some way that would render the metafile output incorrectly. (See DWP_PRINT for more information.)

When regenerating a document to target a new printer, go back to the %WPR_PRINT DWP_BEGINJOB phase and use the same report handle that you used previously; don’t start over with a new report handle.

If you use ^VARARGARRAY, operation is the last declared argument for this routine.

Print previewer

The preview window is displayed when DWP_PREVIEW is passed. From this window, the user can preview any page (or range of pages) in a document to see how it will look when printed. Features include the ability to zoom in or out and change the size of the page as displayed in the window. (See figure 1.)

Some truncation may occur when you zoom a document that contains a font that is not device independent and scalable. We strongly recommend using TrueType or OpenType fonts with the print previewer. Other fonts may only provide a limited number of point sizes and therefore will not scale well. Additionally, some truncation may occur when you use a fixed-pitch TrueType or OpenType font. You can eliminate this truncation by using the enhanced_preview flag in %WPR_PRINT’s DWP_BEGINJOB subfunction.

1. A sample print preview.

To search for text while in the previewer, select Search > Find or click the Find toolbar button. A dialog box will be displayed that prompts for the following search criteria:

Find what

Enter the text you want to search for.

Match case

Select Match case if you want your search to be case-sensitive.

Direction

Select Forward to search forward or Backward to search backward through the previewed text.

To search for subsequent instances of the specified text, select Search > Find next.

Whenever a search in the previewer highlights text, enhanced preview mode is automatically turned off in the page display. However, this does not affect the alignment of the text when it is printed.

To print directly from the previewer, select File > Print now. To display the Print dialog box, select File > Print. If a range of pages was specified (either by the user or via the DWP_SETPAGES subfunction of %WPR_PRINT), the Pages radio button will be selected in the dialog, and the associated text field will contain those page ranges. Otherwise, the All radio button will be selected.

You can also print from the previewer by pressing Ctrl+P. In Synergy .NET, the [STAThread] attribute must be present at the top of the Main method in order for this to work. If [STAThread] is missing and Ctrl+P is pressed, an “Argument is missing” error ($ERR_ARGMIS) occurs.

If the application was responsible for printing the selected pages (in other words, DWP_PRINTDLG_APPPAGE was passed to DWP_PRINTDLG),

the previewer assumes that the pages printed correspond to the specified ranges.
if the user selects a range of pages that lies outside the ranges of pages displayed by the previewer (including selecting All), a message that those pages are not available is displayed and the user is returned to the dialog.
the user may select any subset of the original set of page ranges, including Current page. Any subsequent execution of the DWP_PRINT subfunction of %WPR_EXECUTE will honor that range.

If the application was not responsible for printing the selected pages, the user can select any range of pages (including All) and any subsequent DWP_PRINT operation will print those pages.

If the user selects a different printer in this dialog, that printer becomes the destination for any subsequent execution of the DWP_PRINT subfunction of %WPR_EXECUTE. (Note that this selection has no impact whatsoever on %SYNMSW_PRINTQUERY.) When this happens, the metafile may need to be regenerated. To avoid skewing the report, the metafile must also be regenerated when the page orientation or resolution is changed or when a different paper size is selected. In any of these cases, a value of DWP_PREVIEW_REGEN will be returned to tell the calling application to regenerate the metafile (which should be done prior to calling the DWP_PRINT subfunction of %WPR_EXECUTE). If the calling application does not regenerate the metafile before calling DWP_PRINT, the resulting output will probably differ from what the user expected.

Changes to copies, collation, or selection of Print to file will be applied when printing without requiring regeneration of the metafile. The Properties button in the dialog is disabled to prevent the user from changing the orientation or paper source for the report. If the user clicks the Print button in this dialog, the previewer will update the report settings with the information specified in the dialog. Then the previewer will exit and return DWP_PREVIEW_PRINT to the application.

If the user presses the Apply button on this dialog and then later presses Cancel, the settings are updated, but the previewer won’t exit. The return value when the previewer exits later will be determined by the method used to exit at that time.

Examples

The example below opens a preview window titled “Print Preview.” If the user chooses to print the file, the file is sent to the printer specified by the DWP_GETPRINTER subfunction of %WPR_INFO.

if (%wpr_execute(aPrinter, DWP_PREVIEW, file, "Print Preview", TRUE) .eq.
  & DWP_PREVIEW_PRINT)
  xcall wpr_execute(aPrinter, DWP_PRINT)

Also see Sample programs.