NAME

Wx::PdfDocument - wxPerl wrapper for the wxPdfDocument classes.

SYNOPSYS

    use Wx::PdfDocument;
    use Wx wq( :pdfdocument );
    
    my $pdfdoc = Wx::PlPdfDocument->new;
    
    ....
    
    my $pdfdoc2 = MyDocClass->new();
    
    ....
    
    package MyDocClass;
    use strict;
    use warnings;
    use Wx::PdfDocument;
    use Wx wq( :pdfdocument );
    use base qw( Wx::PlPdfDocument );
    
    sub new { shift->SUPER::new( @_ ); }
    
    # optionally override virtuals
    
    sub Header { .... }
    sub Footer { .... }
    sub AcceptPageBreak { .... }
    

DESCRIPTION

Wx::PdfDocument is a wrapper for the wxPdfDocument wxcode classes for the wxWidgets GUI toolkit. Wx::PdfDocument allows you to create PDF documents directly using Wx::PlPdfDocument methods either directly or in a derivied class. It also provides classes for the wxWidgets printing framework that allow you to print output to a PDF document using any Wx::Printout class. For example, you can print the output of Wx::RichTextPrintout and Wx::HtmlPrintout in addition to any custom Wx::Printout that you may create.

A module is provided in this distribtion for Wx::Demo that gives extensive examples of usage.

Wx::PlPdfDocument

For creating PDF documents with your own code, this may be the only class you will need to use. You can either us the class directly or create a derived class and optionally override the following virtual methods.

    Footer();
    Header();
    AcceptPageBreak();

The interface is fully described at the wxPdfDocument documentation site.

http://wxcode.sourceforge.net/docs/wxpdfdoc/classwx_pdf_document.html

As is the normal practice for wxPerl implementations, where the C++ documentation indicates any type of an array parameter, you should pass a reference to a Perl array containing the appropriate types or objects.

A small number of methods cannot be implemented exactly as they are implemented in C++. The wxPerl implementation for these methods is noted below:

GetTemplateBBox
    my($x, $y, $width, $height) = $pdfdoc->GetTemplateBBox($templateId);
GetTemplateSize
    my($newWidth, $newHeight) = $pdfdoc->GetTemplateSize($templateId, $oldWidth, $oldHeight);

Wx::PdfDC

The distribution provides a Wx::DC class that you can use to write a PDF document using the standard Wx::PrinterDC commands.

    my $pdata = Wx::PrintData->new;
    $pdata->SetFilename('somefilename.pdf');
    $pdata->SetPaperId(wxPAPER_A4);
    $pdata->SetOrientation(wxPORTRAIT);
    my $dc = Wx::PdfDC->new( $pdata );
    $dc->StartDoc;
    $dc->StartPage;
    ... do drawing / writing
    $dc->EndPage;
    $dc->EndDoc;

The interface is described at the wxPdfDocument documentation site but is a near complete implementation of Wx::DC.

http://wxcode.sourceforge.net/docs/wxpdfdoc/classwx_pdf_d_c.html

wxWidgets Printing Framework

Classes are provided that allow you to use Wx::PdfDocument with existing wxWidgets classes in the manner of a PDF printer.

For example, with Wx::RichextPrintout

    my $printdata;
    my $dialogdata = Wx::PageSetupDialogData->new;
    $dialogdata->SetMarginTopLeft([25,25]);
    $dialogdata->SetMarginBottomRight([25,25]);
    $dialogdata->EnableMargins(1);
    $dialogdata->EnablePaper(1);
    $dialogdata->EnableOrientation(1);
    my $dialog = Wx::PdfPageSetupDialog->new($self, $dialogdata);
    if($dialog->ShowModal == wxID_OK ) {
        $dialogdata = $dialog->GetPageSetupDialogData;
        $printdata  = Wx::PdfPrintData->new($dialogdata->GetPrintData);
    }
    $dialog->Destroy;
    return unless $printdata;
    
    my $printbuffer = Wx::RichTextBuffer->new($self->{richtext}->GetBuffer);
    my $printprintout = Wx::RichTextPrintout->new("Demo RichText PDF Printing");
    
    $printprintout->SetMargins(
                      10 * $dialogdata->GetMarginTopLeft->y,
                      10 * $dialogdata->GetMarginBottomRight->y,
                      10 * $dialogdata->GetMarginTopLeft->x,
                      10 * $dialogdata->GetMarginBottomRight->x
                      );
    $printprintout->SetRichTextBuffer($printbuffer);
    
    my $previewbuffer = Wx::RichTextBuffer->new($self->{richtext}->GetBuffer);
    my $previewprintout = Wx::RichTextPrintout->new("Demo RichText PDF Preview");
    
    $previewprintout->SetMargins(
                      10 * $dialogdata->GetMarginTopLeft->y,
                      10 * $dialogdata->GetMarginBottomRight->y,
                      10 * $dialogdata->GetMarginTopLeft->x,
                      10 * $dialogdata->GetMarginBottomRight->x
                      );
    $previewprintout->SetRichTextBuffer($previewbuffer);
    
    # Printouts do not take ownership of buffers so the
    # wxWidgets buffers will be deleted along with our Perl
    # objects. The preview frame is not a modal dialog.
    $self->{storerichtextbuffers} = [ $printbuffer, $previewbuffer ];
    
    my $printpreview = Wx::PdfPrintPreview->new( $previewprintout, $printprintout, $printdata);
    
    my $frame = Wx::PreviewFrame->new( $printpreview, $self,
                                     "PDF RichText Printing Preview", [-1, -1], [600, 600] );
    $frame->Initialize();
    $frame->Show( 1 );

Wx::PdfPageSetupDialog

This page setup dialog allows you to collect settings for margins, paper type and orientation from the user. It uses the standard Wx::PageSetupDialogData that you can use to determine which of the three settings; margins, paper and orientation, will be available to the user to change.

    # get margins and paper but don't let user
    # change orientation
    my $printdata;
    my $dialogdata = Wx::PageSetupDialogData->new;
    $dialogdata->SetMarginTopLeft([25,25]);
    $dialogdata->SetMarginBottomRight([25,25]);
    $dialogdata->EnableMargins(1);
    $dialogdata->EnablePaper(1);
    $dialogdata->EnableOrientation(0);
    $dialogdata->GetPrintData->SetOrientation(&Wx::wxLANDSCAPE);
    my $dialog = Wx::PdfPageSetupDialog->new($self, $dialogdata);
    if($dialog->ShowModal == wxID_OK ) {
        $dialogdata = $dialog->GetPageSetupDialogData;
        $printdata  = $dialogdata->GetPrintData;
    }
    $dialog->Destroy;

Wx::PdfPrintDialog

This print dialog takes the place of the standard printer setup dialog when using the wxWidgets printing framework. It is shown by default when using Wx::PdfPrinter and Wx::PdfPrintPreview and you may also create a dialog yourself to collect user input.

The dialog allows the user to set document properties such as title and subject, choose the output filename and whether to launch the output in a PDF viewer. It also allows setting encryption and document passord options.

You can control which of the options are available to the user by passing a Wx::PdfPrintData object in the constructor with appropropriate settings.

    # all options available
    my $printdata = Wx::PdfPrintData->new;
    my $dialog = Wx::PdfPrintDialog->new($self, $printdata);
    if($dialog->ShowModal == wxID_OK ) {
        $printdata  = $dialog->GetPdfPrintData;
    }
    $dialog->Destroy;
    ...
    # limit options to filepath and launch viewer
    my $printdata = Wx::PdfPrintData->new;
    $printdata->SetPrintDialogFlags( wxPDF_PRINTDIALOG_OPENDOC|wxPDF_PRINTDIALOG_FILEPATH );
    ## check launch doc CheckBox by default
    $printdata->SetLaunchDocumentViewer(1);
    my $dialog = Wx::PdfPrintDialog->new($self, $printdata);
    if($dialog->ShowModal == wxID_OK ) {
        $printdata  = $dialog->GetPdfPrintData;
        Wx::LogMessage('Selected filepath : %s', $printdata->GetFilename);
    }
    $dialog->Destroy;

Wx::PdfPrintData

This class provides most of the custom features for wxPdfPrinting and is the basis for passing options to and from Wx::PdfPrintDialog, Wx::PdfPrinter and Wx::PdfPrintPreview.

Constructors

    my $pdata = Wx::PdfPrintData->new();
    my $pdata = Wx::PdfPrintData->new(<Wx::PdfPrintData>);
    my $pdata = Wx::PdfPrintData->new(<Wx::PrintData>);
    my $pdata = Wx::PdfPrintData->new(<Wx::PrintDialogData>);

PDF Document Properties

Set the output filename and basic paper detail

    $pdata->SetFilename($filename);
    $pdata->SetPaperId(wxPAPER_A4);
    $pdata->SetOrientation(wxPORTRAIT);
    
    $filename = $pdata->GetFilename;
    $paperid = $pdata->GetPaperid;
    $orient = $pdata->GetOrientation;

You can set various PDF Document properties by adding the information to Wx::PdfPrintData

    $pdata->SetDocumentTitle($title);
    $pdata->SetDocumentSubject($subject);
    $pdata->SetDocumentAuthor($author);
    $pdata->SetDocumentKeywords($keywords);
    $pdata->SetDocumentCreator($applicationname);
    
    $title = $pdata->GetDocumentTitle();
    $subject = $pdata->GetDocumentSubject();
    $author = $pdata->GetDocumentAuthor();
    $keywords = $pdata->GetDocumentKeywords();
    $applicationname = $pdata->GetDocumentCreator();

Document Protection

see wxPdfDocument::SetProtection described at

http://wxcode.sourceforge.net/docs/wxpdfdoc/classwx_pdf_document.html

Normally you should collect the options for document protection via the Wx::PdfPrintDialog and let the Wx::PdfPrinter class apply these options for you. To set and apply options directly yourself to a PDF document it is better to call Wx::PdfDocument methods directly.

The following methods of Wx::PdfPrintData are used internally by the Wx::PdfPrinter

    $pdata->SetDocumentProtection($perms, $userpwd, $ownpwd, $cryptm, $keylen);
    
    # Apply document protection and Title, Subject, etc.
    $pdata->UpdateDocument($wx_pdfdocument);

Controlling Dialogs and Printing Process

If you pass a Wx::PdfPrintData instance to the contructor of a Wx::PdfPrinter, Wx::PdfPrintDialog or Wx::PdfPrintPreview object you can control the printing process and dialog options that will be available to the user

    $flags = $pdata->GetPrintDialogFlags();
    $pdata->SetPrintDialogFlags($flags);

$flags is a or'd combination of

    wxPDF_PRINTDIALOG_FILEPATH
    Allow setting of the output filepath in dialog
    
    wxPDF_PRINTDIALOG_PROPERTIES
    Allow setting of document properties (Title, Author, Subject, Keywords) in dialog

    wxPDF_PRINTDIALOG_PROTECTION
    Allow setting of protection options in dialog

    wxPDF_PRINTDIALOG_OPENDOC
    Show the "Launch document in default viewer" checkbox

    wxPDF_PRINTDIALOG_ALLOWNONE
    Allow no settings in dialog

    wxPDF_PRINTDIALOG_ALLOWALL
    Allow all settings in dialog

Set the default value for the "Launch document in default viewer" checkbox

    $bool = $pdata->GetLaunchDocumentViewer();
    $pdata->SetLaunchDocumentViewer($bool);

Although not particularly useful when outputting a PDF document, you can set pages to print in the Wx::PdfPrintData in the same manner as Wx::PrintDialogData

    $pagenum = $pdata->GetFromPage();
    $pagenum = $pdata->GetToPage();
    $pagenum = $pdata->GetMinPage();
    $pagenum = $pdata->GetMaxPage();
    $pdata->SetFromPage($pagenum);
    $pdata->SetToPage($pagenum);
    $pdata->SetMinPage($pagenum);
    $pdata->SetMaxPage($pagenum);

By default, the Wx::PdfPrinter sets up a Wx::PdfDC with a resolution of 600 pixels. perl inch. It does not make any difference to the output quality what you set the resolution to. The PDF format is not pixel based so it is simply a matter of coordinate conversion. However, the Wx::DC drawing functions are integer based and so always introduce rounding and truncation when coordinates are transformed. Therefore, the lower the resolution, the bigger the error you may experience. For example, truncating 600.49 to 600 on a virtual 600 dpi device is a much smaller error that truncating 72.49 to 72 on a virtual 72 dpi device. So you probably don't want to change the resolution defaults.

    $dpi = $pdata->GetPrintResolution();
    $pdata->SetPrintResolution($dpi);

Setting Template Mode

By default a Wx::PdfDC instance creates a Wx::PdfDocument and outputs the result. The Wx::PdfDC can also operate in 'template mode' where an existing Wx::PdfDocument instance is passed to the constructor. This can be useful to combine the text methods of Wx::PdfDocument with the graphics methods of Wx::PdfDC. In this mode, the StartDoc and EndDoc methods of the Wx::PdfDC have no effect. The Wx::PdfDocument is created outside the Wx::PdfDC instance and code must handle writing it to disk independently too.

To allow template mode to be used within the wxWidgets printing framework (perhaps you have a custom Wx::Printout instance designed to handle enhanced PDF features) you can set the template parameters in a Wx::PdfPrintData instance that gets passed to Wx::PdfPrinter or Wx::PdfPrintPreview.

    $pdata->SetTemplate( $wxpdfdocument, $width, $height );
    $pdfdoc =  $pdata->GetTemplateDocument();
    $width  =  $pdata->GetTemplateWidth();
    $height =  $pdata->GetTemplateHeight();
    
    # check if SetTemplate has been called
    $bool   =  $pdata->GetTemplateMode();

Wx::PdfPrintPreview

A drop in for Wx::PrintPreview used in exactly the same way accepting a Wx::PdfPrintData instance in its constructor.

    my $preview = Wx::PdfPrintPreview->new(
              $previewprintout,
              $printprintout,
              $wxPdfPrintData);
    
    my $frame = Wx::PreviewFrame->new( $printpreview, $self,
            "PDF Printing Preview", [-1, -1], [600, 600] );
    $frame->Initialize();
    $frame->Show( 1 );

There are complete examples in the Wx::Demo demomodule provided with the distribution.

Wx::PdfPrinter

A drop in for Wx::Printer used in exactly the same way accepting a Wx::PdfPrintData instance in its constructor.

    my $printer = Wx::PdfPrinter->new($wxPdfPrintData);
    $printer->Print($parent, $wxPrintout, 1);

There are complete examples in the Wx::Demo demomodule provided with the distribution.

makefont and showfont

An interface is provided for calling the makefont and showfont utilities provided with wxPdfDocument. This is necessary to add the wxWidgets and wxPdfDocument libraries in your Perl installation to the appropriate LD_LIBRARY_PATH, DYLD_LIBRARY_PATH and PATH for your operating system and to set the font file location environment variables.

    my ($status, $stdout, $stderr) = Wx::PdfDocument::MakeFont( $makefontparams );
    my ($status, $stdout, $stderr) = Wx::PdfDocument::ShowFont( $showfontparams );

see

makefont http://wxcode.sourceforge.net/docs/wxpdfdoc/makefont.html

showfont http://wxcode.sourceforge.net/docs/wxpdfdoc/showfont.html

Launching a PDF Document Viewer

Wx::PdfDocument provides a static method that will query the system for the correct command to view a pdf document:

    Wx::PdfDocument::LaunchPdfViewer($pdffilepath);

See Also

http://www.wxwidgets.org

http://wxperl.sourceforge.net

http://wxcode.sourceforge.net/docs/wxpdfdoc/

RELEASE NOTES

This 0.10 release builds wxPdfDocument 0.9.3 code with minor changes to Windows makefiles to allow building in the Perl / wxPerl environment. All applied patches are in the patches subfolder of the distribution.

COPYRIGHT AND LICENSE

Copyright (C) 2006 & 2012 by Mark Wardell

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.12 or, at your option, any later version of Perl 5 you may have available.

The wxPdfDocument C++ class was created by Ulrich Telle <ulrich.telle@gmx.de>