docs/userguide/graph_charts.py
author jonas
Fri, 16 Jan 2009 18:23:19 +0000
changeset 3062 d47129e56d9f
child 3232 5284683ed19d
permissions -rw-r--r--
Merged graphguide into userguide.
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
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   136
heading3("Labels")
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
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   249
heading3("Axes")
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
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   579
heading3("Bar Charts")
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
      ["barLabelFormat", """This is a format string or function used for displaying
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   691
labels above each bar. They are positioned automatically
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   692
above the bar for positive values and below for negative ones."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   693
      ["useAbsolute", """Defaults to 0. If 1, the three properties below are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   694
absolute values in points (which means you can make a chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   695
where the bars stick out from the plot rectangle); if 0,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   696
they are relative quantities and indicate the proportional
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   697
widths of the elements involved."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   698
      ["barWidth", """As it says. Defaults to 10."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   699
      ["groupSpacing", """Defaults to 5. This is the space between each group of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   700
bars. If you have only one series, use groupSpacing and not
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   701
barSpacing to split them up. Half of the groupSpacing is used
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   702
before the first bar in the chart, and another half at the end."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   703
      ["barSpacing", """Defaults to 0. This is the spacing between bars in each
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   704
group. If you wanted a little gap between green and red bars in
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   705
the example above, you would make this non-zero."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   706
      ["barLabelFormat", """Defaults to None. As with the YValueAxis, if you supply
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   707
a function or format string then labels will be drawn next
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   708
to each bar showing the numeric value."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   709
      ["barLabels", """A collection of labels used to format all bar labels. Since
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   710
this is a two-dimensional array, you may explicitly format the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   711
third label of the second series using this syntax:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   712
  chart.barLabels[(1,2)].fontSize = 12"""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   713
      ["valueAxis", """The value 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
      ["categoryAxis", """The category axis, which may be formatted as described
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   716
previously."""],
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   717
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   718
      ["title", """Not Implemented Yet. This needs to be like a label, but also
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   719
lets you set the text directly. It would have a default
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   720
location below the axis."""]]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   721
t=Table(data, colWidths=(100,330))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   722
t.setStyle(TableStyle([
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   723
            ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   724
            ('FONT',(0,1),(0,-1),'Courier',8,8),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   725
            ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   726
            ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   727
            ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   728
            ('BOX', (0,0), (-1,-1), 0.25, colors.black),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   729
            ]))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   730
getStory().append(t)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   731
caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - VerticalBarChart properties""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   732
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   733
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   734
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   735
From this table we deduce that adding the following lines to our code
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   736
above should double the spacing between bar groups (the $groupSpacing$
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   737
attribute has a default value of five points) and we should also see
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   738
some tiny space between bars of the same group ($barSpacing$).
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   739
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   740
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   741
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   742
    bc.groupSpacing = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   743
    bc.barSpacing = 2.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   744
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   745
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   746
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   747
And, in fact, this is exactly what we can see after adding these
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   748
lines to the code above.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   749
Notice how the width of the individual bars has changed as well.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   750
This is because the space added between the bars has to be 'taken'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   751
from somewhere as the total chart width stays unchanged.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   752
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   753
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   754
from reportlab.graphics.shapes import Drawing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   755
from reportlab.graphics.charts.barcharts import VerticalBarChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   756
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   757
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   758
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   759
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   760
        (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   761
        (14, 6, 21, 23, 38, 46, 20, 5)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   762
        ]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   763
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   764
bc = VerticalBarChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   765
bc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   766
bc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   767
bc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   768
bc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   769
bc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   770
bc.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   771
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   772
bc.groupSpacing = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   773
bc.barSpacing = 2.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   774
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   775
bc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   776
bc.valueAxis.valueMax = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   777
bc.valueAxis.valueStep = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   778
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   779
bc.categoryAxis.labels.boxAnchor = 'ne'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   780
bc.categoryAxis.labels.dx = 8
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   781
bc.categoryAxis.labels.dy = -2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   782
bc.categoryAxis.labels.angle = 30
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   783
bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   784
       'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   785
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   786
drawing.add(bc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   787
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   788
draw(drawing, 'Like before, but with modified spacing')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   789
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   790
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   791
Bars labels are automatically displayed for negative values
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   792
<i>below</i> the lower end of the bar for positive values
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   793
<i>above</i> the upper end of the other ones.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   794
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   795
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   796
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   797
##Property Value
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   798
##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
   799
##data = [(10,20,30,42),]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   800
##
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   801
##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
   802
##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
   803
##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
   804
##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
   805
##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
   806
##barWidth As it says. Defaults to 10.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   807
##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
   808
##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
   809
##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
   810
##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
   811
##    chart.barLabels[(1,2)].fontSize = 12
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   812
##
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   813
##valueAxis The value axis, which may be formatted as described previously
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   814
##categoryAxis The categoryAxis, which may be formatted as described previously
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   815
##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
   816
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   817
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   818
heading3("Line Charts")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   819
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   820
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   821
We consider "Line Charts" to be essentially the same as
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   822
"Bar Charts", but with lines instead of bars.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   823
Both share the same pair of Category/Value axes pairs.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   824
This is in contrast to "Line Plots", where both axes are
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   825
<i>Value</i> axes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   826
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   827
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   828
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   829
The following code and its output shall serve as a simple
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   830
example.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   831
More explanation will follow.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   832
For the time being you can also study the output of running
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   833
the tool $reportlab/lib/graphdocpy.py$ withough any arguments
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   834
and search the generated PDF document for examples of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   835
Line Charts.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   836
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   837
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   838
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   839
from reportlab.graphics.charts.linecharts import HorizontalLineChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   840
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   841
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   842
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   843
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   844
    (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   845
    (5, 20, 46, 38, 23, 21, 6, 14)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   846
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   847
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   848
lc = HorizontalLineChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   849
lc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   850
lc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   851
lc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   852
lc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   853
lc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   854
lc.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   855
catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   856
lc.categoryAxis.categoryNames = catNames
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   857
lc.categoryAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   858
lc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   859
lc.valueAxis.valueMax = 60
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   860
lc.valueAxis.valueStep = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   861
lc.lines[0].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   862
lc.lines[1].strokeWidth = 1.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   863
drawing.add(lc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   864
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   865
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   866
from reportlab.graphics.charts.linecharts import HorizontalLineChart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   867
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   868
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   869
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   870
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   871
    (13, 5, 20, 22, 37, 45, 19, 4),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   872
    (5, 20, 46, 38, 23, 21, 6, 14)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   873
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   874
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   875
lc = HorizontalLineChart()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   876
lc.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   877
lc.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   878
lc.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   879
lc.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   880
lc.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   881
lc.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   882
catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   883
lc.categoryAxis.categoryNames = catNames
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   884
lc.categoryAxis.labels.boxAnchor = 'n'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   885
lc.valueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   886
lc.valueAxis.valueMax = 60
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   887
lc.valueAxis.valueStep = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   888
lc.lines[0].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   889
lc.lines[1].strokeWidth = 1.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   890
drawing.add(lc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   891
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   892
draw(drawing, 'HorizontalLineChart sample')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   893
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   894
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   895
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   896
todo("Add properties table.")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   897
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   898
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   899
heading3("Line Plots")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   900
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   901
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   902
Below we show a more complex example of a Line Plot that
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   903
also uses some experimental features like line markers
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   904
placed at each data point.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   905
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   906
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   907
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   908
from reportlab.graphics.charts.lineplots import LinePlot
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   909
from reportlab.graphics.widgets.markers import makeMarker
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   910
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   911
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   912
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   913
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   914
    ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   915
    ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   916
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   917
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   918
lp = LinePlot()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   919
lp.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   920
lp.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   921
lp.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   922
lp.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   923
lp.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   924
lp.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   925
lp.lines[0].symbol = makeMarker('FilledCircle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   926
lp.lines[1].symbol = makeMarker('Circle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   927
lp.lineLabelFormat = '%2.0f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   928
lp.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   929
lp.xValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   930
lp.xValueAxis.valueMax = 5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   931
lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   932
lp.xValueAxis.labelTextFormat = '%2.1f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   933
lp.yValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   934
lp.yValueAxis.valueMax = 7
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   935
lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   936
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   937
drawing.add(lp)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   938
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   939
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   940
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   941
from reportlab.graphics.charts.lineplots import LinePlot
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   942
from reportlab.graphics.widgets.markers import makeMarker
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   943
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   944
drawing = Drawing(400, 200)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   945
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   946
data = [
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   947
    ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   948
    ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   949
]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   950
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   951
lp = LinePlot()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   952
lp.x = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   953
lp.y = 50
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   954
lp.height = 125
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   955
lp.width = 300
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   956
lp.data = data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   957
lp.joinedLines = 1
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   958
lp.lines[0].symbol = makeMarker('FilledCircle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   959
lp.lines[1].symbol = makeMarker('Circle')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   960
lp.lineLabelFormat = '%2.0f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   961
lp.strokeColor = colors.black
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   962
lp.xValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   963
lp.xValueAxis.valueMax = 5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   964
lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   965
lp.xValueAxis.labelTextFormat = '%2.1f'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   966
lp.yValueAxis.valueMin = 0
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   967
lp.yValueAxis.valueMax = 7
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   968
lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   969
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   970
drawing.add(lp)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   971
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   972
draw(drawing, 'LinePlot sample')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   973
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   974
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   975
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   976
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   977
todo("Add properties table.")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   978
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   979
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   980
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   981
heading3("Pie Charts")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   982
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   983
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   984
We've already seen a pie chart example above.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   985
This is provisional but seems to do most things.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   986
At the very least we need to change the name.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   987
For completeness we will cover it here.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   988
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   989
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   990
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   991
from reportlab.graphics.charts.piecharts import Pie
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   992
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   993
d = Drawing(200, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   994
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   995
pc = Pie()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   996
pc.x = 65
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   997
pc.y = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   998
pc.width = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
   999
pc.height = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1000
pc.data = [10,20,30,40,50,60]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1001
pc.labels = ['a','b','c','d','e','f']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1002
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1003
pc.slices.strokeWidth=0.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1004
pc.slices[3].popout = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1005
pc.slices[3].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1006
pc.slices[3].strokeDashArray = [2,2]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1007
pc.slices[3].labelRadius = 1.75
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1008
pc.slices[3].fontColor = colors.red
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1009
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1010
d.add(pc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1011
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1012
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1013
from reportlab.graphics.charts.piecharts import Pie
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1014
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1015
d = Drawing(200, 100)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1016
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1017
pc = Pie()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1018
pc.x = 65
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1019
pc.y = 15
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1020
pc.width = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1021
pc.height = 70
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1022
pc.data = [10,20,30,40,50,60]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1023
pc.labels = ['a','b','c','d','e','f']
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1024
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1025
pc.slices.strokeWidth=0.5
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1026
pc.slices[3].popout = 10
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1027
pc.slices[3].strokeWidth = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1028
pc.slices[3].strokeDashArray = [2,2]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1029
pc.slices[3].labelRadius = 1.75
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1030
pc.slices[3].fontColor = colors.red
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1031
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1032
d.add(pc)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1033
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1034
draw(d, 'A bare bones pie chart')
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1035
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1036
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1037
Properties are covered below.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1038
The pie has a 'wedges' collection and we document wedge properties
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1039
in the same table.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1040
This was invented before we finished the $Label$ class and will
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1041
probably be reworked to use such labels shortly.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1042
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1043
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1044
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1045
todo("Add properties table.")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1046
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1047
##Property Value
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1048
##data a list or tuple of numbers
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1049
##x, y, width, height Bounding box of the pie. Note that x and y do NOT specify the centre but the bottom left corner, and that width and height do not have to be equal; pies may be elliptical and wedges will be drawn correctly.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1050
##labels None, or a list of strings. Make it None if you don't want labels around the edge of the pie. Since it is impossible to know the size of slices, we generally discourage placing labels in or around pies; it is much better to put them in a legend alongside.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1051
##startAngle Where is the start angle of the first pie slice? The default is '90' which is twelve o'clock.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1052
##direction Which direction do slices progress in? The default is 'clockwise'.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1053
##wedges Collection of wedges. This lets you customise each wedge, or individual ones. See below
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1054
##wedges.strokeWidth Border width for wedge
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1055
##wedges.strokeColor Border color
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1056
##wedges.strokeDashArray Solid or dashed line configuration for
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1057
##wedges.popout How far out should the slice(s) stick from the centre of
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1058
##the pie? default is zero.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1059
##wedges.fontName
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1060
##wedges.fontSize
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1061
##wedges.fontColor Used for text labels
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1062
##wedges.labelRadius This controls the anchor point for a text label. It
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1063
##is a fraction of the radius; 0.7 will place the text inside the pie,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1064
##1.2 will place it slightly outside. (note that if we add labels, we
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1065
##will keep this to specify their anchor point)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1066
##
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1067
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1068
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1069
heading3("Legends")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1070
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1071
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1072
Various preliminary legend classes can be found but need a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1073
cleanup to be consistent with the rest of the charting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1074
model.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1075
Legends are the natural place to specify the colors and line
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1076
styles of charts; we propose that each chart is created with
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1077
a $legend$ attribute which is invisible.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1078
One would then do the following to specify colors:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1079
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1080
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1081
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1082
myChart.legend.defaultColors = [red, green, blue]
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1083
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1084
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1085
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1086
One could also define a group of charts sharing the same legend:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1087
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1088
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1089
eg("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1090
myLegend = Legend()
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1091
myLegend.defaultColor = [red, green.....] #yuck!
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1092
myLegend.columns = 2
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1093
# etc.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1094
chart1.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1095
chart2.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1096
chart3.legend = myLegend
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1097
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1098
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1099
# Hack to force a new paragraph before the todo() :-(
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1100
disc("")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1101
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1102
todo("""Does this work? Is it an acceptable complication over specifying chart
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1103
colors directly?""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1104
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1105
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1106
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1107
heading3("Remaining Issues")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1108
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1109
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1110
There are several issues that are <i>almost</i> solved, but for which
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1111
is is a bit too early to start making them really public.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1112
Nevertheless, here is a list of things that are under way:
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1113
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1114
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1115
list("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1116
Color specification - right now the chart has an undocumented property
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1117
$defaultColors$, which provides a list of colors to cycle through,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1118
such that each data series gets its own color.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1119
Right now, if you introduce a legend, you need to make sure it shares
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1120
the same list of colors.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1121
Most likely, this will be replaced with a scheme to specify a kind
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1122
of legend containing attributes with different values for each data
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1123
series.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1124
This legend can then also be shared by several charts, but need not
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1125
be visible itself.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1126
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1127
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1128
list("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1129
Additional chart types - when the current design will have become
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1130
more stable, we expect to add variants of bar charts to deal with stacked
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1131
and percentile bars as well as the side-by-side variant seen here.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1132
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1133
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1134
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1135
heading3("Outlook")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1136
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1137
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1138
It will take some time to deal with the full range of chart types.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1139
We expect to finalize bars and pies first and to produce trial
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1140
implementations of more general plots, thereafter.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1141
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1142
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1143
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1144
heading3("X-Y Plots")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1145
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1146
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1147
Most other plots involve two value axes and directly plotting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1148
x-y data in some form.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1149
The series can be plotted as lines, marker symbols, both, or
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1150
custom graphics such as open-high-low-close graphics.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1151
All share the concepts of scaling and axis/title formatting.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1152
At a certain point, a routine will loop over the data series and
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1153
'do something' with the data points at given x-y locations.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1154
Given a basic line plot, it should be very easy to derive a
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1155
custom chart type just by overriding a single method - say,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1156
$drawSeries()$.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1157
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1158
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1159
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1160
heading3("Marker customisation and custom shapes")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1161
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1162
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1163
Well known plotting packages such as excel, Mathematica and Excel
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1164
offer ranges of marker types to add to charts.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1165
We can do better - you can write any kind of chart widget you
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1166
want and just tell the chart to use it as an example.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1167
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1168
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1169
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1170
heading4("Combination plots")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1171
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1172
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1173
Combining multiple plot types is really easy.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1174
You can just draw several charts (bar, line or whatever) in
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1175
the same rectangle, suppressing axes as needed.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1176
So a chart could correlate a line with Scottish typhoid cases
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1177
over a 15 year period on the left axis with a set of bars showing
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1178
inflation rates on the right axis.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1179
If anyone can remind us where this example came from we'll
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1180
attribute it, and happily show the well-known graph as an
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1181
example.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1182
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1183
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1184
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1185
heading3("Interactive editors")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1186
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1187
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1188
One principle of the Graphics package is to make all 'interesting'
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1189
properties of its graphic components accessible and changeable by
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1190
setting apropriate values of corresponding public attributes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1191
This makes it very tempting to build a tool like a GUI editor that
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1192
that helps you with doing that interactively.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1193
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1194
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1195
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1196
ReportLab has built such a tool using the Tkinter toolkit that
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1197
loads pure Python code describing a drawing and records your
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1198
property editing operations.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1199
This "change history" is then used to create code for a subclass
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1200
of that chart, say, that can be saved and used instantly just
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1201
like any other chart or as a new starting point for another
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1202
interactive editing session.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1203
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1204
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1205
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1206
This is still work in progress, though, and the conditions for
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1207
releasing this need to be further elaborated.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1208
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1209
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1210
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1211
heading3("Misc.")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1212
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1213
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1214
This has not been an exhaustive look at all the chart classes.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1215
Those classes are constantly being worked on.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1216
To see exactly what is in the current distribution, use the
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1217
$graphdocpy.py$ utility.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1218
By default, it will run on reportlab/graphics, and produce a full
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1219
report.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1220
(If you want to run it on other modules or packages,
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1221
$graphdocpy.py -h$ prints a help message that will tell you
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1222
how.)
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1223
""")
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1224
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1225
disc("""
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1226
This is the tool that was mentioned in the section on 'Documenting
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1227
Widgets'.
d47129e56d9f Merged graphguide into userguide.
jonas
parents:
diff changeset
  1228
""")