ID Number: Q33252
2.03 2.10 3.00 3.10
WINDOWS
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)
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
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.
The driver assumes that an application using BANDINFO will send 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 reference words: 2.03 2.10 2.x 3.00 3.10 3.x