docs/userguide/ch6_tables.py
author jonas
Thu, 15 Jan 2009 16:59:35 +0000
changeset 3059 3a6ff201e927
parent 3044 7e5a05f30245
child 3061 ecd4963cc832
permissions -rw-r--r--
Added documentation for the table of contents to the userguide.
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2004
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/ch6_tables.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
from reportlab.platypus import Image
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     6
import reportlab
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     7
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     8
heading1("Tables and TableStyles")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     9
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    10
The $Table$  and $LongTable$ classes derive from the $Flowable$ class and are intended
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    11
as a simple textual gridding mechanisms. The $longTable$ class uses a greedy algorithm
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    12
when calculating column widths and is intended for long tables where speed counts.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    13
$Table$ cells can hold anything which can be converted to
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    14
a <b>Python</b> $string$ or $Flowables$ (or lists of $Flowables$).
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    15
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    16
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    17
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    18
Our present tables are a trade-off between efficient drawing and specification
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    19
and functionality.  We assume the reader has some familiarity with HTML tables.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    20
In brief, they have the following characteristics:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    21
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    22
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    23
bullet("""They can contain anything convertible to a string; flowable
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    24
objects such as other tables; or entire sub-stories""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    25
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    26
bullet("""They can work out the row heights to fit the data if you don't supply
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    27
the row height.  (They can also work out the widths, but generally it is better
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    28
for a designer to set the width manually, and it draws faster).""")
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
bullet("""They can split across pages if needed (see the canSplit attribute).
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    31
You can specify that a number of rows at the top and bottom should be
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    32
repeated after the split (e.g. show the headers again on page 2,3,4...)""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    33
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    34
bullet("""They have a simple and powerful notation for specifying shading and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    35
gridlines which works well with financial or database tables, where you
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    36
don't know the number of rows up front.  You can easily say 'make the last row
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    37
bold and put a line above it'""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    38
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    39
bullet("""The style and data are separated, so you can declare a handful of table
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    40
styles and use them for a family of reports.  Styes can also 'inherit', as with
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    41
paragraphs.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    42
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    43
disc("""There is however one main limitation compared to an HTML table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    44
They define a simple rectangular grid.  There is no simple row or column
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    45
spanning; if you need to span cells, you must nest tables inside table cells instead or use a more
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    46
complex scheme in which the lead cell of a span contains the actual contents.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    47
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    48
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    49
$Tables$ are created by passing the constructor an optional sequence of column widths,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    50
an optional sequence of row heights, and the data in row order.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    51
Drawing of the table can be controlled by using a $TableStyle$ instance. This allows control of the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    52
color and weight of the lines (if any), and the font, alignment and padding of the text.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    53
A primitive automatic row height and or column width calculation mechanism is provided for.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    54
""")
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
heading2('$Table$ User Methods')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    57
disc("""These are the main methods which are of interest to the client programmer.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    58
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    59
heading4("""$Table(data, colWidths=None, rowHeights=None, style=None, splitByRow=1,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    60
repeatRows=0, repeatCols=0)$""")
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
disc("""The $data$ argument is a sequence of sequences of cell values each of which
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    63
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.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    64
If a cell value is a $Flowable$ or list of $Flowables$ these must either have a determined width
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    65
or the containing column must have a fixed width.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    66
The first row of cell values
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    67
is in $data[0]$ i.e. the values are in row order. The $i$, $j$<sup>th.</sup> cell value is in
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    68
$data[i][j]$. Newline characters $'\\n'$ in cell values are treated as line split characters and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    69
are used at <i>draw</i> time to format the cell into lines.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    70
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    71
disc("""The other arguments are fairly obvious, the $colWidths$ argument is a sequence
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    72
of numbers or possibly $None$, representing the widths of the columns. The number of elements
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    73
in $colWidths$ determines the number of columns in the table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    74
A value of $None$ means that the corresponding column width should be calculated automatically.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    75
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    76
disc("""The $rowHeights$ argument is a sequence
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    77
of numbers or possibly $None$, representing the heights of the rows. The number of elements
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    78
in $rowHeights$ determines the number of rows in the table.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    79
A value of $None$ means that the corresponding row height should be calculated automatically.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    80
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    81
disc("""The $style$ argument can be an initial style for the table.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    82
disc("""The $splitByRow$ argument is only needed for tables both too tall and too wide
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    83
to fit in the current context.  In this case you must decide whether to 'tile'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    84
down and across, or across and then down.  This parameter is a Boolean indicating that the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    85
$Table$ should split itself
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    86
by row before attempting to split itself by column when too little space is available in
3044
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    87
the current drawing area and the caller wants the $Table$ to split.
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    88
Splitting a $Table$ by column is currently not implemented, so setting $splitByRow$ to $False$ will result in a $NotImplementedError$.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    89
3044
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    90
disc("""The $repeatRows$ argument specifies the number of leading rows
7e5a05f30245 Fixed documentation: tables cannot be split by column.
jonas
parents: 2966
diff changeset
    91
that should be repeated when the $Table$ is asked to split itself. The $repeatCols$ argument is currently ignored as a $Table$ cannot be split by column.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    92
heading4('$Table.setStyle(tblStyle)$')
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
This method applies a particular instance of class $TableStyle$ (discussed below)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    95
to the $Table$ instance. This is the only way to get $tables$ to appear
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    96
in a nicely formatted way.
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
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    99
Successive uses of the $setStyle$ method apply the styles in an additive fashion.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   100
That is, later applications override earlier ones where they overlap.
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
heading2('$TableStyle$')
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 class is created by passing it a sequence of <i>commands</i>, each command
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   106
is a tuple identified by its first element which is a string; the remaining
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   107
elements of the command tuple represent the start and stop cell coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   108
of the command and possibly thickness and colors, etc.
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
heading2("$TableStyle$ User Methods")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   111
heading3("$TableStyle(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   112
disc("""The creation method initializes the $TableStyle$ with the argument
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   113
command sequence as an example:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   114
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   115
    LIST_STYLE = TableStyle(
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   116
        [('LINEABOVE', (0,0), (-1,0), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   117
        ('LINEABOVE', (0,1), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   118
        ('LINEBELOW', (0,-1), (-1,-1), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   119
        ('ALIGN', (1,1), (-1,-1), 'RIGHT')]
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
heading3("$TableStyle.add(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   123
disc("""This method allows you to add commands to an existing
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   124
$TableStyle$, i.e. you can build up $TableStyles$ in multiple statements.
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
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   127
    LIST_STYLE.add('BACKGROUND', (0,0), (-1,0), colors.Color(0,0.7,0.7))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   128
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   129
heading3("$TableStyle.getCommands()$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   130
disc("""This method returns the sequence of commands of the instance.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   131
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   132
    cmds = LIST_STYLE.getCommands()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   133
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   134
heading2("$TableStyle$ Commands")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   135
disc("""The commands passed to $TableStyles$ come in three main groups
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   136
which affect the table background, draw lines, or set cell styles.
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("""The first element of each command is its identifier,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   139
the second and third arguments determine the cell coordinates of
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   140
the box of cells which are affected with negative coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   141
counting backwards from the limit values as in <b>Python</b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   142
indexing. The coordinates are given as
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   143
(column, row) which follows the spreadsheet 'A1' model, but not
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   144
the more natural (for mathematicians) 'RC' ordering.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   145
The top left cell is (0, 0) the bottom right is (-1, -1). Depending on
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   146
the command various extra (???) occur at indices beginning at 3 on.
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
heading3("""$TableStyle$ Cell Formatting Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   149
disc("""The cell formatting commands all begin with an identifier, followed by
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   150
the start and stop cell definitions and the perhaps other arguments.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   151
the cell formatting commands are:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   152
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   153
FONT                    - takes fontname, optional fontsize and optional leading.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   154
FONTNAME (or FACE)      - takes fontname.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   155
FONTSIZE (or SIZE)      - takes fontsize in points; leading may get out of sync.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   156
LEADING                 - takes leading in points.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   157
TEXTCOLOR               - takes a color name or (R,G,B) tuple.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   158
ALIGNMENT (or ALIGN)    - takes one of LEFT, RIGHT and CENTRE (or CENTER) or DECIMAL.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   159
LEFTPADDING             - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   160
RIGHTPADDING            - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   161
BOTTOMPADDING           - takes an integer, defaults to 3.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   162
TOPPADDING              - takes an integer, defaults to 3.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   163
BACKGROUND              - takes a color.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   164
ROWBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   165
COLBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   166
VALIGN                  - takes one of TOP, MIDDLE or the default BOTTOM
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   167
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   168
disc("""This sets the background cell color in the relevant cells.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   169
The following example shows the $BACKGROUND$, and $TEXTCOLOR$ commands in action:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   170
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   171
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   172
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   173
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   174
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   175
t=Table(data)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   176
t.setStyle(TableStyle([('BACKGROUND',(1,1),(-2,-2),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   177
                        ('TEXTCOLOR',(0,0),(1,-1),colors.red)]))
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
disc("""To see the effects of the alignment styles we need  some widths
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   180
and a grid, but it should be easy to see where the styles come from.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   181
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   182
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   183
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   184
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   185
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   186
t=Table(data,5*[0.4*inch], 4*[0.4*inch])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   187
t.setStyle(TableStyle([('ALIGN',(1,1),(-2,-2),'RIGHT'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   188
                        ('TEXTCOLOR',(1,1),(-2,-2),colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   189
                        ('VALIGN',(0,0),(0,-1),'TOP'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   190
                        ('TEXTCOLOR',(0,0),(0,-1),colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   191
                        ('ALIGN',(0,-1),(-1,-1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   192
                        ('VALIGN',(0,-1),(-1,-1),'MIDDLE'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   193
                        ('TEXTCOLOR',(0,-1),(-1,-1),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   194
                        ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   195
                        ('BOX', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   196
                        ]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   197
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   198
heading3("""$TableStyle$ Line Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   199
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   200
    Line commands begin with the identifier, the start and stop cell coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   201
    and always follow this with the thickness (in points) and color of the desired lines. Colors can be names,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   202
    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
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   203
    command names are: GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   204
    and LINEAFTER. BOX and OUTLINE are equivalent, and GRID is the equivalent of applying both BOX and
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   205
    INNERGRID.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   206
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   207
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   208
disc("""We can see some line commands in action with the following example.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   209
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   210
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   211
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   212
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   213
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   214
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   215
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   216
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   217
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   218
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   219
                    ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   220
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   221
disc("""Line commands cause problems for tables when they split; the following example
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   222
shows a table being split in various positions""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   223
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   224
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   225
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   226
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   227
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   228
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   229
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   230
                ('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   231
                ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   232
                ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   233
                ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   234
                ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   235
                ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   236
                ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   237
                ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   238
                ])
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
t=getStory()[-1]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   241
getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   242
for s in t.split(4*inch,30):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   243
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   244
    getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   245
getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   246
for s in t.split(4*inch,36):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   247
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   248
    getStory().append(Spacer(0,6))
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
disc("""When unsplit and split at the first or second row.""")
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
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   253
heading3("""Complex Cell Values""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   254
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   255
As mentioned above we can have complicated cell values including $Paragraphs$, $Images$ and other $Flowables$
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   256
or lists of the same. To see this in operation consider the following code and the table it produces.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   257
Note that the $Image$ has a white background which will obscure any background you choose for the cell.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   258
To get better results you should use a transparent background.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   259
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   260
import os, reportlab.platypus
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   261
I = '../images/replogo.gif'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   262
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   263
I = Image('%s')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   264
I.drawHeight = 1.25*inch*I.drawHeight / I.drawWidth
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   265
I.drawWidth = 1.25*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   266
P0 = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   267
               <b>A pa<font color=red>r</font>a<i>graph</i></b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   268
               <super><font color=yellow>1</font></super>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   269
               styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   270
P = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   271
       <para align=center spaceb=3>The <b>ReportLab Left
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   272
       <font color=red>Logo</font></b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   273
       Image</para>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   274
       styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   275
data=  [['A',   'B', 'C',     P0, 'D'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   276
        ['00', '01', '02', [I,P], '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   277
        ['10', '11', '12', [P,I], '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   278
        ['20', '21', '22',  '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   279
        ['30', '31', '32',  '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   280
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   281
t=Table(data,style=[('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   282
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   283
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   284
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   285
                    ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   286
                    ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   287
                    ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   288
                    ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   289
                    ('GRID',(0,0),(-1,-1),0.5,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   290
                    ('VALIGN',(3,0),(3,0),'BOTTOM'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   291
                    ('BACKGROUND',(3,0),(3,0),colors.limegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   292
                    ('BACKGROUND',(3,1),(3,1),colors.khaki),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   293
                    ('ALIGN',(3,1),(3,1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   294
                    ('BACKGROUND',(3,2),(3,2),colors.beige),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   295
                    ('ALIGN',(3,2),(3,2),'LEFT'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   296
                    ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   297
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   298
t._argW[3]=1.5*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   299
"""%I)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   300
heading3("""$TableStyle$ Span Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   301
disc("""Our $Table$ classes support the concept of spanning, but it isn't specified in the same way
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   302
as html. The style specification
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   303
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   304
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   305
SPAN, (sc,sr), (ec,er)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   306
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   307
disc("""indicates that the cells in columns $sc$ - $ec$ and rows $sr$ - $er$ should be combined into a super cell
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   308
with contents determined by the cell $(sc, sr)$. The other cells should be present, but should contain empty strings 
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   309
or you may get unexpected results.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   310
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   311
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   312
data=  [['Top\\nLeft', '', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   313
        ['', '', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   314
        ['20', '21', '22', 'Bottom\\nRight', ''],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   315
        ['30', '31', '32', '', '']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   316
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   317
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   318
                ('BACKGROUND',(0,0),(1,1),colors.palegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   319
                ('SPAN',(0,0),(1,1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   320
                ('BACKGROUND',(-2,-2),(-1,-1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   321
                ('SPAN',(-2,-2),(-1,-1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   322
                ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   323
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   324
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   325
disc("""notice that we don't need to be conservative with our $GRID$ command. The spanned cells are not drawn through.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   326
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   327
heading3("""Special $TableStyle$ Indeces""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   328
disc("""In any style command the first row index may be set to one of the special strings
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   329
$'splitlast'$ or $'splitfirst'$ to indicate that the style should be used only for the last row of
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   330
a split table, or the first row of a continuation. This allows splitting tables with nicer effects around the split.""")  
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   331
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   332
heading1("""Other Useful $Flowables$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   333
heading2("""$Preformatted(text, style, bulletText = None, dedent=0)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   334
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   335
Creates a preformatted paragraph which does no wrapping, line splitting or other manipulations.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   336
No $XML$ style tags are taken account of in the text.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   337
If dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   338
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   339
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   340
heading2("""$XPreformatted(text, style, bulletText = None, dedent=0, frags=None)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   341
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   342
This is a non rearranging form of the $Paragraph$ class; $XML$ tags are allowed in
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   343
$text$ and have the same meanings as for the $Paragraph$ class.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   344
As for $Preformatted$, if dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   345
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   346
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   347
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   348
from reportlab.lib.styles import getSampleStyleSheet
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   349
stylesheet=getSampleStyleSheet()
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   350
normalStyle = stylesheet['Normal']
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   351
text='''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   352
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   353
   This is a non rearranging form of the <b>Paragraph</b> class;
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   354
   <b><font color=red>XML</font></b> tags are allowed in <i>text</i> and have the same
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   355
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   356
      meanings as for the <b>Paragraph</b> class.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   357
   As for <b>Preformatted</b>, if dedent is non zero <font color=red size=+1>dedent</font>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   358
       common leading spaces will be removed from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   359
   front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   360
   You can have &amp;amp; style entities as well for &amp; &lt; &gt; and &quot;.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   361
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   362
'''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   363
t=XPreformatted(text,normalStyle,dedent=3)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   364
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   365
heading2("""$Image(filename, width=None, height=None)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   366
disc("""Create a flowable which will contain the image defined by the data in file $filename$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   367
The default <b>PDF</b> image type <i>jpeg</i> is supported and if the <b>PIL</b> extension to <b>Python</b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   368
is installed the other image types can also be handled. If $width$ and or $height$ are specified
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   369
then they determine the dimension of the displayed image in <i>points</i>. If either dimension is
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   370
not specified (or specified as $None$) then the corresponding pixel dimension of the image is assumed
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   371
to be in <i>points</i> and used.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   372
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   373
I=os.path.join(os.path.dirname(reportlab.__file__),'docs','images','lj8100.jpg')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   374
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   375
Image("lj8100.jpg")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   376
""",after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   377
disc("""will display as""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   378
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   379
    getStory().append(Image(I))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   380
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   381
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   382
disc("""whereas""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   383
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   384
im = Image("lj8100.jpg", width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   385
im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   386
""", after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   387
disc('produces')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   388
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   389
    im = Image(I, width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   390
    im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   391
    getStory().append(Image(I, width=2*inch, height=2*inch))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   392
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   393
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   394
heading2("""$Spacer(width, height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   395
disc("""This does exactly as would be expected; it adds a certain amount of space into the story.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   396
At present this only works for vertical space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   397
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   398
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   399
heading2("""$PageBreak()$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   400
disc("""This $Flowable$ represents a page break. It works by effectively consuming all vertical
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   401
space given to it. This is sufficient for a single $Frame$ document, but would only be a
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   402
frame break for multiple frames so the $BaseDocTemplate$ mechanism
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   403
detects $pageBreaks$ internally and handles them specially.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   404
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   405
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   406
heading2("""$CondPageBreak(height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   407
disc("""This $Flowable$ attempts to force a $Frame$ break if insufficient vertical space remains
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   408
in the current $Frame$. It is thus probably wrongly named and should probably be renamed as
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   409
$CondFrameBreak$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   410
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   411
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   412
heading2("""$KeepTogether(flowables)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   413
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   414
This compound $Flowable$ takes a list of $Flowables$ and attempts to keep them in the same $Frame$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   415
If the total height of the $Flowables$ in the list $flowables$ exceeds the current frame's available
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   416
space then all the space is used and a frame break is forced.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   417
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   418
CPage(1)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   419
heading2("""$TableOfContents()$""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   420
disc("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   421
A table of contents can be generated by using the $TableOfContents$ flowable.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   422
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   423
The following steps are needed to add a table of contents to your document:
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   424
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   425
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   426
disc("""Create an instance of $TableOfContents$. Override the level styles (optional) and add the object to the story:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   427
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   428
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   429
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   430
PS = ParagraphStyle
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   431
toc.levelStyles = [
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   432
    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   433
            leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   434
    PS(fontSize=12, name='TOCHeading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   435
            leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   436
    PS(fontSize=10, name='TOCHeading3',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   437
            leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   438
    PS(fontSize=10, name='TOCHeading4',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   439
            leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   440
]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   441
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   442
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   443
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   444
disc("""Entries to the table of contents can be done either manually by calling the $addEntry$ method on the $TableOfContents$ object
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   445
or automatically by sending a $'TOCEntry'$ notification in the $afterFlowable$ method of the $DocTemplate$ you are using:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   446
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   447
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   448
def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   449
    """Detect Level 1 and 2 headings, build outline,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   450
    and track chapter title."""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   451
    if isinstance(flowable, Paragraph):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   452
        txt = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   453
        if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   454
            # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   455
            self.notify('TOCEntry', (0, txt, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   456
        elif style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   457
            # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   458
            self.notify('TOCEntry', (1, txt, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   459
        # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   460
''')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   461
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   462
disc("""This way, whenever a paragraph of style $'Heading1'$ or $'Heading2'$ is added to the story, it will appear in the table of contents.""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   463
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   464
disc("""Finally you need to use the $multiBuild$ method of the DocTemplate because tables of contents need several passes to be generated:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   465
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   466
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   467
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   468
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   469
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   470
disc("""Below is a simple but working example of a document with a table of contents:""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   471
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   472
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   473
from reportlab.lib.styles import ParagraphStyle as PS
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   474
from reportlab.platypus import PageBreak
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   475
from reportlab.platypus.paragraph import Paragraph
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   476
from reportlab.platypus.doctemplate import PageTemplate, BaseDocTemplate
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   477
from reportlab.platypus.tableofcontents import TableOfContents
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   478
from reportlab.platypus.frames import Frame
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   479
from reportlab.lib.units import cm
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   480
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   481
class MyDocTemplate(BaseDocTemplate):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   482
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   483
    def __init__(self, filename, **kw):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   484
        self.allowSplitting = 0
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   485
        apply(BaseDocTemplate.__init__, (self, filename), kw)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   486
        template = PageTemplate('normal', [Frame(2.5*cm, 2.5*cm, 15*cm, 25*cm, id='F1')])
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   487
        self.addPageTemplates(template)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   488
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   489
    def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   490
        "Registers TOC entries."
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   491
        if flowable.__class__.__name__ == 'Paragraph':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   492
            text = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   493
            style = flowable.style.name
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   494
            if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   495
                self.notify('TOCEntry', (0, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   496
            if style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   497
                self.notify('TOCEntry', (1, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   498
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   499
h1 = PS(name = 'Heading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   500
       fontSize = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   501
       leading = 16)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   502
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   503
h2 = PS(name = 'Heading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   504
       fontSize = 12,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   505
       leading = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   506
       leftIndent = delta)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   507
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   508
# Build story.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   509
story = []
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   510
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   511
# For conciseness we use the same styles for headings and TOC entries
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   512
toc.levelStyles = [h1, h2]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   513
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   514
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   515
story.append(Paragraph('First heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   516
story.append(Paragraph('Text in first heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   517
story.append(Paragraph('First sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   518
story.append(Paragraph('Text in first sub heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   519
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   520
story.append(Paragraph('Second sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   521
story.append(Paragraph('Text in second sub heading', PS('body')))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   522
story.append(Paragraph('Last heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   523
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   524
doc = MyDocTemplate('mintoc.pdf')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   525
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   526
''')