Expanded BANDINFO Documentation

The information in this article applies to:

• Microsoft Windows Software Development Kit (SDK) for Windows versions 3.1 and 3.0

SUMMARY

The following is an expanded version of the documentation of the BANDINFO escape in earlier manuals. Refer to the index or table of contents section to determine where the BANDINFO information is located in the current versions of the documentation.

   short Escape(hDC, BANDINFO, nCount, lpInData, lpOutData)

MORE INFORMATION

Purpose

Provides better communication between a banding driver and the application.

Parameters

   Parameter     Definition
   ---------     ----------

   hDC           A handle to the printer display context

   nCount        Not used and can be set to NULL

   lpInData      A long pointer to a data structure that has the
                 following structure:

                    typedef struct {
                        BOOL    GraphicsFlag;
                        BOOL    TextFlag;
                        RECT    GraphicsRect;
                        } BANDINFOSTRUCT;

                 This data structure provides the primary
                 communication between the driver and the
                 application as to what (graphics and/or text)
                 is actually on the page. The notes below
                 describe its use.

   lpOutData     A long pointer to a data structure having the same
                 items as lpInData, a BANDINFOSTRUCT

Return Value

   Return Value  Result
   ------------  ------

   nResult       1 if the function is successful
                 0 if the function is not successful or if the escape
                 is not implemented

Notes

This escape is only implemented for devices that use banding to output to the printer. The escape is called immediately after the NEXTBAND escape, every time the NEXTBAND escape is called.

The BANDINFO data structure is used to communicate between the driver and the application as follows:

   Data structure  Used as lpInData            Used as lpOutData
   field           (application communicates   (driver communicates
                   to the driver)              back to the application)

   GraphicsFlag    TRUE if there are graphics  TRUE if the driver is
                   on the page                 expecting graphics in
                                               this band

   TextFlag        TRUE if there is text on    TRUE if the driver is
                   the page                    expecting text in this
                                               band

   GraphicsRect    The bounding rectangle for  No valid return data
                   all graphics on the page

1. On the first band, the driver gives the application a full-page band and asks for text only (GraphicsFlag == FALSE, TextFlag == TRUE). The application sends only text to the driver.

2. If in the first band the application said it had graphics (GraphicsFlag == TRUE), or if the driver encountered any vector fonts, the driver will have to band the rest of the page. If there are no graphics or vector fonts, the next NEXTBAND escape will return an empty rectangle, indicating that the application should move on to the next page.

3. If there are graphics and no vector fonts, (that is, the application set GraphicsFlag == TRUE), the driver only has to band into the rectangle the application passed via NEXTBAND, which bounds all graphics on the page. If there are vector fonts, the driver will band the entire width and depth of the page with the TextFlag == TRUE.

Code Outline

The general outline of a routine using BANDINFO to output a page should be as follows:

   do {
       if (BandingDevice) {
           NEXTBAND
           BANDINFO
           }
       else {

           /* It is not a banding device. */

           /* Set the band to the entire page. */
           BandRect.left   = 0;
           BandRect.top    = 0;
           BandRect.right  = dxPrinter;
           BandRect.bottom = dyPrinter;

           /* Output everything. */
           BandInfoOut.GraphicsFlag = TRUE;
           BandInfoOut.TextFlag     = TRUE;
           }

       if (TextFlag) {
           Do any text.
           }
       if (GraphicsFlag) {
           Do any graphics.
           }

       } while (BandingDevice &&
                more bands to do);

   /* NEWFRAME and NEXTBAND are exclusive; however, at least one must
      be used. Hence we need to do a NEWFRAME if we are not banding. */
   if (!BandingDevice) {

       /* Put out the page. */
       if ((SpoolerError = Escape(hDC, NEWFRAME, 0, 0L, 0L)) <= 0) {
           Result = ConvertSpoolerError(SpoolerError);
           Escape(hDC, ABORTDOC, 0, 0L, 0L);
           goto ErrorExit3;
           }
       }

   prod(winsdk) and four and banding and nonraster

   NEXTBAND and NEWFRAME and BANDINFO and banding and printing