CLASS:: QPenPrinter
summary:: QPen PDF export and printing of vector graphics
categories:: GUI>Accessories
related:: Classes/Pen

DESCRIPTION::
QPenPrinter allows Pen to operate on a printer device. The graphics can be exported to PDF by using "print to file" as printer device.

CLASSMETHODS::
private:: qtClass


METHOD:: new
Create a new QPenPrinter object.

returns:: an instance of QPenPrinter

METHOD:: print
Convenience function to show a print dialog and print.

argument:: printFunc
A link::Classes/Function:: to be evaluated when the user presses "Print", with the printer object as Pen painter target.
See strong::aPrintFunc:: in link::#-print:: below.

argument:: cancelFunc
An optional link::Classes/Function:: to be evaluated if the user presses "Cancel".


INSTANCEMETHODS::
private:: init

subsection:: Printing

METHOD:: showDialog
Shows a Print Dialog to allow the user to configure the printer object. This is asynchronous and the method will return immediately.
When the user presses the "Print" button, strong::aOkFunc:: is called with this QPenPrinter object as argument.

argument:: aOkFunc
A link::Classes/Function:: to be evaluated when the user presses "Print".

argument:: aCancelFunc
An optional link::Classes/Function:: to be evaluated if the user presses "Cancel".


METHOD:: print
This method does the actual printing or PDF export. It evaluates strong::aPrintFunc:: with the printer object as Pen painter target. This QPenPrinter object is passed as the argument.

All the ordinary link::Classes/Pen:: commands can be used inside the function.

argument:: aPrintFunc
A link::Classes/Function:: to be evaluated to draw the graphics.

discussion::
If this method is called without configuring the printer object first, it will print on the default printer with default settings.

This method is typically called from within the strong::aOkFunc:: of link::#-showDialog:: above. After showDialog has configured the printer once, this method can be called multiple times to reuse the last printer configuration.

The point at (0@0) will coincide with the origin of link::#-pageRect::, which is offset by the page margins. So you don't need to translate the Pen.


METHOD:: newPage
Starts a new page. Typically called within the strong::aPrintFunc:: of link::#-print::.


subsection:: Properties

METHOD:: paperRect
Get the paper bounds.

returns:: a link::Classes/Rect::


METHOD:: pageRect
Get the page bounds, which is the printable area and usually smaller than link::#-paperRect:: due to margins.

returns:: a link::Classes/Rect::

discussion::
The strong::origin:: of the Rect is relative to the paper, and will be non-zero due to margins.


METHOD:: pageSize
Get the page size as a Size.

returns:: a link::Classes/Size::

discussion::
This can be used to scale the graphics to fit the page if the bounds of the graphics is known:
code::
x = penPrinter.pageSize.width / bounds.width;
Pen.scale(x,x);
// ... draw stuff here ...
::

subsection:: Page range
The methods below returns the page range selected by the user. Page number starts at 1. When both methods returns 0 it means "print all pages".

METHOD:: fromPage
Get the start page.

returns:: an link::Classes/Integer::

METHOD:: toPage
Get the end page.

returns:: an link::Classes/Integer::



EXAMPLES::

Simple usage:
code::
QPenPrinter.print {
    // first page
    Pen.moveTo(100@100);
    Pen.lineTo(300@300);
    Pen.stroke;

    // second page
    p.newPage;
    Pen.addRect(p.pageSize.asRect);
    Pen.stroke;
}
::

Keep the QPenPrinter object to save configuration state:
code::
p = QPenPrinter();
::
The code below can then be called multiple times:
code::
p.showDialog {
    p.print {
        // first page
        Pen.moveTo(100@100);
        Pen.lineTo(300@300);
        Pen.stroke;

        // second page
        p.newPage;
        Pen.addRect(p.pageSize.asRect);
        Pen.stroke;
    }
} {
    "Printing cancelled!".postln;
};
::