VCL Controls: The Print Dialog Box

Introduction to Printing

Another operation users perform on a file is to print it. Printing is the ability to render, on paper, the result of a control's contents. This is performed using an external device called a peripheral. To do this, users need access to a printer device. There are two main ways users print a document or file. They can ask the application they are using to send the document directly to a printer, or they can use a dialog box to decide how the printing should be done.

To directly send a document to the printer, you need to make sure that the control, whose value needs to be printed, supports printing. To accommodate the users of such an application, you can provide a menu item or a button they would click. An example of such a button would be . To print, the user can click this button. That is the case when using WordPad; its Standard toolbar is equipped with such a button. With this type of printing, when the user decides to print, the whole document would be printed "as is", in color if the document is colored and if the printer supports colors. If there are more than one printer, the computer would use what is known as the default printer.

If you want users to be able to configure or customize the printing process, Microsoft Windows provides a common dialog box called Print:

The print dialog box allows a user to select a printer if more than one are available. The user can decide either to print the whole document, to print a range of pages, or to print a portion of the document that was previously selected. The user can also decide on the number of copies to print from the document, the range specified, or the selected portion. Furthermore, the user can access the particular characteristics of the selected printer and specify how the printer should perform the job. For example, if the selected printer can print in color and the document is in color but the user wants to print in black and white, she can specify this using the Properties button.

There are various ways you can deal with printing (printing is actually one of the most difficult tasks to program). The first thing you should do is to let the users know that printing is available on your application. This is usually done by providing a menu item called Print or a button on a toolbar with a printer-like bitmap.

The easiest and fastest way to send a document to the printer, if the control that holds the document directly supports printing, is by calling the Print() method. For example, since the TRichEdit class and its associated control the RichEdit support printing, you can simply call the TRichEdit::Print() method. This method takes one argument as the name of the document that needs to be printed. The argument can be the name of the file. If you do not have a specific name, you can type anything or specify an empty string. Here is an example:

//---------------------------------------------------------------------------
void __fastcall TForm1::Button1Click(TObject *Sender)
{
	RichEdit1->Print("Mother and Father");
}
//---------------------------------------------------------------------------

If you want to allow your users to customize or control their printing, you can provide them with the Print dialog box:

In the VCL, the Print dialog box is represented through the TPrintDialog class. To add printing during the design of your application, on the Dialogs property sheet of the Component Palette, you can click the PrintDialog button and click on the form.

If you want to programmatically provide a Print dialog box, you can declare a pointer to TPrintDialog class. The compiler will need to know "who" owns the printer. This can be done as follows:

// Adding a Print dialog box at run time
TPrintDialog *dlgPrint = new TPrintDialog(Form1);

Using a menu item or a toolbar button, you can call the Execute() method of the TPrintDialog class. As a Boolean function, you should first make sure that the user was able to open the Print dialog box, then you can execute printing. Suppose you have a RichEdit control whose content you want to print and suppose you have added a menu item called mnuPrint and a PrintDialog control named PrintDialog1, you can perform printing with the following code:

//---------------------------------------------------------------------------
void __fastcall TForm1::mnuPrintClick(TObject *Sender)
{
	if( PrintDialog1->Execute() )
		RichEdit1->Print("");
}
//---------------------------------------------------------------------------

The TPrintDialog class provides all the options to customize the behavior of the Print dialog box.

One of the first choices people make when printing is whether to print the whole document or just sections of it. By default, the Print dialog box always allows users to print the document completely. This is represented by the All radio button. Most other characteristics of the Print dialog box are not singly set. A particular characteristic usually works in connection with another effect of the same Print dialog box.

When customizing the Print dialog box, you will mostly set its options using the Options property with one or more other related properties. The Options property is a set; this means that it allows you to combine the options you want. If you want users to be able to select a portion of text and print only the selected portion, you must make sure the Selection radio button is available. This is done by setting the poSelection option to true. If you want the dialog box to appear with the Selection radio button selected, you can set the PrintRange property to prSelection. Usually this would not be a standard good idea. If you want this radio button to be selected when the dialog box comes up, you should first make sure that a portion of the document to be printed has been selected. For example, if you are (or the user is) trying to print from a RichEdit control, you can check whether there is already selected text before displaying the dialog box as follows:

//---------------------------------------------------------------------------
void __fastcall TForm1::btnPrinterClick(TObject *Sender)
{
	if( RichEdit1->SelLength )
		PrintDialog1->PrintRange = prSelection;
	else
		PrintDialog1->PrintRange = prAllPages;

	if( PrintDialog1->Execute() )
		RichEdit1->Print("");
}
//---------------------------------------------------------------------------

By default, the range of pages to print from the document is not available to the users. If you want the users to be able to set the range, you can set the poPageNums option to true. Consequently, on a document that has 12 pages, users can print for example pages from 4 through 8.