[reportlab-users] BookmarkPage much expanded - thanks to Ian Sparks

[Andy Robinson]

Iam Sparks sent me a superb patch which I have just committed.
This allows fine grained control of how Acrobat Reader
displays when you jump to a destination, either from an
internal hyperlink or the left outline menu. See docstring
below, or run the new test test_pdfgen_links.py and look
at the resulting PDF file, which is self-evident.

This is probably the first time I have received a patch which
(a) does stuff with PDF internals, (b) had good documentation
to add into the user guide, and (c) a thorough test case.  Ian,
well done on a superb addition and thanks!

- Andy Robinson



    def bookmarkPage(self, key,
                      fitType="Fit",
                      left=None,
                      top=None,
                      bottom=None,
                      right=None,
                      zoom=None
                      ):
        """
        This creates a bookmark to the current page which can
        be referred to with the given key elsewhere.

        PDF offers very fine grained control over how Acrobat
        reader is zoomed when people link to this. The default
        is to keep the user's current zoom settings. the last
        arguments may or may not be needed depending on the
        choice of 'fitType'.
        
        Fit types and the other arguments they use are:
        /XYZ left top zoom - fine grained control.  null
          or zero for any of the parameters means 'leave
          as is', so "0,0,0" will keep the reader's settings.
          NB. Adobe Reader appears to prefer "null" to 0's.
          
        /Fit - entire page fits in window

        /FitH top - top coord at top of window, width scaled
                    to fit.

        /FitV left - left coord at left of window, height
                     scaled to fit
                     
        /FitR left bottom right top - scale window to fit
                                  the specified rectangle

        (question: do we support /FitB, FitBH and /FitBV
        which are hangovers from version 1.1 / Acrobat 3.0?)"""