docs/userguide/ch6_tables.py
author rgbecker
Thu, 24 Aug 2000 18:18:47 +0000
changeset 447 e9885eca2bbc
parent 446 400496648288
child 450 37919675ea28
permissions -rw-r--r--
harder test of XPreformatted
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     1
#ch6_tables
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     2
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     3
from genuserguide import *
424
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
     4
from reportlab.platypus import Image
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     5
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     6
heading1("Tables and TableStyles")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     7
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
     8
The $Table$ class is derived from the $Flowable$ class and is intended
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     9
as a simple textual gridding mechanism. $Table$ cells can hold anything which can be converted to
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    10
a <b>Python</b> $string$. 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    11
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    12
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    13
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    14
$Tables$ are created by passing the constructor a sequence of column widths,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    15
a sequence of row heights and the data in
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    16
row order. Drawing of the table can be controlled by using a $TableStyle$ instance. This allows control of the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    17
color and weight of the lines (if any), and the font, alignment and padding of the text.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    18
A primitive automatic row height and or column width calculation mechanism is provided for.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    19
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    20
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    21
heading2('$Table$ User Methods')
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    22
disc("""These are the main methods which are of interest to the client programmer.""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    23
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    24
heading4("""$Table(data, colWidths=None, rowHeights=None, style=None, splitByRow=1,
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    25
repeatRows=0, repeatCols=0)$""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    26
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    27
disc("""The $data$ argument is a sequence of sequences of cell values each of which
424
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
    28
should be convertible to a string value using the $str$ function or should be a Flowable instance (such as a $Paragraph$) or a list (or tuple) of such instances.
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
    29
If a cell value is a $Flowable$ or list of $Flowables$ these must either have a determined width
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
    30
or the containing column must have a fixed width.
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
    31
The first row of cell values
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    32
is in $data[0]$ i.e. the values are in row order. The $i$, $j$<sup>th.</sup> cell value is in
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    33
$data[i][j]$. Newline characters $'\\n'$ in cell values are treated as line split characters and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    34
are used at <i>draw</i> time to format the cell into lines.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    35
""")
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    36
disc("""The other arguments are fairly obvious, the $colWidths$ argument is a sequence
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    37
of numbers or possibly $None$, representing the widths of the columns. The number of elements
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    38
in $colWidths$ determines the number of columns in the table.
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    39
A value of $None$ means that the corresponding column width should be calculated automatically.""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    40
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    41
disc("""The $rowHeights$ argument is a sequence
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    42
of numbers or possibly $None$, representing the heights of the rows. The number of elements
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    43
in $rowHeights$ determines the number of rows in the table.
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    44
A value of $None$ means that the corresponding row height should be calculated automatically.""")
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    45
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    46
disc("""The $style$ argument can be an initial style for the table.""")
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    47
disc("""The $splitByRow$ argument is a Boolean indicating that the $Table$ should split itself
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    48
by row before attempting to split itself by column when too little space is available in
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    49
the current drawing area and the caller wants the $Table$ to split.""")
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    50
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    51
disc("""The $repeatRows$ and $repeatCols$ arguments specify the number of leading rows and columns
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
    52
that should be repeated when the $Table$ is asked to split itself.""")
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    53
heading4('$Table.setStyle(tblStyle)$')
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    54
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    55
This method applies a particular instance of class $TableStyle$ (discussed below)
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    56
to the $Table$ instance. This is the only way to get $tables$ to appear
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    57
in a nicely formatted way.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    58
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    59
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    60
Successive uses of the $setStyle$ method apply the styles in an additive fashion.
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    61
That is, later applications override earlier ones where they overlap.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    62
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    63
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    64
heading2('$TableStyle$')
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    65
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    66
This class is created by passing it a sequence of <i>commands</i>, each command
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    67
is a tuple identified by its first element which is a string; the remaining
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    68
elements of the command tuple represent the start and stop cell coordinates
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    69
of the command and possibly thickness and colors, etc.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    70
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    71
heading2("$TableStyle$ User Methods")
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    72
heading3("$TableStyle(commandSequence)$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    73
disc("""The creation method initializes the $TableStyle$ with the argument
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    74
command sequence as an example:""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    75
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    76
    LIST_STYLE = TableStyle(
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    77
        [('LINEABOVE', (0,0), (-1,0), 2, colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    78
        ('LINEABOVE', (0,1), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    79
        ('LINEBELOW', (0,-1), (-1,-1), 2, colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    80
        ('ALIGN', (1,1), (-1,-1), 'RIGHT')]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    81
        )
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    82
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    83
heading3("$TableStyle.add(commandSequence)$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    84
disc("""This method allows you to add commands to an existing
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
    85
$TableStyle$, i.e. you can build up $TableStyles$ in multiple statements.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    86
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    87
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    88
    LIST_STYLE.add([('BACKGROUND', (0,0), (-1,0), colors.Color(0,0.7,0.7))])
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    89
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    90
heading3("$TableStyle.getCommands()$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    91
disc("""This method returns the sequence of commands of the instance.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    92
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    93
    cmds = LIST_STYLE.getCommands()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    94
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    95
heading2("$TableStyle$ Commands")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    96
disc("""The commands passed to $TableStyles$ come in three main groups
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    97
which affect the table background, draw lines, or set cell styles.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    98
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    99
disc("""The first element of each command is its identifier,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   100
the second and third arguments determine the cell coordinates of
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   101
the box of cells which are affected with negative coordinates
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   102
counting backwards from the limit values as in <b>Python</b>
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   103
indexing. The coordinates are given as
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   104
(column, row) which follows the spreadsheet 'A1' model, but not
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   105
the more natural (for mathematicians) 'RC' ordering.
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   106
The top left cell is (0, 0) the bottom right is (-1, -1). Depending on
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   107
the command various extra (???) occur at indices beginning at 3 on.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   108
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
   109
heading3("""$TableStyle$ Cell Formatting Commands""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   110
disc("""The cell formatting commands all begin with an identifier, followed by
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   111
the start and stop cell definitions and the perhaps other arguments.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   112
the cell formatting commands are:""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   113
eg("""
362
2a124e1f58b3 Changed CellStyles
rgbecker
parents: 360
diff changeset
   114
FONT                    - takes fontname, optional fontsize and optional leading.
2a124e1f58b3 Changed CellStyles
rgbecker
parents: 360
diff changeset
   115
FONTNAME (or FACE)      - takes fontname.
2a124e1f58b3 Changed CellStyles
rgbecker
parents: 360
diff changeset
   116
FONTSIZE (or SIZE)      - takes fontsize in points; leading may get out of sync.
2a124e1f58b3 Changed CellStyles
rgbecker
parents: 360
diff changeset
   117
LEADING                 - takes leading in points.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   118
TEXTCOLOR               - takes a color name or (R,G,B) tuple.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   119
ALIGNMENT (or ALIGN)    - takes one of LEFT, RIGHT and CENTRE (or CENTER).
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   120
LEFTPADDING             - takes an integer, defaults to 6.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   121
RIGHTPADDING            - takes an integer, defaults to 6.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   122
BOTTOMPADDING           - takes an integer, defaults to 3.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   123
TOPPADDING              - takes an integer, defaults to 3.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   124
BACKGROUND              - takes a color.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   125
VALIGN                  - takes one of TOP, MIDDLE or the default BOTTOM
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   126
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   127
disc("""This sets the background cell color in the relevant cells.
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   128
The following example shows the $BACKGROUND$, and $TEXTCOLOR$ commands in action:""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   129
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   130
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   131
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   132
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   133
        ['30', '31', '32', '33', '34']]
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
   134
t=Table(data)
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   135
t.setStyle(TableStyle([('BACKGROUND',(1,1),(-2,-2),colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   136
                        ('TEXTCOLOR',(0,0),(1,-1),colors.red)]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   137
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   138
disc("""To see the effects of the alignment styles we need  some widths
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   139
and a grid, but it should be easy to see where the styles come from.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   140
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   141
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   142
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   143
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   144
        ['30', '31', '32', '33', '34']]
356
377367fe28cb Table argument order changed
rgbecker
parents: 349
diff changeset
   145
t=Table(data,5*[0.4*inch], 4*[0.4*inch])
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   146
t.setStyle(TableStyle([('ALIGN',(1,1),(-2,-2),'RIGHT'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   147
                        ('TEXTCOLOR',(1,1),(-2,-2),colors.red),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   148
                        ('VALIGN',(0,0),(0,-1),'TOP'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   149
                        ('TEXTCOLOR',(0,0),(0,-1),colors.blue),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   150
                        ('ALIGN',(0,-1),(-1,-1),'CENTER'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   151
                        ('VALIGN',(0,-1),(-1,-1),'MIDDLE'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   152
                        ('TEXTCOLOR',(0,-1),(-1,-1),colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   153
                        ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   154
                        ('BOX', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   155
                        ]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   156
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
   157
heading3("""$TableStyle$ Line Commands""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   158
disc("""
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   159
    Line commands begin with the identifier, the start and stop cell coordinates
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   160
    and always follow this with the thickness (in points) and color of the desired lines. Colors can be names,
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   161
    or they can be specified as a (R, G, B) tuple, where R, G and B are floats and (0, 0, 0) is black. The line
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   162
    command names are: GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   163
    and LINEAFTER. BOX and OUTLINE are equivalent, and GRID is the equivalent of applying both BOX and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   164
    INNERGRID.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   165
""")
363
e72f6cceebca Added Keep together CPage
rgbecker
parents: 362
diff changeset
   166
CPage(4.0)
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   167
disc("""We can see some line commands in action with the following example.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   168
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   169
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   170
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   171
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   172
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   173
        ['30', '31', '32', '33', '34']]
360
f9b73082ec6e Table docs adjusted for new styles
rgbecker
parents: 356
diff changeset
   174
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
f9b73082ec6e Table docs adjusted for new styles
rgbecker
parents: 356
diff changeset
   175
                    ('BOX',(0,0),(1,-1),2,colors.red),
f9b73082ec6e Table docs adjusted for new styles
rgbecker
parents: 356
diff changeset
   176
					('LINEABOVE',(1,2),(-2,2),1,colors.blue),
f9b73082ec6e Table docs adjusted for new styles
rgbecker
parents: 356
diff changeset
   177
					('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
f9b73082ec6e Table docs adjusted for new styles
rgbecker
parents: 356
diff changeset
   178
					])
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   179
""")
424
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   180
disc("""Line commands cause problems for tables when they split; the following example
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   181
shows a table being split in various positions""")
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   182
EmbeddedCode("""
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   183
data=  [['00', '01', '02', '03', '04'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   184
		['10', '11', '12', '13', '14'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   185
		['20', '21', '22', '23', '24'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   186
		['30', '31', '32', '33', '34']]
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   187
t=Table(data,style=[
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   188
				('GRID',(0,0),(-1,-1),0.5,colors.grey),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   189
				('GRID',(1,1),(-2,-2),1,colors.green),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   190
				('BOX',(0,0),(1,-1),2,colors.red),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   191
				('BOX',(0,0),(-1,-1),2,colors.black),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   192
				('LINEABOVE',(1,2),(-2,2),1,colors.blue),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   193
				('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   194
				('BACKGROUND', (0, 0), (0, 1), colors.pink),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   195
				('BACKGROUND', (1, 1), (1, 2), colors.lavender),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   196
				('BACKGROUND', (2, 2), (2, 3), colors.orange),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   197
				])
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   198
""")
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   199
t=getStory()[-1]
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   200
getStory().append(Spacer(0,6))
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   201
for s in t.split(4*inch,30):
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   202
	getStory().append(s)
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   203
	getStory().append(Spacer(0,6))
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   204
getStory().append(Spacer(0,6))
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   205
for s in t.split(4*inch,36):
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   206
	getStory().append(s)
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   207
	getStory().append(Spacer(0,6))
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   208
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   209
disc("""When unsplit and split at the first or second row.""")
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   210
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   211
CPage(4.0)
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   212
heading3("""Complex Cell Values""")
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   213
disc("""
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   214
As mentioned above we can have complicated cell values including $Paragraphs$, $Images$ and other $Flowables$
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   215
or lists of the same. To see this in operation consider the following code and the table it produces.
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   216
Note that the $Image$ has a white background which will obscure any background you choose for the cell.
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   217
To get better results you should use a transparent background.
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   218
""")
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   219
import os, reportlab.platypus
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   220
I = '../images/replogo.gif'
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   221
EmbeddedCode("""
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   222
I = Image('%s')
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   223
I.drawHeight = 1.25*inch*I.drawHeight / I.drawWidth
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   224
I.drawWidth = 1.25*inch
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   225
I.noImageCaching = 1
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   226
P0 = Paragraph('''
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   227
               <b>A pa<font color=red>r</font>a<i>graph</i></b>
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   228
               <super><font color=yellow>1</font></super>''',
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   229
               styleSheet["BodyText"])
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   230
P = Paragraph('''
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   231
       <para align=center spaceb=3>The <b>ReportLab Left
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   232
       <font color=red>Logo</font></b>
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   233
       Image</para>''',
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   234
       styleSheet["BodyText"])
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   235
data=  [['A',   'B', 'C',     P0, 'D'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   236
		['00', '01', '02', [I,P], '04'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   237
		['10', '11', '12', [P,I], '14'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   238
		['20', '21', '22',  '23', '24'],
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   239
		['30', '31', '32',  '33', '34']]
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   240
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   241
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   242
					('BOX',(0,0),(1,-1),2,colors.red),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   243
					('LINEABOVE',(1,2),(-2,2),1,colors.blue),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   244
					('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   245
					('BACKGROUND', (0, 0), (0, 1), colors.pink),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   246
					('BACKGROUND', (1, 1), (1, 2), colors.lavender),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   247
					('BACKGROUND', (2, 2), (2, 3), colors.orange),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   248
					('BOX',(0,0),(-1,-1),2,colors.black),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   249
					('GRID',(0,0),(-1,-1),0.5,colors.black),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   250
					('VALIGN',(3,0),(3,0),'BOTTOM'),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   251
					('BACKGROUND',(3,0),(3,0),colors.limegreen),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   252
					('BACKGROUND',(3,1),(3,1),colors.khaki),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   253
					('ALIGN',(3,1),(3,1),'CENTER'),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   254
					('BACKGROUND',(3,2),(3,2),colors.beige),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   255
					('ALIGN',(3,2),(3,2),'LEFT'),
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   256
					])
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   257
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   258
t._argW[3]=1.5*inch
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   259
"""%I)
240ee4e6d0d7 Table cell updates
rgbecker
parents: 399
diff changeset
   260
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   261
heading1("""Other Useful $Flowables$""")
441
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   262
heading2("""$Preformatted(text, style, bulletText = None, dedent=0)$""")
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   263
disc("""
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   264
Creates a preformatted paragraph which does no wrapping, line splitting or other manipulations.
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   265
No $XML$ style tags are taken account of in the text.
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   266
If dedent is non zero $dedent$ common leading
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   267
spaces will be removed from the front of each line.
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   268
""")
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   269
heading2("""$XPreformatted(text, style, bulletText = None, dedent=0, frags=None)$""")
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   270
disc("""
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   271
This is a non rearranging form of the $Paragraph$ class; $XML$ tags are allowed in
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   272
$text$ and have the same meanings as for the $Paragraph$ class.
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   273
As for $Preformatted$, if dedent is non zero $dedent$ common leading
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   274
spaces will be removed from the front of each line.
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   275
""")
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   276
EmbeddedCode("""
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   277
from reportlab.lib.styles import getSampleStyleSheet
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   278
stylesheet=getSampleStyleSheet()
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   279
normalStyle = stylesheet['Normal']
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   280
text='''
446
400496648288 Added blank lines to XPreformatted sample
rgbecker
parents: 441
diff changeset
   281
441
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   282
   This is a non rearranging form of the <b>Paragraph</b> class;
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   283
   <b><font color=red>XML</font></b> tags are allowed in <i>text</i> and have the same
446
400496648288 Added blank lines to XPreformatted sample
rgbecker
parents: 441
diff changeset
   284
   
447
e9885eca2bbc harder test of XPreformatted
rgbecker
parents: 446
diff changeset
   285
      meanings as for the <b>Paragraph</b> class.
441
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   286
   As for <b>Preformatted</b>, if dedent is non zero <font color=red size=+1>dedent</font>
447
e9885eca2bbc harder test of XPreformatted
rgbecker
parents: 446
diff changeset
   287
       common leading spaces will be removed from the
441
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   288
   front of each line.
446
400496648288 Added blank lines to XPreformatted sample
rgbecker
parents: 441
diff changeset
   289
441
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   290
'''
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   291
t=XPreformatted(text,normalStyle,dedent=3)
4b7abf4f9565 Preformatted docco added
rgbecker
parents: 424
diff changeset
   292
""")
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   293
heading2("""$Image(filename, width=None, height=None)$""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   294
disc("""Create a flowable which will contain the image defined by the data in file $filename$.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   295
The default <b>PDF</b> image type <i>jpeg</i> is supported and if the <b>PIL</b> extension to <b>Python</b>
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   296
is installed the other image types can also be handled. If $width$ and or $height$ are specified
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   297
then they determine the dimension of the displayed image in <i>points</i>. If either dimension is
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   298
not specified (or specified as $None$) then the corresponding pixel dimension of the image is assumed
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   299
to be in <i>points</i> and used.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   300
""")
391
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   301
I=os.path.join(os.path.dirname(__file__),'..','images','lj8100.jpg')
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   302
eg("""
389
99e299fc85ea Copied lj8100.jpg
rgbecker
parents: 387
diff changeset
   303
Image("lj8100.jpg")
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   304
""",after=0.1)
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   305
disc("""will display as""")
391
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   306
try:
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   307
	getStory().append(Image(I))
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   308
except:
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   309
	disc("""An image should have appeared here.""")
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   310
disc("""whereas""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   311
eg("""
389
99e299fc85ea Copied lj8100.jpg
rgbecker
parents: 387
diff changeset
   312
Image("lj8100.jpg", width=2*inch, height=2*inch)
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   313
""", after=0.1)
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   314
disc('produces')
391
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   315
try:
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   316
	getStory().append(Image(I, width=2*inch, height=2*inch))
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   317
except:
737b13ef7064 Image probs again
rgbecker
parents: 389
diff changeset
   318
	disc("""An image should have appeared here.""")
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   319
heading2("""$Spacer(width, height)$""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   320
disc("""This does exactly as would be expected; it adds a certain amount of space into the story.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   321
At present this only works for vertical space.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   322
""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   323
CPage(1)
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   324
heading2("""$PageBreak()$""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   325
disc("""This $Flowable$ represents a page break. It works by effectively consuming all vertical
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   326
space given to it. This is sufficient for a single $Frame$ document, but would only be a
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   327
frame break for multiple frames so the $BaseDocTemplate$ mechanism
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   328
detects $pageBreaks$ internally and handles them specially.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   329
""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   330
CPage(1)
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   331
heading2("""$CondPageBreak(height)$""")
399
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   332
disc("""This $Flowable$ attempts to force a $Frame$ break if insufficient vertical space remains 
600ebb5a92cf fixed typos.
dinu_gherman
parents: 391
diff changeset
   333
in the current $Frame$. It is thus probably wrongly named and should probably be renamed as
387
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   334
$CondFrameBreak$.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   335
""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   336
CPage(1)
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   337
heading2("""$KeepTogether(flowables)$""")
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   338
disc("""
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   339
This compound $Flowable$ takes a list of $Flowables$ and attempts to keep them in the same $Frame$.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   340
If the total height of the $Flowables$ in the list $flowables$ exceeds the current frame's available
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   341
space then all the space is used and a frame break is forced.
96aed7d43e4d Added Useful Flowables
rgbecker
parents: 363
diff changeset
   342
""")