Q33252: INFO: Expanded BANDINFO Documentation
Article: Q33252
Product(s): Microsoft Windows Software Development Kit
Version(s): WINDOWS:3.1
Operating System(s):
Keyword(s): kb16bitonly kbOSWin310 _IK kbOSWin300 kbSDKWin16
Last Modified: 02-JUL-1999
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 1986-2002.