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.