GMPRINTSUITE REPORT & PRINT PREVIEW

COMPONENTS

TUTORIAL 1

GETTING STARTED WITH TGMPREVIEW

graham@murtsoft.com
GmPrintSuite Tutorial Tutorial 1

Contents
Contents.................................................................................................................................................................. 2

What is GmPrintSuite............................................................................................................................................. 3

“Hello World” Example ......................................................................................................................................... 3

“Hello World” Example Explained................................................................................................................... 5

Adding Pages to the TGmPreview.......................................................................................................................... 7

“Adding Pages” Example Explained ................................................................................................................ 9

Adding a “Page x of y” Label............................................................................................................................... 10

Changing the Font, Brush & Pen.......................................................................................................................... 11

Working with Different Units of Measurement.................................................................................................... 12

Headers & Footers ................................................................................................................................................ 13

Using “Tokens” in TGmPreview.......................................................................................................................... 13

A Header & Footer Example Using Tokens ......................................................................................................... 14

Tutorial Summary................................................................................................................................................. 17

Self Study ............................................................................................................................................................. 17

www.murtsoft.com Page 2 of 17
GmPrintSuite Tutorial Tutorial 1

What is GmPrintSuite

GmPrintSuite is a collection of components, which provide the ability to generate & print reports with full
print preview capabilities.

The components included with GmPrintSuite are –

• TGmPreview - Main preview/printing component

• TGmThumbnails - Generates thumbnails for the TGmPreview
• TGmGridPrint - TStringGrid printer
• TGmRtfPreview - Rich text preview and printing
• TGmPrinterList - Printer selection combo-box
• TGmMultipageImage - GmPreview property component
• TGmOrientationImage - GmPreview property component
• TGmLabelPrinter - Label printing component
• TGmTreeViewPrint - TTreeview printing component

In this tutorial we will be focusing on the basics of the TGmPreview component.

“Hello World” Example

TGmPreview is the main component in the GmPrintSuite set and provides the developer with a simple
preview & print interface with a rich set of features.

To demonstrate how easy TGmPreview is to use, the first example takes you, step-by-step, through writing &
printing the words “Hello World” to the preview page.

After the tutorial, each line of the code will be explained to give you a clearer understanding of what is
happening.

www.murtsoft.com Page 3 of 17
GmPrintSuite Tutorial Tutorial 1

STEP 1

Start a new application and drop a

TGmPreview and 2 TButton components
on the form.

Call these buttons “Generate” and

“Print”

STEP 2

In the “Generate” button’s OnClick event, place the following code –

procedure TForm1.btnGenerateClick(Sender: TObject);

begin
GmPreview1.BeginUpdate;
GmPreview1.Canvas.Font.Size := 50;
GmPreview1.Canvas.TextOut(30, 30, 'Hello World', GmMillimeters);
GmPreview1.EndUpdate;
end;

STEP 3

In the “Print” button’s OnClick event, place the following code –

procedure TForm1.btnPrintClick(Sender: TObject);

begin
GmPreview1.Print;
end;

www.murtsoft.com Page 4 of 17
GmPrintSuite Tutorial Tutorial 1

STEP 4

And that’s it!

Run the program and click on the

Generate button. You will see the words
“Hello World” appear on the preview
page.

Clicking on “Print” will send this page to

the printer.

“Hello World” Example Explained

Below is an explaination of the code entered into the 2 button OnClick events.

GmPreview1.BeginUpdate;

This line sets TGmPreview into an Updating state and is required to prevent any unneccessary processing
while you are generating your page(s).

GmPreview1.Canvas.Font.Size := 50;

The TGmPreview has a canvas property like a Tform and it is through this that all drawing takes place.
This line sets the font size for all proceeding text operations to 50pt.

GmPreview1.Canvas.TextOut(30, 30, 'Hello World', GmMillimeters);

This line writes the text “Hello World” to the page.

The first 2 parameters are the X and Y values of the text.

www.murtsoft.com Page 5 of 17
GmPrintSuite Tutorial Tutorial 1

The next parameter specifies the text to output (“Hello World”)

The last parameter specifies the measurement which the X and Y values represent – in this case it’s
millimeters.

GmPreview1.EndUpdate;

This last line brings the TGmPreview out of update mode and updates the on-screen display of the page.

GmPreview1.Print;

This is a simple call which will send all pages in the TGmPreview to the printer.

www.murtsoft.com Page 6 of 17
GmPrintSuite Tutorial Tutorial 1

Adding Pages to the TGmPreview

The majority of reports that you will want to create will not fit on one page, fortunately TGmPreview has a
simple method adding extra pages.

Below is a demo which builds on the “Helo World” example above with the added functionallity of adding extra
pages.
This example also demonstrates how to navigate between pages in the report.

STEP 1

Using the previous “Hello World”

program, add 4 extra buttons to the form
as shown opposite.

• A “Clear” button
• A “New Page” button
• A “Previous Page” button
• A “Next Page” Button

STEP 2

Modify the code in the “Generate” button’s OnClick event as shown below –

procedure TForm1.btnGenerateClick(Sender: TObject);

begin
GmPreview1.BeginUpdate;
GmPreview1.Canvas.Font.Size := 50;
GmPreview1.Canvas.TextOut(30, 30, 'Hello World', GmMillimeters);
Î GmPreview1.Canvas.TextOut(50, 70, 'Page Number:'+
IntToStr(GmPreview1.NumPages), GmMillimeters);
GmPreview1.EndUpdate;
end;

www.murtsoft.com Page 7 of 17
GmPrintSuite Tutorial Tutorial 1

STEP 3

Now in the OnClick events for the 4 new buttons add the following code…

(the “New Page” button)

procedure TForm1.btnNewPageClick(Sender: TObject);
begin
GmPreview1.NewPage;
// now call the code for the "Generate" button...
btnGenerate.Click;
end;

(the “Previous Page” button)

procedure TForm1.btnPrevPageClick(Sender: TObject);
begin
GmPreview1.PrevPage;
end;

(the “Next Page” button)

procedure TForm1.btnNextPageClick(Sender: TObject);
begin
GmPreview1.NextPage;
end;

(the “Clear” button)

procedure TForm1.btnClearClick(Sender: TObject);
begin
GmPreview1.Clear;
end;

STEP 4

Now run the program and click on “Generate”

as before.

Click on the “New Page” button and you’ll

see that a page is added to the preview.

You can navigate between the pages using the

“Previous” & “Next” page buttons.

Clicking on “Clear” clears all of the pages.

www.murtsoft.com Page 8 of 17
GmPrintSuite Tutorial Tutorial 1

“Adding Pages” Example Explained

Below is an explaination extra code added to the original “Hello World” example.

GmPreview1.Canvas.TextOut(50, 70, 'Page Number:'+ IntToStr(GmPreview1.NumPages),

GmMillimeters);

This line adds an extra piece of text to each page which displays the page number.

GmPreview1.NewPage;
// now call the code for the "Generate" button...
btnGenerate.Click;

Here, a new page is added to the TGmPreview, then the code in the “Generate” button is called to perform
the drawing of the text to the new page.

GmPreview1.PrevPage;
&
GmPreview1.NextPage

These methods jump to, either the previous page or the next page of the report.

GmPreview1.Clear;

This clears all pages which exist so that only 1 blank page is left.

www.murtsoft.com Page 9 of 17
GmPrintSuite Tutorial Tutorial 1

Adding a “Page x of y” Label

In the real world, it is unlikely that you will have a large caption on the preview page telling you what the
current page number is, therefore, a good idea is to link the preview to a TLabel component which will tell us
the current page and also the total pages.

STEP 1

Add a TLabel component to the form,

between the “Previous” & “Next”
navigation buttons.

Set it’s caption to “Page 1 of 1”

STEP 3

In the TGmPreview’s OnPageChange event, place the following code –

procedure TForm1.GmPreview1PageChange(Sender: TObject; PageNum: Integer);

begin
lblPageCaption.Caption := Format('Page: %d of %d', [PageNum, GmPreview1.NumPages]);
end;

STEP 4

Now run the program again. You will

see that as you add new pages and
navigate through existing pages, the label
caption is updated accordingly.

www.murtsoft.com Page 10 of 17
GmPrintSuite Tutorial Tutorial 1

Changing the Font, Brush & Pen

If you are familiar to the TCanvas object, (for example – TForm.Canvas), then this next section should be easy
to understand as it uses the same principles.
The canvas is the name given to the surface on which we draw text and shapes.
Shapes and Text are drawn to the Canvas using the values of the canvas’ Font, Brush & Pen which represent
the standard TFont, TBrush, and TPen Delphi objects.

Modify the code from the previous example so that it includes the extra lines below –

procedure TForm1.btnGenerateClick(Sender: TObject);

begin
GmPreview1.BeginUpdate;
GmPreview1.Canvas.Font.Size := 50;
Î GmPreview1.Canvas.Font.Style := [fsBold];
Î GmPreview1.Canvas.Font.Color := clRed;
GmPreview1.Canvas.TextOut(30, 30, 'Hello World', GmMillimeters);
Î GmPreview1.Canvas.Font.Color := clBlue;
GmPreview1.Canvas.TextOut(50, 70, 'Page Number:'+
IntToStr(GmPreview1.NumPages), GmMillimeters);
GmPreview1.EndUpdate;
end;

Change the font size, styles & colors and observe the effects in the preview.
The Pen property will be introduced a bit later as it deals with shapes rather than text.

www.murtsoft.com Page 11 of 17
GmPrintSuite Tutorial Tutorial 1

Working with Different Units of Measurement

One of the key features which makes the TGmPreview component so flexible is the wide range of
measurements with which it can operate.
So far in each of the above examples we have only used Millimeters although the following measurements
are also supported –

MEASUREMENT TGMPREVIEW REPRESENTATION

Inches GmInches
Centimeters GmCentimeters
Millimeters GmMillimeters
Pixels GmPixels
GmUnits (1/100 mm) GmUnits
Twips (1/1440 inch) GmTwips

The way in which these measurements are used is identical to the “GmMillimeters” parameter we have used
in the above examples.
For example, the “Hello World” caption is currently drawn at an (x,y)of (30mm x 30mm). If we wanted to
draw this text at an (x,y) of (1 inch x 2 inch) we would modify the code so that it looked like this –
GmPreview1.Canvas.TextOut(1, 2, 'Hello World', GmInches);

Or possibly we wanted to use centimeters instead and draw the text at (10 x 15) centimers –
GmPreview1.Canvas.TextOut(10, 15, 'Hello World', GmCentimeters);

It really is as simple as that. Wherever you can use one of the measurements, you can use them all and this
applies not only for text but for all drawing methods including drawing Graphics, Shapes & Lines.

www.murtsoft.com Page 12 of 17
GmPrintSuite Tutorial Tutorial 1

Headers & Footers

TGmPreview has the ability to draw a header and/or footer on each generated page.

Headers and Footers can each contain 3 pieces of text, a left aligned, a center aligned and a right-aligned
caption. Each of these captions can be written using a different font size/style/colour etc…

The header and footer properties can be set at

design-time through the object inspector.

The header and footer are identical in structure

and their properties are shown in the opposite
screen image of the object inspector. Footer
Properties
If you expand the “Caption” properties you will
see that there is a “Font” and “Caption”
property associated with each.
This allows you to set 3 different captions in 3 Header
different font styles. Properties

The “ShowLine” property determines whether

to draw a line below the header (or above the
footer). This horizontal line is drawn using the
“Pen” property.

Finally, the “Visible” property determines whether the Header/Footer is shown at all.

Using “Tokens” in TGmPreview

The TGmPreview component allows the use of certain text tags called “Tokens” within headers and footers
(and in page text for that matter) which are replaced with their represented values at the time of generating
the report.

The tokens available to use are –

• {DATE} - This is replaced with the current date.
• {TIME} - This is replaced with the current time.
• {PAGE} - This is replaced with the page number.
• {NUMPAGES} - This is replaced with the number of pages in the report.

www.murtsoft.com Page 13 of 17
GmPrintSuite Tutorial Tutorial 1

Using these tokens, it makes it simple to write, for example, “Page # of #” in the page footer (where the #’s
would be replaced with their numerical values)

A Header & Footer Example Using Tokens

Below is an example of setting up a page header and footer using the tokens explained in the previous section.

STEP 1

Drop a TGmPreview component on to a

form and set it’s “Footer” and “Header
properties to True.

You will notice two lines appear on the

preview. The top line is drawn below the
page header and the bottom line is drawn
above the page footer.

Only the lines are drawn because we

haven’t yet set any captions for the
header or footer.

Here I have set the PaperSize to A5 and set the Zoom to 50% so that you will be able to see the page captions
more easily.

STEP 2

Here I have highlighted the two caption entries I

have made in the TGmPreview’s Header section
of the Object Inspector.
Left Caption
The left Caption is set to
Right Caption
“Header & Footer Demo”

The right Caption is set to

“by Graham Murt”

www.murtsoft.com Page 14 of 17
GmPrintSuite Tutorial Tutorial 1

You will notice that as you enter these captions, the TGmPreview component updates itself by adding the
captions to the page.
If you increase the Zoom property you will be able to read the text more clearly which should look like the
below image…

STEP 3

Now we can set the page Footer captions and

make use of the Tokens.

Left Caption
Set the left footer caption to

Right Caption “Printed on: {DATE}”

Set the right footer caption to

“Page: {PAGE} of {NUMPAGES}”

Scroll the preview down to the bottom of the page and you should see that the footer has also updated itself
with the new captions.
Also notice that the tokens have been replaced with their represented values.

www.murtsoft.com Page 15 of 17
GmPrintSuite Tutorial Tutorial 1

STEP 4

Try changing the font’s of the header and footer captions in the object inspector and see the changes updated
in the TGmPreview component with the new fonts.

STEP 5

As in previous examples, add three buttons – “New Page”, “Previous Page” and “Next Page”
The code for each of these buttons is shown again below…

procedure TForm1.btnNewPageClick(Sender: TObject);

begin
GmPreview1.NewPage;
end;

procedure TForm1.btnPrevPageClick(Sender: TObject);

begin
GmPreview1.PrevPage;
end;

procedure TForm1.btnNextPageClick(Sender: TObject);

begin
GmPreview1.NextPage;
end;

STEP 6

Now run the program and click on the “New Page” button several times. As you navigate the pages using the
Previous and Next Page buttons you will notice that the header captions and the left-footer caption remain the
same but the right-footer caption changes from page to page as shown in the below image.

Header Captions and Left-Footer Caption This footer caption is updated from page to
remain the same on all pages. page.

www.murtsoft.com Page 16 of 17
GmPrintSuite Tutorial Tutorial 1

Tutorial Summary

After reading this tutorial and working through the exercises, you should now be aware of the following
TGmPreview functionality…
• Simple text drawing
• Adding pages
• Navigating through the pages using NextPage & PrevPage methods
(you could also include the methods TGmPreview.FirstPage & TGmPreview.LastPage)
• Changing the Canvas Font, Brush & Pen properties.
• Drawing Text using different units of measurement.
• The structure of Headers and Footers
• Using Tokens within Header/Footer captions.

Self Study

Look in the help file under the TGmPreview.Canvas methods. You will see that there are several other text
functions such as “TextOutCenter” and “TextOutRight”. These are extremely similar in structure to the
“TextOut” function we have already used so write a small demo to help familiarise yourselves with these
methods.

There are also a lot of other simple Canvas methods such as Rectangle and Ellipse. Look at their structure and
write a small demo using them. Experiment with changing the Canvas Pen & Brush properties before drawing
the shapes and observe the results in the preview.

www.murtsoft.com Page 17 of 17