docs/userguide/ch6_tables.py
author guillaume
Thu, 27 Sep 2012 13:16:27 +0000
changeset 3615 72e3393c2b81
parent 3603 dd1d19c9cb98
child 3617 ae5744e97c42
permissions -rw-r--r--
Corrected spelling mistake in user guide
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 *
3483
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
     5
from reportlab.platypus import Image,ListFlowable, ListItem
2963
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
3090
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   332
heading1("""Programming $Flowables$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   333
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   334
disc("""The following flowables let you conditionally evaluate and execute expressions and statements at wrap time:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   335
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   336
heading2("""$DocAssign(self, var, expr, life='forever')$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   337
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   338
disc("""Assigns a variable of name $var$ to the expression $expr$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   339
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   340
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   341
DocAssign('i',3)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   342
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   343
                
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   344
heading2("""$DocExec(self, stmt, lifetime='forever')$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   345
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   346
disc("""Executes the statement $stmt$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   347
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   348
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   349
DocExec('i-=1')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   350
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   351
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   352
heading2("""$DocPara(self, expr, format=None, style=None, klass=None, escape=True)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   353
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   354
disc("""Creates a paragraph with the value of expr as text.
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   355
If format is specified it should use %(__expr__)s for string interpolation
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   356
of the expression expr (if any). It may also use %(name)s interpolations
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   357
for other variables in the namespace. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   358
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   359
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   360
DocPara('i',format='The value of i is %(__expr__)d',style=normal)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   361
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   362
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   363
heading2("""$DocAssert(self, cond, format=None)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   364
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   365
disc("""Raises an $AssertionError$ containing the $format$ string if $cond$ evaluates as $False$.""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   366
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   367
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   368
DocAssert(val, 'val is False')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   369
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   370
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   371
heading2("""$DocIf(self, cond, thenBlock, elseBlock=[])$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   372
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   373
disc("""If $cond$ evaluates as $True$, this flowable is replaced by the $thenBlock$ elsethe $elseBlock$.""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   374
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   375
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   376
DocIf('i>3',Paragraph('The value of i is larger than 3',normal),\\
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   377
        Paragraph('The value of i is not larger than 3',normal))
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   378
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   379
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   380
heading2("""$DocWhile(self, cond, whileBlock)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   381
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   382
disc("""Runs the $whileBlock$ while $cond$ evaluates to $True$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   383
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   384
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   385
DocAssign('i',5)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   386
DocWhile('i',[DocPara('i',format='The value of i is %(__expr__)d',style=normal),DocExec('i-=1')])
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   387
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   388
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   389
disc("""This example produces a set of paragraphs of the form:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   390
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   391
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   392
The value of i is 5
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   393
The value of i is 4
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   394
The value of i is 3
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   395
The value of i is 2
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   396
The value of i is 1
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   397
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   398
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   399
heading1("""Other Useful $Flowables$""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   400
heading2("""$Preformatted(text, style, bulletText=None, dedent=0, maxLineLength=None, splitChars=None, newLineChars=None)$""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   401
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   402
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
   403
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
   404
If dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   405
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   406
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   407
heading3("Defining a maximum line length")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   408
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   409
You can use the property $maxLineLength$ to define a maximum line length. If a line length exceeds this maximum value, the line will be automatically splitted.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   410
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   411
disc("""
3615
72e3393c2b81 Corrected spelling mistake in user guide
guillaume
parents: 3603
diff changeset
   412
The line will be split on any single character defined in $splitChars$. If no value is provided for this property, the line will be split on any of the following standard characters: space, colon, full stop, semi-colon, coma, hyphen, forward slash, back slash, left parenthesis, left square bracket and left curly brace
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   413
""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   414
disc("""
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   415
Characters can be automatically inserted at the beginning of each line that has been created. You can set the property $newLineChars$ to the characters you want to use. 
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   416
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   417
EmbeddedCode("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   418
from reportlab.lib.styles import getSampleStyleSheet
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   419
stylesheet=getSampleStyleSheet()
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   420
normalStyle = stylesheet['Code']
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   421
text='''
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   422
class XPreformatted(Paragraph):
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   423
    def __init__(self, text, style, bulletText = None, frags=None, caseSensitive=1):
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   424
        self.caseSensitive = caseSensitive
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   425
        if maximumLineLength and text:
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   426
            text = self.stopLine(text, maximumLineLength, splitCharacters)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   427
        cleaner = lambda text, dedent=dedent: string.join(_dedenter(text or '',dedent),'')
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   428
        self._setup(text, style, bulletText, frags, cleaner)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   429
'''
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   430
t=Preformatted(text,normalStyle,maxLineLength=60, newLineChars='> ')
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   431
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   432
heading2("""$XPreformatted(text, style, bulletText=None, dedent=0, frags=None)$""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   433
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   434
This is a non rearranging form of the $Paragraph$ class; XML tags are allowed in
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   435
$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
   436
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
   437
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   438
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   439
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   440
from reportlab.lib.styles import getSampleStyleSheet
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   441
stylesheet=getSampleStyleSheet()
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   442
normalStyle = stylesheet['Code']
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   443
text='''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   444
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   445
   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
   446
   <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
   447
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   448
      meanings as for the <b>Paragraph</b> class.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   449
   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
   450
       common leading spaces will be removed from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   451
   front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   452
   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
   453
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   454
'''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   455
t=XPreformatted(text,normalStyle,dedent=3)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   456
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   457
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   458
heading2("""$Image(filename, width=None, height=None)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   459
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
   460
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
   461
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
   462
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
   463
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
   464
to be in <i>points</i> and used.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   465
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   466
I="../images/lj8100.jpg"
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   467
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   468
Image("lj8100.jpg")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   469
""",after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   470
disc("""will display as""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   471
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   472
    getStory().append(Image(I))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   473
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   474
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   475
disc("""whereas""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   476
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   477
im = Image("lj8100.jpg", width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   478
im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   479
""", after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   480
disc('produces')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   481
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   482
    im = Image(I, width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   483
    im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   484
    getStory().append(Image(I, width=2*inch, height=2*inch))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   485
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   486
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   487
heading2("""$Spacer(width, height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   488
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
   489
At present this only works for vertical space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   490
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   491
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   492
heading2("""$PageBreak()$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   493
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
   494
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
   495
frame break for multiple frames so the $BaseDocTemplate$ mechanism
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   496
detects $pageBreaks$ internally and handles them specially.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   497
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   498
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   499
heading2("""$CondPageBreak(height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   500
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
   501
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
   502
$CondFrameBreak$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   503
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   504
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   505
heading2("""$KeepTogether(flowables)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   506
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   507
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
   508
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
   509
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
   510
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   511
CPage(1)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   512
heading2("""$TableOfContents()$""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   513
disc("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   514
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
   515
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   516
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
   517
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   518
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   519
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
   520
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   521
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   522
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   523
PS = ParagraphStyle
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   524
toc.levelStyles = [
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   525
    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   526
            leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   527
    PS(fontSize=12, name='TOCHeading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   528
            leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   529
    PS(fontSize=10, name='TOCHeading3',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   530
            leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   531
    PS(fontSize=10, name='TOCHeading4',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   532
            leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   533
]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   534
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   535
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   536
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   537
disc("""Entries to the table of contents can be done either manually by calling
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   538
the $addEntry$ method on the $TableOfContents$ object or automatically by sending
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   539
a $'TOCEntry'$ notification in the $afterFlowable$ method of the $DocTemplate$
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   540
you are using.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   541
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   542
The data to be passed to $notify$ is a list of three or four items countaining
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   543
a level number, the entry text, the page number and an optional destination key
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   544
which the entry should point to.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   545
This list will usually be created in a document template's method
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   546
like afterFlowable(), making notification calls using the notify()
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   547
method with appropriate data like this:
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   548
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   549
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   550
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   551
def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   552
    """Detect Level 1 and 2 headings, build outline,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   553
    and track chapter title."""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   554
    if isinstance(flowable, Paragraph):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   555
        txt = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   556
        if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   557
            # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   558
            self.notify('TOCEntry', (0, txt, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   559
        elif style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   560
            # ...
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   561
            key = 'h2-%s' % self.seq.nextf('heading2')
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   562
            self.canv.bookmarkPage(key)
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   563
            self.notify('TOCEntry', (1, txt, self.page, key))
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   564
        # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   565
''')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   566
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   567
disc("""This way, whenever a paragraph of style $'Heading1'$ or $'Heading2'$ is added to the story, it will appear in the table of contents.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   568
$Heading2$ entries will be clickable because a bookmarked key has been supplied.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   569
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   570
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   571
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
   572
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   573
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   574
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   575
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   576
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   577
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
   578
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   579
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   580
from reportlab.lib.styles import ParagraphStyle as PS
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   581
from reportlab.platypus import PageBreak
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   582
from reportlab.platypus.paragraph import Paragraph
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   583
from reportlab.platypus.doctemplate import PageTemplate, BaseDocTemplate
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   584
from reportlab.platypus.tableofcontents import TableOfContents
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   585
from reportlab.platypus.frames import Frame
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   586
from reportlab.lib.units import cm
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   587
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   588
class MyDocTemplate(BaseDocTemplate):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   589
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   590
    def __init__(self, filename, **kw):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   591
        self.allowSplitting = 0
3326
ce725978d11c Initial Python3 compatibility fixes
damian
parents: 3173
diff changeset
   592
        BaseDocTemplate.__init__(self, filename, **kw)
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   593
        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
   594
        self.addPageTemplates(template)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   595
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   596
    def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   597
        "Registers TOC entries."
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   598
        if flowable.__class__.__name__ == 'Paragraph':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   599
            text = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   600
            style = flowable.style.name
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   601
            if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   602
                self.notify('TOCEntry', (0, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   603
            if style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   604
                self.notify('TOCEntry', (1, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   605
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   606
h1 = PS(name = 'Heading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   607
       fontSize = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   608
       leading = 16)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   609
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   610
h2 = PS(name = 'Heading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   611
       fontSize = 12,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   612
       leading = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   613
       leftIndent = delta)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   614
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   615
# Build story.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   616
story = []
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   617
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   618
# 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
   619
toc.levelStyles = [h1, h2]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   620
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   621
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   622
story.append(Paragraph('First heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   623
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
   624
story.append(Paragraph('First sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   625
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
   626
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   627
story.append(Paragraph('Second sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   628
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
   629
story.append(Paragraph('Last heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   630
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   631
doc = MyDocTemplate('mintoc.pdf')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   632
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   633
''')
3173
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   634
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   635
CPage(1)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   636
heading2("""$SimpleIndex()$""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   637
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   638
An index can be generated by using the $SimpleIndex$ flowable.
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   639
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   640
The following steps are needed to add an index to your document:
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   641
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   642
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   643
disc("""Use the index tag in paragraphs to index terms:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   644
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   645
eg('''
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   646
story = []
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   647
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   648
...
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   649
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   650
story.append('The third <index item="word" />word of this paragraph is indexed.')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   651
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   652
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   653
disc("""Create an instance of $SimpleIndex$ and add it to the story where you want it to appear:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   654
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   655
eg('''
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   656
index = SimpleIndex(dot=' . ', headers=headers)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   657
story.append(index)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   658
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   659
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   660
disc("""The parameters which you can pass into the SimpleIndex constructor are explained in the reportlab reference. Now, build the document by using the canvas maker returned by SimpleIndex.getCanvasMaker():""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   661
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   662
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   663
doc.build(story, canvasmaker=index.getCanvasMaker())
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   664
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   665
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   666
disc("""To build an index with multiple levels, pass a comma-separated list of items to the item attribute of an index tag:""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   667
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   668
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   669
<index item="terma,termb,termc" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   670
<index item="terma,termd" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   671
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   672
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   673
disc("""terma will respresent the top-most level and termc the most specific term. termd and termb will appear in the same level inside terma.""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   674
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   675
disc("""If you need to index a term containing a comma, you will need to escape it by doubling it. To avoid the ambiguity of three consecutive commas (an escaped comma followed by a list separator or a list separator followed by an escaped comma?) introduce a space in the right position. Spaces at the beginning or end of terms will be removed.""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   676
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   677
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   678
<index item="comma(,,), ,, ,...   " />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   679
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   680
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   681
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   682
This indexes the terms "comma (,)", "," and "...".
3326
ce725978d11c Initial Python3 compatibility fixes
damian
parents: 3173
diff changeset
   683
""")
3483
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   684
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   685
heading2("""$ListFlowable(),ListItem()$""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   686
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   687
Use these classes to make ordered and unordered lists.  Lists can be nested.
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   688
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   689
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   690
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   691
$ListFlowable()$ will create an ordered list, which can contain any flowable.  The class has a number of parameters to change font, colour, size, style and position of list numbers, or of bullets in unordered lists.  The type of numbering can also be set to use lower or upper case letters ('A,B,C' etc.) or Roman numerals (capitals or lowercase) using the bulletType property.  To change the list to an unordered type, set bulletType='bullet'.
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   692
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   693
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   694
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   695
Items within a $ListFlowable()$ list can be changed from their default appearance by wrapping them in a $ListItem()$ class and setting its properties.
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   696
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   697
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   698
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   699
The following will create an ordered list, and set the third item to an unordered sublist.
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   700
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   701
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   702
EmbeddedCode("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   703
from reportlab.platypus import ListFlowable, ListItem
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   704
from reportlab.lib.styles import getSampleStyleSheet
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   705
styles = getSampleStyleSheet()
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   706
style = styles["Normal"]
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   707
t = ListFlowable(
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   708
[
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   709
Paragraph("Item no.1", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   710
ListItem(Paragraph("Item no. 2", style),bulletColor="green",value=7),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   711
ListFlowable(
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   712
                [
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   713
                Paragraph("sublist item 1", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   714
                ListItem(Paragraph('sublist item 2', style),bulletColor='red',value='square')
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   715
                ],
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   716
                bulletType='bullet',
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   717
                start='square',
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   718
                ),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   719
Paragraph("Item no.4", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   720
],
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   721
bulletType='i'
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   722
)
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   723
             """)