docs/userguide/ch3_pdffeatures.py
author robin <robin@reportlab.com>
Tue, 07 Mar 2017 10:00:34 +0000
changeset 4330 617ffa6bbdc8
parent 4312 49eee21829a1
child 4370 823a8c33ce43
permissions -rw-r--r--
changes for release 3.4.0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4330
617ffa6bbdc8 changes for release 3.4.0
robin <robin@reportlab.com>
parents: 4312
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2017
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     2
#see license.txt for license details
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     3
#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch3_pdffeatures.py
2966
c9df63ccabdf reportlab-2.2: major changes to make tests run
rgbecker
parents: 2963
diff changeset
     4
from tools.docco.rl_doc_utils import *
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     5
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     6
heading1("Exposing PDF Special Capabilities")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     7
disc("""PDF provides a number of features to make electronic
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     8
    document viewing more efficient and comfortable, and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     9
    our library exposes a number of these.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    10
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    11
heading2("Forms")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    12
disc("""The Form feature lets you create a block of graphics and text
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    13
    once near the start of a PDF file, and then simply refer to it on
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    14
    subsequent pages.  If you are dealing with a run of 5000 repetitive
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    15
    business forms - for example, one-page invoices or payslips - you
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    16
    only need to store the backdrop once and simply draw the changing
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    17
    text on each page.  Used correctly, forms can dramatically cut
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    18
    file size and production time, and apparently even speed things
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    19
    up on the printer.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    20
    """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    21
disc("""Forms do not need to refer to a whole page; anything which
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    22
    might be repeated often should be placed in a form.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    23
disc("""The example below shows the basic sequence used.  A real
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    24
    program would probably define the forms up front and refer to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    25
    them from another location.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    26
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    27
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    28
eg(examples.testforms)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    29
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    30
heading2("Links and Destinations")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    31
disc("""PDF supports internal hyperlinks.  There is a very wide
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    32
    range of link types, destination types and events which
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    33
    can be triggered by a click.  At the moment we just
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    34
    support the basic ability to jump from one part of a document
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    35
    to another, and to control the zoom level of the window after
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    36
    the jump.  The bookmarkPage method defines a destination that
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    37
    is the endpoint of a jump.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    38
#todo("code example here...")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    39
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    40
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    41
    canvas.bookmarkPage(name,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    42
                        fit="Fit",
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    43
                        left=None,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    44
                        top=None,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    45
                        bottom=None,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    46
                        right=None,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    47
                        zoom=None
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    48
                        )
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    49
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    50
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    51
By default the $bookmarkPage$ method defines the page itself as the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    52
destination. After jumping to an endpoint defined by bookmarkPage,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    53
the PDF browser will display the whole page, scaling it to fit the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    54
screen:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    55
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    56
eg("""canvas.bookmarkPage(name)""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    57
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    58
disc("""The $bookmarkPage$ method can be instructed to display the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    59
page in a number of different ways by providing a $fit$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    60
parameter.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    61
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    62
eg("")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    63
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    64
t = Table([
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    65
           ['fit','Parameters Required','Meaning'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    66
           ['Fit',None,'Entire page fits in window (the default)'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    67
           ['FitH','top','Top coord at top of window, width scaled to fit'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    68
           ['FitV','left','Left coord at left of window, height scaled to fit'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    69
           ['FitR','left bottom right top','Scale window to fit the specified rectangle'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    70
           ['XYZ','left top zoom','Fine grained control. If you omit a parameter\nthe PDF browser interprets it as "leave as is"']
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    71
          ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    72
t.setStyle(TableStyle([
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    73
            ('FONT',(0,0),(-1,1),'Times-Bold',10,12),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    74
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    75
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    76
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    77
            ]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    78
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    79
getStory().append(t)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    80
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Required attributes for different fit types""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    81
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    82
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    83
Note : $fit$ settings are case-sensitive so $fit="FIT"$ is invalid
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    84
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    85
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    86
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    87
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    88
Sometimes you want the destination of a jump to be some part of a page.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    89
The $FitR$ fit allows you to identify a particular rectangle, scaling
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    90
the area to fit the entire page.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    91
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    92
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    93
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    94
To set the display to a particular x and y coordinate of the page and to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    95
control the zoom directly use fit="XYZ".
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    96
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    97
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    98
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    99
canvas.bookmarkPage('my_bookmark',fit="XYZ",left=0,top=200)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   100
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   101
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   102
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   103
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   104
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   105
This destination is at the leftmost of the page with the top of the screen
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   106
at position 200. Because $zoom$ was not set the zoom remains at whatever the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   107
user had it set to.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   108
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   109
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   110
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   111
canvas.bookmarkPage('my_bookmark',fit="XYZ",left=0,top=200,zoom=2)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   112
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   113
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   114
disc("""This time zoom is set to expand the page 2X its normal size.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   115
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   116
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   117
Note  : Both $XYZ$ and $FitR$ fit types require that their positional parameters
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   118
($top, bottom, left, right$) be specified in terms of the default user space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   119
They ignore any geometric transform in effect in the canvas graphic state.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   120
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   121
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   122
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   123
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   124
pencilnote()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   125
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   126
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   127
<i>Note:</i> Two previous bookmark methods are supported but deprecated now
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   128
that bookmarkPage is so general.  These are $bookmarkHorizontalAbsolute$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   129
and $bookmarkHorizontal$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   130
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   131
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   132
heading3("Defining internal links")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   133
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   134
 canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, 
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   135
 thickness=0, color=None, dashArray=None, **kw)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   136
 """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   137
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   138
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   139
    The $linkAbsolute$ method defines a starting point for a jump.  When the user
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   140
    is browsing the generated document using a dynamic viewer (such as Acrobat Reader)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   141
    when the mouse is clicked when the pointer is within the rectangle specified
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   142
    by $Rect$ the viewer will jump to the endpoint associated with $destinationname$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   143
    As in the case with $bookmarkHorizontalAbsolute$ the rectangle $Rect$ must be
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   144
    specified in terms of the default user space.  The $contents$ parameter specifies
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   145
    a chunk of text which displays in the viewer if the user left-clicks on the region.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   146
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   147
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   148
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   149
The rectangle $Rect$ must be specified in terms of a tuple ^(x1,y1,x2,y2)^ identifying
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   150
the lower left and upper right points of the rectangle in default user space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   151
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   152
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   153
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   154
For example the code
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   155
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   156
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   157
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   158
    canvas.bookmarkPage("Meaning_of_life")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   159
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   160
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   161
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   162
defines a location as the whole of the current page with the identifier
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   163
$Meaning_of_life$.  To create a rectangular link to it while drawing a possibly
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   164
different page, we would use this code:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   165
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   166
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   167
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   168
 canvas.linkAbsolute("Find the Meaning of Life", "Meaning_of_life",
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   169
                     (inch, inch, 6*inch, 2*inch))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   170
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   171
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   172
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   173
By default during interactive viewing a rectangle appears around the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   174
link. Use the keyword argument $Border='[0 0 0]'$ to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   175
suppress the visible rectangle around the during viewing link.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   176
For example
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   177
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   178
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   179
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   180
 canvas.linkAbsolute("Meaning of Life", "Meaning_of_life",
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   181
                     (inch, inch, 6*inch, 2*inch), Border='[0 0 0]')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   182
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   183
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   184
disc("""The $thickness$, $color$ and $dashArray$ arguments may be used alternately
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   185
to specify a border if no Border argument is specified.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   186
If Border is specified it must be either a string representation of a PDF
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   187
array or a $PDFArray$ (see the pdfdoc module). The $color$ argument (which should be a $Color$ instance) is equivalent to a keyword argument $C$ which should resolve to a PDF color definition (Normally a three entry PDF array).
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   188
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   189
disc("""The $canvas.linkRect$ method is similar in intent to the $linkAbsolute$ method, but has an extra argument $relative=1$ so is intended to obey the local userspace transformation.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   190
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   191
heading2("Outline Trees")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   192
disc("""Acrobat Reader has a navigation page which can hold a
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   193
    document outline; it should normally be visible when you
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   194
    open this guide.  We provide some simple methods to add
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   195
    outline entries.  Typically, a program to make a document
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   196
    (such as this user guide) will call the method
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   197
    $canvas.addOutlineEntry(^self, title, key, level=0,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   198
    closed=None^)$ as it reaches each heading in the document.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   199
    """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   200
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   201
disc("""^title^ is the caption which will be displayed in
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   202
    the left pane.  The ^key^ must be a string which is
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   203
    unique within the document and which names a bookmark,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   204
    as with the hyperlinks.  The ^level^ is zero - the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   205
    uppermost level - unless otherwise specified, and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   206
    it is an error to go down more than one level at a time
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   207
    (for example to follow a level 0 heading by a level 2
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   208
     heading).  Finally, the ^closed^ argument specifies
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   209
    whether the node in the outline pane is closed
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   210
    or opened by default.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   211
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   212
disc("""The snippet below is taken from the document template
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   213
    that formats this user guide.  A central processor looks
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   214
    at each paragraph in turn, and makes a new outline entry
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   215
    when a new chapter occurs, taking the chapter heading text
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   216
    as the caption text.  The key is obtained from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   217
    chapter number (not shown here), so Chapter 2 has the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   218
    key 'ch2'.  The bookmark to which the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   219
    outline entry points aims at the whole page, but it could
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   220
    as easily have been an individual paragraph.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   221
    """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   222
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   223
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   224
#abridged code from our document template
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   225
if paragraph.style == 'Heading1':
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   226
    self.chapter = paragraph.getPlainText()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   227
    key = 'ch%d' % self.chapterNo
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   228
    self.canv.bookmarkPage(key)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   229
    self.canv.addOutlineEntry(paragraph.getPlainText(),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   230
                                            key, 0, 0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   231
    """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   232
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   233
heading2("Page Transition Effects")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   234
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   235
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   236
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   237
 canvas.setPageTransition(self, effectname=None, duration=1,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   238
                        direction=0,dimension='H',motion='I')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   239
                        """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   240
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   241
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   242
The $setPageTransition$ method specifies how one page will be replaced with
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   243
the next.  By setting the page transition effect to "dissolve" for example
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   244
the current page will appear to melt away when it is replaced by the next
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   245
page during interactive viewing.  These effects are useful in spicing up
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   246
slide presentations, among other places.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   247
Please see the reference manual for more detail on how to use this method.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   248
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   249
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   250
heading2("Internal File Annotations")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   251
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   252
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   253
 canvas.setAuthor(name)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   254
 canvas.setTitle(title)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   255
 canvas.setSubject(subj)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   256
 """)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   257
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   258
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   259
These methods have no automatically seen visible effect on the document.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   260
They add internal annotations to the document.  These annotations can be
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   261
viewed using the "Document Info" menu item of the browser and they also can
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   262
be used as a simple standard way of providing basic information about the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   263
document to archiving software which need not parse the entire
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   264
file.  To find the annotations view the $*.pdf$ output file using a standard
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   265
text editor (such as $notepad$ on MS/Windows or $vi$ or $emacs$ on unix) and look
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   266
for the string $/Author$ in the file contents.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   267
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   268
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   269
eg(examples.testannotations)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   270
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   271
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   272
If you want the subject, title, and author to automatically display
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   273
in the document when viewed and printed you must paint them onto the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   274
document like any other text.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   275
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   276
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   277
illust(examples.annotations, "Setting document internal annotations")
3057
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   278
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   279
heading2("Encryption")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   280
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   281
heading3("About encrypting PDF files")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   282
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   283
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   284
Adobe's PDF standard allows you to do three related things to a PDF file when you encrypt it:
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   285
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   286
bullet("""Apply password protection to it, so a user must supply a valid password before being able to read it,
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   287
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   288
bullet("""Encrypt the contents of the file to make it useless until it is decrypted, and
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   289
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   290
bullet("""Control whether the user can print, copy and paste or modify the document while viewing it.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   291
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   292
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   293
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   294
The PDF security handler allows two different passwords to be specified for a document:
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   295
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   296
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   297
bullet("""The 'owner' password (aka the 'security password' or 'master password')
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   298
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   299
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   300
bullet("""The 'user' password (aka the 'open password')
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   301
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   302
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   303
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   304
When a user supplies either one of these passwords, the PDF file will be opened, decrypted and displayed on
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   305
screen.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   306
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   307
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   308
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   309
If the owner password is supplied, then the file is opened with full control - you can do anything to it,
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   310
including changing the security settings and passwords, or re-encrypting it with a new password.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   311
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   312
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   313
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   314
     If the user password was the one that was supplied, you open it up in a more restricted mode. The restrictions were put in
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   315
place when the file was encrypted, and will either allow or deny the user permission to do the following:
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   316
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   317
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   318
bullet("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   319
Modifying the document's contents
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   320
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   321
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   322
bullet("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   323
Copying text and graphics from the document
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   324
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   325
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   326
bullet("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   327
Adding or modifying text annotations and interactive form fields
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   328
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   329
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   330
bullet("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   331
Printing the document
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   332
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   333
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   334
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   335
Note that all password protected PDF files are encrypted, but not all encrypted PDFs are password protected. If
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   336
a document's user password is an empty string, there will be no prompt for the password when the file is
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   337
opened. If you only secure a document with the owner password, there will also not be a prompt for the
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   338
password when you open the file. If the owner and user passwords are set to the same string when encrypting
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   339
the PDF file, the document will always open with the user access privileges. This means that it is possible to
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   340
create a file which, for example, is impossible for anyone to print out, even the person who created it.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   341
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   342
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   343
t = Table([
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   344
           ['Owner Password \nset?','User Password \nset?','Result'],
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   345
           ['Y','-','No password required when opening file. \nRestrictions apply to everyone.'],
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   346
           ['-','Y','User password required when opening file. \nRestrictions apply to everyone.'],
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   347
           ['Y','Y','A password required when opening file. \nRestrictions apply only if user password supplied.'],
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   348
          ],[90, 90, 260])
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   349
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   350
t.setStyle(TableStyle([
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   351
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   352
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   353
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   354
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   355
            ]))
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   356
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   357
getStory().append(t)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   358
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   359
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   360
When a PDF file is encrypted, encryption is applied to all the strings and streams in the file. This prevents
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   361
people who don't have the password from simply removing the password from the PDF file to gain access to it - 
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   362
it renders the file useless unless you actually have the password.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   363
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   364
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   365
PDF's standard encryption methods use the
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   366
MD5 message digest algorithm (as described in RFC 1321, The MD5 Message-Digest Algorithm) and an
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   367
encryption algorithm known as RC4. RC4 is a symmetric stream cipher - the same algorithm is used both for
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   368
encryption and decryption, and the algorithm does not change the length of the data.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   369
""")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   370
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   371
heading3("How To Use Encryption")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   372
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   373
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   374
     Documents can be encrypted by passing an argument to the canvas object.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   375
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   376
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   377
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   378
     If the argument is a string object, it is used as the User password to the PDF.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   379
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   380
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   381
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   382
     The argument can also be an instance of the class $reportlab.lib.pdfencrypt.StandardEncryption$,
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   383
     which allows more finegrained control over encryption settings.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   384
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   385
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   386
disc("""
3058
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   387
     The $StandardEncryption$ constructor takes the following arguments:
3057
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   388
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   389
3058
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   390
eg("""
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   391
    def __init__(self, userPassword,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   392
            ownerPassword=None,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   393
            canPrint=1,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   394
            canModify=1,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   395
            canCopy=1,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   396
            canAnnotate=1,
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   397
            strength=40):
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   398
    """)
7f508fe1227c Slight modification to the StandardEncryption doc in the userguide.
jonas
parents: 3057
diff changeset
   399
3057
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   400
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   401
     The $userPassword$ and $ownerPassword$ parameters set the relevant password on the encrypted PDF.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   402
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   403
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   404
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   405
     The boolean flags $canPrint$, $canModify$, $canCopy$, $canAnnotate$ determine wether a user can
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   406
    perform the corresponding actions on the PDF when only a user password has been supplied.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   407
    """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   408
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   409
    If the user supplies the owner password while opening the PDF, all actions can be performed regardless
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   410
    of the flags.
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   411
    """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   412
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   413
heading3("Example")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   414
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   415
disc("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   416
     To create a document named hello.pdf with a user password of 'rptlab' on which printing is not allowed,
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   417
     use the following code:
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   418
     """)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   419
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   420
eg("""
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   421
from reportlab.pdfgen import canvas
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   422
from reportlab.lib import pdfencrypt
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   423
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   424
enc=pdfencrypt.StandardEncryption("rptlab",canPrint=0)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   425
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   426
def hello(c):
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   427
    c.drawString(100,100,"Hello World")
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   428
c = canvas.Canvas("hello.pdf",encrypt=enc)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   429
hello(c)
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   430
c.showPage()
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   431
c.save()
2106102f874a added encryption section to chapter 4 of userguide
tim
parents: 2966
diff changeset
   432
4311
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   433
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   434
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   435
heading2("Interactive Forms")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   436
heading3("Overview of Interactive Forms")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   437
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   438
disc("""The PDF standard allows for various kinds of interactive elements,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   439
the ReportLab toolkit currently supports only a fraction of the possibilities and should be considered a work in progress.
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   440
At present we allow choices with
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   441
<i>checkbox</i>, <i>radio</i>, <i>choice</i> &amp; <i>listbox</i> widgets; text values can be entered with a
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   442
<i>textfield</i> widget. All the widgets are created by calling methods on the <i>canvas.acroform</i> property."""
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   443
)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   444
heading3("Example")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   445
disc("This shows the basic mechanism of creating an interactive element on the current page.")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   446
eg("""
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   447
        canvas.acroform.checkbox(
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   448
                name='CB0',
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   449
                tooltip='Field CB0',
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   450
                checked=True,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   451
                x=72,y=72+4*36,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   452
                buttonStyle='diamond',
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   453
                borderStyle='bevelled',
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   454
                borderWidth=2,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   455
                borderColor=red,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   456
                fillColor=green,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   457
                textColor=blue,
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   458
                forceBorder=True)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   459
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   460
alStyle=TableStyle([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   461
            ('SPAN',(0,0),(-1,0)),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   462
            ('FONT',(0,0),(-1,0),'Helvetica-Bold',10,12),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   463
            ('FONT',(0,1),(-1,1),'Helvetica-BoldOblique',8,9.6),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   464
            ('FONT',(0,2),(0,-1),'Helvetica-Bold',7,8.4),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   465
            ('FONT',(1,2),(1,-1),'Helvetica',7,8.4),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   466
            ('FONT',(2,2),(2,-1),'Helvetica-Oblique',7,8.4),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   467
            ('ALIGN',(0,0),(-1,0),'CENTER'),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   468
            ('ALIGN',(1,1),(1,1),'CENTER'),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   469
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   470
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   471
            ])
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   472
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   473
disc("""<b>NB</b> note that the <i>acroform</i> canvas property is created automatically on demand and that there is only one form allowd in a document.""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   474
heading3("Checkbox Usage")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   475
disc("""The <i>canvas.acroform.checkbox</i> method creates a <i>checkbox</i> widget on the current page. The value of the checkbox is either <b>YES</b> or <b>OFF</b>.
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   476
The arguments are""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   477
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   478
            ['canvas.acroform.checkbox parameters','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   479
            ['Parameter','Meaning','Default'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   480
            ["name","the parameter's name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   481
            ["x","the horizontal position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   482
            ["y","the vertical position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   483
            ["size","The outline dimensions size x size","20"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   484
            ["checked","if True the checkbox is initially checked","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   485
            ["buttonStyle","the checkbox style (see below)","'check'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   486
            ["shape","The outline of the widget (see below)","'square'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   487
            ["fillColor","colour to be used to fill the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   488
            ["textColor","the colour of the symbol or text","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   489
            ["borderWidth","as it says","1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   490
            ["borderColor","the widget's border colour","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   491
            ["borderStyle","The border style name","'solid'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   492
            ["tooltip","The text to display when hovering over the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   493
            ["annotationFlags","blank separated string of annotation flags","'print'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   494
            ["fieldFlags","Blank separated field flags (see below)","'required'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   495
            ["forceBorder","when true a border force a border to be drawn","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   496
            ["relative","if true obey the current canvas transform","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   497
            ["dashLen ","the dashline to be used if the borderStyle=='dashed'","3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   498
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   499
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   500
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   501
heading3("Radio Usage")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   502
disc("""The <i>canvas.acroform.radio</i> method creates a <i>radio</i> widget on the current page. The value of the radio is the value of the radio group's
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   503
selected value or <b>OFF</b> if none are selected.
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   504
The arguments are""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   505
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   506
            ['canvas.acroform.radio parameters','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   507
            ['Parameter','Meaning','Default'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   508
            ["name","the radio's group (ie parameter) name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   509
            ["value","the radio's group name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   510
            ["x","the horizontal position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   511
            ["y","the vertical position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   512
            ["size","The outline dimensions size x size","20"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   513
            ["selected","if True this radio is the selected one in its group","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   514
            ["buttonStyle","the checkbox style (see below)","'check'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   515
            ["shape","The outline of the widget (see below)","'square'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   516
            ["fillColor","colour to be used to fill the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   517
            ["textColor","the colour of the symbol or text","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   518
            ["borderWidth","as it says","1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   519
            ["borderColor","the widget's border colour","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   520
            ["borderStyle","The border style name","'solid'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   521
            ["tooltip","The text to display when hovering over the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   522
            ["annotationFlags","blank separated string of annotation flags","'print'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   523
            ["fieldFlags","Blank separated field flags (see below)","'noToggleToOff required radio'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   524
            ["forceBorder","when true a border force a border to be drawn","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   525
            ["relative","if true obey the current canvas transform","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   526
            ["dashLen ","the dashline to be used if the borderStyle=='dashed'","3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   527
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   528
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   529
heading3("Listbox Usage")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   530
disc("""The <i>canvas.acroform.listbox</i> method creates a <i>listbox</i> widget on the current page. The listbox contains a
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   531
list of options one or more of which (depending on fieldFlags) may be selected.
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   532
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   533
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   534
            ['canvas.acroform.listbox parameters','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   535
            ['Parameter','Meaning','Default'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   536
            ["name","the radio's group (ie parameter) name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   537
            ["options","List or tuple of avaiable options","[]"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   538
            ["value","Singleton or list of strings of selected options","[]"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   539
            ["x","the horizontal position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   540
            ["y","the vertical position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   541
            ["width","The widget width","120"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   542
            ["height","The widget height","36"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   543
            ["fontName","The name of the type 1 font to be used","'Helvetica'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   544
            ["fontSize","The size of font to be used","12"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   545
            ["fillColor","colour to be used to fill the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   546
            ["textColor","the colour of the symbol or text","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   547
            ["borderWidth","as it says","1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   548
            ["borderColor","the widget's border colour","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   549
            ["borderStyle","The border style name","'solid'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   550
            ["tooltip","The text to display when hovering over the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   551
            ["annotationFlags","blank separated string of annotation flags","'print'"],
4312
49eee21829a1 minor documentation changes
robin <robin@reportlab.com>
parents: 4311
diff changeset
   552
            ["fieldFlags","Blank separated field flags (see below)","''"],
4311
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   553
            ["forceBorder","when true a border force a border to be drawn","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   554
            ["relative","if true obey the current canvas transform","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   555
            ["dashLen ","the dashline to be used if the borderStyle=='dashed'","3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   556
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   557
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   558
heading3("Choice Usage")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   559
disc("""The <i>canvas.acroform.choice</i> method creates a <i>dropdown</i> widget on the current page. The dropdown contains a
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   560
list of options one or more of which (depending on fieldFlags) may be selected. If you add <i>edit</i> to the <i>fieldFlags</i>
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   561
then the result may be edited.
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   562
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   563
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   564
            ['canvas.acroform.choice parameters','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   565
            ['Parameter','Meaning','Default'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   566
            ["name","the radio's group (ie parameter) name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   567
            ["options","List or tuple of avaiable options","[]"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   568
            ["value","Singleton or list of strings of selected options","[]"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   569
            ["x","the horizontal position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   570
            ["y","the vertical position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   571
            ["width","The widget width","120"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   572
            ["height","The widget height","36"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   573
            ["fontName","The name of the type 1 font to be used","'Helvetica'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   574
            ["fontSize","The size of font to be used","12"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   575
            ["fillColor","colour to be used to fill the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   576
            ["textColor","the colour of the symbol or text","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   577
            ["borderWidth","as it says","1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   578
            ["borderColor","the widget's border colour","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   579
            ["borderStyle","The border style name","'solid'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   580
            ["tooltip","The text to display when hovering over the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   581
            ["annotationFlags","blank separated string of annotation flags","'print'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   582
            ["fieldFlags","Blank separated field flags (see below)","'combo'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   583
            ["forceBorder","when true a border force a border to be drawn","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   584
            ["relative","if true obey the current canvas transform","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   585
            ["dashLen ","the dashline to be used if the borderStyle=='dashed'","3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   586
            ["maxlen ","None or maximum length of the widget value","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   587
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   588
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   589
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   590
heading3("Textfield Usage")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   591
disc("""The <i>canvas.acroform.textfield</i> method creates a <i>textfield</i> entry widget on the current page. The textfield may be edited
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   592
to change tha value of the widget
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   593
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   594
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   595
            ['canvas.acroform.textfield parameters','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   596
            ['Parameter','Meaning','Default'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   597
            ["name","the radio's group (ie parameter) name","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   598
            ["value","Value of the text field","''"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   599
            ["maxlen ","None or maximum length of the widget value","100"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   600
            ["x","the horizontal position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   601
            ["y","the vertical position on the page (absolute coordinates)","0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   602
            ["width","The widget width","120"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   603
            ["height","The widget height","36"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   604
            ["fontName","The name of the type 1 font to be used","'Helvetica'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   605
            ["fontSize","The size of font to be used","12"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   606
            ["fillColor","colour to be used to fill the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   607
            ["textColor","the colour of the symbol or text","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   608
            ["borderWidth","as it says","1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   609
            ["borderColor","the widget's border colour","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   610
            ["borderStyle","The border style name","'solid'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   611
            ["tooltip","The text to display when hovering over the widget","None"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   612
            ["annotationFlags","blank separated string of annotation flags","'print'"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   613
            ["fieldFlags","Blank separated field flags (see below)","''"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   614
            ["forceBorder","when true a border force a border to be drawn","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   615
            ["relative","if true obey the current canvas transform","False"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   616
            ["dashLen ","the dashline to be used if the borderStyle=='dashed'","3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   617
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   618
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   619
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   620
heading3("Button styles")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   621
disc("""The button style argument indicates what style of symbol should appear in the button when it is selected. There are several choices""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   622
eg("""  check
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   623
  cross
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   624
  circle
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   625
  star
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   626
  diamond
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   627
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   628
disc("""note that the document renderer can make some of these symbols wrong for their intended application.  Acrobat reader
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   629
prefers to use its own rendering on top of what the specification says should be shown (especially when the forms hihlighting features are used""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   630
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   631
heading3("Widget shape")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   632
disc("""The shape argument describes how the outline of the checkbox or radio widget should appear you can use""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   633
eg("""  circle
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   634
  square
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   635
""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   636
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   637
disc("""The renderer may make its own decisions about how the widget should look; so Acrobat Reader prefers circular outlines for radios.""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   638
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   639
heading3("Border style")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   640
disc("""The borderStyle argument changes the 3D appearance of the widget on the page alternatives are""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   641
eg("""  solid
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   642
  dashed
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   643
  inset
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   644
  bevelled
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   645
  underlined
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   646
    """)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   647
heading3("fieldFlags Argument")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   648
disc("""The fieldFlags arguments can be an integer or a string containing blank separate tokens the values are shown in the table below. For
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   649
more information consult the PDF specification.""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   650
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   651
            ['Field Flag Tokens and values','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   652
            ['Token','Meaning','Value'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   653
            ["readOnly","The widget is read only","1<<0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   654
            ["required","the widget is required","1<<1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   655
            ["noExport","don't export the widget value","1<<2"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   656
            ["noToggleToOff","radios one only must be on","1<<14"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   657
            ["radio","added by the radio method","1<<15"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   658
            ["pushButton","if the button is a push button","1<<16"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   659
            ["radiosInUnison","radios with the same value toggle together","1<<25"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   660
            ["multiline","for multiline text widget","1<<12"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   661
            ["password","password textfield","1<<13"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   662
            ["fileSelect","file selection widget","1<<20"],         #1.4
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   663
            ["doNotSpellCheck","as it says","1<<22"],   #1.4
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   664
            ["doNotScroll","text fields do not scroll","1<<23"],        #1.4
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   665
            ["comb","make a comb style text based on the maxlen value","1<<24"],                #1.5
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   666
            ["richText","if rich text is used","1<<25"],            #1.5
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   667
            ["combo","for choice fields","1<<17"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   668
            ["edit","if the choice is editable","1<<18"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   669
            ["sort","if the values should be sorted","1<<19"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   670
            ["multiSelect","if the choice allows multi-select","1<<21"],        #1.4
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   671
            ["commitOnSelChange","not used by reportlab","1<<26"],  #1.5
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   672
          ],[90, 260, 90],style=alStyle,repeatRows=2)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   673
getStory().append(t)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   674
heading3("annotationFlags Argument")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   675
disc("""PDF widgets are annotations and have annotation properties these are shown in the table below""")
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   676
t = Table([
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   677
            ['Annotation Flag Tokens and values','',''],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   678
            ['Token','Meaning','Value'],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   679
            ["invisible","The widget is not shown","1<<0"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   680
            ["hidden","The widget is hidden","1<<1"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   681
            ["print","The widget will print","1<<2"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   682
            ["nozoom","The annotation will notscale with the rendered page","1<<3"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   683
            ["norotate","The widget won't rotate with the page","1<<4"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   684
            ["noview","Don't render the widget","1<<5"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   685
            ["readonly","Widget cannot be interacted with","1<<6"],
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   686
            ["locked","The widget cannot be changed","1<<7"],           #1.4
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   687
            ["togglenoview","Teh widget may be viewed after some events","1<<8"],       #1.9
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   688
            ["lockedcontents","The contents of the widget are fixed","1<<9"],   #1.7
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   689
          ],[90, 260, 90],style=alStyle)
fab7ad9a3507 preparing for 3.4.0 release
robin <robin@reportlab.com>
parents: 4252
diff changeset
   690
getStory().append(t)