diff options
Diffstat (limited to 'bin/reportlab/docs/graphguide/ch4_widgets.py')
| -rw-r--r-- | bin/reportlab/docs/graphguide/ch4_widgets.py | 422 |
1 files changed, 422 insertions, 0 deletions
diff --git a/bin/reportlab/docs/graphguide/ch4_widgets.py b/bin/reportlab/docs/graphguide/ch4_widgets.py new file mode 100644 index 00000000000..eed115d6a86 --- /dev/null +++ b/bin/reportlab/docs/graphguide/ch4_widgets.py @@ -0,0 +1,422 @@ +#Copyright ReportLab Europe Ltd. 2000-2004 +#see license.txt for license details +#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch4_widgets.py + +from reportlab.tools.docco.rl_doc_utils import * +from reportlab.graphics.shapes import * +from reportlab.graphics.widgets import signsandsymbols + +heading1("Widgets") + +disc(""" +We now describe widgets and how they relate to shapes. +Using many examples it is shown how widgets make reusable +graphics components. +""") + + +heading2("Shapes vs. Widgets") + +disc("""Up until now, Drawings have been 'pure data'. There is no code in them + to actually do anything, except assist the programmer in checking and + inspecting the drawing. In fact, that's the cornerstone of the whole + concept and is what lets us achieve portability - a renderer only + needs to implement the primitive shapes.""") + +disc("""We want to build reusable graphic objects, including a powerful chart + library. To do this we need to reuse more tangible things than + rectangles and circles. We should be able to write objects for other + to reuse - arrows, gears, text boxes, UML diagram nodes, even fully + fledged charts.""") + +disc(""" +The Widget standard is a standard built on top of the shapes module. +Anyone can write new widgets, and we can build up libraries of them. +Widgets support the $getProperties()$ and $setProperties()$ methods, +so you can inspect and modify as well as document them in a uniform +way. +""") + +bullet("A widget is a reusable shape ") +bullet("""it can be initialized with no arguments + when its $draw()$ method is called it creates a primitive Shape or a + Group to represent itself""") +bullet("""It can have any parameters you want, and they can drive the way it is + drawn""") +bullet("""it has a $demo()$ method which should return an attractively drawn + example of itself in a 200x100 rectangle. This is the cornerstone of + the automatic documentation tools. The $demo()$ method should also have + a well written docstring, since that is printed too!""") + +disc("""Widgets run contrary to the idea that a drawing is just a bundle of + shapes; surely they have their own code? The way they work is that a + widget can convert itself to a group of primitive shapes. If some of + its components are themselves widgets, they will get converted too. + This happens automatically during rendering; the renderer will not see + your chart widget, but just a collection of rectangles, lines and + strings. You can also explicitly 'flatten out' a drawing, causing all + widgets to be converted to primitives.""") + + +heading2("Using a Widget") + +disc(""" +Let's imagine a simple new widget. +We will use a widget to draw a face, then show how it was implemented.""") + +eg(""" +>>> from reportlab.lib import colors +>>> from reportlab.graphics import shapes +>>> from reportlab.graphics import widgetbase +>>> from reportlab.graphics import renderPDF +>>> d = shapes.Drawing(200, 100) +>>> f = widgetbase.Face() +>>> f.skinColor = colors.yellow +>>> f.mood = "sad" +>>> d.add(f) +>>> renderPDF.drawToFile(d, 'face.pdf', 'A Face') +""") + +from reportlab.graphics import widgetbase +d = Drawing(200, 120) +f = widgetbase.Face() +f.x = 50 +f.y = 10 +f.skinColor = colors.yellow +f.mood = "sad" +d.add(f) +draw(d, 'A sample widget') + +disc(""" +Let's see what properties it has available, using the $setProperties()$ +method we have seen earlier: +""") + +eg(""" +>>> f.dumpProperties() +eyeColor = Color(0.00,0.00,1.00) +mood = sad +size = 80 +skinColor = Color(1.00,1.00,0.00) +x = 10 +y = 10 +>>> +""") + +disc(""" +One thing which seems strange about the above code is that we did not +set the size or position when we made the face. +This is a necessary trade-off to allow a uniform interface for +constructing widgets and documenting them - they cannot require +arguments in their $__init__()$ method. +Instead, they are generally designed to fit in a 200 x 100 +window, and you move or resize them by setting properties such as +x, y, width and so on after creation. +""") + +disc(""" +In addition, a widget always provides a $demo()$ method. +Simple ones like this always do something sensible before setting +properties, but more complex ones like a chart would not have any +data to plot. +The documentation tool calls $demo()$ so that your fancy new chart +class can create a drawing showing what it can do. +""") + +disc(""" +Here are a handful of simple widgets available in the module +<i>signsandsymbols.py</i>: +""") + +from reportlab.graphics.shapes import Drawing +from reportlab.graphics.widgets import signsandsymbols + +d = Drawing(230, 230) + +ne = signsandsymbols.NoEntry() +ds = signsandsymbols.DangerSign() +fd = signsandsymbols.FloppyDisk() +ns = signsandsymbols.NoSmoking() + +ne.x, ne.y = 10, 10 +ds.x, ds.y = 120, 10 +fd.x, fd.y = 10, 120 +ns.x, ns.y = 120, 120 + +d.add(ne) +d.add(ds) +d.add(fd) +d.add(ns) + +draw(d, 'A few samples from signsandsymbols.py') + +disc(""" +And this is the code needed to generate them as seen in the drawing above: +""") + +eg(""" +from reportlab.graphics.shapes import Drawing +from reportlab.graphics.widgets import signsandsymbols + +d = Drawing(230, 230) + +ne = signsandsymbols.NoEntry() +ds = signsandsymbols.DangerSign() +fd = signsandsymbols.FloppyDisk() +ns = signsandsymbols.NoSmoking() + +ne.x, ne.y = 10, 10 +ds.x, ds.y = 120, 10 +fd.x, fd.y = 10, 120 +ns.x, ns.y = 120, 120 + +d.add(ne) +d.add(ds) +d.add(fd) +d.add(ns) +""") + + +heading2("Compound Widgets") + +disc("""Let's imagine a compound widget which draws two faces side by side. + This is easy to build when you have the Face widget.""") + +eg(""" +>>> tf = widgetbase.TwoFaces() +>>> tf.faceOne.mood +'happy' +>>> tf.faceTwo.mood +'sad' +>>> tf.dumpProperties() +faceOne.eyeColor = Color(0.00,0.00,1.00) +faceOne.mood = happy +faceOne.size = 80 +faceOne.skinColor = None +faceOne.x = 10 +faceOne.y = 10 +faceTwo.eyeColor = Color(0.00,0.00,1.00) +faceTwo.mood = sad +faceTwo.size = 80 +faceTwo.skinColor = None +faceTwo.x = 100 +faceTwo.y = 10 +>>> +""") + +disc("""The attributes 'faceOne' and 'faceTwo' are deliberately exposed so you + can get at them directly. There could also be top-level attributes, + but there aren't in this case.""") + + +heading2("Verifying Widgets") + +disc("""The widget designer decides the policy on verification, but by default + they work like shapes - checking every assignment - if the designer + has provided the checking information.""") + + +heading2("Implementing Widgets") + +disc("""We tried to make it as easy to implement widgets as possible. Here's + the code for a Face widget which does not do any type checking:""") + +eg(""" +class Face(Widget): + \"\"\"This draws a face with two eyes, mouth and nose.\"\"\" + + def __init__(self): + self.x = 10 + self.y = 10 + self.size = 80 + self.skinColor = None + self.eyeColor = colors.blue + self.mood = 'happy' + + def draw(self): + s = self.size # abbreviate as we will use this a lot + g = shapes.Group() + g.transform = [1,0,0,1,self.x, self.y] + # background + g.add(shapes.Circle(s * 0.5, s * 0.5, s * 0.5, + fillColor=self.skinColor)) + # CODE OMITTED TO MAKE MORE SHAPES + return g +""") + +disc("""We left out all the code to draw the shapes in this document, but you + can find it in the distribution in $widgetbase.py$.""") + +disc("""By default, any attribute without a leading underscore is returned by + setProperties. This is a deliberate policy to encourage consistent + coding conventions.""") + +disc("""Once your widget works, you probably want to add support for + verification. This involves adding a dictionary to the class called + $_verifyMap$, which map from attribute names to 'checking functions'. + The $widgetbase.py$ module defines a bunch of checking functions with names + like $isNumber$, $isListOfShapes$ and so on. You can also simply use $None$, + which means that the attribute must be present but can have any type. + And you can and should write your own checking functions. We want to + restrict the "mood" custom attribute to the values "happy", "sad" or + "ok". So we do this:""") + +eg(""" +class Face(Widget): + \"\"\"This draws a face with two eyes. It exposes a + couple of properties to configure itself and hides + all other details\"\"\" + def checkMood(moodName): + return (moodName in ('happy','sad','ok')) + _verifyMap = { + 'x': shapes.isNumber, + 'y': shapes.isNumber, + 'size': shapes.isNumber, + 'skinColor':shapes.isColorOrNone, + 'eyeColor': shapes.isColorOrNone, + 'mood': checkMood + } +""") + +disc("""This checking will be performed on every attribute assignment; or, if + $config.shapeChecking$ is off, whenever you call $myFace.verify()$.""") + + +heading2("Documenting Widgets") + +disc(""" +We are working on a generic tool to document any Python package or +module; this is already checked into ReportLab and will be used to +generate a reference for the ReportLab package. +When it encounters widgets, it adds extra sections to the +manual including:""") + +bullet("the doc string for your widget class ") +bullet("the code snippet from your <i>demo()</i> method, so people can see how to use it") +bullet("the drawing produced by the <i>demo()</i> method ") +bullet("the property dump for the widget in the drawing. ") + +disc(""" +This tool will mean that we can have guaranteed up-to-date +documentation on our widgets and charts, both on the web site +and in print; and that you can do the same for your own widgets, +too! +""") + + +heading2("Widget Design Strategies") + +disc("""We could not come up with a consistent architecture for designing + widgets, so we are leaving that problem to the authors! If you do not + like the default verification strategy, or the way + $setProperties/getProperties$ works, you can override them yourself.""") + +disc("""For simple widgets it is recommended that you do what we did above: + select non-overlapping properties, initialize every property on + $__init__$ and construct everything when $draw()$ is called. You can + instead have $__setattr__$ hooks and have things updated when certain + attributes are set. Consider a pie chart. If you want to expose the + individual wedges, you might write code like this:""") + +eg(""" +from reportlab.graphics.charts import piecharts +pc = piecharts.Pie() +pc.defaultColors = [navy, blue, skyblue] #used in rotation +pc.data = [10,30,50,25] +pc.slices[7].strokeWidth = 5 +""") +#removed 'pc.backColor = yellow' from above code example + +disc("""The last line is problematic as we have only created four wedges - in + fact we might not have created them yet. Does $pc.wedges[7]$ raise an + error? Is it a prescription for what should happen if a seventh wedge + is defined, used to override the default settings? We dump this + problem squarely on the widget author for now, and recommend that you + get a simple one working before exposing 'child objects' whose + existence depends on other properties' values :-)""") + +disc("""We also discussed rules by which parent widgets could pass properties + to their children. There seems to be a general desire for a global way + to say that 'all wedges get their lineWidth from the lineWidth of + their parent' without a lot of repetitive coding. We do not have a + universal solution, so again leave that to widget authors. We hope + people will experiment with push-down, pull-down and pattern-matching + approaches and come up with something nice. In the meantime, we + certainly can write monolithic chart widgets which work like the ones + in, say, Visual Basic and Delphi.""") + +disc("""For now have a look at the following sample code using an early + version of a pie chart widget and the output it generates:""") + +eg(""" +from reportlab.lib.colors import * +from reportlab.graphics import shapes,renderPDF +from reportlab.graphics.charts.piecharts import Pie + +d = Drawing(400,200) +d.add(String(100,175,"Without labels", textAnchor="middle")) +d.add(String(300,175,"With labels", textAnchor="middle")) + +pc = Pie() +pc.x = 25 +pc.y = 50 +pc.data = [10,20,30,40,50,60] +pc.slices[0].popout = 5 +d.add(pc, 'pie1') + +pc2 = Pie() +pc2.x = 150 +pc2.y = 50 +pc2.data = [10,20,30,40,50,60] +pc2.labels = ['a','b','c','d','e','f'] +d.add(pc2, 'pie2') + +pc3 = Pie() +pc3.x = 275 +pc3.y = 50 +pc3.data = [10,20,30,40,50,60] +pc3.labels = ['a','b','c','d','e','f'] +pc3.wedges.labelRadius = 0.65 +pc3.wedges.fontName = "Helvetica-Bold" +pc3.wedges.fontSize = 16 +pc3.wedges.fontColor = colors.yellow +d.add(pc3, 'pie3') +""") + +# Hack to force a new paragraph before the todo() :-( +disc("") + +from reportlab.lib.colors import * +from reportlab.graphics import shapes,renderPDF +from reportlab.graphics.charts.piecharts import Pie + +d = Drawing(400,200) +d.add(String(100,175,"Without labels", textAnchor="middle")) +d.add(String(300,175,"With labels", textAnchor="middle")) + +pc = Pie() +pc.x = 25 +pc.y = 50 +pc.data = [10,20,30,40,50,60] +pc.slices[0].popout = 5 +d.add(pc, 'pie1') + +pc2 = Pie() +pc2.x = 150 +pc2.y = 50 +pc2.data = [10,20,30,40,50,60] +pc2.labels = ['a','b','c','d','e','f'] +d.add(pc2, 'pie2') + +pc3 = Pie() +pc3.x = 275 +pc3.y = 50 +pc3.data = [10,20,30,40,50,60] +pc3.labels = ['a','b','c','d','e','f'] +pc3.slices.labelRadius = 0.65 +pc3.slices.fontName = "Helvetica-Bold" +pc3.slices.fontSize = 16 +pc3.slices.fontColor = colors.yellow +d.add(pc3, 'pie3') + +draw(d, 'Some sample Pies')
\ No newline at end of file |