docs/userguide/ch6_tables.py
author robin <robin@reportlab.com>
Tue, 07 Mar 2017 10:00:34 +0000
changeset 4330 617ffa6bbdc8
parent 4324 a1aed0f6a3b1
child 4370 823a8c33ce43
permissions -rw-r--r--
changes for release 3.4.0
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
4330
617ffa6bbdc8 changes for release 3.4.0
robin <robin@reportlab.com>
parents: 4324
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2017
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     2
#see license.txt for license details
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
     3
#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/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,
4254
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
    60
repeatRows=0, repeatCols=0, rowSplitRange=None, spaceBefore=None, spaceAfter=None)$""")
2963
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
4197
23596473c5b5 userguide fixes version-->3.1.60
robin
parents: 3794
diff changeset
    90
disc("""The $repeatRows$ argument specifies the number or a tuple of leading rows
23596473c5b5 userguide fixes version-->3.1.60
robin
parents: 3794
diff changeset
    91
that should be repeated when the $Table$ is asked to split itself. If it is a tuple it should specify which of the leading rows should be repeated; this allows
23596473c5b5 userguide fixes version-->3.1.60
robin
parents: 3794
diff changeset
    92
for cases where the first appearance of the table hsa more leading rows than later split parts.
23596473c5b5 userguide fixes version-->3.1.60
robin
parents: 3794
diff changeset
    93
The $repeatCols$ argument is currently ignored as a $Table$ cannot be split by column.""")
4254
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
    94
disc("""The $spaceBefore$ &amp; $spaceAfter$ arguments may be used to put extra space before or after the table when renedered in a $platypus$ story.""")
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
    95
disc("""The $rowSplitRange$ argument may be used to control the splitting of the table to a subset of its rows; that can be to prevent splitting too close to the beginning or end of the table.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    96
heading4('$Table.setStyle(tblStyle)$')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    97
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
    98
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
    99
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
   100
in a nicely formatted way.
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
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   103
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
   104
That is, later applications override earlier ones where they overlap.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   105
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   106
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   107
heading2('$TableStyle$')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   108
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   109
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
   110
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
   111
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
   112
of the command and possibly thickness and colors, etc.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   113
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   114
heading2("$TableStyle$ User Methods")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   115
heading3("$TableStyle(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   116
disc("""The creation method initializes the $TableStyle$ with the argument
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   117
command sequence as an example:""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   118
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   119
    LIST_STYLE = TableStyle(
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   120
        [('LINEABOVE', (0,0), (-1,0), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   121
        ('LINEABOVE', (0,1), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   122
        ('LINEBELOW', (0,-1), (-1,-1), 2, colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   123
        ('ALIGN', (1,1), (-1,-1), 'RIGHT')]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   124
        )
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
heading3("$TableStyle.add(commandSequence)$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   127
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
   128
$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
   129
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   130
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   131
    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
   132
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   133
heading3("$TableStyle.getCommands()$")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   134
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
   135
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   136
    cmds = LIST_STYLE.getCommands()
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
heading2("$TableStyle$ Commands")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   139
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
   140
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
   141
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   142
disc("""The first element of each command is its identifier,
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   143
the second and third arguments determine the cell coordinates of
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   144
the box of cells which are affected with negative coordinates
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   145
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
   146
indexing. The coordinates are given as
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   147
(column, row) which follows the spreadsheet 'A1' model, but not
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   148
the more natural (for mathematicians) 'RC' ordering.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   149
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
   150
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
   151
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   152
heading3("""$TableStyle$ Cell Formatting Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   153
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
   154
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
   155
the cell formatting commands are:""")
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   156
npeg("""
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   157
FONT                    - takes fontname, optional fontsize and optional leading.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   158
FONTNAME (or FACE)      - takes fontname.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   159
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
   160
LEADING                 - takes leading in points.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   161
TEXTCOLOR               - takes a color name or (R,G,B) tuple.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   162
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
   163
LEFTPADDING             - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   164
RIGHTPADDING            - takes an integer, defaults to 6.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   165
BOTTOMPADDING           - takes an integer, defaults to 3.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   166
TOPPADDING              - takes an integer, defaults to 3.
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   167
BACKGROUND              - takes a color defined by an object, string name or numeric tuple/list,
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   168
                          or takes a list/tuple describing a desired gradient fill which should
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   169
                          contain three elements of the form [DIRECTION, startColor, endColor]
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   170
                          where DIRECTION is either VERTICAL or HORIZONTAL.
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   171
ROWBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   172
COLBACKGROUNDS          - takes a list of colors to be used cyclically.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   173
VALIGN                  - takes one of TOP, MIDDLE or the default BOTTOM
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   174
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   175
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
   176
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
   177
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   178
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   179
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   180
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   181
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   182
t=Table(data)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   183
t.setStyle(TableStyle([('BACKGROUND',(1,1),(-2,-2),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   184
                        ('TEXTCOLOR',(0,0),(1,-1),colors.red)]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   185
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   186
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
   187
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
   188
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   189
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   190
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   191
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   192
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   193
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
   194
t.setStyle(TableStyle([('ALIGN',(1,1),(-2,-2),'RIGHT'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   195
                        ('TEXTCOLOR',(1,1),(-2,-2),colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   196
                        ('VALIGN',(0,0),(0,-1),'TOP'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   197
                        ('TEXTCOLOR',(0,0),(0,-1),colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   198
                        ('ALIGN',(0,-1),(-1,-1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   199
                        ('VALIGN',(0,-1),(-1,-1),'MIDDLE'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   200
                        ('TEXTCOLOR',(0,-1),(-1,-1),colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   201
                        ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   202
                        ('BOX', (0,0), (-1,-1), 0.25, colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   203
                        ]))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   204
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   205
heading3("""$TableStyle$ Line Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   206
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   207
    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
   208
    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
   209
    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
   210
    command names are: GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   211
    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
   212
    INNERGRID.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   213
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   214
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   215
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
   216
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   217
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   218
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   219
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   220
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   221
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   222
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
   223
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   224
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   225
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   226
                    ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   227
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   228
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
   229
shows a table being split in various positions""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   230
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   231
data=  [['00', '01', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   232
        ['10', '11', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   233
        ['20', '21', '22', '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   234
        ['30', '31', '32', '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   235
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   236
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   237
                ('GRID',(1,1),(-2,-2),1,colors.green),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   238
                ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   239
                ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   240
                ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   241
                ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   242
                ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   243
                ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   244
                ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   245
                ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   246
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   247
t=getStory()[-1]
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
for s in t.split(4*inch,30):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   250
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   251
    getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   252
getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   253
for s in t.split(4*inch,36):
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   254
    getStory().append(s)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   255
    getStory().append(Spacer(0,6))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   256
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   257
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
   258
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   259
CPage(4.0)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   260
heading3("""Complex Cell Values""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   261
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   262
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
   263
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
   264
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
   265
To get better results you should use a transparent background.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   266
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   267
import os, reportlab.platypus
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   268
I = '../images/replogo.gif'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   269
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   270
I = Image('%s')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   271
I.drawHeight = 1.25*inch*I.drawHeight / I.drawWidth
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   272
I.drawWidth = 1.25*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   273
P0 = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   274
               <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
   275
               <super><font color=yellow>1</font></super>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   276
               styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   277
P = Paragraph('''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   278
       <para align=center spaceb=3>The <b>ReportLab Left
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   279
       <font color=red>Logo</font></b>
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   280
       Image</para>''',
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   281
       styleSheet["BodyText"])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   282
data=  [['A',   'B', 'C',     P0, 'D'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   283
        ['00', '01', '02', [I,P], '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   284
        ['10', '11', '12', [P,I], '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   285
        ['20', '21', '22',  '23', '24'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   286
        ['30', '31', '32',  '33', '34']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   287
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   288
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
   289
                    ('BOX',(0,0),(1,-1),2,colors.red),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   290
                    ('LINEABOVE',(1,2),(-2,2),1,colors.blue),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   291
                    ('LINEBEFORE',(2,1),(2,-2),1,colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   292
                    ('BACKGROUND', (0, 0), (0, 1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   293
                    ('BACKGROUND', (1, 1), (1, 2), colors.lavender),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   294
                    ('BACKGROUND', (2, 2), (2, 3), colors.orange),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   295
                    ('BOX',(0,0),(-1,-1),2,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   296
                    ('GRID',(0,0),(-1,-1),0.5,colors.black),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   297
                    ('VALIGN',(3,0),(3,0),'BOTTOM'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   298
                    ('BACKGROUND',(3,0),(3,0),colors.limegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   299
                    ('BACKGROUND',(3,1),(3,1),colors.khaki),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   300
                    ('ALIGN',(3,1),(3,1),'CENTER'),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   301
                    ('BACKGROUND',(3,2),(3,2),colors.beige),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   302
                    ('ALIGN',(3,2),(3,2),'LEFT'),
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
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   305
t._argW[3]=1.5*inch
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   306
"""%I)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   307
heading3("""$TableStyle$ Span Commands""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   308
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
   309
as html. The style specification
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
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   312
SPAN, (sc,sr), (ec,er)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   313
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   314
disc("""indicates that the cells in columns $sc$ - $ec$ and rows $sr$ - $er$ should be combined into a super cell
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   315
with contents determined by the cell $(sc, sr)$. The other cells should be present, but should contain empty strings
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   316
or you may get unexpected results.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   317
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   318
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   319
data=  [['Top\\nLeft', '', '02', '03', '04'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   320
        ['', '', '12', '13', '14'],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   321
        ['20', '21', '22', 'Bottom\\nRight', ''],
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   322
        ['30', '31', '32', '', '']]
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   323
t=Table(data,style=[
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   324
                ('GRID',(0,0),(-1,-1),0.5,colors.grey),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   325
                ('BACKGROUND',(0,0),(1,1),colors.palegreen),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   326
                ('SPAN',(0,0),(1,1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   327
                ('BACKGROUND',(-2,-2),(-1,-1), colors.pink),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   328
                ('SPAN',(-2,-2),(-1,-1)),
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   329
                ])
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   330
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   331
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   332
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
   333
""")
4254
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   334
heading3("""$TableStyle$ Miscellaneous Commands""")
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   335
disc("""To control $Table$ splitting the $NOSPLIT$ command may be used
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   336
The style specification
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   337
""")
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   338
eg("""
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   339
NOSPLIT, (sc,sr), (ec,er)
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   340
""")
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   341
disc("""demands that the cells in columns $sc$ - $ec$ and rows $sr$ - $er$ may not be split.""")
b0f678afac12 document table NOSPLIT style etc
robin
parents: 4252
diff changeset
   342
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   343
heading3("""Special $TableStyle$ Indeces""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   344
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
   345
$'splitlast'$ or $'splitfirst'$ to indicate that the style should be used only for the last row of
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   346
a split table, or the first row of a continuation. This allows splitting tables with nicer effects around the split.""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   347
3090
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   348
heading1("""Programming $Flowables$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   349
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   350
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
   351
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   352
heading2("""$DocAssign(self, var, expr, life='forever')$""")
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("""Assigns a variable of name $var$ to the expression $expr$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   355
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   356
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   357
DocAssign('i',3)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   358
""")
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   359
3090
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   360
heading2("""$DocExec(self, stmt, lifetime='forever')$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   361
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   362
disc("""Executes the statement $stmt$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   363
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   364
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   365
DocExec('i-=1')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   366
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   367
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   368
heading2("""$DocPara(self, expr, format=None, style=None, klass=None, escape=True)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   369
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   370
disc("""Creates a paragraph with the value of expr as text.
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   371
If format is specified it should use %(__expr__)s for string interpolation
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   372
of the expression expr (if any). It may also use %(name)s interpolations
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   373
for other variables in the namespace. E.g.:""")
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
DocPara('i',format='The value of i is %(__expr__)d',style=normal)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   377
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   378
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   379
heading2("""$DocAssert(self, cond, format=None)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   380
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   381
disc("""Raises an $AssertionError$ containing the $format$ string if $cond$ evaluates as $False$.""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   382
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   383
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   384
DocAssert(val, 'val is False')
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   385
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   386
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   387
heading2("""$DocIf(self, cond, thenBlock, elseBlock=[])$""")
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("""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
   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
DocIf('i>3',Paragraph('The value of i is larger than 3',normal),\\
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   393
        Paragraph('The value of i is not larger than 3',normal))
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   394
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   395
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   396
heading2("""$DocWhile(self, cond, whileBlock)$""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   397
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   398
disc("""Runs the $whileBlock$ while $cond$ evaluates to $True$. E.g.:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   399
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   400
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   401
DocAssign('i',5)
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   402
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
   403
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   404
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   405
disc("""This example produces a set of paragraphs of the form:""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   406
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   407
eg("""
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   408
The value of i is 5
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   409
The value of i is 4
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   410
The value of i is 3
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   411
The value of i is 2
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   412
The value of i is 1
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   413
""")
09b11ad17a4d Userguide documentation for programmable flowables.
jonas
parents: 3061
diff changeset
   414
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   415
heading1("""Other Useful $Flowables$""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   416
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
   417
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   418
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
   419
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
   420
If dedent is non zero $dedent$ common leading
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   421
spaces will be removed from the front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   422
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   423
heading3("Defining a maximum line length")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   424
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   425
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
   426
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   427
disc("""
3615
72e3393c2b81 Corrected spelling mistake in user guide
guillaume
parents: 3603
diff changeset
   428
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
   429
""")
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   430
disc("""
4258
d3e9de82a5aa add table cell support for simple background shadings, contributed by Jeffrey Creem jcreem@bitbucket
robin
parents: 4254
diff changeset
   431
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.
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   432
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   433
EmbeddedCode("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   434
from reportlab.lib.styles import getSampleStyleSheet
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   435
stylesheet=getSampleStyleSheet()
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   436
normalStyle = stylesheet['Code']
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   437
text='''
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   438
class XPreformatted(Paragraph):
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   439
    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
   440
        self.caseSensitive = caseSensitive
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   441
        if maximumLineLength and text:
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   442
            text = self.stopLine(text, maximumLineLength, splitCharacters)
3794
398ea04239b5 string module usage minimization
robin
parents: 3790
diff changeset
   443
        cleaner = lambda text, dedent=dedent: ''.join(_dedenter(text or '',dedent))
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   444
        self._setup(text, style, bulletText, frags, cleaner)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   445
'''
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   446
t=Preformatted(text,normalStyle,maxLineLength=60, newLineChars='> ')
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   447
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   448
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
   449
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   450
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
   451
$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
   452
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
   453
spaces will be removed from the front of each line.
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
EmbeddedCode("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   456
from reportlab.lib.styles import getSampleStyleSheet
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   457
stylesheet=getSampleStyleSheet()
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   458
normalStyle = stylesheet['Code']
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   459
text='''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   460
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   461
   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
   462
   <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
   463
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   464
      meanings as for the <b>Paragraph</b> class.
3790
2d62ae94f4cb docs: more fixes to userguide
robin
parents: 3617
diff changeset
   465
   As for <b>Preformatted</b>, if dedent is non zero <font color="red" size="+1">dedent</font>
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   466
       common leading spaces will be removed from the
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   467
   front of each line.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   468
   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
   469
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   470
'''
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   471
t=XPreformatted(text,normalStyle,dedent=3)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   472
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   473
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   474
heading2("""$Image(filename, width=None, height=None)$""")
4318
40df5b03ecad documentation changes
robin <robin@reportlab.com>
parents: 4258
diff changeset
   475
disc("""Create a flowable which will contain the image defined by the data in file $filename$ which can be
40df5b03ecad documentation changes
robin <robin@reportlab.com>
parents: 4258
diff changeset
   476
filepath, file like object or an instance of a $reportlab.graphics.shapes.Drawing$.
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   477
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
   478
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
   479
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
   480
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
   481
to be in <i>points</i> and used.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   482
""")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   483
I="../images/lj8100.jpg"
2963
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   484
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   485
Image("lj8100.jpg")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   486
""",after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   487
disc("""will display as""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   488
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   489
    getStory().append(Image(I))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   490
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   491
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   492
disc("""whereas""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   493
eg("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   494
im = Image("lj8100.jpg", width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   495
im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   496
""", after=0.1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   497
disc('produces')
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   498
try:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   499
    im = Image(I, width=2*inch, height=2*inch)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   500
    im.hAlign = 'CENTER'
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   501
    getStory().append(Image(I, width=2*inch, height=2*inch))
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   502
except:
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   503
    disc("""An image should have appeared here.""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   504
heading2("""$Spacer(width, height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   505
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
   506
At present this only works for vertical space.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   507
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   508
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   509
heading2("""$PageBreak()$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   510
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
   511
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
   512
frame break for multiple frames so the $BaseDocTemplate$ mechanism
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   513
detects $pageBreaks$ internally and handles them specially.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   514
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   515
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   516
heading2("""$CondPageBreak(height)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   517
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
   518
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
   519
$CondFrameBreak$.
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   520
""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   521
CPage(1)
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   522
heading2("""$KeepTogether(flowables)$""")
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   523
disc("""
c414c0ab69e7 reportlab-2.2: first stage of major re-org
rgbecker
parents:
diff changeset
   524
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
   525
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
   526
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
   527
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   528
CPage(1)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   529
heading2("""$TableOfContents()$""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   530
disc("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   531
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
   532
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   533
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
   534
""")
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
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
   537
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   538
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   539
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   540
PS = ParagraphStyle
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   541
toc.levelStyles = [
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   542
    PS(fontName='Times-Bold', fontSize=14, name='TOCHeading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   543
            leftIndent=20, firstLineIndent=-20, spaceBefore=5, leading=16),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   544
    PS(fontSize=12, name='TOCHeading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   545
            leftIndent=40, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   546
    PS(fontSize=10, name='TOCHeading3',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   547
            leftIndent=60, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   548
    PS(fontSize=10, name='TOCHeading4',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   549
            leftIndent=100, firstLineIndent=-20, spaceBefore=0, leading=12),
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   550
]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   551
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   552
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   553
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   554
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
   555
the $addEntry$ method on the $TableOfContents$ object or automatically by sending
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   556
a $'TOCEntry'$ notification in the $afterFlowable$ method of the $DocTemplate$
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   557
you are using.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   558
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   559
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
   560
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
   561
which the entry should point to.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   562
This list will usually be created in a document template's method
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   563
like afterFlowable(), making notification calls using the notify()
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   564
method with appropriate data like this:
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   565
""")
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   566
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   567
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   568
def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   569
    """Detect Level 1 and 2 headings, build outline,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   570
    and track chapter title."""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   571
    if isinstance(flowable, Paragraph):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   572
        txt = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   573
        if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   574
            # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   575
            self.notify('TOCEntry', (0, txt, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   576
        elif style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   577
            # ...
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   578
            key = 'h2-%s' % self.seq.nextf('heading2')
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   579
            self.canv.bookmarkPage(key)
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   580
            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
   581
        # ...
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   582
''')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   583
3061
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   584
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
   585
$Heading2$ entries will be clickable because a bookmarked key has been supplied.
ecd4963cc832 Userguide documentation for clickable TableOfContents entries.
jonas
parents: 3059
diff changeset
   586
""")
3059
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
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
   589
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   590
eg("""
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   591
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   592
""")
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   593
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   594
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
   595
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   596
eg('''
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   597
from reportlab.lib.styles import ParagraphStyle as PS
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   598
from reportlab.platypus import PageBreak
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   599
from reportlab.platypus.paragraph import Paragraph
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   600
from reportlab.platypus.doctemplate import PageTemplate, BaseDocTemplate
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   601
from reportlab.platypus.tableofcontents import TableOfContents
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   602
from reportlab.platypus.frames import Frame
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   603
from reportlab.lib.units import cm
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   604
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   605
class MyDocTemplate(BaseDocTemplate):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   606
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   607
    def __init__(self, filename, **kw):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   608
        self.allowSplitting = 0
3326
ce725978d11c Initial Python3 compatibility fixes
damian
parents: 3173
diff changeset
   609
        BaseDocTemplate.__init__(self, filename, **kw)
3059
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   610
        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
   611
        self.addPageTemplates(template)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   612
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   613
    def afterFlowable(self, flowable):
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   614
        "Registers TOC entries."
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   615
        if flowable.__class__.__name__ == 'Paragraph':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   616
            text = flowable.getPlainText()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   617
            style = flowable.style.name
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   618
            if style == 'Heading1':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   619
                self.notify('TOCEntry', (0, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   620
            if style == 'Heading2':
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   621
                self.notify('TOCEntry', (1, text, self.page))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   622
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   623
h1 = PS(name = 'Heading1',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   624
       fontSize = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   625
       leading = 16)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   626
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   627
h2 = PS(name = 'Heading2',
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   628
       fontSize = 12,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   629
       leading = 14,
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   630
       leftIndent = delta)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   631
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   632
# Build story.
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   633
story = []
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   634
toc = TableOfContents()
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   635
# 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
   636
toc.levelStyles = [h1, h2]
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   637
story.append(toc)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   638
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   639
story.append(Paragraph('First heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   640
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
   641
story.append(Paragraph('First sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   642
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
   643
story.append(PageBreak())
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   644
story.append(Paragraph('Second sub heading', h2))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   645
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
   646
story.append(Paragraph('Last heading', h1))
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   647
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   648
doc = MyDocTemplate('mintoc.pdf')
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   649
doc.multiBuild(story)
3a6ff201e927 Added documentation for the table of contents to the userguide.
jonas
parents: 3044
diff changeset
   650
''')
3173
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   651
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   652
CPage(1)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   653
heading2("""$SimpleIndex()$""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   654
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   655
An index can be generated by using the $SimpleIndex$ flowable.
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   656
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   657
The following steps are needed to add an index to your document:
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("""Use the index tag in paragraphs to index terms:""")
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
story = []
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
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   667
story.append('The third <index item="word" />word of this paragraph is indexed.')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   668
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   669
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   670
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
   671
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   672
eg('''
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   673
index = SimpleIndex(dot=' . ', headers=headers)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   674
story.append(index)
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   675
''')
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   676
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   677
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
   678
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   679
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   680
doc.build(story, canvasmaker=index.getCanvasMaker())
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   681
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   682
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   683
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
   684
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   685
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   686
<index item="terma,termb,termc" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   687
<index item="terma,termd" />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   688
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   689
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   690
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
   691
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   692
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
   693
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   694
eg("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   695
<index item="comma(,,), ,, ,...   " />
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   696
""")
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   697
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   698
disc("""
ded6e2bbf425 More documentation for SimpleIndex.
jonas
parents: 3090
diff changeset
   699
This indexes the terms "comma (,)", "," and "...".
3326
ce725978d11c Initial Python3 compatibility fixes
damian
parents: 3173
diff changeset
   700
""")
3483
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   701
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   702
heading2("""$ListFlowable(),ListItem()$""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   703
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   704
Use these classes to make ordered and unordered lists.  Lists can be nested.
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   705
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   706
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   707
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   708
$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
   709
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   710
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   711
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   712
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
   713
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   714
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   715
disc("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   716
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
   717
""")
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   718
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   719
EmbeddedCode("""
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   720
from reportlab.platypus import ListFlowable, ListItem
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   721
from reportlab.lib.styles import getSampleStyleSheet
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   722
styles = getSampleStyleSheet()
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   723
style = styles["Normal"]
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   724
t = ListFlowable(
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   725
[
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   726
Paragraph("Item no.1", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   727
ListItem(Paragraph("Item no. 2", style),bulletColor="green",value=7),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   728
ListFlowable(
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   729
                [
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   730
                Paragraph("sublist item 1", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   731
                ListItem(Paragraph('sublist item 2', style),bulletColor='red',value='square')
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   732
                ],
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   733
                bulletType='bullet',
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   734
                start='square',
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   735
                ),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   736
Paragraph("Item no.4", style),
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   737
],
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   738
bulletType='i'
c75bbc74e609 list flowables added to userguide
tim
parents: 3326
diff changeset
   739
)
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3485
diff changeset
   740
             """)
4324
a1aed0f6a3b1 documentation updates
robin <robin@reportlab.com>
parents: 4318
diff changeset
   741
a1aed0f6a3b1 documentation updates
robin <robin@reportlab.com>
parents: 4318
diff changeset
   742
disc("""To cope with nesting the $start$ parameter can be set to a list of possible starts; for $ul$ acceptable starts are any unicode character or specific names known to flowables.py eg
a1aed0f6a3b1 documentation updates
robin <robin@reportlab.com>
parents: 4318
diff changeset
   743
$bulletchar$, $circle$, $square$, $disc$, $diamond$, $diamondwx$, $rarrowhead$, $sparkle$, $squarelrs$ or  $blackstar$. For $ol$ the $start$ can be any character from $'1iaAI'$ to indicate different number styles.
a1aed0f6a3b1 documentation updates
robin <robin@reportlab.com>
parents: 4318
diff changeset
   744
""")
a1aed0f6a3b1 documentation updates
robin <robin@reportlab.com>
parents: 4318
diff changeset
   745