A value that indicates whether there are graphics in the next bandshort Escape(hDC, BANDINFO, sizeof(BANDINFOSTRUCT),lpInData,lpOutData)
This escape copies information about a device with banding capabilities to a structure pointed to by the lpOutData parameter. It is implemented only for devices that use banding.
Banding is a property of an output device that allows a page of output to be stored in a metafile and divided into bands, each of which is sent to the device to create a com-plete page.
The information copied to the structure pointed to by lpOutData includes:
A value that indicates whether there are graphics in the next band
A value that indicates whether there is text on the page
A RECT data structure that contains a bounding rectangle for all graphics on the page
The lpOutData parameter is NULL if no data are returned.
The lpInData parameter specifies information sent by the application to the device driver. This information is read by the device driver only on the first BANDINFO escape call on a page.
| Parameter | Type/Description |
| hDC | HDC Identifies the device context. |
| lpInData | BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT data structure that contains information to be passed to the driver. See the following “Comments” section for more information on the BANDINFOSTRUCT data structure. |
| lpOutData | BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT data structure that contains information returned by the driver. See the following “Comments” section for more information on the BANDINFOSTRUCT data structure. |
The return value specifies the outcome of the escape. It is 1 if the escape is successful. It is zero if the function fails or is not implemented by the driver.
The BANDINFOSTRUCT data structure contains information about the contents of a page and supplies a bounding rectangle for graphics on the page. The following shows the format of BANDINFOSTRUCT:
typedef struct {
BOOL fGraphicsFlag;
BOOL fTextFlag;
RECT GraphicsRect;
} BANDINFOSTRUCT;
The BANDINFOSTRUCT structure has the following fields:
| Field | Description |
| fGraphicsFlag | Is TRUE if graphics are or are expected to be on the page or in the band; otherwise, it is FALSE. | |
| fTextFlag | Is TRUE if text is or is expected to be on the page or in the band; otherwise, it is FALSE. | |
| GraphicsRect | Contains a RECT data structure that supplies a bounding region for all graphics on the page. |
Table R.1 shows the meaning of these fields, depending on which parameter contains the structure.
Table R.1 Meaning of BANDINFOSTRUCT Fields
| Field | When Used in lpInData | When Used in lpOutData |
| fGraphicsFlag | TRUE if the application is informing the driver that graphics are on the page. | TRUE if the driver is informing the application that it expects graphics in this band. |
| fTextFlag | TRUE if the application is informing the driver that text is on the page. | TRUE if the driver is informing the application that it expects text in this band. |
| GraphicsRect | Supplies the bounding rectangle for all graphics on the page. | No valid return data. |
An application should call this escape immediately after each call to the NEXTBAND escape. It is in reference to the band the driver returned to that escape.
An application should use this escape in the following manner:
On the first band, the driver may give the application a full-page band and ask for text only (fGraphicsFlag is set to FALSE and fTextFlag is set to TRUE). The application sends only text to the driver.
If in the first band the application indicated that it had graphics (fGraphicsFlag is set to TRUE), or that the driver encountered vector fonts, then the driver will band the rest of the page. If there are no graphics or vector fonts, then the next NEXTBAND will return an empty rectangle to indicate that the application should move on to the next page.
If there are graphics but no vector fonts (the application set fGraphicsFlag to TRUE, but there were no graphics in the first full-page text band), then for subsequent bands the driver may optionally band only into the rectangle the application passed. This rectangle bounds all graphics on the page. If there are vector fonts, then the driver will band the entire width and depth of the page with fTextFlag set to TRUE. It will also set fGraphicsFlag to true if the application set it.
The driver assumes that an application using BANDINFO will only send text in the first full-page text band since that is all the driver requested. Therefore, if the driver encounters a vector font or graphics in the band, it assumes they were generated by a text primitive and sets fTextFlag to TRUE for all subsequent graphics bands so they can be output as graphics. If the application does not satisfy this expectation, the image will still be generated properly, but the driver will spend time sending spurious text primitives to graphics bands.
Older drivers written before the BANDINFO escape was designed used full-page banding for text. If a particular driver does not support the BANDINFO escape but sets RC_BANDING, the application can detect full-page banding for text by determining if the first band on the page covers the entire page.