BANDINFO

short Escape(hdc, BANDINFO, sizeof(BANDINFOSTRUCT),lpInData,lpOutData)

The BANDINFO printer escape is maintained for backwards compatibility. Applications written for Windows 3.1 should send both text and graphics in every band.

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 to send output to the printer.

Banding is the 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 complete page.

The information copied to the structure pointed to by the lpOutData parameter 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 structure that contains a bounding rectangle for all graphics on the page.

If no data is returned, the lpOutData parameter is NULL.

The lpInData parameter specifies information sent by the application to the printer driver. This information is read by the driver only on the first call to the BANDINFO escape on a page.

Parameters

hdc

HDC Identifies the device context.

lpInData

BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT structure that contains information to be passed to the driver. For more information about this structure, see the following Comments section.

lpOutData

BANDINFOSTRUCT FAR * Points to a BANDINFOSTRUCT structure that contains information returned by the driver. For more information about this structure, see the following Comments section.

Return Value

The return value specifies the outcome of the escape. This value is 1 if the escape is successful. It is zero if the function fails or is not implemented by the driver.

Comments

The BANDINFOSTRUCT structure contains information about the contents of a page and supplies a bounding rectangle for graphics on the page. This structure has the following form:

typedef struct tagBANDINFOSTRUCT {
    BOOL    fGraphics;
    BOOL    fText;
    RECT    rcGraphics;
} BANDINFOSTRUCT;

Following are the members in the BANDINFOSTRUCT structure:

fGraphics

Specifies nonzero if graphics are or are expected to be on the page or in the band. Otherwise, it is zero.

fText

Specifies nonzero if text is or is expected to be on the page or in the band. Otherwise, it is zero.

rcGraphics

Contains a RECT structure that supplies a bounding region for all graphics on the page.

The meaning of these members depends on which parameter contains the structure, as follows.

Member When used in lpInData When used in lpOutData

fGraphics Nonzero if the application informs the driver that graphics are on the page Nonzero if the driver informs the application that it expects graphics in this band
fText Nonzero if the application informs the driver that text is on the page Nonzero if the driver informs the application that it expects text in this band
rcGraphics Bounding rectangle supplied for all graphics on the page No valid return data

An application should call this escape immediately after each call to the NEXTBAND escape. The BANDINFO escape is in reference to the band that the driver returned to the NEXTBAND 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 (the fGraphics member is set to zero and the fText member is set to nonzero). Then the application sends only text to the driver.

If in the first band the application indicates that it has graphics (the fGraphics member is set to nonzero) or the driver encounters vector fonts, the driver bands the rest of the page.

If there are no graphics or vector fonts, the next NEXTBAND escape returns 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 sets the fGraphics member to nonzero, but there are no graphics in the first full-page text band), the driver may optionally band only into the rectangle the application passes for subsequent bands. This rectangle bounds all graphics on the page.

If there are vector fonts, the driver bands the entire width and depth of the page with the fText member set to nonzero. It also sets the fGraphics flag to nonzero if the application has set it.

The driver assumes that an application using the BANDINFO escape only sends text in the first full-page text band because that is all the driver has 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 the fText member to nonzero for all subsequent graphics bands, so they can be output as graphics. If the application does not meet this expectation, the image still generates properly, but the driver spends time sending spurious text primitives to graphics bands.

Older drivers written before the BANDINFO escape was designed use full-page banding for text. If a particular driver does not support the BANDINFO escape but sets the RC_BANDING raster capability, the application can detect full-page banding for text by determining if the first band on the page covers the entire page.