Class

PrinterSetup

Description

Used to get and set the page setup settings.

Methods

Name

Parameters

Returns

Shared

OpenPrinter

setup As PrinterSetup

Graphics

✓

ShowPageSetupDialog

Optional window As Window

Boolean

Optional window As DesktopWindow

Boolean

ShowPrinterDialog

Optional parentWindow As Window

Graphics

Optional parentWindow As DesktopWindow

Graphics

Property descriptions

PrinterSetup.Height

Height As Integer

The height of the printable area on the page (in pixels). The height is the PageHeight minus the margins.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)

PrinterSetup.HorizontalResolution

HorizontalResolution As Integer

The horizontal resolution in dots per inch of the output device (usually a printer).

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.Landscape

Landscape As Boolean

Gets and sets the landscape state of the PrinterSetup object. It is True for the landscape orientation; False otherwise. Currently supported on Windows and macOS only.

This example sets the Landscape property.

Var settings As String
Var p As New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If
p.MaximumHorizontalResolution = 300
p.MaximumVerticalResolution = 300
p.Landscape = True

PrinterSetup.Left

Left As Integer

The left origin of the printable area. This should always be zero.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString
Label11.Text = "Left=" + p.Left.ToString

PrinterSetup.MaximumHorizontalResolution

MaximumHorizontalResolution As Integer

Set to request the maximum horizontal resolution for the printer to use.

You can change it to the maximum printer resolution you're prepared to handle or -1 for the highest possible resolution of the output device. After calling ShowPageSetupDialog, OpenPrinter, or ShowPrinterDialog, the HorizontalResolution property will automatically be set to the highest resolution supported by the printer driver, within your specified constraints, although this may be less than what you have specified. Printing occurs at HorizontalResolution, so you should always check and use that value after setting this value.

This example sets the MaximumHorizontalResolution and MaximumVerticalResolution properties.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.ShowPageSetupDialog Then
  settings = p.ConfigurationData
End If
p.MaximumHorizontalResolution = 1200
p.MaximumVerticalResolution = 1200

PrinterSetup.MaximumVerticalResolution

MaximumVerticalResolution As Integer

Set to the maximum vertical resolution at which you wish to print. The default value is 72.

You can change it to the maximum printer resolution you're prepared to handle or -1 for the highest possible resolution of the output device. After calling ShowPageSetupDialog, OpenPrinter, or ShowPrinterDialog, the VerticalResolution property will automatically be set to the highest resolution supported by the printer driver, within your specified constraints, although this may be less than what you have specified. Printing occurs at VerticalResolution, so you should always check and use that value after setting this value.

This example sets the MaximumVerticalResolution and MaximumHorizontalResolution properties.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.ShowPageSetupDialog Then
  settings = p.ConfigurationData
End If
p.MaximumHorizontalResolution = 1200
p.MaximumVerticalResolution = 1200

PrinterSetup.PageHeight

PageHeight As Integer

The height of the page in pixels.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.PageLeft

PageLeft As Integer

The offset distance (in pixels) from the left margin of the printable area to the left edge of the physical page, i.e., the left margin.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.PageTop

PageTop As Integer

The offset distance (in pixels) from the top margin of the printable area to the top edge of the physical page, i.e., the top margin.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.PageWidth

PageWidth As Integer

The width of the page in pixels.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.Settings

Settings As String

A value that represents all of the other properties.

When the user clicks OK in the Page Setup dialog box, this value will be populated. You can then store this value to store the user's Page Setup settings. Assigning one of these stored values to this property will then update all of the other properties restoring the page setup settings.

This example displays the Page Setup dialog box and then stores the settings the user chose in a variable:

Var s As String
Var pageSetup As New PrinterSetup
If pageSetup.ShowPageSetupDialog Then
  s = pageSetup.Settings
End If

This example restores the page setup settings stored in a variable (s) and then displays the Page Setup dialog box with those settings:

Var pageSetup As New PrinterSetup
pageSetup.Settings = s
If pageSetup.ShowPageSetupDialog Then
  s = PageSetup.Settings
End If

PrinterSetup.Top

Top As Integer

The top origin of the printable area. This should always be zero.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.VerticalResolution

VerticalResolution As Integer

The vertical resolution in dots per inch of the output device (usually a printer).

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

PrinterSetup.Width

Width As Integer

The width of the printable area on the page in pixels. The width is the PageWidth minus the margins.

This property is read-only.

This example displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)
Label9.Text = "Horizontal resolution=" + p.HorizontalResolution.ToString
Label10.Text = "Vertical Resolution=" + p.VerticalResolution.ToString

Method descriptions

PrinterSetup.OpenPrinter

OpenPrinter(setup As PrinterSetup) As Graphics

The OpenPrinter function returns a Graphics object. The various drawing routines can then be used to draw into the Graphics object and will be sent to the printer for printing.

Although the pageSetup parameter is optional, in order to get the correct horizontal and vertical resolutions for drawing and positioning you will need to provide a PrinterSetup. You can do this without prompting the user with a dialog like this:

Var p As New PrinterSetup
g = PrinterSetup.OpenPrinter(p)
Var horizontalDPI As Integer = p.HorizontalResolution
Var verticalDPI As Integer = p.VerticalResolution

This code prints "Hello World" to the currently selected printer:

Var p As New PrinterSetup
Var g As Graphics
g = PrinterSetup.OpenPrinter(p)
If g <> Nil Then
  // Draw text 1 inch across and 1 inch down
  g.DrawText("Hello World", p.HorizontalResolution, p.VerticalResolution)
End If

This code uses the Page Setup properties for the printer chosen by the user by the PageSetup dialog:

Var ps As New PrinterSetup
If ps.ShowPageSetupDialog Then
  Var g As Graphics
  g = PrinterSetup.OpenPrinter(ps)
  If g <> Nil Then
    // Draw text 1 inch across and 1 inch down
    g.DrawText("Hello World", ps.HorizontalResolution, ps.VerticalResolution)
  End If
End If

PrinterSetup.ShowPageSetupDialog

ShowPageSetupDialog(Optional window As Window) As Boolean

Displays the standard Page Setup dialog box.

PrinterSetup.ShowPageSetupDialog

ShowPageSetupDialog(Optional window As DesktopWindow) As Boolean

Displays the standard Page Setup dialog box.

If the SetupString property has been populated before this method is called, the Page Setup dialog box will reflect the settings stored in the SetupString property. After the user clicks the OK button to close the Page Setup dialog box, all of the PrinterSetup properties will be updated to reflect the settings the user chose.

On a macOS, PageSetupDialog takes an optional parameter, window. If specified, the Page Setup dialog will appear as a sheet connected to that window.

Returns a Boolean. This function returns True if the User clicks OK and False if the user clicks Cancel.

This example displays the Page Setup dialog box and then stores the settings the user chose in a variable:

Var printerSettings As String
Var printer As New PrinterSetup
If printer.ShowPageSetupDialog Then
  printerSettings = printer.SetupString
End If

PrinterSetup.ShowPrinterDialog

ShowPrinterDialog(Optional parentWindow As Window) As Graphics

Displays the standard Print dialog box and returns a Graphics object in order to print to the currently selected printer.

PrinterSetup.ShowPrinterDialog

ShowPrinterDialog(Optional parentWindow As DesktopWindow) As Graphics

Displays the standard Print dialog box and returns a Graphics object in order to print to the currently selected printer.

The ShowPrinterDialog function returns a Graphics object. The various drawing routines can then be used to draw into the Graphics object and will be sent to the printer for printing. You can get the values in the Copies, From and To fields of the Print dialog box using the Copies, FirstPage and LastPage properties of the Graphics object returned by the ShowPrinterDialog function.

If the user clicks the Cancel button, the ShowPrinterDialog function returns Nil.

Although the pageSetup parameter is optional, in order to get the correct horizontal and vertical resolutions for drawing and positioning you will need to provide a PrinterSetup. You can do this without prompting the user with a dialog like this:

Var g As Graphics
Var ps As New PrinterSetup
g = ps.ShowPrinterDialog(MyWindow)
Var horizontalDPI As Integer = ps.HorizontalResolution
Var verticalDPI As Integer = ps.VerticalResolution

This example prints "Hello World" to the currently selected printer.

Var ps As New PrinterSetup
Var g As Graphics
g = ps.ShowPrinterDialog()
If g <> Nil Then
  // Draw text 1 inch across and 1 inch down
  g.DrawText("Hello World", ps.HorizontalResolution, ps.VerticalResolution)
End If

This example uses the Page Setup properties for the printer chosen by the user by the PageSetup dialog:

Var ps As New PrinterSetup
If ps.ShowPageSetupDialog Then
  Var g As Graphics
  g = ps.ShowPrinterDialog()
  If g <> Nil Then
    // Draw text 1 inch across and 1 inch down
    g.DrawText("Hello World", ps.HorizontalResolution, ps.VerticalResolution)
  End If
End If

This example checks if the Windows printer supports alpha blending:

Declare Function GetDeviceCaps Lib "gdi32" ( hdc As Ptr, index As Int32 ) As Int32
Const SHADEBLENDCAPS = 120
Const SB_NONE = 0
Const SB_CONST_ALPHA = 1
Const SB_PIXEL_ALPHA = 2
Const SB_PREMULT_ALPHA = 4
Const SB_GRAD_RECT = &h10
Const SB_GRAD_TRI = &h20

Var ps As New PrinterSetup
Var g As Graphics = ps.ShowPrinterDialog(Nil)
Var hdc As Ptr = g.Handle = Graphics.HandleTypes.HDC

If GetDeviceCaps(hdc, SHADEBLENDCAPS) = SB_NONE Then
  MessageBox("This Printer does not support alpha blending.")
Else
  MessageBox("Yay! This Printer supports alpha blending.")
End If

Notes

The printer reports back a virtual drawing surface that has the resolution supplied in the HorizontalResolution and VerticalResolution properties. This varies by OS platform. Actual printing resolution is determined by the printer based on guidance provided by you using the MaximumHorizontalResolution and MaximumVerticalResolution properties.

When drawing to the Graphic object returned by OpenPrinter, you should always use the HorizontalResolution and VerticalResolution properties to ensure correct sizing. This allows your print output to draw correctly when the printer draws at its native resolution.

Passing a PrinterSetup object to the OpenPrinter or ShowPrinterDialog functions will cause the printer to utilize those PrinterSetup object's properties when printing. For example, if the user chose 200% for the scale in the Page Setup dialog box, the printer would automatically print at 200%.

Maximumhorizontalresolution and maximumverticalresolution

These tell the printer the maximum resolutions you would like to use. Changing these does not mean the printer will use the resolutions you specify. You still have to use the HorizontalResolution and VerticalResolution properties to get the resolution to use for drawing.

Sample code

This code displays the Page Setup dialog box and then stores the settings the user chose in a variable:

Var s As String
Var pageSetup As PrinterSetup
pageSetup = New PrinterSetup
If pageSetup.ShowPageSetupDialog Then
  s = pageSetup.Settings
End If

This code restores the page setup settings stored in a String variable called "settings" and then displays the Page Setup dialog box with those settings:

Var pageSetup As PrinterSetup
pageSetup = New PrinterSetup
pageSetup.Settings = s
If pageSetup.ShowPageSetupDialog Then
  s = pageSetup.Settings
End If

This code displays the Page Setup dialog box and then passes the settings the user chose to the ShowPrinterDialog function. It then prints a sample string:

Var g As Graphics
Var p As PrinterSetup
p = New PrinterSetup
If p.ShowPageSetupDialog Then
  g = p.ShowPrinterDialog
  If g <> Nil Then
    g.DrawText("Hello World", 50, 50)
  End If
End If

This code displays the Page Setup box and then displays the page size, printable area, and margins in Label controls. Results, of course, depend on the page size that the user selects. Since PageLeft and PageTop are the horizontal and vertical margins as measured from the printable area rather than the edge of the page, they are negative.

Var settings As String
Var p As PrinterSetup
p = New PrinterSetup
If p.PageSetupDialog Then
  settings = p.SetupString
End If

Label1.Text = "PageLeft=" + p.PageLeft.ToString
Label2.Text = "PageTop=" + p.PageTop.ToString
Label3.Text = "PageHeight=" + p.PageHeight.ToString
Label4.Text = "PageWidth=" + p.PageWidth.ToString
Label5.Text = "Height=" + p.Height.ToString
Label6.Text = "Width=" + p.Width.ToString
Label7.Text = "Computed height=" + Str(p.Height - 2 * p.PageTop)
Label8.Text = "Computed width=" + Str(p.Width - 2 * p.PageLeft)

Compatibility

All project types on all supported operating systems.

See also

Object parent class; Graphics, StyledTextPrinter classes; OpenPrinter, ShowPrinterDialog functions.