docs/userguide/genuserguide.py
author aaron_watters
Mon, 19 Jun 2000 21:13:02 +0000
changeset 283 50f6c1be3e51
parent 273 cd705b27b6a5
child 293 84a2635a8c30
permissions -rw-r--r--
2nd try. more text
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     1
#!/bin/env python
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     2
###############################################################################
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     3
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     4
#	ReportLab Public License Version 1.0
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     5
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     6
#   Except for the change of names the spirit and intention of this
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     7
#   license is the same as that of Python
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     8
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
     9
#	(C) Copyright ReportLab Inc. 1998-2000.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    10
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    11
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    12
# All Rights Reserved
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    13
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    14
# Permission to use, copy, modify, and distribute this software and its
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    15
# documentation for any purpose and without fee is hereby granted, provided
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    16
# that the above copyright notice appear in all copies and that both that
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    17
# copyright notice and this permission notice appear in supporting
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    18
# documentation, and that the name of ReportLab not be used
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    19
# in advertising or publicity pertaining to distribution of the software
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    20
# without specific, written prior permission. 
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    21
# 
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    22
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    23
# Disclaimer
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    24
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    25
# ReportLab Inc. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    26
# SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    27
# IN NO EVENT SHALL ReportLab BE LIABLE FOR ANY SPECIAL, INDIRECT
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    28
# OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    29
# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    30
# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    31
# PERFORMANCE OF THIS SOFTWARE. 
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    32
#
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    33
###############################################################################
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    34
#	$Log: genuserguide.py,v $
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
    35
#	Revision 1.2  2000/06/19 21:13:02  aaron_watters
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
    36
#	2nd try. more text
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
    37
#
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    38
#	Revision 1.1  2000/06/17 02:57:56  aaron_watters
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    39
#	initial checkin. user guide generation framework.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
    40
#	
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
    41
__version__=''' $Id: genuserguide.py,v 1.2 2000/06/19 21:13:02 aaron_watters Exp $ '''
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    42
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    43
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    44
__doc__ = """
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    45
This module contains the script for building the user guide.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    46
"""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    47
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    48
from reportlab.platypus.doctemplate import SimpleDocTemplate
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    49
from reportlab.platypus.flowables import Flowable
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    50
from reportlab.lib.units import inch
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    51
from reportlab.lib.pagesizes import letter
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    52
from reportlab.platypus import Paragraph, Spacer, Preformatted, PageBreak
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    53
from reportlab.lib.styles import PropertySet, getSampleStyleSheet, ParagraphStyle
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    54
from reportlab.lib import colors
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    55
import examples
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    56
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    57
styleSheet = getSampleStyleSheet()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    58
from reportlab.lib.corp import ReportLabLogo
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    59
LOGO = ReportLabLogo(0.25*inch, 0.25*inch, inch, 0.75*inch)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    60
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    61
class PageAnnotations:
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    62
    """ "closure" containing onfirstpage, onnextpage actions
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    63
        and any data they might want to use.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    64
    """
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    65
    pagesize = letter
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    66
    pagenumber = 1
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    67
    def onFirstPage(self, canvas, doc):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    68
        (xsize, ysize) = self.pagesize
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    69
        LOGO.draw(canvas)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    70
        #  width=6.25*inch,height=0.62*inch)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    71
        canvas.setFont("Helvetica", 12)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    72
        canvas.drawRightString(xsize-inch, ysize-0.8*inch, "ReportLab User Guide")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    73
        self.pagenumber = self.pagenumber+1
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    74
    def onNextPage(self, canvas, doc):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    75
        canvas.saveState()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    76
        (xsize, ysize) = self.pagesize
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    77
        canvas.setFont("Helvetica", 12)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    78
        canvas.drawString(inch, ysize-0.8*inch, "Page %s" % self.pagenumber)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    79
        self.onFirstPage(canvas, doc)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    80
        canvas.restoreState()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    81
        
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    82
class Guide:
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    83
    def __init__(self):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    84
        self.myannotations = PageAnnotations()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    85
        self.story = story()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    86
    def go(self, filename="userguide.pdf"):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    87
        # generate the doc...
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    88
	doc = SimpleDocTemplate(filename,pagesize = letter ,showBoundary=0,
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    89
	  leftMargin=inch, rightMargin=inch, topMargin=1.7*inch, bottomMargin=inch+90)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    90
	story = self.story
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    91
	doc.build(story, self.myannotations.onFirstPage, self.myannotations.onNextPage)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    92
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    93
H = styleSheet['Heading2']
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    94
lessonnamestyle = ParagraphStyle("lessonname", parent=H)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    95
lessonnamestyle.fontName = 'Helvetica-Bold'
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    96
B = styleSheet['BodyText']
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    97
discussiontextstyle = ParagraphStyle("discussiontext", parent=B)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    98
discussiontextstyle.fontName= 'Helvetica'
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    99
exampletextstyle = styleSheet['Code']
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   100
# size for every example
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   101
examplefunctionxinches = 5.5
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   102
examplefunctionyinches = 3
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   103
examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   104
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   105
# for testing
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   106
def NOP(*x,**y):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   107
    return None
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   108
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   109
BODY = []
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   110
def story():
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   111
    return BODY
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   112
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   113
def disc(text, klass=Paragraph, style=discussiontextstyle):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   114
    P = klass(text, style)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   115
    BODY.append(P)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   116
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   117
def eg(text):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   118
    BODY.append(Spacer(0.1*inch, 0.1*inch))
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   119
    disc(text, klass=Preformatted, style=exampletextstyle)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   120
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   121
#eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   122
#this
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   123
#  is 
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   124
#    an 
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   125
#     example""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   126
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   127
def head(text):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   128
    disc(text, style=lessonnamestyle)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   129
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   130
#head("this is a header")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   131
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   132
def lesson(text):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   133
    BODY.append(PageBreak())
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   134
    head(text)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   135
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   136
def canvasdemo(function):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   137
    BODY.append(Spacer(0.1*inch, 0.1*inch))
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   138
    BODY.append(OperationWrapper(function))
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   139
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   140
class OperationWrapper(Flowable):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   141
    """wrap a drawing operation as a flowable.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   142
       the operation should respect the examplefunctiondisplaysizes
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   143
       limitations.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   144
       This example wraps a drawing operator f(pdfgen.canvas).
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   145
       Always enclosed in a rectangle.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   146
    """
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   147
    def __init__(self, operation):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   148
        self.operation = operation
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   149
        
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   150
    def wrap(self, aw, ah):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   151
        return examplefunctiondisplaysizes # always the same
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   152
        
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   153
    def draw(self):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   154
        canvas = self.canv
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   155
        canvas.saveState()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   156
        (x,y) = examplefunctiondisplaysizes
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   157
        self.operation(canvas)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   158
        canvas.restoreState()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   159
        canvas.rect(0,0,x,y)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   160
        
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   161
###### testing...
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   162
#canvasdemo(NOP)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   163
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   164
#lesson("this is a new lesson")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   165
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   166
#disc("this explains the example")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   167
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   168
#eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   169
#this
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   170
#  is the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   171
#    example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   172
#      code""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   173
      
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   174
#disc("the execution of the example follows")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   175
      
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   176
#canvasdemo(NOP) # execute some code
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   177
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   178
head("ReportLab User Guide")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   179
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   180
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   181
This document is intended to be a conversational introduction
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   182
to the use of the ReportLab packages.  Some previous programming experience
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   183
is presumed and familiarity with the Python Programming language is
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   184
recommended.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   185
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   186
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   187
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   188
This document is in a <em>very</em> preliminary form.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   189
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   190
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   191
lesson("Introduction to pdfgen")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   192
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   193
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   194
The pdfgen package is the lowest level interface for
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   195
generating PDF documents.  A pdfgen program is essentially
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   196
a sequence of instructions for "painting" a document onto
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   197
a sequence of pages.  The interface object which provides the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   198
painting operations is the pdfgen canvas.  
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   199
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   200
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   201
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   202
The canvas should be thought of as a sheet of white paper
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   203
with points on the sheet identified using Cartesian (X,Y) coordinates
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   204
which by default have the (0,0) origin point at the lower
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   205
left corner of the page.  Furthermore the first coordinate (x)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   206
goes to the right and the second coordinate (y) goes up, by
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   207
default.""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   208
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   209
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   210
A simple example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   211
program that uses a canvas follows.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   212
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   213
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   214
eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   215
    from reportlab.pdfgen import canvas
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   216
    c = canvas.Canvas("hello.pdf")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   217
    hello(c)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   218
    c.showPage()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   219
    c.save()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   220
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   221
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   222
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   223
The above code creates a canvas object which will generate
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   224
a PDF file named hello.pdf in the current working directory.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   225
It then calls the hello function passing the canvas as an argument.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   226
Finally the showPage method saves the current page of the canvas
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   227
and the save method stores the file and closes the canvas.""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   228
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   229
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   230
The showPage method causes the canvas to stop drawing on the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   231
current page and any further operations will draw on a subsequent
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   232
page (if there are any further operations -- if not there no
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   233
new page is created).  The save method must be called after the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   234
construction of the document is complete -- it generates the PDF
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   235
document, which is the whole purpose of the canvas object.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   236
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   237
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   238
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   239
Suppose the hello function referenced above is implemented as
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   240
follows (we will not explain each of the operations in detail
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   241
yet).
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   242
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   243
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   244
eg(examples.testhello)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   245
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   246
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   247
Examining this code notice that there are essentially two types
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   248
of operations performed using a canvas.  The first type draws something
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   249
on the page such as a text string or a rectangle or a line.  The second
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   250
type changes the state of the canvas such as
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   251
changing the current fill or stroke color or changing the current font
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   252
type and size.  
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   253
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   254
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   255
disc("""
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   256
If we imagine the program as a painter working on
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   257
the canvas the "draw" operations apply paint to the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   258
the current set of tools (colors, line styles, fonts, etcetera)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   259
and the "state change" operations change one of the current tools
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   260
(changing the fill color from whatever it was to blue, or changing
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   261
the current font to Times-Roman in 15 points, for example).
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   262
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   263
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   264
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   265
The document generated by the "hello world" program listed above would contain
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   266
the following graphics.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   267
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   268
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   269
canvasdemo(examples.hello)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   270
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   271
head("About the demos in this document")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   272
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   273
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   274
This document contains demonstrations of the code discussed like the one shown
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   275
in the rectangle above.  These demos are drawn on a "tiny page" embedded
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   276
within the real pages of the guide.  The tiny pages are %s inches wide
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   277
and %s inches tall.  The demos displays show the actual output of the demo
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   278
code.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   279
""" % (examplefunctionxinches, examplefunctionyinches))
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   280
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   281
lesson('The tools: the "draw" operations')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   282
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   283
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   284
This section briefly lists the tools available to the program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   285
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   286
These will be discussed in detail in later sections.  They are listed
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   287
here for easy reference and for summary purposes.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   288
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   289
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   290
head("Line methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   291
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   292
eg("""canvas.line(x1,y1,x2,y2)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   293
eg("""canvas.lines(linelist)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   294
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   295
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   296
The line methods draw straight line segments on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   297
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   298
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   299
head("Shape methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   300
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   301
eg("""canvas.grid(xlist, ylist) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   302
eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   303
eg("""canvas.arc(x1,y1,x2,y2) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   304
eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   305
eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   306
eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   307
eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   308
eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   309
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   310
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   311
The shape methods draw common complex shapes on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   312
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   313
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   314
head("The draw string methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   315
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   316
eg("""canvas.drawString(x, y, text):""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   317
eg("""canvas.drawRightString(x, y, text) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   318
eg("""canvas.drawCentredString(x, y, text)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   319
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   320
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   321
The draw string methods draw single lines of text on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   322
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   323
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   324
head("The text object methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   325
eg("""textobject = canvas.beginText(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   326
eg("""canvas.drawText(textobject) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   327
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   328
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   329
Text objects are used to format text in ways that
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   330
are not supported directly by the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   331
A program creates a text object from the canvas using beginText
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   332
and then formats text by invoking textobject methods.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   333
Finally the textobject is drawn onto the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   334
drawText.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   335
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   336
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   337
head("The path object methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   338
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   339
eg("""path = canvas.beginPath() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   340
eg("""canvas.drawPath(path, stroke=1, fill=0 """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   341
eg("""canvas.clipPath(path, stroke=1, fill=0 """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   342
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   343
head("Image methods")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   344
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   345
eg("""canvas.drawInlineImage(self, image, x,y, width=None,height=None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   346
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   347
head("Ending a page")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   348
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   349
eg("""canvas.showPage()""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   350
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   351
lesson('The toolbox: the "state change" operations')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   352
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   353
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   354
This section briefly lists the ways to switch the tools used by the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   355
program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   356
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   357
These too will be discussed in detail in later sections.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   358
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   359
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   360
head("Changing Colors")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   361
eg("""canvas.setFillColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   362
eg("""canvas.setStrikeColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   363
eg("""canvas.setFillColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   364
eg("""canvas.setStrokeColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   365
eg("""canvas.setFillColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   366
eg("""canvas.setStrokeColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   367
eg("""canvas.setFillGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   368
eg("""canvas.setStrokeGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   369
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   370
head("Changing Fonts")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   371
eg("""canvas.setFont(psfontname, size, leading = None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   372
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   373
head("Changing Graphical Styles")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   374
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   375
eg("""canvas.setLineWidth(width) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   376
eg("""canvas.setLineCap(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   377
eg("""canvas.setLineJoin(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   378
eg("""canvas.setMiterLimit(limit) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   379
eg("""canvas.setDash(self, array=[], phase=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   380
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   381
head("Changing Geometry")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   382
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   383
eg("""canvas.setPageSize(pair) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   384
eg("""canvas.transform(a,b,c,d,e,f): """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   385
eg("""canvas.translate(dx, dy) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   386
eg("""canvas.scale(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   387
eg("""canvas.rotate(theta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   388
eg("""canvas.skew(alpha, beta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   389
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   390
head("State control")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   391
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   392
eg("""canvas.saveState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   393
eg("""canvas.restoreState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   394
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   395
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   396
lesson("Other canvas methods.")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   397
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   398
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   399
Not all methods of the canvas object fit into the "tool" or "toolbox"
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   400
categories.  Below are some of the misfits, included here for completeness.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   401
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   402
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   403
eg("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   404
 canvas.setAuthor()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   405
 canvas.addOutlineEntry(title, key, level=0, closed=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   406
 canvas.setTitle(title)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   407
 canvas.setSubject(subj)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   408
 canvas.pageHasData()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   409
 canvas.showOutline()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   410
 canvas.bookmarkPage(name)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   411
 canvas.bookmarkHorizontalAbsolute(name, yhorizontal)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   412
 canvas.doForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   413
 canvas.beginForm(name, lowerx=0, lowery=0, upperx=None, uppery=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   414
 canvas.endForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   415
 canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   416
 canvas.getPageNumber()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   417
 canvas.addLiteral()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   418
 canvas.getAvailableFonts()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   419
 canvas.stringWidth(self, text, fontName, fontSize)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   420
 canvas.setPageCompression(onoff=1)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   421
 canvas.setPageTransition(self, effectname=None, duration=1, 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   422
                        direction=0,dimension='H',motion='I')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   423
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   424
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   425
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   426
lesson('Coordinates (default user space)')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   427
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   428
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   429
By default locations on a page are identified by a pair of numbers.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   430
For example the pair (4.5*inch, 1*inch) identifies the location
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   431
found on the page by starting at the lower left corner and moving to
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   432
the right 4.5 inches and up one inch.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   433
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   434
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   435
disc("""For example, the following function draws
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   436
a number of elements on a canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   437
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   438
eg(examples.testcoords)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   439
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   440
disc("""In the default user space the (0,0) point is at the lower
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   441
left corner.  Executing the coords function in the default user space
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   442
(for the "demo minipage") we obtain the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   443
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   444
canvasdemo(examples.coords)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   445
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   446
head("Moving the origin: the translate method")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   447
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   448
disc("""Often it is useful to "move the origin" to a new point off
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   449
the lower left corner.  The canvas.translate(x,y) method moves the origin
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   450
for the current page to the point currently identified by (x,y).""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   451
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   452
disc("""For example the following translate function first moves
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   453
the origin before drawing the same objects as shown above.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   454
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   455
eg(examples.testtranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   456
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   457
disc("""This produces the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   458
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   459
canvasdemo(examples.translate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   460
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   461
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   462
<em>Note:</em> As illustrated in the example it is perfectly possible to draw objects 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   463
or parts of objects "off the page".
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   464
In particular a common confusing bug is a translation operation that translates the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   465
entire drawing off the visible area of the page.  If a program produces a blank page
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   466
it is possible that all the drawn objects are off the page.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   467
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   468
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   469
head("Shrinking and growing: the scale operation")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   470
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   471
disc("""Another important operation is scaling.  The scaling operation canvas.scale(dx,dy)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   472
stretches or shrinks the x and y dimensions by the dx, dy factors respectively.  Often
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   473
dx and dy are the same -- for example to reduce a drawing by half in all dimensions use
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   474
dx = dy = 0.5.  However for the purposes of illustration we show an example where
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   475
dx and dy are different.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   476
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   477
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   478
eg(examples.testscale)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   479
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   480
disc("""This produces a "short and fat" reduced version of the previously displayed operations.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   481
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   482
canvasdemo(examples.scale)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   483
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   484
disc("""<em>Note:</em> scaling may also move objects or parts of objects off the page,
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   485
or may cause objects to "shrink to nothing." """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   486
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   487
disc("""Scaling and translation can be combined, but the order of the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   488
operations are important.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   489
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   490
eg(examples.testscaletranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   491
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   492
disc("""This example function first saves the current canvas state
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   493
and then does a scaling followed by a translate.  Afterward the function
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   494
restores the state (effectively removing the effects of the scaling and
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   495
translation) and then does the <em>same</em> operations in a different order.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   496
Observe the effect below.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   497
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   498
canvasdemo(examples.scaletranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   499
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   500
disc("""<em>Note:</em> scaling shrinks or grows everything including line widths
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   501
so using the canvas.scale method to render a microscopic drawing in 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   502
scaled microscopic units
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   503
may produce a blob (because all line widths will get expanded a huge amount).  
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   504
Also rendering an aircraft wing in meters scaled to centimeters may cause the lines
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   505
to shrink to the point where they disappear.  For engineering or scientific purposes
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   506
such as these scale and translate
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   507
the units externally before rendering them using the canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   508
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   509
head("Saving and restoring the canvas state: saveState and restoreState")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   510
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   511
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   512
The scaletranslate function used an important feature of the canvas object:
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   513
the ability to save and restore the current parameters of the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   514
By enclosing a sequence of operations in a matching pair of canvas.saveState()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   515
an canvas.restoreState() operations all changes of font, color, line style,
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   516
scaling, translation, or other aspects of the canvas graphics state can be
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   517
restored to the state at the point of the saveState().  Remember that the save/restore
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   518
calls must match: a stray save or restore operation may cause unexpected
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   519
and undesirable behavior.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   520
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   521
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   522
lesson('Painting back to front')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   523
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   524
eg(examples.testspumoni)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   525
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   526
canvasdemo(examples.spumoni)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   527
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   528
eg(examples.testspumoni2)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   529
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   530
canvasdemo(examples.spumoni2)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   531
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   532
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   533
lesson('Fonts and text objects')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   534
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   535
lesson('Paths and polygons')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   536
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   537
lesson('Rectangles, circles, ellipses')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   538
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   539
lesson('Bezier curves')
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   540
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   541
lesson("...more lessons...")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   542
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   543
if __name__=="__main__":
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   544
    g = Guide()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   545
    g.go()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   546