GUI ScreenIO for
Windows|
GUI ScreenIO for
Windows |
This API invokes the standard Windows Printer Dialog, which allows users to choose the printer.
Note: Actual Dialog varies depending on Windows Version
It returns the name of the printer, as well as the port name. The printer name can be used for other Windows Print APIs and the Port name can be used for CopyFile API or direct transmission to a printer port. Optionally, you can request that additional Windows Data areas are made available (via handles) for advanced printing APIs (not yet available) or for interfacing with other printing software.
You can set several options which tailor the appearance of the printer dialog box.
This API runs in Client Server mode ONLY at the Client. It would be inappropriate to allow the remote users to pop up this dialog box on the server, so it always runs on the client, showing only printers available directly from the Client's computer. If you need to present a list of printers on Server to remote clients, see our GetPrinters API.
Many compilers have a facility to invoke the Standard Windows Printer Dialog. However these will not work with the Client Server, as the window opens on the machine running the program (the Server) which may be several hundred miles from the Client. By using this API to fetch the user's printer selection, you can assure that your application will run in client server deployments as well as stand alone situations.
Files available to copy to your system:
|
COPY WIN32API.
COPY GSPRTDEF.
* ------------------------:
Load the window handle of the window |
See the copybook for the fields documented below.
The first field in the copybook is a choice option for how you want data returned.
Normally we would recommend you take the default (Auto-Cleanup). If you have need of the areas that the Print Dialog is capable of returning, you can take the second option, Retain Handles, which would cause the PRTDLG-HANDLES area to be filled in (see below) upon return. If you choose this option, you are responsible for making a subsequent call at some later point to release these data area. You would call this same API with PRTDLG-RELEASE-HANDLES set to true. Failure to do so would cause your application to "leak memory".
For most operations you only need the Printer Name or Port, so the Auto Cleanup option is the default.
This field must be filled in with the panel-HWND (its in every panel copybook) of the panel that "owns" the Printer Dialog box. Essentially you should move the panel-HWND from the most recently displayed panel into this field.
This area contains two fields, PRTDLG-MIN-PAGE and PRTDLG-MAX-PAGE, which are page numbers in your impending print job. Usually Min is set to page 1, and Max is set to the highest number of pages in your job.
If you don't know, OR you are not prepared to honor requests to print other than the TOTAL report, SET the supplied 88 PRTDLG-PAGES-UNKNOWN to true and the printer dialog will gray out these fields.
The flags field is an additive field used to control the behavior and contents of the Print Dialog box. You ADD the options you want, GIVING this field. The options we support are included at the bottom of this copybook for your convenience.
It is possible to add mutually exclusive and totally silly combinations of these values into these fields. Of course, if you do, we will all get a big laugh at your expense when you call for tech support.
If you make NO settings, (MOVE LOW-VALUES TO PRINTDIALOG-PARMS it will work just fine, and give you a default of All pages.
These options are described in the following table:
| PRINTER-ATTRIBUTES | Meaning |
|---|---|
| PRTF-ALLPAGES | Requests that the ALL pages radio button be selected. This is the default |
| PRTF-SELECTION | The Selection Radio Box is shown in the selected state. |
| PRTF-PAGENUMS | The Page Numbers (range selection) radio button is shown in the selected state. |
| PRTF-NOSELECTION | Disables the Selection Radio button |
| PRTF-COLLATE | Shows the Collate Check box as Checked |
| PRTF-PRINTTOFILE | Sets the Print to file Checkbox as checked |
| PRTF-PRINTSETUP | Shows the Print Setup screen instead of the Printer Selection Screen. Varies by Windows version. |
| PRTF-NOWARNING | Prevents windows from issuing a warning when there is no default printer. |
| PRTF-RETURNDEFAULT | Suppresses the dialog box entirely and simply returns information about the Default printer. |
| PRTF-USEDEVMODECOPIES | If your application is not prepared to print copies or collate add this value. It will suppress the copies and collate options unless the printer driver can handle these functions by itself. (Recommended). |
| PRTF-HIDEPRINTTOFILE | Hide the Print to file option. |
This group level item is where the selected printer information will be returned. But you can also preload this area with data from a previous call to "Suggest" a specific printer while still allowing the user to over ride your suggestion.
This section leads off with an 88 which you should set if you do not want to suggest a printer. Its effect is to clear these fields: SET PRTDLG-NO-PRINTER-PRESELECTION TO TRUE.
This is the name by which windows knows this printer, and by which it is listed in the Printers control panel applet. THIS IS THE NAME THAT YOU WANT if you will be printing via our Print APIs.
This is the name of the device driver used by this printer. We supply it mostly because if you want to pre-select a printer (suggest a printer) you need to feed this field back into this API on subsequent calls.
This is the port to which this printer is connected. May be a share name rather than a port. If the user has selected print to file, it will contain FILE:.
Use this port name if you are going to use our CopyFile API to send print to this printer.
The user selected collation, but the print driver can not do this, and therefore your program should generate multiple sets in page number order, rather than n sets of page 1 followed by n sets of page 2, etc.
The user requested N copies, but the print driver can not do this. You should print N sets of page 1 followed by N sets of page 2, etc. Except when Simulate Collation is also set, in which case see above.
The user requested you print selected pages beginning with this page number.
The user requested you print selected pages ending with this page number.
Three handles are returned, but only if you specifically ask for them. These handles allow you to access memory areas allocated by windows as a result of your invocation of this API. Normally these area are freed up by GUI ScreenIO immediately. If you have reason to use these areas you can select PRTDLG-RETAIN-HANDLES (above) on your initial call and these areas will be retained and their handles passed back to you.
We do not document these areas here, as they are not normally used, but may be needed with some third party printing packages. Their structure varies with the capabilities of the printer.
DO NOT frivolously request these handles (and their associated memory) to be retained. And if you do request them ALWAYS make a subsequent call to this API to release these handles. Failure to do so may cause your application to use large chunks of memory which it may never free up.
The Handles are:
Found in the GSPRTDEF.COB copybook, this data area contains the setup defaults (or the selections made by the user) for the selected printer. This data needs to be passed intact to the OpenPrinter or PrintFile API when you want to print. This data area is described on this page.
This argument is standard for all CALLs to GSWINAPI. It is used to select the desired API or function, and to return the status of the operation.
Used to return the status of a call to GSWINAPI. A value of zero is a failure, any other value indicates success.
Recommended usage is to test the 88-level value WIN32API to see if it worked, then to use the text error message to see why it failed.
|
* ------------------------: If function failed,
|
Error code that was returned by Windows. This is not generally useful unless you have the Windows Platform SDK documentation available to you.
Plain-text error message that describes why the operation failed.
The number of these present varies depending on how many arguments are used by the desired function. These are not used, but must be present because this CALL requires seven arguments.
| © 2000-2019 Norcom, all rights reserved |