diff options
Diffstat (limited to 'bin/reportlab/docs/userguide/ch3_pdffeatures.py')
| -rw-r--r-- | bin/reportlab/docs/userguide/ch3_pdffeatures.py | 271 |
1 files changed, 271 insertions, 0 deletions
diff --git a/bin/reportlab/docs/userguide/ch3_pdffeatures.py b/bin/reportlab/docs/userguide/ch3_pdffeatures.py new file mode 100644 index 00000000000..36fe8b8be07 --- /dev/null +++ b/bin/reportlab/docs/userguide/ch3_pdffeatures.py @@ -0,0 +1,271 @@ +#Copyright ReportLab Europe Ltd. 2000-2004 +#see license.txt for license details +#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch3_pdffeatures.py +from reportlab.tools.docco.rl_doc_utils import * + + +heading1("Exposing PDF Special Capabilities") +disc("""PDF provides a number of features to make electronic + document viewing more efficient and comfortable, and + our library exposes a number of these.""") + +heading2("Forms") +disc("""The Form feature lets you create a block of graphics and text + once near the start of a PDF file, and then simply refer to it on + subsequent pages. If you are dealing with a run of 5000 repetitive + business forms - for example, one-page invoices or payslips - you + only need to store the backdrop once and simply draw the changing + text on each page. Used correctly, forms can dramatically cut + file size and production time, and apparently even speed things + up on the printer. + """) +disc("""Forms do not need to refer to a whole page; anything which + might be repeated often should be placed in a form.""") +disc("""The example below shows the basic sequence used. A real + program would probably define the forms up front and refer to + them from another location.""") + + +eg(examples.testforms) + +heading2("Links and Destinations") +disc("""PDF supports internal hyperlinks. There is a very wide + range of link types, destination types and events which + can be triggered by a click. At the moment we just + support the basic ability to jump from one part of a document + to another, and to control the zoom level of the window after + the jump. The bookmarkPage method defines a destination that + is the endpoint of a jump.""") +#todo("code example here...") + +eg(""" + canvas.bookmarkPage(name, + fitType="Fit", + left=None, + top=None, + bottom=None, + right=None, + zoom=None + ) +""") +disc(""" +By default the $bookmarkPage$ method defines the page itself as the +destination. After jumping to an endpoint defined by bookmarkPage, +the PDF browser will display the whole page, scaling it to fit the +screen:""") + +eg("""canvas.bookmarkPage(name)""") + +disc("""The $bookmarkPage$ method can be instructed to display the +page in a number of different ways by providing a $fitType$ +parameter.""") + +eg("") + +t = Table([ + ['fitType','Parameters Required','Meaning'], + ['Fit',None,'Entire page fits in window (the default)'], + ['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'], + ['XYZ','left top zoom','Fine grained control. If you omit a parameter\nthe PDF browser interprets it as "leave as is"'] + ]) +t.setStyle(TableStyle([ + ('FONT',(0,0),(-1,1),'Times-Bold',10,12), + ('VALIGN',(0,0),(-1,-1),'MIDDLE'), + ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black), + ('BOX', (0,0), (-1,-1), 0.25, colors.black), + ])) + +getStory().append(t) +caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Required attributes for different fit types""") + +disc(""" +Note : $fitType$ settings are case-sensitive so $fitType="FIT"$ is invalid$ +""") + + +disc(""" +Sometimes you want the destination of a jump to be some part of a page. +The $FitR$ fitType allows you to identify a particular rectangle, scaling +the area to fit the entire page. +""") + +disc(""" +To set the display to a particular x and y coordinate of the page and to +control the zoom directly use fitType="XYZ". +""") + +eg(""" +canvas.bookmarkPage('my_bookmark',fitType="XYZ",left=0,top=200) +""") + + + +disc(""" +This destination is at the leftmost of the page with the top of the screen +at position 200. Because $zoom$ was not set the zoom remains at whatever the +user had it set to. +""") + +eg(""" +canvas.bookmarkPage('my_bookmark',fitType="XYZ",left=0,top=200,zoom=2) +""") + +disc("""This time zoom is set to expand the page 2X its normal size.""") + +disc(""" +Note : Both $XYZ$ and $FitR$ fitTypes require that their positional parameters +($top, bottom, left, right$) be specified in terms of the default user space. +They ignore any geometric transform in effect in the canvas graphic state. +""") + + + +pencilnote() + +disc(""" +<i>Note:</i> Two previous bookmark methods are supported but deprecated now +that bookmarkPage is so general. These are $bookmarkHorizontalAbsolute$ +and $bookmarkHorizontal$. +""") + +heading3("Defining internal links") +eg(""" + canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw) + """) + +disc(""" + The $linkAbsolute$ method defines a starting point for a jump. When the user + is browsing the generated document using a dynamic viewer (such as Acrobat Reader) + when the mouse is clicked when the pointer is within the rectangle specified + by $Rect$ the viewer will jump to the endpoint associated with $destinationname$. + As in the case with $bookmarkHorizontalAbsolute$ the rectangle $Rect$ must be + specified in terms of the default user space. The $contents$ parameter specifies + a chunk of text which displays in the viewer if the user left-clicks on the region. +""") + +disc(""" +The rectangle $Rect$ must be specified in terms of a tuple ^(x1,y1,x2,y2)^ identifying +the lower left and upper right points of the rectangle in default user space. +""") + +disc(""" +For example the code +""") + +eg(""" + canvas.bookmarkPage("Meaning_of_life") +""") + +disc(""" +defines a location as the whole of the current page with the identifier +$Meaning_of_life$. To create a rectangular link to it while drawing a possibly +different page, we would use this code: +""") + +eg(""" + canvas.linkAbsolute("Find the Meaning of Life", "Meaning_of_life", + (inch, inch, 6*inch, 2*inch)) +""") + +disc(""" +By default during interactive viewing a rectangle appears around the +link. Use the keyword argument $Border='[0 0 0]'$ to +suppress the visible rectangle around the during viewing link. +For example +""") + +eg(""" + canvas.linkAbsolute("Meaning of Life", "Meaning_of_life", + (inch, inch, 6*inch, 2*inch), Border='[0 0 0]') +""") + + +heading2("Outline Trees") +disc("""Acrobat Reader has a navigation page which can hold a + document outline; it should normally be visible when you + open this guide. We provide some simple methods to add + outline entries. Typically, a program to make a document + (such as this user guide) will call the method + $canvas.addOutlineEntry(^self, title, key, level=0, + closed=None^)$ as it reaches each heading in the document. + """) + +disc("""^title^ is the caption which will be displayed in + the left pane. The ^key^ must be a string which is + unique within the document and which names a bookmark, + as with the hyperlinks. The ^level^ is zero - the + uppermost level - unless otherwise specified, and + it is an error to go down more than one level at a time + (for example to follow a level 0 heading by a level 2 + heading). Finally, the ^closed^ argument specifies + whether the node in the outline pane is closed + or opened by default.""") + +disc("""The snippet below is taken from the document template + that formats this user guide. A central processor looks + at each paragraph in turn, and makes a new outline entry + when a new chapter occurs, taking the chapter heading text + as the caption text. The key is obtained from the + chapter number (not shown here), so Chapter 2 has the + key 'ch2'. The bookmark to which the + outline entry points aims at the whole page, but it could + as easily have been an individual paragraph. + """) + +eg(""" +#abridged code from our document template +if paragraph.style == 'Heading1': + self.chapter = paragraph.getPlainText() + key = 'ch%d' % self.chapterNo + self.canv.bookmarkPage(key) + self.canv.addOutlineEntry(paragraph.getPlainText(), + key, 0, 0) + """) + +heading2("Page Transition Effects") + + +eg(""" + canvas.setPageTransition(self, effectname=None, duration=1, + direction=0,dimension='H',motion='I') + """) + +disc(""" +The $setPageTransition$ method specifies how one page will be replaced with +the next. By setting the page transition effect to "dissolve" for example +the current page will appear to melt away when it is replaced by the next +page during interactive viewing. These effects are useful in spicing up +slide presentations, among other places. +Please see the reference manual for more detail on how to use this method. +""") + +heading2("Internal File Annotations") + +eg(""" + canvas.setAuthor(name) + canvas.setTitle(title) + canvas.setSubject(subj) + """) + +disc(""" +These methods have no automatically seen visible effect on the document. +They add internal annotations to the document. These annotations can be +viewed using the "Document Info" menu item of the browser and they also can +be used as a simple standard way of providing basic information about the +document to archiving software which need not parse the entire +file. To find the annotations view the $*.pdf$ output file using a standard +text editor (such as $notepad$ on MS/Windows or $vi$ or $emacs$ on unix) and look +for the string $/Author$ in the file contents. +""") + +eg(examples.testannotations) + +disc(""" +If you want the subject, title, and author to automatically display +in the document when viewed and printed you must paint them onto the +document like any other text. +""") + +illust(examples.annotations, "Setting document internal annotations") |