Delphi Basics : TPrintDialog command

DelphiBasics

TPrintDialog
Type

Class that creates a printer selection and control dialog

Dialogs unit

type TPrintDialog = class;

Description

The TPrintDialog class is used to create a printer selection and print control dialog.

Before printing from your application, it is wise to display a print dialog. This allows the user to select the desired printer and attributes, along with control over how the document is printed. Such as multiple copies and pages to be printed.

You first use the class by creating an object from it, and then setting the required dialog attributes from the following list:

Collate	Whether to preset the Collate option
Copies	How many copies to print
FromPage	Selected page in page range
ToPage	Selected page in page range
MinPage	Earliest selectable page
MaxPage	Latest selectable page
PrintRange	Starting page selection type
Options	Various multi-selectable options
PrintToFile	If false, we print to paper

The PrintRange values are:

prAllPages	All pages to print
prSelection	Page selection to print
prPageNums	Page number range to print

You choose one before the dialog starts - and check to see if the user has changed it when the dialog ends.

The Options values may be one of the following:

poPrintToFile	Print to file
poPageNums	Print by page range
poSelection	Print by page selection
poWarning	Warning if bad printer
poHelp	Disply help
poDisablePrintToFile	Print to file disallowed

Some of these options may also be set by the dialog user. Always check their values afterwards.

After setting these options, use the Execute method to display the dialog, checking the Boolean outcome after it runs to know whether to proceed with the printing.

Notes

Used in conjunction with the Printer object.

Related commands

Printer		Returns a reference to the global Printer object
TObject		The base class type that is ancestor to all other classes

Download this web site as a Windows program.

Example code : A relatively simple example

const
  TOTAL_PAGES = 4;      // How many pages to print
var
  printDialog    : TPrintDialog;
  page, startPage, endPage : Integer;

begin
  // Create a printer selection dialog
  printDialog := TPrintDialog.Create(Form1);

  // Set up print dialog options
  printDialog.MinPage := 1;              // First allowed page number
  printDialog.MaxPage := TOTAL_PAGES;    // Highest allowed page number
  printDialog.ToPage  := TOTAL_PAGES;    // 1 to ToPage page range allowed
  printDialog.Options := [poPageNums];    // Allow page range selection

  // If the user has selected a printer (or default), then print!
  if printDialog.Execute then
  begin
    // Use the Printer function to get access to the global TPrinter object.
    // Set to landscape orientation
    Printer.Orientation := poLandscape;

    // Set the printjob title - as it it appears in the print job manager
    Printer.Title := 'Test print for Delphi';

    // Set the number of copies to print each page
    // This is crude - it doies not take Collation into account
    Printer.Copies := printDialog.Copies;

    // Start printing
    Printer.BeginDoc;

    // Has the user selected a page range?
    if printDialog.PrintRange = prPageNums then
    begin
      startPage := printDialog.FromPage;
      endPage   := printDialog.ToPage;
    end
    else// All pages
    begin
      startPage := 1;
      endPage   := TOTAL_PAGES;
    end;

    // Set up the start page number
    page := startPage;

    // Keep printing whilst all OK
    while (not Printer.Aborted) and Printer.Printing do
    begin
      // Write out the page number
      Printer.Canvas.Font.Color := clBlue;
      Printer.Canvas.TextOut(40,  20, 'Page number = '+IntToStr(page));

      // Increment the page number
      Inc(page);

      // Now start a new page - if not the last
      if (page <= endPage) and (not Printer.Aborted)
      then Printer.NewPage;
    end;

    // Finish printing
    Printer.EndDoc;
  end;
end;

Show full unit code

  The print dialog is displayed, and various pages printed if the
  user hits OK. Otherwise, no pages are printed.

  If printed, the page number appears on each page in blue