docs/userguide/graph_charts.py
author guillaume
Tue, 18 Sep 2012 12:42:58 +0000
changeset 3603 dd1d19c9cb98
parent 3591 73e1edc35b63
child 3617 ae5744e97c42
permissions -rw-r--r--
Added documentation for preformatted text wrapping and property tables for charts
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     1
#Copyright ReportLab Europe Ltd. 2000-2008
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     2
#see license.txt for license details
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     3
__version__=''' $Id$ '''
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     4
from tools.docco.rl_doc_utils import *
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     5
from reportlab.graphics.shapes import *
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     6
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     7
heading2("Charts")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     8
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
     9
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    10
The motivation for much of this is to create a flexible chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    11
package.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    12
This section presents a treatment of the ideas behind our charting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    13
model, what the design goals are and what components of the chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    14
package already exist.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    15
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    16
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    17
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    18
heading3("Design Goals")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    19
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    20
disc("Here are some of the design goals: ")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    21
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    22
disc("<i>Make simple top-level use really simple </i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    23
disc("""<para lindent=+36>It should be possible to create a simple chart with minimum lines of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    24
       code, yet have it 'do the right things' with sensible automatic
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    25
       settings. The pie chart snippets above do this. If a real chart has
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    26
       many subcomponents, you still should not need to interact with them
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    27
       unless you want to customize what they do.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    28
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    29
disc("<i>Allow precise positioning </i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    30
disc("""<para lindent=+36>An absolute requirement in publishing and graphic design is to control
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    31
       the placing and style of every element. We will try to have properties
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    32
       that specify things in fixed sizes and proportions of the drawing,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    33
       rather than having automatic resizing. Thus, the 'inner plot
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    34
       rectangle' will not magically change when you make the font size of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    35
       the y labels bigger, even if this means your labels can spill out of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    36
       the left edge of the chart rectangle. It is your job to preview the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    37
       chart and choose sizes and spaces which will work.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    38
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    39
disc("""<para lindent=+36>Some things do need to be automatic. For example, if you want to fit N
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    40
       bars into a 200 point space and don't know N in advance, we specify
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    41
       bar separation as a percentage of the width of a bar rather than a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    42
       point size, and let the chart work it out. This is still deterministic
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    43
       and controllable.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    44
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    45
disc("<i>Control child elements individually or as a group</i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    46
disc("""<para lindent=+36>We use smart collection classes that let you customize a group of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    47
       things, or just one of them. For example you can do this in our
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    48
       experimental pie chart:""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    49
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    50
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    51
d = Drawing(400,200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    52
pc = Pie()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    53
pc.x = 150
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    54
pc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    55
pc.data = [10,20,30,40,50,60]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    56
pc.labels = ['a','b','c','d','e','f']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    57
pc.slices.strokeWidth=0.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    58
pc.slices[3].popout = 20
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    59
pc.slices[3].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    60
pc.slices[3].strokeDashArray = [2,2]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    61
pc.slices[3].labelRadius = 1.75
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    62
pc.slices[3].fontColor = colors.red
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    63
d.add(pc, '')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    64
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    65
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    66
disc("""<para lindent=+36>pc.slices[3] actually lazily creates a little object which holds
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    67
       information about the slice in question; this will be used to format a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    68
       fourth slice at draw-time if there is one.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    69
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    70
disc("<i>Only expose things you should change </i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    71
disc("""<para lindent=+36>It would be wrong from a statistical viewpoint to let you directly
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    72
       adjust the angle of one of the pie wedges in the above example, since
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    73
       that is determined by the data. So not everything will be exposed
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    74
       through the public properties. There may be 'back doors' to let you
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    75
       violate this when you really need to, or methods to provide advanced
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    76
       functionality, but in general properties will be orthogonal.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    77
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    78
disc("<i>Composition and component based </i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    79
disc("""<para lindent=+36>Charts are built out of reusable child widgets. A Legend is an
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    80
       easy-to-grasp example. If you need a specialized type of legend (e.g.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    81
       circular colour swatches), you should subclass the standard Legend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    82
       widget. Then you could either do something like...""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    83
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    84
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    85
c = MyChartWithLegend()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    86
c.legend = MyNewLegendClass()    # just change it
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    87
c.legend.swatchRadius = 5    # set a property only relevant to the new one
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    88
c.data = [10,20,30]   #   and then configure as usual...
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    89
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    90
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    91
disc("""<para lindent=+36>...or create/modify your own chart or drawing class which creates one
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    92
       of these by default. This is also very relevant for time series
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    93
       charts, where there can be many styles of x axis.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    94
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    95
disc("""<para lindent=+36>Top level chart classes will create a number of such components, and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    96
       then either call methods or set private properties to tell them their
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    97
       height and position - all the stuff which should be done for you and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    98
       which you cannot customise. We are working on modelling what the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
    99
       components should be and will publish their APIs here as a consensus
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   100
       emerges.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   101
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   102
disc("<i>Multiples </i>")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   103
disc("""<para lindent=+36>A corollary of the component approach is that you can create diagrams
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   104
       with multiple charts, or custom data graphics. Our favourite example
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   105
       of what we are aiming for is the weather report in our gallery
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   106
       contributed by a user; we'd like to make it easy to create such
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   107
       drawings, hook the building blocks up to their legends, and feed that
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   108
       data in a consistent way.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   109
disc("""<para lindent=+36>(If you want to see the image, it is available on our website at
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   110
<font color=blue>http://www.reportlab.com/demos/provencio.pdf</font>)""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   111
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   112
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   113
##heading3("Key Concepts and Components")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   114
heading3("Overview")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   115
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   116
disc("""A chart or plot is an object which is placed on a drawing; it is not
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   117
       itself a drawing. You can thus control where it goes, put several on
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   118
       the same drawing, or add annotations.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   119
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   120
disc("""Charts have two axes; axes may be Value or Category axes. Axes in turn
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   121
       have a Labels property which lets you configure all text labels or
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   122
       each one individually. Most of the configuration details which vary
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   123
       from chart to chart relate to axis properties, or axis labels.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   124
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   125
disc("""Objects expose properties through the interfaces discussed in the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   126
       previous section; these are all optional and are there to let the end
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   127
       user configure the appearance. Things which must be set for a chart to
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   128
       work, and essential communication between a chart and its components,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   129
       are handled through methods.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   130
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   131
disc("""You can subclass any chart component and use your replacement instead
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   132
       of the original provided you implement the essential methods and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   133
       properties.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   134
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   135
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   136
heading2("Labels")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   137
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   138
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   139
A label is a string of text attached to some chart element.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   140
They are used on axes, for titles or alongside axes, or attached
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   141
to individual data points.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   142
Labels may contain newline characters, but only one font.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   143
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   144
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   145
disc("""The text and 'origin' of a label are typically set by its parent
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   146
       object. They are accessed by methods rather than properties. Thus, the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   147
       X axis decides the 'reference point' for each tickmark label and the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   148
       numeric or date text for each label. However, the end user can set
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   149
       properties of the label (or collection of labels) directly to affect
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   150
       its position relative to this origin and all of its formatting.""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   151
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   152
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   153
from reportlab.graphics import shapes
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   154
from reportlab.graphics.charts.textlabels import Label
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   155
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   156
d = Drawing(200, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   157
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   158
# mark the origin of the label
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   159
d.add(Circle(100,90, 5, fillColor=colors.green))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   160
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   161
lab = Label()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   162
lab.setOrigin(100,90)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   163
lab.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   164
lab.angle = 45
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   165
lab.dx = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   166
lab.dy = -20
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   167
lab.boxStrokeColor = colors.green
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   168
lab.setText('Some\nMulti-Line\nLabel')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   169
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   170
d.add(lab)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   171
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   172
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   173
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   174
from reportlab.graphics import shapes
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   175
from reportlab.graphics.charts.textlabels import Label
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   176
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   177
d = Drawing(200, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   178
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   179
# mark the origin of the label
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   180
d.add(Circle(100,90, 5, fillColor=colors.green))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   181
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   182
lab = Label()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   183
lab.setOrigin(100,90)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   184
lab.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   185
lab.angle = 45
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   186
lab.dx = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   187
lab.dy = -20
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   188
lab.boxStrokeColor = colors.green
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   189
lab.setText('Some\nMulti-Line\nLabel')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   190
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   191
d.add(lab)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   192
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   193
draw(d, 'Label example')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   194
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   195
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   196
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   197
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   198
In the drawing above, the label is defined relative to the green blob.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   199
The text box should have its north-east corner ten points down from
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   200
the origin, and be rotated by 45 degrees about that corner.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   201
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   202
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   203
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   204
At present labels have the following properties, which we believe are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   205
sufficient for all charts we have seen to date:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   206
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   207
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   208
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   209
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   210
data=[["Property", "Meaning"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   211
      ["dx", """The label's x displacement."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   212
      ["dy", """The label's y displacement."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   213
      ["angle", """The angle of rotation (counterclockwise) applied to the label."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   214
      ["boxAnchor", "The label's box anchor, one of 'n', 'e', 'w', 's', 'ne', 'nw', 'se', 'sw'."],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   215
      ["textAnchor", """The place where to anchor the label's text, one of 'start', 'middle', 'end'."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   216
      ["boxFillColor", """The fill color used in the label's box."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   217
      ["boxStrokeColor", "The stroke color used in the label's box."],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   218
      ["boxStrokeWidth", """The line width of the label's box."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   219
      ["fontName", """The label's font name."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   220
      ["fontSize", """The label's font size."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   221
      ["leading", """The leading value of the label's text lines."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   222
      ["x", """The X-coordinate of the reference point."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   223
      ["y", """The Y-coordinate of the reference point."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   224
      ["width", """The label's width."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   225
      ["height", """The label's height."""]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   226
      ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   227
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   228
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   229
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   230
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   231
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   232
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   233
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   234
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   235
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   236
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   237
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Label properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   238
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   239
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   240
To see many more examples of $Label$ objects with different
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   241
combinations of properties, please have a look into the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   242
ReportLab test suite in the folder $tests$, run the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   243
script $test_charts_textlabels.py$ and look at the PDF document
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   244
it generates!
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   245
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   246
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   247
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   248
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   249
heading2("Axes")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   250
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   251
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   252
We identify two basic kinds of axes - <i>Value</i> and <i>Category</i>
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   253
ones.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   254
Both come in horizontal and vertical flavors.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   255
Both can be subclassed to make very specific kinds of axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   256
For example, if you have complex rules for which dates to display
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   257
in a time series application, or want irregular scaling, you override
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   258
the axis and make a new one.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   259
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   260
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   261
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   262
Axes are responsible for determining the mapping from data to image
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   263
coordinates; transforming points on request from the chart; drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   264
themselves and their tickmarks, gridlines and axis labels.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   265
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   266
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   267
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   268
This drawing shows two axes, one of each kind, which have been created
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   269
directly without reference to any chart:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   270
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   271
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   272
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   273
from reportlab.graphics import shapes
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   274
from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   275
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   276
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   277
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   278
data = [(10, 20, 30, 40), (15, 22, 37, 42)]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   279
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   280
xAxis = XCategoryAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   281
xAxis.setPosition(75, 75, 300)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   282
xAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   283
xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   284
xAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   285
xAxis.labels[3].dy = -15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   286
xAxis.labels[3].angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   287
xAxis.labels[3].fontName = 'Times-Bold'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   288
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   289
yAxis = YValueAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   290
yAxis.setPosition(50, 50, 125)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   291
yAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   292
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   293
drawing.add(xAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   294
drawing.add(yAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   295
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   296
draw(drawing, 'Two isolated axes')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   297
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   298
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   299
disc("Here is the code that created them: ")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   301
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   302
from reportlab.graphics import shapes
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   303
from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   304
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   305
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   306
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   307
data = [(10, 20, 30, 40), (15, 22, 37, 42)]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   308
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   309
xAxis = XCategoryAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   310
xAxis.setPosition(75, 75, 300)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   311
xAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   312
xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   313
xAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   314
xAxis.labels[3].dy = -15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   315
xAxis.labels[3].angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   316
xAxis.labels[3].fontName = 'Times-Bold'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   317
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   318
yAxis = YValueAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   319
yAxis.setPosition(50, 50, 125)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   320
yAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   321
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   322
drawing.add(xAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   323
drawing.add(yAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   324
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   325
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   326
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   327
Remember that, usually, you won't have to create axes directly;
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   328
when using a standard chart, it comes with ready-made axes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   329
The methods are what the chart uses to configure it and take care
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   330
of the geometry.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   331
However, we will talk through them in detail below.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   332
The orthogonally dual axes to those we describe have essentially
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   333
the same properties, except for those refering to ticks.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   334
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   335
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   336
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   337
heading3("XCategoryAxis class")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   338
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   339
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   340
A Category Axis doesn't really have a scale; it just divides itself
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   341
into equal-sized buckets.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   342
It is simpler than a value axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   343
The chart (or programmer) sets its location with the method
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   344
$setPosition(x, y, length)$.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   345
The next stage is to show it the data so that it can configure
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   346
itself.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   347
This is easy for a category axis - it just counts the number of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   348
data points in one of the data series. The $reversed$ attribute (if 1)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   349
indicates that the categories should be reversed.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   350
When the drawing is drawn, the axis can provide some help to the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   351
chart with its $scale()$ method, which tells the chart where
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   352
a given category begins and ends on the page.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   353
We have not yet seen any need to let people override the widths
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   354
or positions of categories.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   355
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   356
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   357
disc("An XCategoryAxis has the following editable properties:")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   358
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   359
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   360
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   361
data=[["Property", "Meaning"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   362
      ["visible", """Should the axis be drawn at all? Sometimes you don't want
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   363
to display one or both axes, but they still need to be there as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   364
they manage the scaling of points."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   365
      ["strokeColor", "Color of the axis"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   366
      ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   367
Defaults to None"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   368
      ["strokeWidth", "Width of axis in points"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   369
      ["tickUp", """How far above the axis should the tick marks protrude?
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   370
(Note that making this equal to chart height gives you a gridline)"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   371
      ["tickDown", """How far below the axis should the tick mark protrude?"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   372
      ["categoryNames", """Either None, or a list of strings. This should have the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   373
same length as each data series."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   374
      ["labels", """A collection of labels for the tick marks. By default the 'north'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   375
of each text label (i.e top centre) is positioned 5 points down
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   376
from the centre of each category on the axis. You may redefine
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   377
any property of the whole label group or of any one label. If
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   378
categoryNames=None, no labels are drawn."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   379
      ["title", """Not Implemented Yet. This needs to be like a label, but also
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   380
lets you set the text directly. It would have a default
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   381
location below the axis."""]]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   382
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   383
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   384
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   385
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   386
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   387
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   388
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   389
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   390
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   391
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   392
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - XCategoryAxis properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   393
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   394
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   395
heading3("YValueAxis")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   396
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   397
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   398
The left axis in the diagram is a YValueAxis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   399
A Value Axis differs from a Category Axis in that each point along
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   400
its length corresponds to a y value in chart space.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   401
It is the job of the axis to configure itself, and to convert Y values
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   402
from chart space to points on demand to assist the parent chart in
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   403
plotting.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   404
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   405
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   406
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   407
$setPosition(x, y, length)$ and $configure(data)$ work exactly as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   408
for a category axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   409
If you have not fully specified the maximum, minimum and tick
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   410
interval, then $configure()$ results in the axis choosing suitable
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   411
values.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   412
Once configured, the value axis can convert y data values to drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   413
space with the $scale()$ method.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   414
Thus:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   415
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   416
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   417
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   418
>>> yAxis = YValueAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   419
>>> yAxis.setPosition(50, 50, 125)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   420
>>> data = [(10, 20, 30, 40),(15, 22, 37, 42)]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   421
>>> yAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   422
>>> yAxis.scale(10)  # should be bottom of chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   423
50.0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   424
>>> yAxis.scale(40)  # should be near the top
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   425
167.1875
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   426
>>>
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   427
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   428
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   429
disc("""By default, the highest data point is aligned with the top of the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   430
       axis, the lowest with the bottom of the axis, and the axis choose
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   431
       'nice round numbers' for its tickmark points. You may override these
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   432
       settings with the properties below. """)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   433
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   434
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   435
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   436
data=[["Property", "Meaning"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   437
      ["visible", """Should the axis be drawn at all? Sometimes you don't want
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   438
to display one or both axes, but they still need to be there as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   439
they manage the scaling of points."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   440
      ["strokeColor", "Color of the axis"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   441
      ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   442
Defaults to None"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   443
      ["strokeWidth", "Width of axis in points"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   444
      ["tickLeft", """How far to the left of the axis should the tick marks protrude?
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   445
(Note that making this equal to chart height gives you a gridline)"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   446
      ["tickRight", """How far to the right of the axis should the tick mark protrude?"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   447
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   448
      ["valueMin", """The y value to which the bottom of the axis should correspond.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   449
Default value is None in which case the axis sets it to the lowest
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   450
actual data point (e.g. 10 in the example above). It is common to set
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   451
this to zero to avoid misleading the eye."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   452
      ["valueMax", """The y value to which the top of the axis should correspond.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   453
Default value is None in which case the axis sets it to the highest
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   454
actual data point (e.g. 42 in the example above). It is common to set
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   455
this to a 'round number' so data bars do not quite reach the top."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   456
      ["valueStep", """The y change between tick intervals. By default this is
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   457
None, and the chart tries to pick 'nice round numbers' which are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   458
just wider than the minimumTickSpacing below."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   459
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   460
      ["valueSteps", """A list of numbers at which to place ticks."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   461
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   462
      ["minimumTickSpacing", """This is used when valueStep is set to None, and ignored
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   463
otherwise. The designer specified that tick marks should be no
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   464
closer than X points apart (based, presumably, on considerations
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   465
of the label font size and angle). The chart tries values of the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   466
type 1,2,5,10,20,50,100... (going down below 1 if necessary) until
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   467
it finds an interval which is greater than the desired spacing, and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   468
uses this for the step."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   469
      ["labelTextFormat", """This determines what goes in the labels. Unlike a category
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   470
axis which accepts fixed strings, the labels on a ValueAxis are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   471
supposed to be numbers. You may provide either a 'format string'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   472
like '%0.2f' (show two decimal places), or an arbitrary function
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   473
which accepts a number and returns a string. One use for the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   474
latter is to convert a timestamp to a readable year-month-day
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   475
format."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   476
      ["title", """Not Implemented Yet. This needs to be like a label, but also
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   477
lets you set the text directly. It would have a default
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   478
location below the axis."""]]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   479
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   480
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   481
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   482
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   483
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   484
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   485
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   486
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   487
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   488
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   489
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - YValueAxis properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   490
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   491
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   492
The $valueSteps$ property lets you explicitly specify the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   493
tick mark locations, so you don't have to follow regular intervals.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   494
Hence, you can plot month ends and month end dates with a couple of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   495
helper functions, and without needing special time series chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   496
classes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   497
The following code show how to create a simple $XValueAxis$ with special
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   498
tick intervals. Make sure to set the $valueSteps$ attribute before calling
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   499
the configure method!
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   500
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   501
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   502
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   503
from reportlab.graphics.shapes import Drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   504
from reportlab.graphics.charts.axes import XValueAxis
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   505
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   506
drawing = Drawing(400, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   507
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   508
data = [(10, 20, 30, 40)]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   509
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   510
xAxis = XValueAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   511
xAxis.setPosition(75, 50, 300)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   512
xAxis.valueSteps = [10, 15, 20, 30, 35, 40]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   513
xAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   514
xAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   515
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   516
drawing.add(xAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   517
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   518
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   519
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   520
from reportlab.graphics import shapes
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   521
from reportlab.graphics.charts.axes import XValueAxis
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   522
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   523
drawing = Drawing(400, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   524
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   525
data = [(10, 20, 30, 40)]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   526
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   527
xAxis = XValueAxis()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   528
xAxis.setPosition(75, 50, 300)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   529
xAxis.valueSteps = [10, 15, 20, 30, 35, 40]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   530
xAxis.configure(data)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   531
xAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   532
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   533
drawing.add(xAxis)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   534
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   535
draw(drawing, 'An axis with non-equidistant tick marks')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   536
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   537
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   538
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   539
In addition to these properties, all axes classes have three
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   540
properties describing how to join two of them to each other.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   541
Again, this is interesting only if you define your own charts
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   542
or want to modify the appearance of an existing chart using
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   543
such axes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   544
These properties are listed here only very briefly for now,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   545
but you can find a host of sample functions in the module
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   546
$reportlab/graphics/axes.py$ which you can examine...
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   547
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   548
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   549
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   550
One axis is joined to another, by calling the method
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   551
$joinToAxis(otherAxis, mode, pos)$ on the first axis,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   552
with $mode$ and $pos$ being the properties described by
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   553
$joinAxisMode$ and $joinAxisPos$, respectively.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   554
$'points'$ means to use an absolute value, and $'value'$
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   555
to use a relative value (both indicated by the the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   556
$joinAxisPos$ property) along the axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   557
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   558
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   559
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   560
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   561
data=[["Property", "Meaning"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   562
      ["joinAxis", """Join both axes if true."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   563
      ["joinAxisMode", """Mode used for connecting axis ('bottom', 'top', 'left', 'right', 'value', 'points', None)."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   564
      ["joinAxisPos", """Position at which to join with other axis."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   565
      ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   566
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   567
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   568
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   569
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   570
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   571
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   572
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   573
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   574
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   575
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   576
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Axes joining properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   577
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   578
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   579
heading2("Bar Charts")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   580
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   581
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   582
This describes our current $VerticalBarChart$ class, which uses the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   583
axes and labels above.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   584
We think it is step in the right direction but is is
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   585
far from final.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   586
Note that people we speak to are divided about 50/50 on whether to
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   587
call this a 'Vertical' or 'Horizontal' bar chart.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   588
We chose this name because 'Vertical' appears next to 'Bar', so
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   589
we take it to mean that the bars rather than the category axis
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   590
are vertical.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   591
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   592
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   593
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   594
As usual, we will start with an example:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   595
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   596
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   597
from reportlab.graphics.shapes import Drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   598
from reportlab.graphics.charts.barcharts import VerticalBarChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   599
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   600
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   601
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   602
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   603
        (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   604
        (14, 6, 21, 23, 38, 46, 20, 5)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   605
        ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   606
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   607
bc = VerticalBarChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   608
bc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   609
bc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   610
bc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   611
bc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   612
bc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   613
bc.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   614
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   615
bc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   616
bc.valueAxis.valueMax = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   617
bc.valueAxis.valueStep = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   618
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   619
bc.categoryAxis.labels.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   620
bc.categoryAxis.labels.dx = 8
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   621
bc.categoryAxis.labels.dy = -2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   622
bc.categoryAxis.labels.angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   623
bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   624
       'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   625
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   626
drawing.add(bc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   627
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   628
draw(drawing, 'Simple bar chart with two data series')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   629
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   630
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   631
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   632
    # code to produce the above chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   633
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   634
    from reportlab.graphics.shapes import Drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   635
    from reportlab.graphics.charts.barcharts import VerticalBarChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   636
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   637
    drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   638
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   639
    data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   640
            (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   641
            (14, 6, 21, 23, 38, 46, 20, 5)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   642
            ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   643
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   644
    bc = VerticalBarChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   645
    bc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   646
    bc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   647
    bc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   648
    bc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   649
    bc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   650
    bc.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   651
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   652
    bc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   653
    bc.valueAxis.valueMax = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   654
    bc.valueAxis.valueStep = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   655
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   656
    bc.categoryAxis.labels.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   657
    bc.categoryAxis.labels.dx = 8
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   658
    bc.categoryAxis.labels.dy = -2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   659
    bc.categoryAxis.labels.angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   660
    bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   661
           'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   662
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   663
    drawing.add(bc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   664
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   665
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   666
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   667
Most of this code is concerned with setting up the axes and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   668
labels, which we have already covered.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   669
Here are the top-level properties of the $VerticalBarChart$ class:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   670
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   671
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   672
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   673
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   674
data=[["Property", "Meaning"],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   675
      ["data", """This should be a "list of lists of numbers" or "list of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   676
tuples of numbers". If you have just one series, write it as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   677
data = [(10,20,30,42),]"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   678
      ["x, y, width, height", """These define the inner 'plot rectangle'. We
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   679
highlighted this with a yellow border above. Note that it is
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   680
your job to place the chart on the drawing in a way which leaves
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   681
room for all the axis labels and tickmarks. We specify this 'inner
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   682
rectangle' because it makes it very easy to lay out multiple charts
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   683
in a consistent manner."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   684
      ["strokeColor", """Defaults to None. This will draw a border around the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   685
plot rectangle, which may be useful in debugging. Axes will
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   686
overwrite this."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   687
      ["fillColor", """Defaults to None. This will fill the plot rectangle with
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   688
a solid color. (Note that we could implement dashArray etc.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   689
as for any other solid shape)"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   690
      ["useAbsolute", """Defaults to 0. If 1, the three properties below are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   691
absolute values in points (which means you can make a chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   692
where the bars stick out from the plot rectangle); if 0,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   693
they are relative quantities and indicate the proportional
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   694
widths of the elements involved."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   695
      ["barWidth", """As it says. Defaults to 10."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   696
      ["groupSpacing", """Defaults to 5. This is the space between each group of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   697
bars. If you have only one series, use groupSpacing and not
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   698
barSpacing to split them up. Half of the groupSpacing is used
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   699
before the first bar in the chart, and another half at the end."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   700
      ["barSpacing", """Defaults to 0. This is the spacing between bars in each
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   701
group. If you wanted a little gap between green and red bars in
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   702
the example above, you would make this non-zero."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   703
      ["barLabelFormat", """Defaults to None. As with the YValueAxis, if you supply
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   704
a function or format string then labels will be drawn next to each bar
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   705
showing the numeric value. They are positioned automatically
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   706
above the bar for positive values and below for negative ones."""],
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   707
      ["barLabels", """A collection of labels used to format all bar labels. Since
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   708
this is a two-dimensional array, you may explicitly format the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   709
third label of the second series using this syntax:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   710
  chart.barLabels[(1,2)].fontSize = 12"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   711
      ["valueAxis", """The value axis, which may be formatted as described
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   712
previously."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   713
      ["categoryAxis", """The category axis, which may be formatted as described
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   714
previously."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   715
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   716
      ["title", """Not Implemented Yet. This needs to be like a label, but also
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   717
lets you set the text directly. It would have a default
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   718
location below the axis."""]]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   719
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   720
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   721
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   722
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   723
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   724
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   725
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   726
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   727
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   728
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   729
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - VerticalBarChart properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   730
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   731
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   732
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   733
From this table we deduce that adding the following lines to our code
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   734
above should double the spacing between bar groups (the $groupSpacing$
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   735
attribute has a default value of five points) and we should also see
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   736
some tiny space between bars of the same group ($barSpacing$).
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   737
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   738
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   739
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   740
    bc.groupSpacing = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   741
    bc.barSpacing = 2.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   742
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   743
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   744
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   745
And, in fact, this is exactly what we can see after adding these
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   746
lines to the code above.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   747
Notice how the width of the individual bars has changed as well.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   748
This is because the space added between the bars has to be 'taken'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   749
from somewhere as the total chart width stays unchanged.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   750
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   751
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   752
from reportlab.graphics.shapes import Drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   753
from reportlab.graphics.charts.barcharts import VerticalBarChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   754
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   755
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   756
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   757
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   758
        (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   759
        (14, 6, 21, 23, 38, 46, 20, 5)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   760
        ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   761
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   762
bc = VerticalBarChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   763
bc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   764
bc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   765
bc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   766
bc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   767
bc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   768
bc.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   769
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   770
bc.groupSpacing = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   771
bc.barSpacing = 2.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   772
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   773
bc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   774
bc.valueAxis.valueMax = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   775
bc.valueAxis.valueStep = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   776
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   777
bc.categoryAxis.labels.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   778
bc.categoryAxis.labels.dx = 8
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   779
bc.categoryAxis.labels.dy = -2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   780
bc.categoryAxis.labels.angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   781
bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   782
       'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   783
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   784
drawing.add(bc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   785
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   786
draw(drawing, 'Like before, but with modified spacing')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   787
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   788
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   789
Bars labels are automatically displayed for negative values
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   790
<i>below</i> the lower end of the bar for positive values
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   791
<i>above</i> the upper end of the other ones.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   792
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   793
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   794
3232
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   795
disc("""
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   796
Stacked bars are also supported for vertical bar graphs.
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   797
You enable this layout for your chart by setting the $style$
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   798
attribute to $'stacked'$ on the $categoryAxis$.
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   799
""")
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   800
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   801
eg("""
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   802
    bc.categoryAxis.style = 'stacked'
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   803
""")
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   804
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   805
disc("""
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   806
Here is an example of the previous chart values arranged
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   807
in the stacked style.
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   808
""")
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   809
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   810
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   811
drawing = Drawing(400, 200)
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   812
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   813
data = [
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   814
        (13, 5, 20, 22, 37, 45, 19, 4),
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   815
        (14, 6, 21, 23, 38, 46, 20, 5)
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   816
        ]
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   817
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   818
bc = VerticalBarChart()
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   819
bc.x = 50
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   820
bc.y = 50
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   821
bc.height = 125
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   822
bc.width = 300
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   823
bc.data = data
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   824
bc.strokeColor = colors.black
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   825
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   826
bc.groupSpacing = 10
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   827
bc.barSpacing = 2.5
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   828
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   829
bc.valueAxis.valueMin = 0
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   830
bc.valueAxis.valueMax = 100
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   831
bc.valueAxis.valueStep = 20
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   832
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   833
bc.categoryAxis.labels.boxAnchor = 'ne'
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   834
bc.categoryAxis.labels.dx = 8
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   835
bc.categoryAxis.labels.dy = -2
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   836
bc.categoryAxis.labels.angle = 30
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   837
bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   838
       'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   839
bc.categoryAxis.style = 'stacked'
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   840
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   841
drawing.add(bc)
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   842
draw(drawing, 'Stacking bars on top of each other.')
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   843
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
   844
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   845
##Property Value
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   846
##data This should be a "list of lists of numbers" or "list of tuples of numbers". If you have just one series, write it as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   847
##data = [(10,20,30,42),]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   848
##
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   849
##x, y, width, height These define the inner 'plot rectangle'. We highlighted this with a yellow border above. Note that it is your job to place the chart on the drawing in a way which leaves room for all the axis labels and tickmarks. We specify this 'inner rectangle' because it makes it very easy to lay out multiple charts in a consistent manner.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   850
##strokeColor Defaults to None. This will draw a border around the plot rectangle, which may be useful in debugging. Axes will overwrite this.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   851
##fillColor Defaults to None. This will fill the plot rectangle with a solid color. (Note that we could implement dashArray etc. as for any other solid shape)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   852
##barLabelFormat This is a format string or function used for displaying labels above each bar. We're working on ways to position these labels so that they work for positive and negative bars.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   853
##useAbsolute Defaults to 0. If 1, the three properties below are absolute values in points (which means you can make a chart where the bars stick out from the plot rectangle); if 0, they are relative quantities and indicate the proportional widths of the elements involved.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   854
##barWidth As it says. Defaults to 10.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   855
##groupSpacing Defaults to 5. This is the space between each group of bars. If you have only one series, use groupSpacing and not barSpacing to split them up. Half of the groupSpacing is used before the first bar in the chart, and another half at the end.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   856
##barSpacing Defaults to 0. This is the spacing between bars in each group. If you wanted a little gap between green and red bars in the example above, you would make this non-zero.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   857
##barLabelFormat Defaults to None. As with the YValueAxis, if you supply a function or format string then labels will be drawn next to each bar showing the numeric value.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   858
##barLabels A collection of labels used to format all bar labels. Since this is a two-dimensional array, you may explicitly format the third label of the second series using this syntax:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   859
##    chart.barLabels[(1,2)].fontSize = 12
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   860
##
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   861
##valueAxis The value axis, which may be formatted as described previously
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   862
##categoryAxis The categoryAxis, which may be formatted as described previously
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   863
##title, subTitle Not implemented yet. These would be label-like objects whose text could be set directly and which would appear in sensible locations. For now, you can just place extra strings on the drawing.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   864
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   865
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   866
heading2("Line Charts")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   867
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   868
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   869
We consider "Line Charts" to be essentially the same as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   870
"Bar Charts", but with lines instead of bars.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   871
Both share the same pair of Category/Value axes pairs.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   872
This is in contrast to "Line Plots", where both axes are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   873
<i>Value</i> axes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   874
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   875
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   876
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   877
The following code and its output shall serve as a simple
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   878
example.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   879
More explanation will follow.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   880
For the time being you can also study the output of running
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   881
the tool $reportlab/lib/graphdocpy.py$ withough any arguments
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   882
and search the generated PDF document for examples of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   883
Line Charts.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   884
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   885
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   886
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   887
from reportlab.graphics.charts.linecharts import HorizontalLineChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   888
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   889
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   890
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   891
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   892
    (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   893
    (5, 20, 46, 38, 23, 21, 6, 14)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   894
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   895
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   896
lc = HorizontalLineChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   897
lc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   898
lc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   899
lc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   900
lc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   901
lc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   902
lc.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   903
catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   904
lc.categoryAxis.categoryNames = catNames
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   905
lc.categoryAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   906
lc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   907
lc.valueAxis.valueMax = 60
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   908
lc.valueAxis.valueStep = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   909
lc.lines[0].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   910
lc.lines[1].strokeWidth = 1.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   911
drawing.add(lc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   912
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   913
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   914
from reportlab.graphics.charts.linecharts import HorizontalLineChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   915
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   916
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   917
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   918
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   919
    (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   920
    (5, 20, 46, 38, 23, 21, 6, 14)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   921
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   922
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   923
lc = HorizontalLineChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   924
lc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   925
lc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   926
lc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   927
lc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   928
lc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   929
lc.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   930
catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   931
lc.categoryAxis.categoryNames = catNames
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   932
lc.categoryAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   933
lc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   934
lc.valueAxis.valueMax = 60
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   935
lc.valueAxis.valueStep = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   936
lc.lines[0].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   937
lc.lines[1].strokeWidth = 1.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   938
drawing.add(lc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   939
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   940
draw(drawing, 'HorizontalLineChart sample')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   941
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   942
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   943
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   944
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   945
data=[["Property","Meaning"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   946
      ["data", "Data to be plotted, list of (lists of) numbers."],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   947
      ["x, y, width, height", """Bounding box of the line chart.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   948
Note that x and y do NOT specify the centre but the bottom left corner"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   949
      ["valueAxis", """The value axis, which may be formatted as described previously."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   950
      ["categoryAxis", """The category axis, which may be formatted as described previously."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   951
 ["strokeColor", """Defaults to None. This will draw a border around the plot rectangle,
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   952
which may be useful in debugging. Axes will overwrite this."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   953
      ["fillColor", """Defaults to None. This will fill the plot rectangle with a solid color."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   954
      ["lines.strokeColor", """Color of the line."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   955
      ["lines.strokeWidth", """Width of the line."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   956
      ["lineLabels", """A collection of labels used to format all line labels. Since
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   957
this is a two-dimensional array, you may explicitly format the
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   958
third label of the second line using this syntax:
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   959
  chart.lineLabels[(1,2)].fontSize = 12"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   960
      ["lineLabelFormat", """Defaults to None. As with the YValueAxis, if you supply
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   961
a function or format string then labels will be drawn next
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   962
to each line showing the numeric value. You can also set it
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   963
to 'values' to display the values explicity defined in lineLabelArray."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   964
      ["lineLabelArray", """Explicit array of line label values, must match size of data if present.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   965
These labels values will be displayed only if the property
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   966
lineLabelFormat above is set to 'values'."""]]
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   967
t=Table(data, colWidths=(100,330))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   968
t.setStyle(TableStyle([
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   969
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   970
            ('FONT',(0,1),(0,-1),'Courier',8,8),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   971
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   972
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   973
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   974
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   975
            ]))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   976
getStory().append(t)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   977
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - HorizontalLineChart properties""")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   978
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
   979
heading2("Line Plots")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   980
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   981
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   982
Below we show a more complex example of a Line Plot that
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   983
also uses some experimental features like line markers
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   984
placed at each data point.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   985
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   986
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   987
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   988
from reportlab.graphics.charts.lineplots import LinePlot
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   989
from reportlab.graphics.widgets.markers import makeMarker
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   990
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   991
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   992
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   993
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   994
    ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   995
    ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   996
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   997
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   998
lp = LinePlot()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   999
lp.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1000
lp.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1001
lp.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1002
lp.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1003
lp.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1004
lp.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1005
lp.lines[0].symbol = makeMarker('FilledCircle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1006
lp.lines[1].symbol = makeMarker('Circle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1007
lp.lineLabelFormat = '%2.0f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1008
lp.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1009
lp.xValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1010
lp.xValueAxis.valueMax = 5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1011
lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1012
lp.xValueAxis.labelTextFormat = '%2.1f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1013
lp.yValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1014
lp.yValueAxis.valueMax = 7
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1015
lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1016
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1017
drawing.add(lp)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1018
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1019
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1020
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1021
from reportlab.graphics.charts.lineplots import LinePlot
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1022
from reportlab.graphics.widgets.markers import makeMarker
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1023
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1024
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1025
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1026
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1027
    ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1028
    ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1029
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1030
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1031
lp = LinePlot()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1032
lp.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1033
lp.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1034
lp.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1035
lp.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1036
lp.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1037
lp.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1038
lp.lines[0].symbol = makeMarker('FilledCircle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1039
lp.lines[1].symbol = makeMarker('Circle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1040
lp.lineLabelFormat = '%2.0f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1041
lp.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1042
lp.xValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1043
lp.xValueAxis.valueMax = 5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1044
lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1045
lp.xValueAxis.labelTextFormat = '%2.1f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1046
lp.yValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1047
lp.yValueAxis.valueMax = 7
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1048
lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1049
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1050
drawing.add(lp)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1051
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1052
draw(drawing, 'LinePlot sample')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1053
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1054
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1055
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1056
disc("")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1057
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1058
data=[["Property","Meaning"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1059
      ["data", "Data to be plotted, list of (lists of) numbers."],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1060
      ["x, y, width, height", """Bounding box of the line chart.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1061
Note that x and y do NOT specify the centre but the bottom left corner"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1062
      ["xValueAxis", """The vertical value axis, which may be formatted as described previously."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1063
      ["yValueAxis", """The horizontal value axis, which may be formatted as described previously."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1064
      ["strokeColor", """Defaults to None. This will draw a border around the plot rectangle,
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1065
which may be useful in debugging. Axes will overwrite this."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1066
      ["strokeWidth", """Defaults to None. Width of the border around the plot rectangle."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1067
      ["fillColor", """Defaults to None. This will fill the plot rectangle with a solid color."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1068
      ["lines.strokeColor", """Color of the line."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1069
      ["lines.strokeWidth", """Width of the line."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1070
      ["lines.symbol", """Marker used for each point.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1071
You can create a new marker using the function makeMarker().
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1072
For example to use a circle, the function call would be makeMarker('Circle')"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1073
      ["lineLabels", """A collection of labels used to format all line labels. Since
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1074
this is a two-dimensional array, you may explicitly format the
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1075
third label of the second line using this syntax:
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1076
  chart.lineLabels[(1,2)].fontSize = 12"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1077
      ["lineLabelFormat", """Defaults to None. As with the YValueAxis, if you supply
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1078
a function or format string then labels will be drawn next
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1079
to each line showing the numeric value. You can also set it
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1080
to 'values' to display the values explicity defined in lineLabelArray."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1081
      ["lineLabelArray", """Explicit array of line label values, must match size of data if present.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1082
These labels values will be displayed only if the property
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1083
lineLabelFormat above is set to 'values'."""]]
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1084
t=Table(data, colWidths=(100,330))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1085
t.setStyle(TableStyle([
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1086
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1087
            ('FONT',(0,1),(0,-1),'Courier',8,8),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1088
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1089
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1090
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1091
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1092
            ]))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1093
getStory().append(t)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1094
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - LinePlot properties""")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1095
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1096
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1097
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1098
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1099
heading2("Pie Charts")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1100
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1101
disc("""
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1102
As usual, we will start with an example:
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1103
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1104
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1105
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1106
from reportlab.graphics.charts.piecharts import Pie
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1107
d = Drawing(200, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1108
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1109
pc = Pie()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1110
pc.x = 65
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1111
pc.y = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1112
pc.width = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1113
pc.height = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1114
pc.data = [10,20,30,40,50,60]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1115
pc.labels = ['a','b','c','d','e','f']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1116
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1117
pc.slices.strokeWidth=0.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1118
pc.slices[3].popout = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1119
pc.slices[3].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1120
pc.slices[3].strokeDashArray = [2,2]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1121
pc.slices[3].labelRadius = 1.75
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1122
pc.slices[3].fontColor = colors.red
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1123
d.add(pc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1124
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1126
from reportlab.graphics.charts.piecharts import Pie
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1127
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1128
d = Drawing(400, 200)
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1129
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1130
pc = Pie()
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1131
pc.x = 125
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1132
pc.y = 25
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1133
pc.width = 150
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1134
pc.height = 150
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1135
pc.data = [10,20,30,40,50,60]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1136
pc.labels = ['a','b','c','d','e','f']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1137
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1138
pc.slices.strokeWidth=0.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1139
pc.slices[3].popout = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1140
pc.slices[3].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1141
pc.slices[3].strokeDashArray = [2,2]
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1142
pc.slices[3].labelRadius = 1.25
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1143
pc.slices[3].fontColor = colors.red
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1144
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1145
d.add(pc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1146
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1147
draw(d, 'A bare bones pie chart')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1148
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1149
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1150
Properties are covered below.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1151
The pie has a 'wedges' collection and we document wedge properties
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1152
in the same table.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1153
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1154
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1155
disc("")
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1156
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1157
data=[["Property", "Meaning"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1158
      ["data", "A list or tuple of numbers"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1159
      ["x, y, width, height", """Bounding box of the pie.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1160
Note that x and y do NOT specify the centre but the bottom left
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1161
corner, and that width and height do not have to be equal;
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1162
pies may be elliptical and wedges will be drawn correctly."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1163
      ["labels", """None, or a list of strings.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1164
Make it None if you don't want labels around the edge of the pie.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1165
Since it is impossible to know the size of slices, we generally
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1166
discourage placing labels in or around pies; it is much better 
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1167
to put them in a legend alongside."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1168
      ["startAngle", """Where is the start angle of the first pie slice?
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1169
The default is '90' which is twelve o'clock."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1170
      ["direction", """Which direction do slices progress in?
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1171
The default is 'clockwise'."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1172
      ["sideLabels", """This creates a chart with the labels in two columns,
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1173
one on either side."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1174
      ["sideLabelsOffset", """This is a fraction of the width of the pie that defines the horizontal
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1175
distance between the pie and the columns of labels."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1176
      ["simpleLabels", """Default is 1. Set to 0 to enable the use of customizable labels 
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1177
and of properties prefixed by label_ in the collection slices."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1178
      ["wedges", """Collection of wedges.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1179
This lets you customise each wedge, or individual ones. See below"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1180
      ["wedges.strokeWidth", "Border width for wedge"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1181
      ["wedges.strokeColor", "Border color"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1182
      ["wedges.strokeDashArray", "Solid or dashed line configuration"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1183
      ["wedges.popout", """How far out should the slice(s) stick from the centre of the pie?
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1184
Default is zero."""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1185
      ["wedges.fontName", "Name of the label font"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1186
      ["wedges.fontSize", "Size of the label font"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1187
      ["wedges.fontColor", "Color of the label text"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1188
      ["wedges.labelRadius", """This controls the anchor point for a text label.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1189
It is a fraction of the radius; 0.7 will place the text inside the
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1190
pie, 1.2 will place it slightly outside. (note that if we add labels,
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1191
we will keep this to specify their anchor point)"""]]
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1192
t=Table(data, colWidths=(130,300))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1193
t.setStyle(TableStyle([
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1194
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1195
            ('FONT',(0,1),(0,-1),'Courier',8,8),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1196
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1197
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1198
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1199
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1200
            ]))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1201
getStory().append(t)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1202
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Pie properties""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1203
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1204
heading3("Customizing Labels")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1205
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1206
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1207
Each slide label can be customized individually by changing
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1208
the properties prefixed by $label_$ in the collection $wedges$.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1209
For example $pc.slices[2].label_angle = 10$ changes the angle 
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1210
of the third label.
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1211
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1212
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1213
disc("""
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1214
Before being able to use these customization properties, you need
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1215
to disable simple labels with: $pc.simplesLabels = 0$
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1216
""")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1217
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1218
disc("")
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1219
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1220
data=[["Property", "Meaning"],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1221
      ["label_dx", """X Offset of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1222
      ["label_dy", """Y Offset of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1223
      ["label_angle", """Angle of the label, default (0) is horizontal, 90 is vertical,
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1224
180 is upside down"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1225
      ["label_boxAnchor", """Anchoring point of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1226
      ["label_boxStrokeColor", """Border color for the label box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1227
      ["label_boxStrokeWidth", """Border width for the label box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1228
      ["label_boxFillColor", """Filling color of the label box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1229
      ["label_strokeColor", """Border color for the label text"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1230
      ["label_strokeWidth", """Border width for the label text"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1231
      ["label_text", """Text of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1232
      ["label_width", """Width of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1233
      ["label_maxWidth", """Maximum width the label can grow to"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1234
      ["label_height", """Height of the label"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1235
      ["label_textAnchor", """Maximum height the label can grow to"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1236
      ["label_visible", """True if the label is to be drawn"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1237
      ["label_topPadding", """Padding at top of box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1238
      ["label_leftPadding", """Padding at left of box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1239
      ["label_rightPadding", """Padding at right of box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1240
      ["label_bottomPadding", """Padding at bottom of box"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1241
      ["label_simple_pointer", """Set to 1 for simple pointers"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1242
      ["label_pointer_strokeColor", """Color of indicator line"""],
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1243
      ["label_pointer_strokeWidth", """Width of indicator line"""]]
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1244
t=Table(data, colWidths=(130,300))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1245
t.setStyle(TableStyle([
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1246
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1247
            ('FONT',(0,1),(0,-1),'Courier',8,8),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1248
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1249
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1250
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1251
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1252
            ]))
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1253
getStory().append(t)
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1254
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Pie.wedges label customization properties""")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1255
3585
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1256
heading3("Side Labels")
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1257
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1258
disc("""
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1259
If the sideLabels attribute is set to true, then the labels of 
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1260
the slices are placed in two columns, one on either side of the 
3587
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1261
pie and the start angle of the pie will be set automatically.
3591
73e1edc35b63 Changes to side label pie chart in userguide
jamesmc
parents: 3587
diff changeset
  1262
The anchor of the right hand column is set to 'start' and the 
73e1edc35b63 Changes to side label pie chart in userguide
jamesmc
parents: 3587
diff changeset
  1263
anchor of the left hand column is set to 'end'.
3587
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1264
The distance from the edge of the pie from the edge of either 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1265
column is decided by the sideLabelsOffset attribute, which is 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1266
a fraction of the width of the pie.
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1267
If xradius is changed, the pie can overlap the labels, and so 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1268
we advise leaving xradius as None.
3585
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1269
There is an example below.
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1270
""")
338f2023ff43 Basic change to graph_charts.py
jamesmc
parents: 3232
diff changeset
  1271
3587
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1272
from reportlab.graphics.charts.piecharts import sample5, sample7, sample8
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1273
drawing5 = sample5()
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1274
draw(drawing5, 'An example of a piechart with sideLabels =1')
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1275
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1276
disc("""
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1277
If you have sideLabels set to True, then some of the attributes 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1278
become redundant, such as pointerLabelMode.
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1279
Also sideLabelsOffset only changes the piechart if sideLabels is 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1280
set to true.
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1281
""")
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1282
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1283
heading4("Some issues")
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1284
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1285
disc("""
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1286
The pointers can cross if there are too many slices.
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1287
""")
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1288
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1289
drawing7 = sample7()
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1290
draw(drawing7, 'An example of pointers crossing')
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1291
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1292
disc("""
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1293
Also the labels can overlap despite checkLabelOverlap if they 
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1294
correspond to slices that are not adjacent.
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1295
""")
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1296
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1297
drawing8 = sample8()
25c545d2de65 Changes to userguide about sideLabels
jamesmc
parents: 3585
diff changeset
  1298
draw(drawing8, 'An example of labels overlapping')
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1299
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1300
heading2("Legends")
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1301
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1302
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1303
Various preliminary legend classes can be found but need a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1304
cleanup to be consistent with the rest of the charting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1305
model.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1306
Legends are the natural place to specify the colors and line
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1307
styles of charts; we propose that each chart is created with
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1308
a $legend$ attribute which is invisible.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1309
One would then do the following to specify colors:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1310
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1311
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1312
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1313
myChart.legend.defaultColors = [red, green, blue]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1314
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1315
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1316
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1317
One could also define a group of charts sharing the same legend:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1318
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1319
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1320
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1321
myLegend = Legend()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1322
myLegend.defaultColor = [red, green.....] #yuck!
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1323
myLegend.columns = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1324
# etc.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1325
chart1.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1326
chart2.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1327
chart3.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1328
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1329
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1330
# Hack to force a new paragraph before the todo() :-(
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1331
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1332
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1333
todo("""Does this work? Is it an acceptable complication over specifying chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1334
colors directly?""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1335
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1336
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1337
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1338
heading3("Remaining Issues")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1339
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1340
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1341
There are several issues that are <i>almost</i> solved, but for which
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1342
is is a bit too early to start making them really public.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1343
Nevertheless, here is a list of things that are under way:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1344
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1345
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1346
bullet("""
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1347
Color specification - right now the chart has an undocumented property
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1348
$defaultColors$, which provides a list of colors to cycle through,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1349
such that each data series gets its own color.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1350
Right now, if you introduce a legend, you need to make sure it shares
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1351
the same list of colors.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1352
Most likely, this will be replaced with a scheme to specify a kind
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1353
of legend containing attributes with different values for each data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1354
series.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1355
This legend can then also be shared by several charts, but need not
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1356
be visible itself.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1357
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1358
3603
dd1d19c9cb98 Added documentation for preformatted text wrapping and property tables for charts
guillaume
parents: 3591
diff changeset
  1359
bullet("""
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1360
Additional chart types - when the current design will have become
3232
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
  1361
more stable, we expect to add variants of bar charts to deal with
5284683ed19d Updated userguide to include information about stacked bar charts
damian
parents: 3062
diff changeset
  1362
percentile bars as well as the side-by-side variant seen here.
3062
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1363
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1364
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1365
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1366
heading3("Outlook")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1367
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1368
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1369
It will take some time to deal with the full range of chart types.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1370
We expect to finalize bars and pies first and to produce trial
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1371
implementations of more general plots, thereafter.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1372
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1373
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1374
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1375
heading3("X-Y Plots")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1376
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1377
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1378
Most other plots involve two value axes and directly plotting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1379
x-y data in some form.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1380
The series can be plotted as lines, marker symbols, both, or
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1381
custom graphics such as open-high-low-close graphics.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1382
All share the concepts of scaling and axis/title formatting.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1383
At a certain point, a routine will loop over the data series and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1384
'do something' with the data points at given x-y locations.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1385
Given a basic line plot, it should be very easy to derive a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1386
custom chart type just by overriding a single method - say,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1387
$drawSeries()$.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1388
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1389
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1390
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1391
heading3("Marker customisation and custom shapes")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1392
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1393
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1394
Well known plotting packages such as excel, Mathematica and Excel
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1395
offer ranges of marker types to add to charts.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1396
We can do better - you can write any kind of chart widget you
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1397
want and just tell the chart to use it as an example.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1398
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1399
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1400
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1401
heading4("Combination plots")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1402
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1403
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1404
Combining multiple plot types is really easy.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1405
You can just draw several charts (bar, line or whatever) in
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1406
the same rectangle, suppressing axes as needed.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1407
So a chart could correlate a line with Scottish typhoid cases
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1408
over a 15 year period on the left axis with a set of bars showing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1409
inflation rates on the right axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1410
If anyone can remind us where this example came from we'll
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset