INFO: Expanded BANDINFO Documentation

ID: Q33252

3.00 3.10 WINDOWS kbprg

The information in this article applies to:

Microsoft Windows Software Development Kit (SDK) 3.1

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

This escape is always executed immediately after a NEXTBAND escape and is in reference to the band the driver returned to that escape. Listed below are examples of how the BANDINFO escape can be used to communicate between driver and application.

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.

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 returns an empty rectangle, indicating that the application should move on to the next page.

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 bands the entire width and depth of the page with the TextFlag == TRUE.

The driver assumes that an application using BANDINFO sends only text in the first full-page text band because that is all the driver asked for. Therefore, if the driver sees a vector font or any graphics in the band, it assumes they were generated by a text primitive and sets the TextFlag == TRUE for all of the subsequent graphics bands to ensure that they can be output as graphics. If the application does not meet this assumption, the image will still be generated properly; however, some time will be wasted by sending spurious text primitives to graphics bands.

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;
       }
   }

For more information on full-page banding for text, query on the following words:

prod(winsdk) and four and banding and nonraster

For more information on BANDINFO, query on the following words:

NEXTBAND and NEWFRAME and BANDINFO and banding and printing

Additional query words: 3.00 3.10

Keywords : kb16bitonly kbWinOS310 kbDSupport kbWinOS300 kbSDKWin16
Version : WINDOWS:3.1
Platform : WINDOWS
Issue type : kbinfo