docs/userguide/ch6_tables.py
author rgbecker
Tue, 11 Jul 2000 12:37:20 +0000
changeset 349 d96f5098af2b
parent 341 27c68d524504
child 356 377367fe28cb
permissions -rw-r--r--
Pargraph & Table
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     1
#ch6_tables
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     2
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     3
from genuserguide import *
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     4
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     5
heading1("Tables and TableStyles")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     6
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     7
The $Table class$ is derived from the $Flowable class$ and is intended
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     8
as a simple textual gridding mechanism. $Table$ cells can hold anything which can be converted to
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     9
a <b>Python</b> $string$. 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    10
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    11
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    12
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    13
$Tables$ are created by passing the constructor a sequence of column widths,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    14
a sequence of row heights and the data in
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    15
row order. Drawing of the table can be controlled by using a $TableStyle$ instance. This allows control of the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    16
color and weight of the lines (if any), and the font, alignment and padding of the text.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    17
A primitive automatic row height and or column width calculation mechanism is provided for.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    18
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    19
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    20
heading2('$class Table$ User Methods')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    21
disc("""These are the main methods which are of interest to the client programmer""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    22
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    23
heading4('$Table(colWidths, rowHeights, data)$')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    24
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    25
disc("""The arguments are fairly obvious, the $colWidths$ argument is a sequence
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    26
of numbers or possibly $None$, representing the widths of the rows. The number of elements
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    27
in $colWidths$ determines the number of columns in the table.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    28
A value of $None$ means that the corresponding column width should be calculated automatically""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    29
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    30
disc("""The $rowHeights$ argument is a sequence
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    31
of numbers or possibly $None$, representing the heights of the rows. The number of elements
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    32
in $rowHeights$ determines the number of rows in the table.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    33
A value of $None$ means that the corresponding row height should be calculated automatically""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    34
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    35
disc("""The $data$ argument is a sequence of sequences of cell values each of which
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    36
should be convertible to a string value using the $str$ function. The first row of cell values
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    37
is in $data[0]$ ie the values are in row order. The $i$, $j$<sup>th.</sup> cell value is in
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    38
$data[i][j]$. Newline characters $'\\n'$ in cell values are treated as line split characters and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    39
are used at <i>draw</i> time to format the cell into lines.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    40
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    41
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    42
heading4('$Table.$setStyle(tblStyle)$')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    43
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    44
This method applies a particular instance of $class TableStyle$ (discussed below)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    45
to the $Table$ instance. This is the only way to get $tables$ to appear
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    46
in a nicely formatted way.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    47
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    48
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    49
Successive uses of the $setStyle$ method apply the styles in an additive fashion.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    50
That is later applications override earlier ones where thes overlap.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    51
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    52
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    53
heading2('$class TableStyle$')
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    54
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    55
This $class$ is created by passing it a sequence of <i>commands</i>, each command
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    56
is a tuple identified by its first element which is a string; the remaining
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    57
elements of the command tuple represent the start and finish cell coordinates
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    58
of the command and possibly thickness and colors etc.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    59
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    60
heading2("$TableStyle$ User Methods")
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    61
heading3("$TableStyle(commandSequence)$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    62
disc("""The creation method initializes the $TableStyle$ with the argument
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    63
command sequence as an example:""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    64
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    65
    LIST_STYLE = TableStyle(
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    66
        [('LINEABOVE', (0,0), (-1,0), 2, colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    67
        ('LINEABOVE', (0,1), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    68
        ('LINEBELOW', (0,-1), (-1,-1), 2, colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    69
        ('ALIGN', (1,1), (-1,-1), 'RIGHT')]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    70
        )
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    71
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    72
heading3("$TableStyle.add(commandSequence)$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    73
disc("""This method allows you to add commands to an existing
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    74
$TableStyle$, ie you can build up $TableStyles$ in multiple statements.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    75
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    76
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    77
    LIST_STYLE.add([('BACKGROUND', (0,0), (-1,0), colors.Color(0,0.7,0.7))])
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    78
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    79
heading3("$TableStyle.getCommands()$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    80
disc("""This method returns the sequence of commands of the instance.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    81
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    82
    cmds = LIST_STYLE.getCommands()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    83
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    84
heading2("$TableStyle$ Commands")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    85
disc("""The commands passed to $TableStyles$ come in three main groups
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    86
which affect the table background, draw lines, or set cell styles.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    87
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    88
disc("""The first element of each command is its identifier,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    89
the second and third arguments determine the cell coordinates of
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    90
the box of cells which are affected with negative coordinates
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    91
counting backwards from the limit values as in <b>Python</b>
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    92
indexing. The coordinates are given as
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    93
(column,row) which follows the spreadsheet 'A1' model, but not
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    94
the more natural (for mathematicians) 'RC' ordering.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    95
The top left cell is (0,0) the bottom right is (-1,-1). Depending on
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    96
the command various extra occur at indeces beginning at 3 on.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    97
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
    98
heading3("""$TableStyle$ Cell Formatting Commands""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    99
disc("""The cell formatting commands all begin with an identifier, followed by
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   100
the start and stop cell definitions and the perhaps other arguments.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   101
the cell formatting commands are:""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   102
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   103
FONT                    - takes fontname, fontsize and (optional) leading.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   104
TEXTCOLOR               - takes a color name or (R,G,B) tuple.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   105
ALIGNMENT (or ALIGN)    - takes one of LEFT, RIGHT and CENTRE (or CENTER).
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   106
LEFTPADDING             - takes an integer, defaults to 6.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   107
RIGHTPADDING            - takes an integer, defaults to 6.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   108
BOTTOMPADDING           - takes an integer, defaults to 3.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   109
TOPPADDING              - takes an integer, defaults to 3.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   110
BACKGROUND              - takes a color.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   111
VALIGN                  - takes one of TOP, MIDDLE or the default BOTTOM
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   112
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   113
disc("""This sets the background cell color in the relevant cells.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   114
The following example shows the $BACKGROUND$, and $TEXTCOLOR$ commands in action""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   115
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   116
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   117
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   118
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   119
        ['30', '31', '32', '33', '34']]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   120
t=Table(5*[None], 4*[None], data)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   121
t.setStyle(TableStyle([('BACKGROUND',(1,1),(-2,-2),colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   122
                        ('TEXTCOLOR',(0,0),(1,-1),colors.red)]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   123
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   124
disc("""To see the effects of the alignment styles we need  some widths
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   125
and a grid, but it should be easy to see where the styles come from.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   126
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   127
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   128
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   129
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   130
        ['30', '31', '32', '33', '34']]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   131
t=Table(5*[0.4*inch], 4*[0.4*inch], data)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   132
t.setStyle(TableStyle([('ALIGN',(1,1),(-2,-2),'RIGHT'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   133
                        ('TEXTCOLOR',(1,1),(-2,-2),colors.red),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   134
                        ('VALIGN',(0,0),(0,-1),'TOP'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   135
                        ('TEXTCOLOR',(0,0),(0,-1),colors.blue),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   136
                        ('ALIGN',(0,-1),(-1,-1),'CENTER'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   137
                        ('VALIGN',(0,-1),(-1,-1),'MIDDLE'),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   138
                        ('TEXTCOLOR',(0,-1),(-1,-1),colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   139
                        ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   140
                        ('BOX', (0,0), (-1,-1), 0.25, colors.black),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   141
                        ]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   142
""")
349
d96f5098af2b Pargraph & Table
rgbecker
parents: 341
diff changeset
   143
heading3("""$TableStyle$ Line Commands""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   144
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   145
    Line commands begin with the identfier, the start and stop cell coordinates
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   146
    and always follow this with the thickness (in points) and color of the desired lines. Colors can be names,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   147
    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
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   148
    command names are: GRID, BOX, OUTLINE, INNERGRID, LINEBELOW, LINEABOVE, LINEBEFORE
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   149
    and LINEAFTER. BOX and OUTLINE are equivalent, and GRID is the equivalent of applying both BOX and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   150
    INNERGRID.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   151
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   152
disc("""We can see some line commands in action with the following example.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   153
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   154
EmbeddedCode("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   155
data=  [['00', '01', '02', '03', '04'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   156
        ['10', '11', '12', '13', '14'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   157
        ['20', '21', '22', '23', '24'],
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   158
        ['30', '31', '32', '33', '34']]
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   159
t=Table(5*[None], 4*[None], data)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   160
t.setStyle(TableStyle([('GRID',(1,1),(-2,-2),1,colors.green),
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   161
                        ('BOX',(0,0),(1,-1),2,colors.red)]))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   162
""")