18 heading3("Design Goals") |
18 heading3("Design Goals") |
19 |
19 |
20 disc("Here are some of the design goals: ") |
20 disc("Here are some of the design goals: ") |
21 |
21 |
22 disc("<i>Make simple top-level use really simple </i>") |
22 disc("<i>Make simple top-level use really simple </i>") |
23 disc("""<para lindent=+36>It should be possible to create a simple chart with minimum lines of |
23 disc("""<para lindent="+36">It should be possible to create a simple chart with minimum lines of |
24 code, yet have it 'do the right things' with sensible automatic |
24 code, yet have it 'do the right things' with sensible automatic |
25 settings. The pie chart snippets above do this. If a real chart has |
25 settings. The pie chart snippets above do this. If a real chart has |
26 many subcomponents, you still should not need to interact with them |
26 many subcomponents, you still should not need to interact with them |
27 unless you want to customize what they do.""") |
27 unless you want to customize what they do.</para>""") |
28 |
28 |
29 disc("<i>Allow precise positioning </i>") |
29 disc("<i>Allow precise positioning </i>") |
30 disc("""<para lindent=+36>An absolute requirement in publishing and graphic design is to control |
30 disc("""<para lindent="+36">An absolute requirement in publishing and graphic design is to control |
31 the placing and style of every element. We will try to have properties |
31 the placing and style of every element. We will try to have properties |
32 that specify things in fixed sizes and proportions of the drawing, |
32 that specify things in fixed sizes and proportions of the drawing, |
33 rather than having automatic resizing. Thus, the 'inner plot |
33 rather than having automatic resizing. Thus, the 'inner plot |
34 rectangle' will not magically change when you make the font size of |
34 rectangle' will not magically change when you make the font size of |
35 the y labels bigger, even if this means your labels can spill out of |
35 the y labels bigger, even if this means your labels can spill out of |
36 the left edge of the chart rectangle. It is your job to preview the |
36 the left edge of the chart rectangle. It is your job to preview the |
37 chart and choose sizes and spaces which will work.""") |
37 chart and choose sizes and spaces which will work.</para>""") |
38 |
38 |
39 disc("""<para lindent=+36>Some things do need to be automatic. For example, if you want to fit N |
39 disc("""<para lindent="+36">Some things do need to be automatic. For example, if you want to fit N |
40 bars into a 200 point space and don't know N in advance, we specify |
40 bars into a 200 point space and don't know N in advance, we specify |
41 bar separation as a percentage of the width of a bar rather than a |
41 bar separation as a percentage of the width of a bar rather than a |
42 point size, and let the chart work it out. This is still deterministic |
42 point size, and let the chart work it out. This is still deterministic |
43 and controllable.""") |
43 and controllable.</para>""") |
44 |
44 |
45 disc("<i>Control child elements individually or as a group</i>") |
45 disc("<i>Control child elements individually or as a group</i>") |
46 disc("""<para lindent=+36>We use smart collection classes that let you customize a group of |
46 disc("""<para lindent="+36">We use smart collection classes that let you customize a group of |
47 things, or just one of them. For example you can do this in our |
47 things, or just one of them. For example you can do this in our |
48 experimental pie chart:""") |
48 experimental pie chart:</para>""") |
49 |
49 |
50 eg(""" |
50 eg(""" |
51 d = Drawing(400,200) |
51 d = Drawing(400,200) |
52 pc = Pie() |
52 pc = Pie() |
53 pc.x = 150 |
53 pc.x = 150 |
61 pc.slices[3].labelRadius = 1.75 |
61 pc.slices[3].labelRadius = 1.75 |
62 pc.slices[3].fontColor = colors.red |
62 pc.slices[3].fontColor = colors.red |
63 d.add(pc, '') |
63 d.add(pc, '') |
64 """) |
64 """) |
65 |
65 |
66 disc("""<para lindent=+36>pc.slices[3] actually lazily creates a little object which holds |
66 disc("""<para lindent="+36">pc.slices[3] actually lazily creates a little object which holds |
67 information about the slice in question; this will be used to format a |
67 information about the slice in question; this will be used to format a |
68 fourth slice at draw-time if there is one.""") |
68 fourth slice at draw-time if there is one.</para>""") |
69 |
69 |
70 disc("<i>Only expose things you should change </i>") |
70 disc("<i>Only expose things you should change </i>") |
71 disc("""<para lindent=+36>It would be wrong from a statistical viewpoint to let you directly |
71 disc("""<para lindent="+36">It would be wrong from a statistical viewpoint to let you directly |
72 adjust the angle of one of the pie wedges in the above example, since |
72 adjust the angle of one of the pie wedges in the above example, since |
73 that is determined by the data. So not everything will be exposed |
73 that is determined by the data. So not everything will be exposed |
74 through the public properties. There may be 'back doors' to let you |
74 through the public properties. There may be 'back doors' to let you |
75 violate this when you really need to, or methods to provide advanced |
75 violate this when you really need to, or methods to provide advanced |
76 functionality, but in general properties will be orthogonal.""") |
76 functionality, but in general properties will be orthogonal.</para>""") |
77 |
77 |
78 disc("<i>Composition and component based </i>") |
78 disc("<i>Composition and component based </i>") |
79 disc("""<para lindent=+36>Charts are built out of reusable child widgets. A Legend is an |
79 disc("""<para lindent="+36">Charts are built out of reusable child widgets. A Legend is an |
80 easy-to-grasp example. If you need a specialized type of legend (e.g. |
80 easy-to-grasp example. If you need a specialized type of legend (e.g. |
81 circular colour swatches), you should subclass the standard Legend |
81 circular colour swatches), you should subclass the standard Legend |
82 widget. Then you could either do something like...""") |
82 widget. Then you could either do something like...</para>""") |
83 |
83 |
84 eg(""" |
84 eg(""" |
85 c = MyChartWithLegend() |
85 c = MyChartWithLegend() |
86 c.legend = MyNewLegendClass() # just change it |
86 c.legend = MyNewLegendClass() # just change it |
87 c.legend.swatchRadius = 5 # set a property only relevant to the new one |
87 c.legend.swatchRadius = 5 # set a property only relevant to the new one |
88 c.data = [10,20,30] # and then configure as usual... |
88 c.data = [10,20,30] # and then configure as usual... |
89 """) |
89 """) |
90 |
90 |
91 disc("""<para lindent=+36>...or create/modify your own chart or drawing class which creates one |
91 disc("""<para lindent="+36">...or create/modify your own chart or drawing class which creates one |
92 of these by default. This is also very relevant for time series |
92 of these by default. This is also very relevant for time series |
93 charts, where there can be many styles of x axis.""") |
93 charts, where there can be many styles of x axis.</para>""") |
94 |
94 |
95 disc("""<para lindent=+36>Top level chart classes will create a number of such components, and |
95 disc("""<para lindent="+36">Top level chart classes will create a number of such components, and |
96 then either call methods or set private properties to tell them their |
96 then either call methods or set private properties to tell them their |
97 height and position - all the stuff which should be done for you and |
97 height and position - all the stuff which should be done for you and |
98 which you cannot customise. We are working on modelling what the |
98 which you cannot customise. We are working on modelling what the |
99 components should be and will publish their APIs here as a consensus |
99 components should be and will publish their APIs here as a consensus |
100 emerges.""") |
100 emerges.</para>""") |
101 |
101 |
102 disc("<i>Multiples </i>") |
102 disc("<i>Multiples </i>") |
103 disc("""<para lindent=+36>A corollary of the component approach is that you can create diagrams |
103 disc("""<para lindent="+36">A corollary of the component approach is that you can create diagrams |
104 with multiple charts, or custom data graphics. Our favourite example |
104 with multiple charts, or custom data graphics. Our favourite example |
105 of what we are aiming for is the weather report in our gallery |
105 of what we are aiming for is the weather report in our gallery |
106 contributed by a user; we'd like to make it easy to create such |
106 contributed by a user; we'd like to make it easy to create such |
107 drawings, hook the building blocks up to their legends, and feed that |
107 drawings, hook the building blocks up to their legends, and feed that |
108 data in a consistent way.""") |
108 data in a consistent way.</para>""") |
109 disc("""<para lindent=+36>(If you want to see the image, it is available on our website |
109 disc("""<para lindent="+36">(If you want to see the image, it is available on our website |
110 <font color="blue"><a href="https://www.reportlab.com/media/imadj/data/RLIMG_e5e5cb85cc0a555f5433528ac38c5884.PDF">here</a></font>)""") |
110 <font color="blue"><a href="https://www.reportlab.com/media/imadj/data/RLIMG_e5e5cb85cc0a555f5433528ac38c5884.PDF">here</a></font>)</para>""") |
111 |
111 |
112 |
112 |
113 ##heading3("Key Concepts and Components") |
113 ##heading3("Key Concepts and Components") |
114 heading3("Overview") |
114 heading3("Overview") |
115 |
115 |