# CPrint Class

Allows to attach/choose a printer and get/set its setting values.

Include file: AfxNova/CPrint.inc

### Methods

Name | Description
--- | ---
AttachPrinter | Attaches the specified printer to the class.
ChoosePrinter | Displays the printer dialog to select a printer.
PageSetup | Displays a Page Setup dialog box that enables the user to specify the attributes of a printed page.
GetPrinterName | Returns the name of the attached printer.
SetDefaultPrinter | Sets the default printer.
GetDefaultPrinter | Returns the name of the default printer.
GetDefaultPrinterDriver | Returns the name of the default printer driver.
GetDefaultPrinterPort | Returns the name of the default printer port.
EnumPrinterNames | Returns a list with the available printers, print servers, domains, or print providers.
GetDC | Returns the handle of the device context of the attached printer.
GetPPIX | Returns the number of pixels per inch of the page (horizontal resolution).
GetPPIY | Returns the number of pixels per inch of the page (vertical resolution).
GetHorizontalUnits | Returns the width, in world units, of the printable area of the page.
GetVerticalUnits | Returns the height, in world units, of the printable area of the page.
GetHorizontalResolution | Returns the width, in pixels, of the printable area of the page.
GetVerticalResolution | Returns the height, in pixels, of the printable area of the page.
GetMarginsPixels | Retrieves the margins (the non-printable area) of the printer page, in pixels.
GetMarginsUnits | Retrieves the margins (the non-printable area) of the printer page, in world units.
PixelsToUnitsX | Converts pixels to world units. (horizontal resolution).
PixelsToUnitsY | Converts pixels to world units. (vertical resolution).
UnitsToPixelsX | Converts world units to pixels (horizontal resolution).
UnitsToPixelsY | Converts world units to pixels (vertical resolution).
PixelsToPointsX | Converts pixels to point size (1/72 of an inch) (horizontal resolution).
PixelsToPointsY | Converts pixels to point size (1/72 of an inch) (vertical resolution).
PointsToPixelsX | Converts a point size (1/72 of an inch) to pixels (horizontal resolution).
PointsToPixelsY | Converts a point size (1/72 of an inch) to pixels (vertical resolution).
GetPaperNames | Returns a list of supported paper names.
PrintBitmap | Prints a Windows bitmap in the attached printer.
PrintBitmapToFile | Prints a Windows bitmap in the specified file.

### Properties

Name | Description
--- | ---
Collate | Returns true if the printer supports collating mode; False, otherwise.
CollateMode | Gets/sets the collate setting value.
Color | Returns true if the printer supports color mode; False, otherwise.
ColorMode | Switches between color and monochrome on color printers.
Copies | Gets/sets the number of copies to print if the device supports multiple-page copies.
Duplex | Checks if the printer supports duplex printing.
DuplexMode | Gets/sets the current duplex mode.
Orientation | Gets/sets the printer orientation.
PaperLength | Gets/sets the paper length in units of 1/10 of a millimeter.
PaperSize | Gets/sets the printer paper size.
PaperWidth | Gets/sets the paper width in units of 1/10 of a millimeter.
Quality | Gets/sets the printer print quality mode.
Scale | Gets/sets the factor by which the printed output is to be scaled.
SetPaperSize | Sets the paper length and width in units of 1/10 of a millimeter.
Tray | Specifies the paper source.

## AttachPrinter

Creates a device context (DC) for the specified printer and attaches it to the class.

    FUNCTION AttachPrinter (BYREF wszPrinterName AS WSTRING) AS BOOLEAN

Parameter | Description
--- | ---
wszPrinterName | The name of the printer to attach (as shown in the Devices and Printers applet of the Control Panel).

#### Return value

BOOLEAN. True or false.

#### Example

The following console example creates an instance of the `CPrint` class to attach the “Microsoft Print to PDF” driver, retrieves a handle to its device context and uses the WinFBX GDI+ classes to draw the contents of the page.

    '#CONSOLE ON
    #define UNICODE
    #INCLUDE ONCE "AfxNova/CPrint.inc"
    #INCLUDE ONCE "AfxNova/CGdiplus.inc"
    USING AfxNova

    DIM pPrint AS CPrint
    pPrint.AttachPrinter("Microsoft Print to PDF")
    DIM hdcPrint AS HDC = pPrint.GetDC
    DIM docInfo AS DOCINFOW
    docInfo.cbSize = SIZEOF(DOCINFOW)
    DIM wszDocName AS WSTRING * 260 = "GdiplusPrint"
    docInfo.lpszDocName = VARPTR(wszDocName)
    StartDocW(hdcPrint, @docInfo)
    StartPage(hdcPrint)
    SCOPE
       DIM graphics AS CGpGraphics = hdcPrint
       DIM pen AS CGpPen = GDIP_ARGB(255, 0, 0, 0)
       graphics.DrawLine(@pen, 50, 50, 350, 550)
       graphics.DrawRectangle(@pen, 50, 50, 300, 500)
       graphics.DrawEllipse(@pen, 50, 50, 300, 500)
    END SCOPE
    EndPage(hdcPrint)
    EndDoc(hdcPrint)

    PRINT "Press any key to end..."
    SLEEP

## ChoosePrinter

Displays a Print Dialog Box to select a printer.

    FUNCTION ChoosePrinter (BYVAL hwndOwner AS HWND = NULL) AS BOOLEAN

Parameter | Description
--- | ---
hwndOwner | Optional. A handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

#### Return value

BOOLEAN. If the user clicks the OK button, the return value is true. If the user canceled or closed the Print dialog box or an error occurred, the return value is false.

#### Example

    DIM pPrint AS CPrint
    pPrint.ChoosePrinter

## PageSetup

Displays a Page Setup dialog box that enables the user to specify the attributes of a printed page. These attributes include the paper size and source, the page orientation (portrait or landscape), and the width of the page margins.

    FUNCTION PageSetup (BYVAL hwndOwner AS HWND = NULL) AS BOOLEAN

Parameter | Description
--- | ---
hwndOwner | Optional. A handle to the window that owns the dialog box. This member can be any valid window handle, or it can be NULL if the dialog box has no owner.

#### Return value

BOOLEAN. If the user clicks the OK button, the return value is true. If the user canceled or closed the Page Setup dialog box or an error occurred, the return value is false.

#### Example

    DIM pPrint AS CPrint
    pPrint.PageSetup

## GetPrinterName

Returns the name of the attached printer.

    FUNCTION GetPrinterName () AS DWSTRING

#### Return value

DWSTRING. The name of the attached printer. If there is not a printer attached, it returns an empty string.

## SetDefaultPrinter

Sets the printer name of the default printer for the current user on the local computer.

    FUNCTION SetDefaultPrinter (BYREF wszPrinterName AS WSTRING) AS BOOLEAN

Parameter | Description
--- | ---
wszPrinterName | A pointer to a null-terminated string containing the default printer name. For a remote printer connection, the name format is **\server\printername. For a local printer, the name format is printername. If this parameter is NULL or an empty string, that is, ““, SetDefaultPrinter will select a default printer from one of the installed printers. If a default printer already exists, calling SetDefaultPrinter with a NULL** or an empty string in this parameter might change the default printer.

#### Return value

BOOLEAN. True or false.

#### Remarks

When using this method, you must specify a valid printer, driver, and port. If they are invalid, the APIs do not fail but the result is not defined. This could cause other programs to set the printer back to the previous valid printer. You can use EnumPrinters to retrieve the printer name, driver name, and port name of all available printers.

#### Note

This is a blocking or synchronous function and might not return immediately. How quickly this function returns depends on run-time factors such as network status, print server configuration, and printer driver implementation factors that are difficult to predict when writing an application. Calling this function from a thread that manages interaction with the user interface could make the application appear to be unresponsive.

## GetDefaultPrinter

Returns the name of the default printer.

    FUNCTION GetDefaultPrinter () AS DWSTRING

## GetDefaultPrinterDriver

Returns the name of the default printer driver.

    FUNCTION GetDefaultPrinterDriver () AS DWSTRING

## GetDefaultPrinterPort

Returns the name of the default printer port.

    FUNCTION GetDefaultPrinterPort () AS DWSTRING

## EnumPrinterNames

Returns a list with the available printers, print servers, domains, or print providers. Names are separated with a carriage return and a line feed characters.

    FUNCTION EnumPrinterNames () AS DWSTRING

## GetDC

Returns the handle of the attached printer.

    FUNCTION GetDC () AS HDC

#### Return value

HDC. The handle of the device context of the attached printer. If there is not a printer attached, it returns NULL.

## GetPPIX

Returns the number of pixels per inch of the specified host printer page (horizontal resolution).

    FUNCTION GetPPIX () AS LONG

#### Return value

LONG. The number of pixels per inch of the specified host printer page. If there is not a printer attached, it returns 0.

## GetPPIY

Returns the number of pixels per inch of the specified host printer page (vertical resolution).

    FUNCTION GetPPIY () AS LONG

#### Return value

LONG. The number of pixels per inch of the specified host printer page. If there is not a printer attached, it returns 0.

## GetHorizontalUnits

Returns the width, in world units, of the printable area of the page.

    FUNCTION GetHorizontalUnits () AS LONG

#### Return value

LONG. The width, in world units, of the printable area of the page. If there is not a printer attached, it returns 0.

## GetVerticalUnits

Returns the height, in world units, of the printable area of the page.

    FUNCTION GetVerticalUnits () AS LONG

#### Return value

LONG. The height, in world units, of the printable area of the page. If there is not a printer attached, it returns 0.

## GetHorizontalResolution

Returns the width, in pixels, of the printable area of the page.

    FUNCTION GetHorizontalResolution () AS LONG

## GetVerticalResolution

Returns the height, in pixels, of the printable area of the page.

    FUNCTION GetVerticalResolution () AS LONG

## GetMarginsPixels

Retrieves the margins (the non-printable area) of the printer page, in pixels.

    SUB GetMarginsPixels (BYREF nLeft AS LONG, BYREF nTop AS LONG, BYREF nRight AS LONG, BYREF nBottom AS LONG)
    FUNCTION GetMarginsPixels () AS RECT

Parameter | Description
--- | ---
nLeft | Left margin.
nTop | Top margin.
nRight | Right margin.
nBottom | Bottom margin.

The overloaded function returns a RECT structure.

#### Return value

LONG. The height, in pixels, of the printable area of the page. If there is not a printer attached, it returns 0.

## GetMarginsUnits

Retrieves the margins (the non-printable area) of the printer page, in world units.

    SUB GetMarginsUnits (BYREF nLeft AS LONG, BYREF nTop AS LONG, BYREF nRight AS LONG, BYREF nBottom AS LONG)
    FUNCTION GetMarginsUnits () AS RECT

Parameter | Description
--- | ---
nLeft | Left margin.
nTop | Top margin.
nRight | Right margin.
nBottom | Bottom margin.

The overloaded function returns a RECT structure.

## PixelsToUnitsX

Converts pixels to world units (horizontal resolution).

    FUNCTION PixelsToUnitsX (BYVAL pix AS LONG) AS LONG

Parameter | Description
--- | ---
pix | The number of pixels to convert.

## PixelsToUnitsY

Converts pixels to world units (vertical resolution).

    FUNCTION PixelsToUnitsY (BYVAL pix AS LONG) AS LONG

Parameter | Description
--- | ---
pix | The number of pixels to convert.

## UnitsToPixelsX

Converts world units to pixels (horizontal resolution).

    FUNCTION UnitsToPixelsX (BYVAL units AS LONG) AS LONG

Parameter | Description
--- | ---
units | The number of world units to convert.

## UnitsToPixelsY

Converts world units to pixels (vertical resolution).

    FUNCTION UnitsToPixelsY (BYVAL units AS LONG) AS LONG

Parameter | Description
--- | ---
units | The number of world units to convert.

## PixelsToPointsX

Converts pixels to point size (1/72 of an inch) according to the PPI of the printer (horizontal resolution).

    FUNCTION PixelsToPointsX (BYVAL pix AS LONG) AS LONG

Parameter | Description
--- | ---
pix | The number of pixels to convert.

#### Return value

LONG. The number of points. If there is not a printer attached, it returns 0.

## PixelsToPointsY

Converts pixels to point size (1/72 of an inch) according to the PPI of the printer (vertical resolution).

    FUNCTION PixelsToPointsY (BYVAL pix AS LONG) AS LONG

Parameter | Description
--- | ---
pix | The number of pixels to convert.

#### Return value

LONG. The number of points. If there is not a printer attached, it returns 0.

## PointsToPixelsX

Converts a point size (1/72 of an inch) to pixels according to the PPI of the printer (horizontal resolution).

    FUNCTION PointsToPixelsX (BYVAL pts AS LONG) AS LONG

Parameter | Description
--- | ---
pts | The number of points to convert.

#### Return value

LONG. The number of pixels. If there is not a printer attached, it returns 0.

## PointsToPixelsY

Converts a point size (1/72 of an inch) to pixels according to the PPI of the printer (vertical resolution).

    FUNCTION PointsToPixelsY (BYVAL pts AS LONG) AS LONG

Parameter | Description
--- | ---
pts | The number of points to convert.

#### Return value

LONG. The number of pixels. If there is not a printer attached, it returns 0.

## GetPaperNames

Returns a list of supported paper names (for example, Letter or Legal).

    FUNCTION GetPaperNames () AS DWSTRING

#### Return value

DWSTRING. A list of supported paper names on success, or an empty string on failure. The names are separated by a carriage return and a line feed characters.

## PrintBitmap

Prints a Windows bitmap to the attached printer.

    FUNCTION PrintBitmap ( _
       BYREF wszDocName AS WSTRING, _
       BYVAL hbmp AS HBITMAP, _
       BYVAL bStretch AS BOOLEAN = FALSE, _
       BYVAL nStretchMode AS LONG = InterpolationModeHighQualityBicubic _
    ) AS BOOLEAN

Parameter | Description
--- | ---
wszDocName | WSTRING. The document name.
hbmp | HBITMAP. Handle to the bitmap.
bStretch | BOOLEAN. Optional. True to strech the image or false. Defaults to False.
nStretchMode | LONG. Optional. Stretching mode. Defaults to InterpolationModeHighQualityBicubic. Predefined constants: InterpolationModeLowQuality = Specifies a low-quality mode. InterpolationModeHighQuality = Specifies a high-quality mode. InterpolationModeBilinear = Specifies bilinear interpolation. No prefiltering is done. This mode is not suitable for shrinking an image below 50 percent of its original size. InterpolationModeBicubic = Specifies bicubic interpolation. No prefiltering is done. This mode is not suitable for shrinking an image below 25 percent of its original size. InterpolationModeNearestNeighbor = Specifies nearest-neighbor interpolation. InterpolationModeHighQualityBilinear = Specifies high-quality, bilinear interpolation. Prefiltering is performed to ensure high-quality shrinking. InterpolationModeHighQualityBicubic = Specifies high-quality, bicubic interpolation. Prefiltering is performed to ensure high-quality shrinking. This mode produces the highest quality transformed images.

#### Return value

BOOLEAN. Returns TRUE if the bitmap has been printed successfully, or FALSE otherwise.

## PrintBitmapToFile

Prints a Windows bitmap to the specified output file.

    FUNCTION PrintBitmapToFile ( _
       BYREF wszDocName AS WSTRING, _
       BYREF wszOutputFileName AS WSTRING, _
       BYVAL hbmp AS HBITMAP, _
       BYVAL bStretch AS BOOLEAN = FALSE, _
       BYVAL nStretchMode AS LONG = InterpolationModeHighQualityBicubic _
    ) AS BOOLEAN

Parameter | Description
--- | ---
wszDocName | WSTRING. The document name.
wszOutputFileName | WSTRING. The output file name.
hbmp | HBITMAP. Handle to the bitmap.
bStretch | BOOLEAN. Optional. True to strech the image or false. Defaults to False.
nStretchMode | LONG. Optional. Stretching mode. Defaults to InterpolationModeHighQualityBicubic. Predefined constants: InterpolationModeLowQuality = Specifies a low-quality mode. InterpolationModeHighQuality = Specifies a high-quality mode. InterpolationModeBilinear = Specifies bilinear interpolation. No prefiltering is done. This mode is not suitable for shrinking an image below 50 percent of its original size. InterpolationModeBicubic = Specifies bicubic interpolation. No prefiltering is done. This mode is not suitable for shrinking an image below 25 percent of its original size. InterpolationModeNearestNeighbor = Specifies nearest-neighbor interpolation. InterpolationModeHighQualityBilinear = Specifies high-quality, bilinear interpolation. Prefiltering is performed to ensure high-quality shrinking. InterpolationModeHighQualityBicubic = Specifies high-quality, bicubic interpolation. Prefiltering is performed to ensure high-quality shrinking. This mode produces the highest quality transformed images.

#### Return value

BOOLEAN. Returns TRUE if the bitmap has been printed successfully, or FALSE otherwise.

## Collate

If the printer supports collating, the return value is TRUE; otherwise, the return value is FALSE.

    PROPERTY Collate () AS BOOLEAN

## CollateMode

Gets/sets the printer collating mode.

    PROPERTY CollateMode () AS LONG
    PROPERTY CollateMode (BYVAL nMode AS LONG)

Parameter | Description
--- | ---
nMode | LONG. The collating mode. Possible values: DMCOLLATE_TRUE, DMCOLLATE_FALSE.

#### Return value

BOOLEAN. If the printer supports collating, the return value is TRUE; otherwise, the return value is FALSE. If TRUE, the pages that are printed should be collated. To collate is to print out the entire document before printing the next copy, as opposed to printing out each page of the document the required number of times.

## Color

If the printer supports color mode, the return value is TRUE; otherwise, the return value is FALSE.

    PROPERTY Color () AS BOOLEAN

## ColorMode

Switches between color and monochrome on color printers. Some color printers have the capability to print using true black instead of a combination of cyan, magenta, and yellow (CMY). This usually creates darker and sharper text for documents. This option is only useful for color printers that support true black printing.

    PROPERTY ColorMode () AS LONG
    PROPERTY ColorMode (BYVAL nMode AS LONG)

Parameter | Description
--- | ---
nMode | LONG. The color mode. Possible values: DMCOLOR_MONOCHROME, DMCOLOR_COLOR.

#### Return value

LONG. Returns the printer color mode: DMCOLOR_MONOCHROME or DMCOLOR_COLOR.

# Copies

Gets/sets the number of copies to print if the device supports multiple-page copies.

    PROPERTY Copies () AS BOOLEAN
    PROPERTY Copies (BYVAL nCopies AS LONG)

Parameter | Description
--- | ---
nCopies | LONG. The number of copies to print if the device supports multiple-page copies.

#### Return value

LONG. The number of copies.

## Duplex

Checks if the printer supports duplex printing.

    PROPERTY Duplex () AS BOOLEAN

#### Return value

BOOLEAN. If the printer supports duplex printing, the return value is TRUE; otherwise, the return value is FALSE.

## DuplexMode

Gets/sets the current duplex mode.

    PROPERTY DuplexMode () AS LONG
    PROPERTY DuplexMode (BYVAL nMode AS LONG)

Parameter | Description
--- | ---
nMode | LONG. The duplex mode. DMDUP_SIMPLEX = Single sided printing. DMDUP_VERTICAL = Page flipped on the vertical edge. DMDUP_HORIZONTAL = Page flipped on the horizontal edge.

#### Return value

LONG. If the printer supports duplex printing, returns the current duplex mode

## Orientation

Gets/sets the printer orientation.

    PROPERTY Orientation () AS LONG
    PROPERTY Orientation (BYVAL nOrientation AS LONG)

Parameter | Description
--- | ---
nOrientation | LONG. The printer orientation. DMORIENT_PORTRAIT = Portrait. DMORIENT_LANDSCAPE = Landscape.

#### Return value

LONG. The printer orientation.

## PaperLength

Gets/sets the printer paper length in units of 1/10 of a millimeter. This value overrides the length of the paper specified by the PaperSize property, and is used if the paper is of a custom size, or if the device is a dot matrix printer, which can print a page of arbitrary length. If you use this property, you must also use the PaperWidth property to set the print paper width. Alternatively, you can use the SetPageSize function to set both the length and width with only one call.

    PROPERTY PaperLength () AS LONG
    PROPERTY PaperLength (BYVAL nLength AS LONG)

Parameter | Description
--- | ---
nLength | LONG. The printer paper length.

#### Return value

LONG. The printer paper length.

## PaperSize

Gets/sets the printer paper size.

    PROPERTY PaperSize () AS LONG
    PROPERTY PaperSize (BYVAL nSize AS LONG)

Parameter | Description
--- | ---
nSize | LONG. Specifies the printer paper size, with DMPAPER_LETTER, DMPAPER_LEGAL, DMPAPER_A3, and DMPAPER_A4 being the most typical. Note that the paper size types cannot be combined with one another. For a list of paper sizes see Paper Sizes.

#### Return value

LONG. The printer paper size.

## SetPaperSize

Sets the printer paper length and width.

    FUNCTION SetPaperSize (BYVAL nLength AS LONG, BYVAL nWidth AS LONG) AS BOOLEAN

Parameter | Description
--- | ---
nLength | LONG. The length of the printer paper size.
nWidth | LONG. The width of the printer paper size.

#### Return value

BOOLEAN. Returns True on success or False on failure.

## PaperWidth

Gets/sets the printer paper width in units of 1/10 of a millimeter. This value overrides the length of the paper specified by the PaperSize property, and is used if the paper is of a custom size, or if the device is a dot matrix printer, which can print a page of arbitrary length. It must be used if the PaperLength is also used. Alternatively, you can use the SetPageSize function to set both the length and width with only one call.

    PROPERTY PaperWidth () AS LONG
    PROPERTY PaperWidth (BYVAL nWidth AS LONG)

Parameter | Description
--- | ---
nWidth | LONG. The printer paper length.

#### Return value

LONG. The printer paper width.

## Quality

Gets/sets the printer print quality mode.

    PROPERTY Quality () AS LONG
    PROPERTY Quality (BYVAL nMode AS LONG)

Parameter | Description
--- | ---
nMode | LONG. The printer print quality mode. There are four predefined device-independent values: DMRES_DRAFT (-1) = Draft. DMRES_LOW (-2) = Low DMRES_MEDIUM (-3) = Medium DMRES_HIGH (-4) = High If a positive value is specified, it represents the number of pixels per inch (PPI) for the x resolution.

#### Return value

LONG. The printer print quality mode.

## Scale

Gets/sets the factor by which the printed output is to be scaled.

    PROPERTY Scale () AS LONG
    PROPERTY Scale (BYVAL nScale AS LONG)

Parameter | Description
--- | ---
nScale | LONG. The factor by which the printed output is to be scaled. The apparent page size is scaled from the physical page size by a factor of nScale / 100. For example, a letter-sized page with a nScale value of 50 would contain as much data as a page of 17- by 22-inches because the output text and graphics would be half their original height and width.

#### Return value

LONG. The printer scaling factor.

## Tray

Gets/sets the paper source.

    PROPERTY Tray () AS LONG
    PROPERTY Tray (BYVAL nTray AS LONG)

Parameter | Description
--- | ---
nTray | LONG. The paper source. Can be one of the following values, or it can be a device-specific value greater than or equal to DMBIN_USER (256). DMBIN_UPPER = Select the upper paper bin. This value is also used for the paper source for printers that only have one paper bin. DMBIN_LOWER = Select the lower bin. DMBIN_MIDDLE = Select the middle paper bin. DMBIN_MANUAL = Manually select the paper bin. DMBIN_ENVELOPE = Select the auto envelope bin. DMBIN_ENVMANUAL = Select the manual envelope bin. DMBIN_AUTO = Auto-select the bin. DMBIN_TRACTOR = Select the bin with the tractor paper. DMBIN_SMALLFMT = Select the bin with the smaller paper format. DMBIN_LARGEFMT = Select the bin with the larger paper format. DMBIN_LARGECAPACITY = Select the bin with large capacity. DMBIN_CASSETTE = Select the cassette bin. DMBIN_FORMSOURCE = Select the bin with the required form.

#### Return value

LONG. The paper source.