Printing text and graphic

Teleprinter type printing

Delphi reveals its heritage from the 1970's and earlier when console and line printers were standard.
The AssignPrn command allows you to use the Write and WriteLn commands to write a stream of
text to your printer. It is simply that. There is no control of font, of page throws, page numbering and
so on. And of course, no graphics.

Full control printing

Delphi does provide modern full text and graphics printing. The Delphi print model is very different
from that of Java, where Java asks the application for pages it chooses. In Delphi, we interrogate the
print dialog, and determine ourselves what pages are to be printed, and in what sequence.

There are in fact two Printer objects, depending on whether you have a CLX or VCL application.
The differences are minor.

Using the printer dialog

It is highly recommended that you display the printer dialog so that the user can control printing. In
the example program that we will build up during this tutorial, we will show a print dialog that
allows the user to select all pages, or a range of pages. We keep things as simple as possible by
ignoring the Collate option. Unfortunately, when the user selects multiple copies, we cannot switch
off the collate option, so you should code for it in your application.

const
TOTAL_PAGES = 4; // How many pages to print
var
printDialog : TPrintDialog;
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
... Your print statements
end;
end;
Here we have created a print dialog object, set up some options, and then displayed it. The Execute
method returns true if the user has hit OK rather than cancel. We then print the document. The user
can select, via these options, whether to print all 4 pages or a range of these pages, as seen in a
portion of the dialog shown below:

Starting to print
The Printer object is permanently available to your code (you must use the Printers unit to get
access to its methods and fields though). With this object, printing proceeds in an orderly fashion.
 // 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;
This starts a print job, with a landscape page layout, and a title, and the user specified number of
copies. Note that we are ignoring collation - we always print all page 1 copies before page 2 etc.

Responding to the dialog settings

The following code snippet defines some new variables :

var
page, startPage, endPage : Integer;
And we now set these variables from the print dialog:

// 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;
The prPageNums value is a TPrintRange value, and is one of the values that PrintRange may have.
If set, it means that the user has selected a range of pages. The FromPage and ToPage values will
then be set to the user specified values.

The main printing logic

The following code snippet shows the main part of our printing code:

// Keep printing whilst all OK

while (not Printer.Aborted) and Printer.Printing do
begin
// Show a message saying we are starting a page
ShowMessagePos('Starting to print page '+IntToStr(page),300,300);

// Set up a medium sized font

Printer.Canvas.Font.Size := 10;

// Allow Windows to keep processing messages

Application.ProcessMessages;

// Write out the page number

Printer.Canvas.Font.Color := clBlue;
Printer.Canvas.TextOut(40, 20, 'Page number = '+IntToStr(page));

// Underline this page number

Printer.Canvas.MoveTo(40,80);
Printer.Canvas.LineTo(Printer.PageWidth-20,80);

// Write out the page size

Printer.Canvas.Font.Color := clRed;
Printer.Canvas.TextOut(40, 100, 'Page width = '+
IntToStr(Printer.PageWidth));
Printer.Canvas.TextOut(40, 180, 'Page height = '+
IntToStr(Printer.PageHeight));
 // 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;
The functions highlighted in red illustrate printing graphics and text operations. We have drawn a
line across the page after moving the line start point to the appropriate position. And we have written
out the page number and size values. Text is also positioned by graphical coordinate.

Both graphical and textual operations are performed on the Printer Canvas. This is very important. It
allows you to have a very similar or identical block of code that displays to a form canvas as it does
to a printer canvas. This lets you print what you display.

Notice that we handle the page numbering, and page throws (Printer.NewPage) ourselves.

Finally, when all pages have been printed, the last page throw is performed when we close the print
job using Printer.EndDoc.

We are not done there

In practice, you may print documents greater in complexity and size than this simple one. It may be
important to you to provide a print cancel mechanism, so that the user can easily abandon unwanted
print runs. However, we cannot just display a cancel dialog, since this will hold up our processing.
We must display this dialog in a separate threa of execution.

Threading is somewhat beyond the remit of this article, but is included in the final, complete code
given below. You can copy and paste this code into Delphi, as long as you follow the instructions at
the top of the code:
// Full Unit code.
// -----------------------------------------------------------
// You must store this code in a unit called Unit1 with a form
// called Form1 that has an OnCreate event called FormCreate.

unit Unit1;

interface

uses
Printers, // Unit containing the Printer command
SysUtils, Graphics, Windows,
Forms, Dialogs;

type
TForm1 = class(TForm)
procedure FormCreate(Sender: TObject);
end;

var
Form1: TForm1;

implementation
{$R *.dfm} // Include form definitions

// A subroutine used to display a print-cancel dialog

procedure CancelDialog;
begin
// Display the cancel print dialog
Dialogs.MessageDlg('Press cancel to abort printing',mtCustom,[mbCancel],0);

// Now that the user has pressed cancel, we abort the printing
if Printer.Printing then
begin
Printer.Abort;
ShowMessage('Printing aborted');
end;
 // End this thread
endThread(0);
end;

// The main form On Create routine - our main program

procedure TForm1.FormCreate(Sender: TObject);
const
TOTAL_PAGES = 4; // How many pages to print
var
printDialog : TPrintDialog;
cancelThreadId : Integer;
threadId : LongWord;
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
// Start a cancel print dilaog as a separate thread!
cancelThreadId := beginThread(nil,
0,
Addr(CancelDialog),
nil,
0,
threadId);

// 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
// Show a message saying we are starting a page
ShowMessagePos('Starting to print page '+IntToStr(page),300,300);

// Set up a medium sized font

Printer.Canvas.Font.Size := 10;

// Allow Windows to keep processing messages

Application.ProcessMessages;

// Write out the page number

Printer.Canvas.Font.Color := clBlue;
 Printer.Canvas.TextOut(40, 20, 'Page number = '+IntToStr(page));

// Underline this page number

Printer.Canvas.MoveTo(40,80);
Printer.Canvas.LineTo(Printer.PageWidth-20,80);

// Write out the page size

Printer.Canvas.Font.Color := clRed;
Printer.Canvas.TextOut(40, 100, 'Page width = '+
IntToStr(Printer.PageWidth));
Printer.Canvas.TextOut(40, 180, 'Page height = '+
IntToStr(Printer.PageHeight));

// 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;

end.