more text, more pdfgen examples
authoraaron_watters
Wed, 12 Jul 2000 16:06:11 +0000
changeset 364 21f5c8641230
parent 363 e72f6cceebca
child 365 2a6ac05b39e8
more text, more pdfgen examples
docs/userguide/ch2_graphics.py
docs/userguide/examples.py
--- a/docs/userguide/ch2_graphics.py	Wed Jul 12 15:47:37 2000 +0000
+++ b/docs/userguide/ch2_graphics.py	Wed Jul 12 16:06:11 2000 +0000
@@ -325,7 +325,7 @@
 
 disc("""
 All PDF drawings fit into a specified page size.  Elements drawn outside of the specified
-page size are ignored.  Furthermore all drawn elements are passed through an affine
+page size are not visible.  Furthermore all drawn elements are passed through an affine
 transformation which may adjust their location and/or distort their appearence.  The
 $setPageSize$ method adjusts the current page size.  The $transform$, $translate$, $scale$,
 $rotate$, and $skew$ methods add additional transformations to the current transformation.
@@ -343,7 +343,8 @@
 other graphics state in order to restore them later. The $saveState$ method marks the
 current graphics state for later restoration by a matching $restoreState$.  Note that
 the save and restore method invokation must match -- a restore call restores the state to
-the most recently saved state.  You cannot save the state on one page and restore
+the most recently saved state which hasn't been restored yet.  
+You cannot save the state on one page and restore
 it on the next, however -- no state is preserved between pages.""")
 
 heading2("Other $canvas$ methods.")
@@ -816,7 +817,7 @@
 
 eg(examples.testcaps)
 
-disc("""The line cap setting, like the line join setting, is only
+disc("""The line cap setting, like the line join setting, is only clearly
 visible when the lines are thick.""")
 
 illust(examples.caps, "line cap settings")
@@ -931,31 +932,142 @@
 
 heading2("Path object methods")
 
+disc("""
+Path objects build complex graphical figures by setting
+the "pen" or "brush" at a start point on the canvas and drawing
+lines or curves to additional points on the canvas.  Most operations
+apply paint on the canvas starting at the end point of the last
+operation and leave the brush at a new end point.
+""")
+
 eg("""pathobject.moveTo(x,y)""")
 
+disc("""
+The $moveTo$ method lifts the brush (ending any current sequence
+of lines or curves if there is one) and replaces the brush at the
+new ^(x,y)^ location on the canvas to start a new path sequence.
+""")
+
 eg("""pathobject.lineTo(x,y)""")
 
+disc("""
+The $lineTo$ method paints straight line segment from the current brush
+location to the new ^(x,y)^ location.
+""")
+
 eg("""pathobject.curveTo(x1, y1, x2, y2, x3, y3) """)
 
+disc("""
+The $curveTo$ method starts painting a Bezier curve beginning at
+the current brush location, using ^(x1,y1)^, ^(x2,y2)^, and ^(x3,y3)^
+as the other three control points, leaving the brush on ^(x3,y3)^.
+""")
+
 eg("""pathobject.arc(x1,y1, x2,y2, startAng=0, extent=90) """)
 
 eg("""pathobject.arcTo(x1,y1, x2,y2, startAng=0, extent=90) """)
 
+disc("""
+The $arc$ and $arcTo$ methods paint partial ellipses.  The $arc$ method first "lifts the brush"
+and starts a new shape sequence.  The $arcTo$ method joins the start of 
+the partial ellipse to the current
+shape sequence by line segment before drawing the partial ellipse.  The points
+^(x1,y1)^ and ^(x2,y2)^ define opposite corner points of a rectangle enclosing
+the ellipse.  The $startAng$ is an angle (in degrees) specifying where to begin
+the partial ellipse where the 0 angle is the midpoint of the right border of the enclosing
+rectangle (when ^(x1,y1)^ is the lower left corner and ^(x2,y2)^ is the upper
+right corner).  The $extent$ is the angle in degrees to traverse on the ellipse.
+""")
+
+eg(examples.testarcs)
+
+disc("""The $arcs$ function above exercises the two partial ellipse methods.
+It produces the following drawing.""")
+
+illust(examples.arcs, "arcs in path objects")
+
 eg("""pathobject.rect(x, y, width, height) """)
 
+disc("""The $rect$ method draws a rectangle with lower left corner
+at ^(x,y)^ of the specified ^width^ and ^height^.""")
+
 eg("""pathobject.ellipse(x, y, width, height)""")
 
+disc("""The $ellipse$ method
+draws an ellipse enclosed in the rectange with lower left corner
+at ^(x,y)^ of the specified ^width^ and ^height^.
+""")
+
 eg("""pathobject.circle(x_cen, y_cen, r) """)
 
+disc("""The $circle$ method
+draws a circle centered at ^(x_cen, y_cen)^ with radius ^r^.
+""")
+
+eg(examples.testvariousshapes)
+
+disc("""
+The $variousshapes$ function above shows a rectangle, circle and ellipse
+placed in a frame of reference grid.
+""")
+
+illust(examples.variousshapes, "rectangles, circles, ellipses in path objects")
+
 eg("""pathobject.close() """)
 
+disc("""
+The $close$ method closes the current graphical figure
+by painting a line segment from the last point of the figure
+to the starting point of the figure (the the most
+recent point where the brush was placed on the paper by $moveTo$
+or $arc$ or other placement operations).
+""")
+
+eg(examples.testclosingfigures)
+
+disc("""
+The $closingfigures$ function illustrates the
+effect of closing or not closing figures including a line
+segment and a partial ellipse.
+""")
+
+illust(examples.closingfigures, "closing and not closing pathobject figures")
+
+disc("""
+Closing or not closing graphical figures effects only the stroked outline
+of a figure, not the filling of the figure as illustrated above.
+""")
+
+
+disc("""
+For a more extensive example of drawing using a path object
+examine the $hand$ function.
+""")
+
 eg(examples.testhand)
 
+disc("""
+In debug mode (the default) the $hand$ function shows the tangent line segments
+to the bezier curves used to compose the figure.  Note that where the segments
+line up the curves join smoothly, but where they do not line up the curves show
+a "sharp edge".
+""")
+
 illust(examples.hand, "an outline of a hand using bezier curves")
 
+disc("""
+Used in non-debug mode the $hand$ function only shows the
+Bezier curves.  With the $fill$ parameter set the figure is
+filled using the current fill color.
+""")
 
 eg(examples.testhand2)
 
+disc("""
+Note that the "stroking" of the border draws over the interior fill where
+they overlap.
+""")
+
 illust(examples.hand2, "the finished hand, filled")
 
 
--- a/docs/userguide/examples.py	Wed Jul 12 15:47:37 2000 +0000
+++ b/docs/userguide/examples.py	Wed Jul 12 16:06:11 2000 +0000
@@ -101,17 +101,22 @@
     from reportlab.lib import colors
     from reportlab.lib.units import inch
     black = colors.black
-    y = x = 0; dy=inch*3/4.0; dx=inch*5.5/5; w=h=dy/2; rdx=(dx-w)/2; rdy=h/5.0; texty=h+2*rdy
+    y = x = 0; dy=inch*3/4.0; dx=inch*5.5/5; w=h=dy/2; rdx=(dx-w)/2
+    rdy=h/5.0; texty=h+2*rdy
     canvas.setFont("Helvetica",10)
-    for name in ("lavenderblush", "lawngreen", "lemonchiffon", "lightblue", "lightcoral"):
-        color = getattr(colors,name) # colors.lavenderblush, ... (shorthand)
-        canvas.setFillColor(color)
+    for [namedcolor, name] in (
+           [colors.lavenderblush, "lavenderblush"], 
+           [colors.lawngreen, "lawngreen"],
+           [colors.lemonchiffon, "lemonchiffon"],
+           [colors.lightblue, "lightblue"],
+           [colors.lightcoral, "lightcoral"]):
+        canvas.setFillColor(namedcolor)
         canvas.rect(x+rdx, y+rdy, w, h, fill=1)
         canvas.setFillColor(black)
         canvas.drawCentredString(x+dx/2, y+texty, name)
         x = x+dx
     y = y + dy; x = 0
-    for rgb in [(1,0,0), (0,1,0), (0,0,1), (0.5,0.3,0.1), (0.1,0.5,0.3)]:
+    for rgb in [(1,0,0), (0,1,0), (0,0,1), (0.5,0.3,0.1), (0.4,0.5,0.3)]:
         r,g,b = rgb
         canvas.setFillColorRGB(r,g,b)
         canvas.rect(x+rdx, y+rdy, w, h, fill=1)
@@ -127,8 +132,7 @@
         canvas.drawCentredString(x+dx/2, y+texty, "c%s m%s y%s k%s"%cmyk)
         x = x+dx
     y = y + dy; x = 0
-    for g in range(5):
-        gray = g/4.0
+    for gray in (0.0, 0.25, 0.50, 0.75, 1.0):
         canvas.setFillGray(gray)
         canvas.rect(x+rdx, y+rdy, w, h, fill=1)
         canvas.setFillColor(black)
@@ -344,7 +348,8 @@
 """
 
 teststar = """
-def star(canvas, title="Title Here", aka="Comment here.", xcenter=None, ycenter=None, nvertices=5):
+def star(canvas, title="Title Here", aka="Comment here.", 
+         xcenter=None, ycenter=None, nvertices=5):
     from math import pi
     from reportlab.lib.units import inch
     radius=inch/3.0
@@ -581,6 +586,57 @@
         y = y-13
 """
 
+testarcs = """
+def arcs(canvas):
+    from reportlab.lib.units import inch
+    canvas.setLineWidth(4)
+    canvas.setStrokeColorRGB(0.8, 1, 0.6)
+    # draw rectangles enclosing the arcs
+    canvas.rect(inch, inch, 1.5*inch, inch)
+    canvas.rect(3*inch, inch, inch, 1.5*inch)
+    canvas.setStrokeColorRGB(0, 0.2, 0.4)
+    canvas.setFillColorRGB(1, 0.6, 0.8)
+    p = canvas.beginPath()
+    p.moveTo(0.2*inch, 0.2*inch)
+    p.arcTo(inch, inch, 2.5*inch,2*inch, startAng=-30, extent=135)
+    p.arc(3*inch, inch, 4*inch, 2.5*inch, startAng=-45, extent=270)
+    canvas.drawPath(p, fill=1, stroke=1)
+"""
+testvariousshapes = """
+def variousshapes(canvas):
+    from reportlab.lib.units import inch
+    inch = int(inch)
+    canvas.setStrokeGray(0.5)
+    canvas.grid(range(0,11*inch/2,inch/2), range(0,7*inch/2,inch/2))
+    canvas.setLineWidth(4)
+    canvas.setStrokeColorRGB(0, 0.2, 0.7)
+    canvas.setFillColorRGB(1, 0.6, 0.8)
+    p = canvas.beginPath()
+    p.rect(0.5*inch, 0.5*inch, 0.5*inch, 2*inch)
+    p.circle(2.75*inch, 1.5*inch, 0.3*inch)
+    p.ellipse(3.5*inch, 0.5*inch, 1.2*inch, 2*inch)
+    canvas.drawPath(p, fill=1, stroke=1)
+"""
+
+testclosingfigures = """
+def closingfigures(canvas):
+    from reportlab.lib.units import inch
+    h = inch/3.0; k = inch/2.0
+    canvas.setStrokeColorRGB(0.2,0.3,0.5)
+    canvas.setFillColorRGB(0.8,0.6,0.2)
+    canvas.setLineWidth(4)
+    p = canvas.beginPath()
+    for i in (1,2,3,4):
+        for j in (1,2):
+            xc,yc = inch*i, inch*j
+            p.moveTo(xc,yc)
+            p.arcTo(xc-h, yc-k, xc+h, yc+k, startAng=0, extent=60*i)
+            # close only the first one, not the second one
+            if j==1:
+                p.close()
+    canvas.drawPath(p, fill=1, stroke=1)
+"""
+
 testforms = """
 def forms(canvas):
     #first create a form...