DOCUMENT:Q33252 02-JUL-1999 [win16sdk] TITLE :INFO: Expanded BANDINFO Documentation PRODUCT :Microsoft Windows Software Development Kit PROD/VER:WINDOWS:3.1 OPER/SYS: KEYWORDS:kb16bitonly kbOSWin310 _IK kbOSWin300 kbSDKWin16 ====================================================================== 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. 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 returns 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 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 kbOSWin310 _IK kbOSWin300 kbSDKWin16 Technology : kbAudDeveloper kbWin3xSearch kbSDKSearch kbWinSDKSearch kbWinSDK310 Version : WINDOWS:3.1 Issue type : kbinfo ============================================================================= THE INFORMATION PROVIDED IN THE MICROSOFT KNOWLEDGE BASE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND. MICROSOFT DISCLAIMS ALL WARRANTIES, EITHER EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. IN NO EVENT SHALL MICROSOFT CORPORATION OR ITS SUPPLIERS BE LIABLE FOR ANY DAMAGES WHATSOEVER INCLUDING DIRECT, INDIRECT, INCIDENTAL, CONSEQUENTIAL, LOSS OF BUSINESS PROFITS OR SPECIAL DAMAGES, EVEN IF MICROSOFT CORPORATION OR ITS SUPPLIERS HAVE BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. SOME STATES DO NOT ALLOW THE EXCLUSION OR LIMITATION OF LIABILITY FOR CONSEQUENTIAL OR INCIDENTAL DAMAGES SO THE FOREGOING LIMITATION MAY NOT APPLY. Copyright Microsoft Corporation 1999.