Microsoft Windows API:PrintDlg Function

Declare Auto Function PrintDlg Lib "comdlg32.dll" Alias "PrintDlg" (byRef pPrintdlg As PRINTDLG_TYPE) As Long

Platforms: Win 32s, Win 95/98, Win NT

PrintDlg displays either the Print common dialog box or the Print Setup dialog box. Either box can be used to allow the user to select a printer and other settings, such as the number of copies and the page range, desired for a print operation. Information for initializing the dialog box as well as information returned from it is stored in the structure passed as pPrintdlg. See the pages for the PRINTDLG_TYPE, DEVMODE, and DEVNAMES structures for more details about using this function. Note that instead of using the latter two structures explicitly, handles to the memory blocks holding their data are required by the function; see the example below. The function returns 0 if either an error occured or the user pressed Cancel, or a non-zero value if the user successfully pressed OK.

pPrintdlg

Stores both the dialog box's initialization settings and the information returned from the dialog box.

Type PRINTDLG_TYPE

  lStructSize As Long
  hwndOwner As Long
  hDevMode As Long
  hDevNames As Long
  hdc As Long
  flags As Long
  nFromPage As Integer
  nToPage As Integer
  nMinPage As Integer
  nMaxPage As Integer
  nCopies As Integer
  hInstance As Long
  lCustData As Long
  lpfnPrintHook As Long
  lpfnSetupHook As Long
  lpPrintTemplateName As String
  lpSetupTemplateName As String
  hPrintTemplate As Long
  hSetupTemplate As Long
End Type

PRINTDLG_TYPE-type variables store the necessary information to use a Print common dialog box or a Print Setup common dialog box. This structure holds all information necessary to initialize the box and receives the data selected by the user. Set the various members for the box's default selections -- they will be set by the called function to the selections of the user. Note that two other structures, DEVMODE and DEVNAMES, are included by specifying handles to a memory block. These memory blocks contain a copy of each structure's data. See the example for PrintDlg for information on how to create, use, and free these memory blocks.

lStructSize

The size in bytes of this structure.

hwndOwner

A handle to the window opening the dialog box, if any.

hDevMode

A handle to the memory block holding the information contained in a DEVMODE structure. This data specifies information about the printer.

hDevNames

A handle to the memory block holding the information contained in a DEVNAMES structure. This data specifies the driver name, printer name, and port name(s) of the printer.

hdc

Receives either a device context or an information context (depending on the value set as flags) to the printer the user selected.

flags

Zero or more of the following flags specifying various options for creating the Print or Print Setup dialog. Note that when PrintDlg returns, many of these flags will be set by the function to indicate selections by the user:

PD_ALLPAGES = &H0

Select the All Pages radio button.

PD_COLLATE = &H10

Check the Collate check box. If this flag is set when the function returns, the user checked the box and the printer doesn't automatically support collation. If the box is checked and the printer does support it, this flag will not be set.

PD_DISABLEPRINTTOFILE = &H80000

Disable the Print to File check box.

PD_ENABLEPRINTHOOK = &H1000

Use the hook function pointed to by lpfnPrintHook to process the Print dialog box's messages.

PD_ENABLEPRINTTEMPLATE = &H4000

Use the Print dialog box template specified by lpPrintTemplateName.

PD_ENABLEPRINTTEMPLATEHANDLE = &H10000

Use the preloaded Print dialog box template specified by hPrintTemplate.

PD_ENABLESETUPHOOK = &H2000

Use the hook function pointed to by lpfnSetupHook to process the Print Setup dialog box's messages.

PD_ENABLESETUPTEMPLATE = &H8000

Use the Print Setup dialog box template specified by lpSetupTemplateName.

PD_ENABLESETUPTEMPLATEHANDLE = &H20000

Use the preloaded Print Setup dialog box template specified by hSetupTemplate.

PD_HIDEPRINTTOFILE = &H100000

Hide the Print to File check box.

PD_NONETWORKBUTTON = &H200000

Do not display any buttons associated with the network.

PD_NOPAGENUMS = &H8

Disable the Page Range radio button and edit boxes.

PD_NOSELECTION = &H4

Disable the Selection radio button.

PD_NOWARNING = &H80

Do not warn the user if there is no default printer.

PD_PAGENUMS = &H2

Select the Page Range radio button.

PD_PRINTSETUP = &H40

Display the Print Setup dialog box instead of the Print dialog box.

PD_PRINTTOFILE = &H20

Select the Print to File check box.

PD_RETURNDC = &H100

Return a device context to the selected printer as hdc.

PD_RETURNDEFAULT = &H400

Instead of displaying either dialog box, simply load information about the default printer into hDevMode and hDevNames. For this to work, those two values must be set to 0 before calling the function.

PD_RETURNIC = &H200

Return an information context to the selected printer as hdc.

PD_SELECTION = &H1

Select the Selection radio button.

PD_SHOWHELP = &H800

Display the Help button.

PD_USEDEVMODECOPIES = &H40000

Same as PD_USEDEVMODECOPIESANDCOLLATE.

PD_USEDEVMODECOPIESANDCOLLATE = &H40000

If the printer does not automatically support multiple copies or collation, disable the corresponding options in the dialog box. The number of copies to print and the collation setting will be placed into hDevMode. The information returned to this structure will specify the number of pages and the collation which the program must print with -- the printer will print the copies or collate itself.

nFromPage

The value entered in the From Page text box, specifying which page begin printing at.

nToPage

The value entered in the To Page text box, specifying which page to stop printing at.

nMinPage

The minimum allowable value for nFromPage and nToPage.

nMaxPage

The maximum allowable value for nFromPage and nToPage.

nCopies

The number of copies the program needs to print.

hInstance

A handle to the application instance which has the desired dialog box template.

lCustData

A program-defined value to pass to whichever hook function is used.

lpfnPrintHook

A handle to the program-defined hook function to use to process the Print dialog box's messages.

lpfnSetupHook

A handle to the program-defined hook function to use to process the Print Setup dialog box's messages.

lpPrintTemplateName

The name of the Print dialog box template to use from the application instance specified by hInstance.

lpSetupTemplateName

The name of the Print Setup dialog box template to use from the application instance specified by hInstance.

hPrintTemplate

A handle to the preloaded Print dialog box template to use.

hSetupTemplate

A handle to the preloaded Print Setup dialog box template to

Type DEVMODE
  dmDeviceName As String * 32
  dmSpecVersion As Integer
  dmDriverVersion As Integer
  dmSize As Integer
  dmDriverExtra As Integer
  dmFields As Long
  dmOrientation As Integer
  dmPaperSize As Integer
  dmPaperLength As Integer
  dmPaperWidth As Integer
  dmScale As Integer
  dmCopies As Integer
  dmDefaultSource As Integer
  dmPrintQuality As Integer
  dmColor As Integer
  dmDuplex As Integer
  dmYResolution As Integer
  dmTTOption As Integer
  dmCollate As Integer
  dmFormName As String * 32
  dmUnusedPadding As Integer
  dmBitsPerPixel As Integer
  dmPelsWidth As Long
  dmPelsHeight As Long
  dmDisplayFlags As Long
  dmDisplayFrequency As Long
  ' the following members are only valid under Win 95/98 -- omit them in Win NT:
  dmICMMethod As Long
  dmICMIntent As Long
  dmMediaType As Long
  dmDitherType As Long
  dmReserved1 As Long
  dmReserved2 As Long
End Type

DEVMODE-type variables store information about various settings and properties of a device, such as a printer. Some of the properties only apply to certain devices; for example, the dmDisplayFrequency has no meaning for a printer. Look at the dmFields member to determine which of the structure's member values have meaningful information.

dmDeviceName

The name of the device.

dmSpecVersion

The version number of the device's initialization information specification.

dmDriverVersion

The version number of the device driver.

dmSize

The size of the structure, in bytes.

dmDriverExtra

The number of bytes of information trailing the structure in memory.

dmFields

One or more of the following flags specifying which of the rest of the structure's members contain information about the device:

DM_BITSPERPEL = &H40000

dmBitsPerPel contains information.

DM_COLLATE = &H8000

dmCollate contains information.

DM_COLOR = &H800

dmColor contains information.

DM_COPIES = &H100

dmCopies contains information.

DM_DEFAULTSOURCE = &H200

dmDefaultSource contains information.

DM_DISPLAYFLAGS = &H200000

dmDisplayFlags contains information.

DM_DISPLAYFREQUENCY = &H400000

dmDisplayFrequency contains information.

DM_DITHERTYPE = &H4000000

Win 95/98 only: dmDitherType contains information.

DM_DUPLEX = &H1000

dmDuplex contains information.

DM_FORMNAME = &H10000

dmFormName contains information.

DM_ICMINTENT = &H1000000

Win 95/98 only: dmICMIntent contains information.

DM_ICMMETHOD = &H800000

Win 95/98 only: dmICMMethod contains information.

DM_LOGPIXELS = &H20000

dmLogPixels contains information.

DM_MEDIATYPE = &H2000000

Win 95/98 only: dmMediaType contains information.

DM_ORIENTATION = &H1

dmOrientation contains information.

DM_PAPERLENGTH = &H4

dmPaperLength contains information.

DM_PAPERSIZE = &H2

dmPaperSize contains information.

DM_PAPERWIDTH = &H8

dmPaperWidth contains information.

DM_PELSHEIGHT = &H100000

dmPelsHeight contains information.

DM_PELSWIDTH = &H80000

dmPelsWidth contains information.

DM_PRINTQUALITY = &H400

dmPrintQuality contains information.

DM_SCALE = &H10

dmScale contains information.

DM_TTOPTION = &H4000

dmTTOption contains information.

DM_YRESOLUTION = &H2000

dmYResolution contains information.

dmOrientation

Exactly one of the following flags specifying the orientation of the printer paper:

DMORIENT_LANDSCAPE = 2

Landscape (wide) mode.

DMORIENT_PORTRAIT = 1

Portrait (tall) mode.

dmPaperSize

If nonzero, exactly one of the following flags specifying the size of the printer paper. If zero, the paper size is determined by dmPaperLength and dmPaperWidth.

DMPAPER_10X11 = 45

10 x 11 inches.

DMPAPER_10X14 = 16

10 x 14 inches.

DMPAPER_11X17 = 17

11 x 17 inches.

DMPAPER_15X11 = 46

15 x 11 inches.

DMPAPER_9X11 = 44

9 x 11 inches.

DMPAPER_A_PLUS = 57

A plus sheet.

DMPAPER_A2 = 66

A2 sheet.

DMPAPER_A3 = 8

A3 sheet, 297 x 420 millimeters.

DMPAPER_A3_EXTRA = 63

A3 extra sheet.

DMPAPER_A3_EXTRA_TRANSVERSE = 68

A3 extra transverse sheet.

DMPAPER_A3_TRANSVERSE = 67

A3 transverse sheet.

DMPAPER_A4 = 9

A4 sheet, 210 x 297 millimeters.

DMPAPER_A4_EXTRA = 53

A4 extra sheet.

DMPAPER_A4_PLUS = 60

A4 plus sheet.

DMPAPER_A4_TRANSVERSE = 55

A4 transverse sheet.

DMPAPER_A4SMALL = 10

A4 small sheet, 210 x 297 millimeters.

DMPAPER_A5 = 11

A5 sheet, 148 x 210 millimeters.

DMPAPER_A5_EXTRA = 64

A5 extra sheet.

DMPAPER_A5_TRANSVERSE = 61

A5 transverse sheet.

DMPAPER_B_PLUS = 58

B plus sheet.

DMPAPER_B4 = 12

B4 sheet, 250 x 354 millimeters.

DMPAPER_B5 = 13

B5 sheet, 192 x 257 millimeters.

DMPAPER_B5_EXTRA = 65

B5 extra sheet.

DMPAPER_B5_TRANSVERSE = 62

B5 transverse sheet.

DMPAPER_CSHEET = 24

C sheet, 17 x 22 inches.

DMPAPER_DSHEET = 25

D sheet, 22 x 34 inches.

DMPAPER_ENV_10 = 20

#10 envelope, 4.125 x 9.5 inches.

DMPAPER_ENV_11 = 21

#11 envelope, 4.5 x 10.375 inches.

DMPAPER_ENV_12 = 22

#12 envelope, 4.75 x 11 inches.

DMPAPER_ENV_14 = 23

#14 envelope, 5 x 11.5 inches.

DMPAPER_ENV_9 = 19

#9 envelope, 3.875 x 8.875 inches.

DMPAPER_ENV_B4 = 33

B4 envelope, 250 x 353 millimeters.

DMPAPER_ENV_B5 = 34

B5 envelope, 176 x 250 millimeters.

DMPAPER_ENV_B6 = 35

B6 envelope, 176 x 125 millimeters.

DMPAPER_ENV_C3 = 29

C3 envelope, 324 x 458 millimeters.

DMPAPER_ENV_C4 = 30

C4 envelope, 229 x 324 millimeters.

DMPAPER_ENV_C5 = 28

C5 envelope, 162 x 229 millimeters.

DMPAPER_ENV_C6 = 31

C6 envelope, 114 x 162 millimeters.

DMPAPER_ENV_C65 = 32

C65 envelope, 114 x 229 millimeters.

DMPAPER_ENV_DL = 27

DL envelope, 110 x 220 millimeters.

DMPAPER_ENV_INVITE = 47

Invitation envelope.

DMPAPER_ENV_ITALY = 36

Italy envelope, 110 x 230 millimeters.

DMPAPER_ENV_MONARCH = 37

Monarch envelope, 3.875 x 7.5 inches.

DMPAPER_ENV_PERSONAL = 38

Personal (6.75) envelope, 3.625 x 6.5 inches.

DMPAPER_ESHEET = 26

E sheet, 34 x 44 inches.

DMPAPER_EXECUTIVE = 7

Executive, 7.25 x 10.5 inches.

DMPAPER_FANFOLD_LGL_GERMAN = 41

German legal fanfold, 8.5 x 13 inches.

DMPAPER_FANFOLD_STD_GERMAN = 40

German standard fanfold, 8.5 x 12 inches.

DMPAPER_FANFOLD_US = 39

US standard fanfold, 14.875 x 11 inches.

DMPAPER_FIRST = 1

Same as DMPAPER_LETTER.

DMPAPER_FOLIO = 14

Folio, 8.5 x 13 inches.

DMPAPER_ISO_B4 = 42

ISO B4 sheet.

DMPAPER_JAPANESE_POSTCARD = 43

Japanese postcard.

DMPAPER_LAST = 41

Same as DMPAPER_FANFOLD_LGL_GERMAN.

DMPAPER_LEDGER = 4

Ledger, 17 x 11 inches.

DMPAPER_LEGAL = 5

Legal, 8.5 x 14 inches.

DMPAPER_LEGAL_EXTRA = 51

Legal extra.

DMPAPER_LETTER = 1

Letter, 8.5 x 11 inches.

DMPAPER_LETTER_EXTRA = 50

Letter extra.

DMPAPER_LETTER_EXTRA_TRANSVERSE = 56

Letter extra transverse.

DMPAPER_LETTER_PLUS = 59

Letter plus.

DMPAPER_LETTER_TRANSVERSE = 54

Letter transverse.

DMPAPER_LETTERSMALL = 2

Letter small, 8.5 x 11 inches.

DMPAPER_NOTE = 18

Note, 8.5 x 11 inches.

DMPAPER_QUARTO = 15

Quarto, 215 x 275 millimeters.

DMPAPER_STATEMENT = 6

Statement, 5.5 x 8.5 inches.

DMPAPER_TABLOID = 3

Tabloid, 11 x 17 inches.

DMPAPER_TABLOID_EXTRA = 52

Tabloid extra.

DMPAPER_USER = 256

User-defined size (?).

dmPaperLength

The length of the printer paper, measured in tenths of a millimeter.

dmPaperWidth

The width of the printer paper, measured in tenths of a millimeter.

dmScale

The scale percentage factor (e.g., 100 means 100%, or no, scaling; 200 means two times the size, etc.).

dmCopies

The number of document copies to print, if the device supports it.

dmDefaultSource

Reserved -- set to 0.

dmPrintQuality

Either exactly one of the following flags specifying the printer's print quality setting, or a positive value specifying the printer's dots per inch (DPI) rating.

DMRES_DRAFT = -1

Draft-quality output.

DMRES_HIGH = -4

High-quality output.

DMRES_LOW = -2

Low-quality output.

DMRES_MEDIUM = -3

Medium-quality output.

dmColor

Exactly one of the following flags specifying whether the device supports color:

DMCOLOR_COLOR = 2

The device supports color output.

DMCOLOR_MONOCHROME = 1

The device does not support color output.

dmDuplex

Exactly one of the following flags specifying the printer's double-sided (duplex) printing capability:

DMDUP_HORIZONTAL = 3

Configured for double-sided printing with horizontal page turning (?).

DMDUP_SIMPLEX = 1

Configured for single-sided printing (?).

DMDUP_VERTICAL = 2

Configured for double-sided printing with vertical page turning (?).

dmYResolution

The number of the vertical dots per inch of the printer. If this value contains useful data, the number of horizontal dots per inch is inside dmPrintQuality.

dmTTOption

Exactly one of the following flags specifying how the printer prints TrueType fonts:

DMTT_BITMAP = 1

The printer prints TrueType fonts as graphics (default for dot-matrix printers).

DMTT_DOWNLOAD = 2

The printer downloads TrueType fonts as soft fonts (default for Hewlett-Packerd printers using Printer Control Language).

DMTT_SUBDEV = 4

The printer substitutes device fonts for TrueType fonts (default for PostScript printers).

dmCollate

Exactly one of the following flags specifying whether the printer can collate copies:

DMCOLLATE_FALSE = 0

Does not collate pages when printing multiple copies.

DMCOLLATE_TRUE = 1

Does collate pages when printing multiple copies.

dmFormName

Win NT only: The name of the type of paper loaded in the printer.

dmUnusedPadding

Reserved -- set to 0. This member merely takes up space to align other members in memory.

dmBitsPerPel

The number of color bits used per pixel on the display device.

dmPelsWidth

The width of the display, measured in pixels.

dmPelsHeight

The height of the display, measured in pixels.

dmDisplayFlags

Zero or more of the following flags specifying the device's display mode:

DM_GRAYSCALE = 1

The display does not support color. (If this flag is omitted, assume color is supported.)

DM_INTERLACED = 2

The display is interlaced.

dmDisplayFrequency

The display frequency of the display, measured in Hz.

dmICMMethod

Win 95/98 only: Either exactly one of the following flags specifying how image color matching (ICM) is supported, or a device-defined value greater than 256:

DMICMMETHOD_DEVICE = 4

ICM is handled by the device.

DMICMMETHOD_DRIVER = 3

ICM is handled by the device driver.

DMICMMETHOD_NONE = 1

ICM is disabled.

DMICMMETHOD_SYSTEM = 2

ICM is handled by Windows.

dmICMIntent

Win 95/98 only: Either exactly one of the following flags specifying the image color matching (ICM) method used when ICM is not intrinsically supported, or a device-defined value greater than 256:

DMICM_COLORMETRIC = 3

Color matching attempts to match the exact color requested.

DMICM_CONTRAST = 2

Color matching attempts to optimize color contrast.

DMICM_SATURATE = 1

Color matching attempts to optimize color saturation.

dmMediaType

Win 95/98 only: Either exactly one of the following flags specifying what type of medium the printer is printing on, or a device-defined value greater than 256:

DMMEDIA_GLOSSY = 2

Glossy paper.

DMMEDIA_STANDARD = 1

Plain paper.

DMMEDIA_TRANSPARECNY = 3

Transparent film.

dmDitherType

Win 95/98 only: Either exactly one of the following flags specifying the dithering method used by the device, or a device-defined value greater than 256:

DMDITHER_COARSE = 2

Dithering with a coarse brush.

DMDITHER_FINE = 3

Dithering with a fine brush.

DMDITHER_GRAYSCALE = 5

Grayscaling.

DMDITHER_LINEART = 4

Line art dithering, which makes well-defined borders between black, white, and gray.

DMDITHER_NONE = 1

No dithering.

dmReserved1

Win 95/98 only: Reserved -- set to 0.

dmReserved2

Win 95/98 only: Reserved -- set

Type DEVNAMES

  wDriverOffset As Integer
  wDeviceOffset As Integer
  wOutputOffset As Integer
  wDefault As Integer
  extra As String * 100
End Type

DEVNAMES-type variables store some information about a device. This information includes the device driver name, the device name, and the names of any output ports it uses. Note that instead of storing strings in the usual way, this structure puts all three strings into extra, where null characters separate them. The offset values specify the location of these strings in extra, measured in bytes from the beginning of the structure. For example, the very first character in extra would have an offset of 8. See the example for the PrintDlg function for a demonstration of using this structure.

wDriverOffset

The offset of the string in extra identifying the name of the device driver filename (without the extension).

wDeviceOffset

The offset of the string in extra identifying the name of the device.

wOutputOffset

The offset of the string in extra identifying the output port(s) which the device uses, separated by commas.

wDefault

If non-zero, the information in the structure identifies the default device of its type. If zero, the information does not necessarily descibe the default device.

extra

Buffer which holds the three strings identified by wDriverOffset, wDeviceOffset, and wOutputOffset