Gambas Documentation
Documents

How To Print

To print something in Gambas 3, you have to :

The Printing Process

When running the Print method, a local event-loop is run, and the method returns only when the printing is finished or cancelled.

During this local event-loop, the following events are raised :

You have to implement the draw event. All other events are optional.

The Begin event

This event is raised when the print starts.

You can define the Printer.Count property there if you know how many pages you have to print.

Otherwise, you have to implement the Paginate event to layout your document and compute the page count.

By default, only one page is printed.

The Paginate event

This event is raised so that you can paginate your document in the background.

If you define no event handler, this event will not be raised, and you will have to define the Count property inside the Begin event handler.

Otherwise, if you handle this event, the event handler will be called again and again until you explicitely define the count property.

The Draw event

This event is called once for each page that must be printed.

The current page number is returned by the Printer.Page property.

All drawing is done by using the Paint class.

The End event

This event is raised when the printing process is finished.

How To Draw A Page

Page dimensions

Drawing is done inside a rectangle representing the page with or without the margins. The origin of the rectangle is (0, 0), and the size of the rectangle is (Paint.Width, Paint.Height).

Printing margins

Printers usually cannot print on the entire page, i.e. there is a margin where you cannot print.

The previous rectangle represents the entire page only if the Printer.FullPage property is set. Otherwise these margins are taken into account.

You must take that into account when designing your printing!

I strongly suggest always printing with Printer.FullPage set, and let the user choose its own margins from the borders of the page, so that he gets exactly what he wants.

Absolute coordinates

Instead of using the drawing coordinates, you usually prefer using absolute coordinates in centimeters or millimiters.

To do that, you have to use the Printer.PaperWidth and Printer.PaperHeight properties that return the size of the paper in millimeters.

Then you can use the Paint.Scale method to scale the coordinate system so that every coordinate you specify is now in millimeters: 

Dim MyPrinter As Printer

MyPrinter = New Printer As "MyPrinter"

...

Public Sub MyPrinter_Draw()

  Paint.Scale(Paint.Width / MyPrinter.PaperWidth, Paint.Height / MyPrinter.PaperHeight)
  ...

End

Font size

BEWARE: The font size, as returned by Paint.Font.Size, is an absolute size.

Its unit is the typographic point.

A typographic point is 1/72 of an inch, i.e. about 0,353 mm.

Consequently, if a 10 points font is a good size for drawing text on the screen, it may be too big for the paper: as the printer resolution is far greater than the screen resolution, you usually print things smaller.

BUT: The font size will be modified according to the paint matrix (i.e. if you use Paint.Scale, Paint.Translate, Paint.Rotate...)

There is a printing example provided with Gambas, that shows most of the previous concepts.

A custom sample implementation

There is a sample implementation for graphics-centered applications in Basic considerations and optimized printing for graphics-centered applications.