GUI ScreenIO for Windows

 ScreenIO.com


PrinterDLG

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.   

Client/Server issues

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.

Why Use This:

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

Files available to copy to your system:

Usage

     COPY WIN32API.
     COPY PRINTDLG.

     COPY GSPRTDEF.

      * ------------------------: Load the window handle of the window
      *                         : that will own this dialog; (it's
      *                         : passed back by GUI ScreenIO when you
      *                         : display a panel).  Zero is OK.
           MOVE LOW-VALUES TO PRINTDIALOG-PARAMETER-AREA.
           MOVE mypanel-HWND TO PRTDLG-HWNDOWNER.
           SET PRTDLG-PAGES-UNKNOWN TO TRUE
           SET PRTDLG-NO-PRINTER-PRESELECTION TO TRUE
      * ------------------------: Set the options you want
      *
           ADD
               PRTF-ALLPAGES
               PRTF-USEDEVMODECOPIES
               GIVING PRTDLG-FLAGS
      *
           SET API-PRINTDIALOG TO TRUE
      *
      * ------------------------: Call the GUI ScreenIO API routine:
      *
           CALL 'GSWINAPI' USING WIN32API-PARMS
                                 PRINTDIALOG-PARMS
                                 GS-DEVMODE-DATA
                                 WIN32API-C
                                 WIN32API-D
                                 WIN32API-E
                                 WIN32API-F.
       
           IF WIN32API-FAILED
             do print-not-possible-or-canceled
           ELSE
             print-the-report
      *

Parameters specific to this function (In prtdlg.cob)

See the copybook for the fields documented below.

Request Type (filler item with 88s)

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.

PRTDLG-HWNDOWNER

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.

PRTDLD-PAGES-IN-JOB

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.

PRTDLG-FLAGS

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. 

 

PRTDLG-PRINTER-INFORMATION

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.

PRTDLG-PRINTER-NAME

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.

PRTDLG-PRINTER-DEVICE-DRIVER

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.

PRTDLG-PRINTER-PORT-NAME

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.

PRTDLG-SIMULATE-COLLATION

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.

PRTDLG-NUM-COPIES

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.

PRTDLG-FROM-PAGE

The user requested you print selected pages beginning with this page number.

PRTDLG-TO-PAGE

The user requested you print selected pages ending with this page number.

PRTDLG-HANDLES

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:

GS-DEVMODE-DATA 

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.

WIN32API-PARMS - Used in all GSWINAPI calls

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.

WIN32API-RC

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,
*                         :   display the error in a message box.
*
     IF WIN32API-FAILED
       MOVE WIN32API-ERROR-TEXT TO panel-MESSAGE-TEXT
       SET panel-MESSAGE-IN-MESSAGEBOX TO TRUE.

WIN32API-ERROR-CODE

Error code that was returned by Windows.  This is not generally useful unless you have the Windows Platform SDK documentation available to you.

WIN32API-ERROR-TEXT

Plain-text error message that describes why the operation failed.

WIN32API-A through WIN32API-F

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-2006 Norcom, all rights reserved 

TOC

Send feedback to Norcom