docs/userguide/genuserguide.py
author andy_robinson
Tue, 04 Jul 2000 22:22:40 +0000
changeset 320 7a4ca2b5bb89
parent 318 03c9f114c621
child 323 5795e28c5910
permissions -rw-r--r--
Tidied up genuserguide.py, especially figure handling; began adding PDF special features docco
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
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
     4
#   ReportLab Public License Version 1.0
273
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
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
     9
#   (C) Copyright ReportLab Inc. 1998-2000.
273
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
###############################################################################
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    34
#   $Log: genuserguide.py,v $
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    35
#   Revision 1.16  2000/07/04 22:22:40  andy_robinson
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    36
#   Tidied up genuserguide.py, especially figure handling; began
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    37
#   adding PDF special features docco
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    38
#
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    39
#   Revision 1.15  2000/07/03 16:03:31  andy_robinson
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    40
#   Changes to heading structure
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    41
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    42
#   Revision 1.14  2000/07/03 15:50:31  andy_robinson
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    43
#   Pushed down most existing lessons one level; added
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    44
#   functions heading1..heading3 for building story
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    45
#   unambiguously; spelled Hugh Hefner right!
314
72c75740504b abspath is 1.5.2 only
rgbecker
parents: 311
diff changeset
    46
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    47
#   Revision 1.13  2000/07/03 09:51:38  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    48
#   abspath is 1.5.2 only
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    49
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    50
#   Revision 1.12  2000/06/28 16:10:00  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    51
#   Fix unwanted 'i'
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    52
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    53
#   Revision 1.11  2000/06/28 14:52:43  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    54
#   Documentation changes
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    55
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    56
#   Revision 1.10  2000/06/27 10:09:48  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    57
#   Minor cosmetic changes
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    58
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    59
#   Revision 1.9  2000/06/23 21:09:03  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    60
#   text text and more text
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    61
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    62
#   Revision 1.8  2000/06/22 19:05:24  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    63
#   added quickhack for font changes in paragraphs and lots of new text
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    64
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    65
#   Revision 1.7  2000/06/22 13:55:59  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    66
#   showPage resets all state parameters warning.
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    67
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    68
#   Revision 1.6  2000/06/22 13:35:28  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    69
#   textobject and pathobject methods, among other things
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    70
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    71
#   Revision 1.5  2000/06/21 21:19:29  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    72
#   colors, line styles, more examples
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    73
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    74
#   Revision 1.4  2000/06/21 15:16:05  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    75
#   Lots of graphical examples added
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    76
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    77
#   Revision 1.3  2000/06/20 20:31:42  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    78
#   typos and more examples
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    79
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    80
#   Revision 1.2  2000/06/19 21:13:02  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    81
#   2nd try. more text
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    82
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    83
#   Revision 1.1  2000/06/17 02:57:56  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    84
#   initial checkin. user guide generation framework.
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    85
#   
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    86
__version__=''' $Id: genuserguide.py,v 1.16 2000/07/04 22:22:40 andy_robinson Exp $ '''
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    87
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    88
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    89
__doc__ = """
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    90
This module contains the script for building the user guide.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    91
"""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
    92
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    93
import os, sys
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    94
sys.path.insert(0,os.path.join(os.path.dirname(sys.argv[0]),'..','tools'))
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    95
from rltemplate import RLDocTemplate
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    96
from stylesheet import getStyleSheet
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    97
styleSheet = getStyleSheet()
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
    98
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    99
#from reportlab.platypus.doctemplate import SimpleDocTemplate
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   100
from reportlab.platypus.flowables import Flowable
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   101
from reportlab.lib.units import inch
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   102
from reportlab.lib.pagesizes import letter
308
a09abac33167 Minor cosmetic changes
rgbecker
parents: 304
diff changeset
   103
from reportlab.platypus import Paragraph, Spacer, Preformatted, PageBreak, CondPageBreak
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   104
from reportlab.lib.styles import ParagraphStyle
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   105
from reportlab.lib import colors
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   106
from reportlab.lib.sequencer import getSequencer
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   107
import examples
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   108
import platdemos
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   109
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   110
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   111
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   112
from reportlab.lib.corp import ReportLabLogo
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   113
LOGO = ReportLabLogo(0.25*inch, 0.25*inch, inch, 0.75*inch)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   114
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   115
from t_parse import Template
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   116
QFcodetemplate = Template("X$X$", "X")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   117
QFreptemplate = Template("X^X^", "X")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   118
codesubst = "%s<font name=Courier>%s</font>"
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   119
QFsubst = "%s<font name=Courier><i>%s</i></font>"
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   120
    
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   121
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   122
def quickfix(text):
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   123
    """inside text find any subsequence of form $subsequence$.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   124
       Format the subsequence as code.  If similarly if text contains ^arg^
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   125
       format the arg as replaceable.  The escape sequence for literal
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   126
       $ is $\\$ (^ is ^\\^.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   127
    """
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   128
    from string import join
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   129
    for (template,subst) in [(QFcodetemplate, codesubst), (QFreptemplate, QFsubst)]:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   130
        fragment = text
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   131
        parts = []
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   132
        try:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   133
            while fragment:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   134
                try:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   135
                    (matches, index) = template.PARSE(fragment)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   136
                except: raise ValueError
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   137
                else:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   138
                    [prefix, code] = matches
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   139
                    if code == "\\":
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   140
                        part = fragment[:index]
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   141
                    else:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   142
                        part = subst % (prefix, code)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   143
                    parts.append(part)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   144
                    fragment = fragment[index:]
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   145
        except ValueError:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   146
            parts.append(fragment)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   147
        text = join(parts, "")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   148
    return text
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   149
#print quickfix("$testing$ testing $one$ ^two^ $three(^four^)$")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   150
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   151
class Guide:
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   152
    def __init__(self):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   153
        self.story = story()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   154
    def go(self, filename="userguide.pdf"):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   155
        # generate the doc...
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   156
        doc = RLDocTemplate(filename,pagesize = letter)
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   157
        story = self.story
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   158
        doc.build(story)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   159
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   160
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   161
H1 = styleSheet['Heading1']
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   162
H2 = styleSheet['Heading2']
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   163
H3 = styleSheet['Heading3']
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   164
B = styleSheet['BodyText']
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   165
Comment = styleSheet['Comment']
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   166
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   167
#set up numbering
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   168
seq = getSequencer()
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   169
seq.setFormat('Chapter','1')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   170
seq.setFormat('Section','1')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   171
seq.setFormat('Appendix','A')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   172
seq.chain('Chapter','Section')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   173
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   174
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   175
lessonnamestyle = H2
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   176
discussiontextstyle = B
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   177
exampletextstyle = styleSheet['Code']
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   178
# size for every example
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   179
examplefunctionxinches = 5.5
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   180
examplefunctionyinches = 3
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   181
examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   182
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   183
# for testing
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   184
def NOP(*x,**y):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   185
    return None
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   186
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   187
BODY = []
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   188
def story():
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   189
    return BODY
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   190
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   191
def disc(text, klass=Paragraph, style=discussiontextstyle):
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   192
    text = quickfix(text)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   193
    P = klass(text, style)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   194
    BODY.append(P)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   195
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   196
def eg(text):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   197
    BODY.append(Spacer(0.1*inch, 0.1*inch))
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   198
    disc(text, klass=Preformatted, style=exampletextstyle)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   199
    
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   200
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   201
def title(text):
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   202
    """Use this for the document title only"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   203
    disc(text,style=styleSheet['Title'])
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   204
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   205
#AR 3/7/2000 - defining three new levels of headings; code
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   206
#should be swapped over to using them.
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   207
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   208
def heading1(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   209
    """Use this for chapters.  Lessons within a big chapter
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   210
    should now use heading2 instead.  Chapters get numbered."""
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   211
    BODY.append(PageBreak())
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   212
    p = Paragraph('Chapter <seq id="Chapter"/> - ' + quickfix(text), H1)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   213
    BODY.append(p)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   214
    
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   215
def heading2(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   216
    """Used to be 'lesson'"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   217
    BODY.append(CondPageBreak(inch))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   218
    p = Paragraph('<seq template="%(Chapter)s.%(Section+)s - "/>' + quickfix(text), H2)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   219
    BODY.append(p)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   220
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   221
def heading3(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   222
    """Used to be most of the plain old 'head' sections"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   223
    BODY.append(CondPageBreak(inch))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   224
    p = Paragraph(quickfix(text), H3)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   225
    BODY.append(p)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   226
    
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   227
def todo(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   228
    """Used for notes to ourselves"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   229
    BODY.append(Paragraph(quickfix(text), Comment))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   230
    
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   231
##class OperationWrapper(Flowable):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   232
##    """wrap a drawing operation as a flowable.
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   233
##       the operation should respect the examplefunctiondisplaysizes
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   234
##       limitations.
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   235
##       This example wraps a drawing operator f(pdfgen.canvas).
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   236
##       Always enclosed in a rectangle.
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   237
##    """
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   238
##    def __init__(self, operation):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   239
##        self.operation = operation
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   240
##        
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   241
##    def wrap(self, aw, ah):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   242
##        return examplefunctiondisplaysizes # always the same
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   243
##        
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   244
##    def draw(self):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   245
##        canvas = self.canv
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   246
##        canvas.saveState()
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   247
##        (x,y) = examplefunctiondisplaysizes
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   248
##        self.operation(canvas)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   249
##        canvas.restoreState()
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   250
##        canvas.rect(0,0,x,y)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   251
        
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   252
class Illustration(platdemos.Figure):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   253
    """The examples are all presented as functions which do
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   254
    something to a canvas, with a constant height and width
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   255
    used.  This puts them inside a figure box with a caption."""
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   256
    
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   257
    def __init__(self, operation, caption):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   258
        stdwidth, stdheight = examplefunctiondisplaysizes
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   259
        #platdemos.Figure.__init__(self, stdwidth * 0.75, stdheight * 0.75)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   260
        platdemos.Figure.__init__(self, stdwidth, stdheight)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   261
        self.operation = operation
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   262
        self.caption = 'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   263
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   264
    def drawFigure(self):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   265
        #shrink it a little...
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   266
        #self.canv.scale(0.75, 0.75)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   267
        self.operation(self.canv)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   268
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   269
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   270
def illust(operation, caption):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   271
    i = Illustration(operation, caption)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   272
    BODY.append(i)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   273
    
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   274
def pencilnote():
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   275
    BODY.append(examples.NoteAnnotation())
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   276
        
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   277
###### testing...
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   278
#illust(NOP)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   279
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   280
#heading2("this is a new lesson")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   281
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   282
#disc("this explains the example")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   283
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   284
#eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   285
#this
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   286
#  is the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   287
#    example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   288
#      code""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   289
      
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   290
#disc("the execution of the example follows")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   291
      
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   292
#illust(NOP) # execute some code
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   293
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   294
#pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   295
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   296
title("ReportLab User Guide")
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   297
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   298
todo("""To-do items to authors, or points under discussion,
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   299
appear in italics like this.""")
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   300
todo("")
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   301
todo("""Sequencer is post-incrementing chapters, so all
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   302
section numbers are getting a chapter number one too high!""")
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   303
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   304
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   305
heading1("Introduction")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   306
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   307
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   308
This document is intended to be a conversational introduction
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   309
to the use of the ReportLab packages.  Some previous programming experience
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   310
is presumed and familiarity with the Python Programming language is
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   311
recommended.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   312
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   313
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   314
heading2("What is PDFgen all about")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   315
todo("rationale - from Andy")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   316
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   317
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   318
heading2("About Python")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   319
todo("If they don't know Python, rave a little then tell them where to get it")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   320
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   321
heading2("Installation and Setup")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   322
todo("need notes on packages, Windows, PIL and zlib; how to test it works")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   323
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   324
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   325
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   326
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   327
This document is in a <em>very</em> preliminary form.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   328
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   329
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   330
heading1("Graphics and Text with $pdfgen$")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   331
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   332
heading2("Basic Concepts")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   333
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   334
The $pdfgen$ package is the lowest level interface for
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   335
generating PDF documents.  A $pdfgen$ program is essentially
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   336
a sequence of instructions for "painting" a document onto
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   337
a sequence of pages.  The interface object which provides the
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   338
painting operations is the $pdfgen canvas$.  
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   339
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   340
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   341
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   342
The canvas should be thought of as a sheet of white paper
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   343
with points on the sheet identified using Cartesian ^(X,Y)^ coordinates
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   344
which by default have the ^(0,0)^ origin point at the lower
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   345
left corner of the page.  Furthermore the first coordinate ^x^
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   346
goes to the right and the second coordinate ^y^ goes up, by
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   347
default.""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   348
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   349
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   350
A simple example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   351
program that uses a canvas follows.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   352
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   353
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   354
eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   355
    from reportlab.pdfgen import canvas
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   356
    c = canvas.Canvas("hello.pdf")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   357
    hello(c)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   358
    c.showPage()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   359
    c.save()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   360
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   361
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   362
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   363
The above code creates a $canvas$ object which will generate
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   364
a PDF file named $hello.pdf$ in the current working directory.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   365
It then calls the $hello$ function passing the $canvas$ as an argument.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   366
Finally the $showPage$ method saves the current page of the canvas
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   367
and the $save$ method stores the file and closes the canvas.""")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   368
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   369
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   370
The $showPage$ method causes the $canvas$ to stop drawing on the
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   371
current page and any further operations will draw on a subsequent
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   372
page (if there are any further operations -- if not no
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   373
new page is created).  The $save$ method must be called after the
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   374
construction of the document is complete -- it generates the PDF
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   375
document, which is the whole purpose of the $canvas$ object.
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   376
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   377
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   378
heading2("More about the Canvas")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   379
disc("""
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   380
Before describing the drawing operations, we will digress to cover
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   381
some of the things which can be done to configure a canvas.  There
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   382
are many different settings available.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   383
todo("""Cover all constructor arguments, and setAuthor etc.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   384
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   385
heading2("Drawing Operations")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   386
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   387
Suppose the $hello$ function referenced above is implemented as
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   388
follows (we will not explain each of the operations in detail
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   389
yet).
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   390
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   391
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   392
eg(examples.testhello)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   393
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   394
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   395
Examining this code notice that there are essentially two types
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   396
of operations performed using a canvas.  The first type draws something
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   397
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
   398
type changes the state of the canvas such as
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   399
changing the current fill or stroke color or changing the current font
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   400
type and size.  
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   401
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   402
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   403
disc("""
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   404
If we imagine the program as a painter working on
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   405
the canvas the "draw" operations apply paint to the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   406
the current set of tools (colors, line styles, fonts, etcetera)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   407
and the "state change" operations change one of the current tools
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   408
(changing the fill color from whatever it was to blue, or changing
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   409
the current font to $Times-Roman$ in 15 points, for example).
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   410
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   411
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   412
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   413
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
   414
the following graphics.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   415
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   416
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   417
illust(examples.hello, '"Hello World" in pdfgen')
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   418
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   419
heading3("About the demos in this document")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   420
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   421
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   422
This document contains demonstrations of the code discussed like the one shown
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   423
in the rectangle above.  These demos are drawn on a "tiny page" embedded
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   424
within the real pages of the guide.  The tiny pages are %s inches wide
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   425
and %s inches tall. The demo displays show the actual output of the demo code.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   426
""" % (examplefunctionxinches, examplefunctionyinches))
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   427
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   428
heading2('The tools: the "draw" operations')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   429
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   430
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   431
This section briefly lists the tools available to the program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   432
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   433
These will be discussed in detail in later sections.  They are listed
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   434
here for easy reference and for summary purposes.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   435
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   436
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   437
heading3("Line methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   438
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   439
eg("""canvas.line(x1,y1,x2,y2)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   440
eg("""canvas.lines(linelist)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   441
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   442
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   443
The line methods draw straight line segments on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   444
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   445
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   446
heading3("Shape methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   447
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   448
eg("""canvas.grid(xlist, ylist) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   449
eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   450
eg("""canvas.arc(x1,y1,x2,y2) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   451
eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   452
eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   453
eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   454
eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   455
eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)
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("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   458
The shape methods draw common complex shapes on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   459
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   460
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   461
heading3("String drawing methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   462
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   463
eg("""canvas.drawString(x, y, text):""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   464
eg("""canvas.drawRightString(x, y, text) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   465
eg("""canvas.drawCentredString(x, y, text)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   466
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   467
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   468
The draw string methods draw single lines of text on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   469
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   470
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   471
heading3("The text object methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   472
eg("""textobject = canvas.beginText(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   473
eg("""canvas.drawText(textobject) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   474
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   475
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   476
Text objects are used to format text in ways that
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   477
are not supported directly by the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   478
A program creates a text object from the canvas using beginText
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   479
and then formats text by invoking textobject methods.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   480
Finally the textobject is drawn onto the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   481
drawText.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   482
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   483
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   484
heading3("The path object methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   485
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   486
eg("""path = canvas.beginPath() """)
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   487
eg("""canvas.drawPath(path, stroke=1, fill=0) """)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   488
eg("""canvas.clipPath(path, stroke=1, fill=0) """)
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   489
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   490
heading3("Image methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   491
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   492
eg("""canvas.drawInlineImage(self, image, x,y, width=None,height=None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   493
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   494
heading3("Ending a page")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   495
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   496
eg("""canvas.showPage()""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   497
300
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   498
disc("""The showPage method finishes the current page.  All additional drawing will
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   499
be done on another page.""")
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   500
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   501
pencilnote()
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   502
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   503
disc("""Warning!  All state changes (font changes, color settings, geometry transforms, etcetera)
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   504
are FORGOTTEN when you advance to a new page in $pdfgen$.  Any state settings you wish to preserve
300
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   505
must be set up again before the program proceeds with drawing!""")
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   506
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   507
heading2('The toolbox: the "state change" operations')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   508
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   509
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   510
This section briefly lists the ways to switch the tools used by the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   511
program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   512
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   513
These too will be discussed in detail in later sections.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   514
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   515
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   516
heading3("Changing Colors")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   517
eg("""canvas.setFillColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   518
eg("""canvas.setStrikeColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   519
eg("""canvas.setFillColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   520
eg("""canvas.setStrokeColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   521
eg("""canvas.setFillColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   522
eg("""canvas.setStrokeColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   523
eg("""canvas.setFillGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   524
eg("""canvas.setStrokeGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   525
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   526
heading3("Changing Fonts")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   527
eg("""canvas.setFont(psfontname, size, leading = None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   528
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   529
heading3("Changing Graphical Styles")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   530
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   531
eg("""canvas.setLineWidth(width) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   532
eg("""canvas.setLineCap(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   533
eg("""canvas.setLineJoin(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   534
eg("""canvas.setMiterLimit(limit) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   535
eg("""canvas.setDash(self, array=[], phase=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   536
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   537
heading3("Changing Geometry")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   538
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   539
eg("""canvas.setPageSize(pair) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   540
eg("""canvas.transform(a,b,c,d,e,f): """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   541
eg("""canvas.translate(dx, dy) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   542
eg("""canvas.scale(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   543
eg("""canvas.rotate(theta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   544
eg("""canvas.skew(alpha, beta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   545
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   546
heading3("State control")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   547
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   548
eg("""canvas.saveState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   549
eg("""canvas.restoreState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   550
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   551
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   552
heading2("Other canvas methods.")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   553
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   554
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   555
Not all methods of the canvas object fit into the "tool" or "toolbox"
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   556
categories.  Below are some of the misfits, included here for completeness.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   557
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   558
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   559
eg("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   560
 canvas.setAuthor()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   561
 canvas.addOutlineEntry(title, key, level=0, closed=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   562
 canvas.setTitle(title)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   563
 canvas.setSubject(subj)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   564
 canvas.pageHasData()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   565
 canvas.showOutline()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   566
 canvas.bookmarkPage(name)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   567
 canvas.bookmarkHorizontalAbsolute(name, yhorizontal)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   568
 canvas.doForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   569
 canvas.beginForm(name, lowerx=0, lowery=0, upperx=None, uppery=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   570
 canvas.endForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   571
 canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   572
 canvas.getPageNumber()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   573
 canvas.addLiteral()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   574
 canvas.getAvailableFonts()
308
a09abac33167 Minor cosmetic changes
rgbecker
parents: 304
diff changeset
   575
 canvas.stringWidth(self, text, fontName, fontSize, encoding=None)
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   576
 canvas.setPageCompression(onoff=1)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   577
 canvas.setPageTransition(self, effectname=None, duration=1, 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   578
                        direction=0,dimension='H',motion='I')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   579
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   580
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   581
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   582
heading2('Coordinates (default user space)')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   583
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   584
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   585
By default locations on a page are identified by a pair of numbers.
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   586
For example the pair $(4.5*inch, 1*inch)$ identifies the location
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   587
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
   588
the right 4.5 inches and up one inch.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   589
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   590
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   591
disc("""For example, the following function draws
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   592
a number of elements on a canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   593
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   594
eg(examples.testcoords)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   595
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   596
disc("""In the default user space the "origin" ^(0,0)^ point is at the lower
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   597
left corner.  Executing the $coords$ function in the default user space
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   598
(for the "demo minipage") we obtain the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   599
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   600
illust(examples.coords, 'The Coordinate System')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   601
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   602
heading3("Moving the origin: the $translate$ method")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   603
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   604
disc("""Often it is useful to "move the origin" to a new point off
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   605
the lower left corner.  The $canvas.translate(^x,y^)$ method moves the origin
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   606
for the current page to the point currently identified by ^(x,y)^.""")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   607
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   608
disc("""For example the following translate function first moves
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   609
the origin before drawing the same objects as shown above.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   610
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   611
eg(examples.testtranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   612
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   613
disc("""This produces the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   614
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   615
illust(examples.translate, "Moving the origin: the $translate$ method")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   616
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   617
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   618
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   619
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   620
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   621
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   622
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   623
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   624
<i>Note:</i> As illustrated in the example it is perfectly possible to draw objects 
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   625
or parts of objects "off the page".
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   626
In particular a common confusing bug is a translation operation that translates the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   627
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
   628
it is possible that all the drawn objects are off the page.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   629
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   630
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   631
heading3("Shrinking and growing: the scale operation")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   632
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   633
disc("""Another important operation is scaling.  The scaling operation $canvas.scale(^dx,dy^)$
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   634
stretches or shrinks the ^x^ and ^y^ dimensions by the ^dx^, ^dy^ factors respectively.  Often
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   635
^dx^ and ^dy^ are the same -- for example to reduce a drawing by half in all dimensions use
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   636
$dx = dy = 0.5$.  However for the purposes of illustration we show an example where
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   637
$dx$ and $dy$ are different.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   638
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   639
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   640
eg(examples.testscale)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   641
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   642
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
   643
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   644
illust(examples.scale, "Scaling the coordinate system")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   645
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   646
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   647
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   648
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   649
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   650
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   651
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   652
disc("""<i>Note:</i> scaling may also move objects or parts of objects off the page,
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   653
or may cause objects to "shrink to nothing." """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   654
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   655
disc("""Scaling and translation can be combined, but the order of the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   656
operations are important.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   657
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   658
eg(examples.testscaletranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   659
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   660
disc("""This example function first saves the current canvas state
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   661
and then does a $scale$ followed by a $translate$.  Afterward the function
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   662
restores the state (effectively removing the effects of the scaling and
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   663
translation) and then does the <i>same</i> operations in a different order.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   664
Observe the effect below.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   665
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   666
illust(examples.scaletranslate, "Scaling and Translating")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   667
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   668
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   669
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   670
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   671
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   672
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   673
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   674
disc("""<em>Note:</em> scaling shrinks or grows everything including line widths
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   675
so using the canvas.scale method to render a microscopic drawing in 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   676
scaled microscopic units
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   677
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
   678
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
   679
to shrink to the point where they disappear.  For engineering or scientific purposes
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   680
such as these scale and translate
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   681
the units externally before rendering them using the canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   682
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   683
heading3("Saving and restoring the canvas state: $saveState$ and $restoreState$")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   684
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   685
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   686
The $scaletranslate$ function used an important feature of the canvas object:
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   687
the ability to save and restore the current parameters of the canvas.
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   688
By enclosing a sequence of operations in a matching pair of $canvas.saveState()$
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   689
an $canvas.restoreState()$ operations all changes of font, color, line style,
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   690
scaling, translation, or other aspects of the canvas graphics state can be
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   691
restored to the state at the point of the $saveState()$.  Remember that the save/restore
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   692
calls must match: a stray save or restore operation may cause unexpected
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   693
and undesirable behavior.  Also, remember that <i>no</i> canvas state is
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   694
preserved across page breaks, and the save/restore mechanism does not work
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   695
across page breaks.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   696
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   697
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   698
heading3("Mirror image")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   699
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   700
disc("""
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   701
It is interesting although perhaps not terribly useful to note that
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   702
scale factors can be negative.  For example the following function
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   703
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   704
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   705
eg(examples.testmirror)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   706
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   707
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   708
creates a mirror image of the elements drawn by the $coord$ function.
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   709
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   710
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   711
illust(examples.mirror, "Mirror Images")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   712
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   713
disc("""
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   714
Notice that the text strings are painted backwards.
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   715
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   716
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   717
heading2("Colors")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   718
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   719
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   720
There are four way to specify colors in $pdfgen$: by name (using the $color$
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   721
module, by red/green/blue (additive, $RGB$) value,
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   722
by cyan/magenta/yellow/darkness (subtractive, $CMYK$), or by gray level.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   723
The $colors$ function below exercises each of the four methods.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   724
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   725
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   726
eg(examples.testcolors)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   727
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   728
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   729
The $RGB$ or additive color specification follows the way a computer
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   730
screen adds different levels of the red, green, or blue light to make
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   731
any color, where white is formed by turning all three lights on full
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   732
$(1,1,1)$.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   733
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   734
disc("""The $CMYK$ or subtractive method follows the way a printer
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   735
mixes three pigments (cyan, magenta, and yellow) to form colors.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   736
Because mixing chemicals is more difficult than combining light there
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   737
is a fourth parameter for darkness.  For example a chemical
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   738
combination of the $CMY$ pigments generally never makes a perfect
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   739
black -- instead producing a muddy color -- so, to get black printers
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   740
don't use the $CMY$ pigments but use a direct black ink.  Because
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   741
$CMYK$ maps more directly to the way printer hardware works it may
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   742
be the case that colors specified in $CMYK$ will provide better fidelity
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   743
and better control when printed.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   744
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   745
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   746
illust(examples.colors, "Color Models")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   747
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   748
heading2('Painting back to front')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   749
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   750
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   751
Objects may be painted over other objects to good effect in $pdfgen$.  As
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   752
in painting with oils the object painted last will show up on top.  For
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   753
example, the $spumoni$ function below paints up a base of colors and then
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   754
paints a white text over the base.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   755
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   756
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   757
eg(examples.testspumoni)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   758
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   759
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   760
The word "SPUMONI" is painted in white over the colored rectangles,
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   761
with the apparent effect of "removing" the color inside the body of
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   762
the word.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   763
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   764
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   765
illust(examples.spumoni, "Painting over colors")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   766
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   767
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   768
The last letters of the word are not visible because the default canvas
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   769
background is white and painting white letters over a white background
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   770
leaves no visible effect.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   771
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   772
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   773
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   774
This method of building up complex paintings in layers can be done
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   775
in very many layers in $pdfgen$ -- there are fewer physical limitations
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   776
than there are when dealing with physical paints.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   777
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   778
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   779
eg(examples.testspumoni2)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   780
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   781
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   782
The $spumoni2$ function layers an ice cream cone over the
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   783
$spumoni$ drawing.  Note that different parts of the cone
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   784
and scoops layer over eachother as well.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   785
""")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   786
illust(examples.spumoni2, "building up a drawing in layers")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   787
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   788
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   789
heading2('Fonts and text objects')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   790
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   791
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   792
Text may be drawn in many different colors, fonts, and sizes in $pdfgen$.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   793
The $textsize$ function demonstrates how to change the color and font and
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   794
size of text and how to place text on the page.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   795
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   796
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   797
eg(examples.testtextsize)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   798
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   799
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   800
The $textsize$ function generates the following page.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   801
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   802
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   803
illust(examples.textsize, "text in different fonts and sizes")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   804
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   805
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   806
A number of different fonts are always available in $pdfgen$.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   807
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   808
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   809
eg(examples.testfonts)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   810
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   811
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   812
The $fonts$ function lists the fonts that are always available.
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   813
These don;t need to be stored in a PDF document, since they
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   814
are guaranteed to be present in Acrobat Reader.
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   815
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   816
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   817
illust(examples.fonts, "the 14 standard fonts")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   818
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   819
disc("""
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   820
In the near future we will add the ability to embed other fonts
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   821
within a PDF file.  However, this will add a little to file size.
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   822
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   823
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   824
heading2("Text object methods")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   825
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   826
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   827
For the dedicated presentation of text in a PDF document, use a text object.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   828
The text object interface provides detailed control of text layout parameters
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   829
not available directly at the canvas level.  In addition, it results in smaller
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   830
PDF that will render faster than many separate calls to the $drawString$ methods.
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   831
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   832
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   833
eg("""textobject.setTextOrigin(x,y)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   834
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   835
eg("""textobject.setTextTransform(a,b,c,d,e,f)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   836
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   837
eg("""textobject.moveCursor(dx, dy) # from start of current LINE""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   838
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   839
eg("""(x,y) = textobject.getCursor()""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   840
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   841
eg("""x = textobject.getX(); y = textobject.getY()""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   842
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   843
eg("""textobject.setFont(psfontname, size, leading = None)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   844
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   845
eg("""textobject.textOut(text)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   846
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   847
eg("""textobject.textLine(text='')""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   848
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   849
eg("""textobject.textLines(stuff, trim=1)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   850
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   851
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   852
The text object methods shown above relate to basic text geometry.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   853
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   854
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   855
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   856
A text object maintains a text cursor which moves about the page when 
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   857
text is drawn.  For example the $setTextOrigin$ places the cursor
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   858
in a known position and the $textLine$ and $textLines$ methods move
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   859
the text cursor down past the lines that have been missing.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   860
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   861
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   862
eg(examples.testcursormoves1)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   863
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   864
disc("""
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   865
The $cursormoves$ function relies on the automatic
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   866
movement of the text cursor for placing text after the origin
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   867
has been set.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   868
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   869
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   870
illust(examples.cursormoves1, "How the text cursor moves")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   871
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   872
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   873
It is also possible to control the movement of the cursor
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   874
more explicitly by using the $moveCursor$ method (which moves
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   875
the cursor as an offset from the start of the current <i>line</i>
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   876
NOT the current cursor, and which also has positive ^y^ offsets
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   877
move <i>down</i> (in contrast to the normal geometry where
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   878
positive ^y^ usually moves up.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   879
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   880
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   881
eg(examples.testcursormoves2)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   882
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   883
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   884
Here the $textOut$ does not move the down a line in contrast
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   885
to the $textLine$ function which does move down.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   886
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   887
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   888
illust(examples.cursormoves2, "How the text cursor moves again")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   889
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   890
heading3("Character Spacing")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   891
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   892
eg("""textobject.setCharSpace(charSpace)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   893
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   894
disc("""The $setCharSpace$ method adjusts one of the parameters of text -- the inter-character
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   895
spacing.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   896
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   897
eg(examples.testcharspace)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   898
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   899
disc("""The 
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   900
$charspace$ function exercises various spacing settings.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   901
It produces the following page.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   902
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   903
illust(examples.charspace, "Adjusting inter-character spacing")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   904
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   905
heading3("Word Spacing")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   906
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   907
eg("""textobject.setWordSpace(wordSpace)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   908
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   909
disc("The $setWordSpace$ method adjusts the space between word.")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   910
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   911
eg(examples.testwordspace)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   912
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   913
disc("""The $wordspace$ function shows what various word space settings
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   914
look like below.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   915
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   916
illust(examples.wordspace, "Adjusting word spacing")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   917
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   918
heading3("Horizontal Scaling")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   919
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   920
eg("""textobject.setHorizScale(horizScale)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   921
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   922
disc("""Lines of text can be stretched or shrunken horizontally by the 
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   923
$setHorizScale$ method.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   924
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   925
eg(examples.testhorizontalscale)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   926
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   927
disc("""The horizontal scaling parameter ^horizScale^
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   928
is given in percentages (with 100 as the default), so the 80 setting
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   929
shown below looks skinny.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   930
""")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   931
illust(examples.horizontalscale, "adjusting horizontal text scaling")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   932
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   933
heading3("Interline spacing (Leading)")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   934
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   935
eg("""textobject.setLeading(leading)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   936
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   937
disc("""The vertical offset between the point at which one
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   938
line starts and where the next starts is called the leading
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   939
offset.  The $setLeading$ method adjusts the leading offset.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   940
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   941
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   942
eg(examples.testleading)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   943
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   944
disc("""As shown below if the leading offset is set too small
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   945
characters of one line my write over the bottom parts of characters
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   946
in the previous line.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   947
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   948
illust(examples.leading, "adjusting the leading")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   949
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   950
heading3("Other text object methods")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   951
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   952
eg("""textobject.setTextRenderMode(mode)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   953
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   954
disc("""The $setTextRenderMode$ method allows text to be used
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   955
as a forground for clipping background drawings, for example.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   956
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   957
eg("""textobject.setRise(rise)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   958
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   959
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   960
The $setRise$ method <super>raises</super> or <sub>lowers</sub> text on the line
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   961
(for creating superscripts or subscripts, for example).
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   962
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   963
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   964
eg("""textobject.setFillColor(aColor); 
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   965
textobject.setStrokeColor(self, aColor) 
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   966
# and similar""")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   967
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   968
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   969
These color change operations change the <font color=darkviolet>color</font> of the text and are otherwise
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   970
similar to the color methods for the canvas object.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   971
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   972
heading2('Paths and Lines')
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   973
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   974
disc("""Just as textobjects are designed for the dedicated presentation
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   975
of text, path objects are designed for the dedicated construction of
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   976
graphical figures.  When path objects are drawn onto a canvas they are
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   977
are drawn as one figure (like a rectangle) and the mode of drawing
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   978
for the entire figure can be adjusted: the lines of the figure can
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   979
be drawn (stroked) or not; the interior of the figure can be filled or
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   980
not; and so forth.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   981
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   982
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   983
For example the $star$ function uses a path object
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   984
to draw a star
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   985
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   986
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   987
eg(examples.teststar)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   988
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   989
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   990
The $star$ function has been designed to be useful in illustrating
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   991
various line style parameters supported by $pdfgen$.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   992
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   993
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   994
illust(examples.star, "line style parameters")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   995
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   996
heading3("Line join settings")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   997
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   998
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   999
The $setLineJoin$ method can adjust whether line segments meet in a point
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1000
a square or a rounded vertex.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1001
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1002
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1003
eg(examples.testjoins)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1004
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1005
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1006
The line join setting is only really of interest for thick lines because
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1007
it cannot be seen clearly for thin lines.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1008
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1009
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1010
illust(examples.joins, "different line join styles")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1011
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1012
heading3("Line cap settings")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1013
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1014
disc("""The line cap setting, adjusted using the $setLineCap$ method,
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1015
determines whether a terminating line
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1016
ends in a square exactly at the vertex, a square over the vertex
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1017
or a half circle over the vertex.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1018
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1019
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1020
eg(examples.testcaps)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1021
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1022
disc("""The line cap setting, like the line join setting, is only
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1023
visible when the lines are thick.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1024
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1025
illust(examples.caps, "line cap settings")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1026
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1027
heading3("Dashes and broken lines")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1028
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1029
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1030
The $setDash$ method allows lines to be broken into dots or dashes.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1031
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1032
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1033
eg(examples.testdashes)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1034
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1035
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1036
The patterns for the dashes or dots can be in a simple on/off repeating pattern
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1037
or they can be specified in a complex repeating pattern.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1038
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1039
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1040
illust(examples.dashes, "some dash patterns")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
  1041
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1042
heading3("Creating complex figures with path objects")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1043
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1044
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1045
Combinations of lines, curves, arcs and other figures
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1046
can be combined into a single figure using path objects.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1047
For example the function shown below constructs two path
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1048
objects using lines and curves.  
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1049
This function will be used later on as part of a
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1050
pencil icon construction.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1051
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1052
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1053
eg(examples.testpenciltip)
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1054
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1055
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1056
Note that the interior of the pencil tip is filled
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1057
as one object even though it is constructed from
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1058
several lines and curves.  The pencil lead is then
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1059
drawn over it using a new path object.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1060
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1061
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1062
illust(examples.penciltip, "a pencil tip")
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1063
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1064
heading2('Rectangles, circles, ellipses')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
  1065
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1066
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1067
The $pdfgen$ module supports a number of generally useful shapes
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1068
such as rectangles, rounded rectangles, ellipses, and circles.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1069
Each of these figures can be used in path objects or can be drawn
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1070
directly on a canvas.  For example the $pencil$ function below
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1071
draws a pencil icon using rectangles and rounded rectangles with
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1072
various fill colors and a few other annotations.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1073
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1074
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1075
eg(examples.testpencil)
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1076
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1077
pencilnote()
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1078
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1079
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1080
Note that this function is used to create the "margin pencil" to the left.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1081
Also note that the order in which the elements are drawn are important
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1082
because, for example, the white rectangles "erase" parts of a black rectangle
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1083
and the "tip" paints over part of the yellow rectangle.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1084
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1085
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1086
illust(examples.pencil, "a whole pencil")
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1087
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1088
heading2('Bezier curves')
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
  1089
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1090
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1091
Programs that wish to construct figures with curving borders
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1092
generally use Bezier curves to form the borders.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1093
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1094
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1095
eg(examples.testbezier)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1096
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1097
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1098
A Bezier curve is specified by four control points 
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1099
$(x1,y1)$, $(x2,y2)$, $(x3,y3)$, $(x4,y4)$.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1100
The curve starts at $(x1,y1)$ and ends at $(x4,y4)$
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1101
and the line segment from $(x1,y1)$ to $(x2,y2)$
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1102
and the line segment from $(x3,y3)$ to $(x4,y4)$
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1103
both form tangents to the curve.  Furthermore the
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1104
curve is entirely contained in the convex figure with vertices
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1105
at the control points.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1106
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1107
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1108
illust(examples.bezier, "basic bezier curves")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1109
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1110
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1111
The drawing above (the output of $testbezier$) shows
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1112
a bezier curves, the tangent lines defined by the control points
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1113
and the convex figure with vertices at the control points.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1114
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1115
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1116
heading3("Smoothly joining bezier curve sequences")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1117
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1118
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1119
It is often useful to join several bezier curves to form a
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1120
single smooth curve.  To construct a larger smooth curve from
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1121
several bezier curves make sure that the tangent lines to adjacent
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1122
bezier curves that join at a control point lie on the same line.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1123
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1124
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1125
eg(examples.testbezier2)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1126
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1127
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1128
The figure created by $testbezier2$ describes a smooth
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1129
complex curve because adjacent tangent lines "line up" as
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1130
illustrated below.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1131
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1132
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1133
illust(examples.bezier2, "bezier curves")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
  1134
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1135
heading2("Path object methods")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1136
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1137
eg("""pathobject.moveTo(x,y)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1138
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1139
eg("""pathobject.lineTo(x,y)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1140
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1141
eg("""pathobject.curveTo(x1, y1, x2, y2, x3, y3) """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1142
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1143
eg("""pathobject.arc(x1,y1, x2,y2, startAng=0, extent=90) """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1144
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1145
eg("""pathobject.arcTo(x1,y1, x2,y2, startAng=0, extent=90) """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1146
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1147
eg("""pathobject.rect(x, y, width, height) """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1148
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1149
eg("""pathobject.ellipse(x, y, width, height)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1150
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1151
eg("""pathobject.circle(x_cen, y_cen, r) """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1152
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1153
eg("""pathobject.close() """)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1154
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1155
eg(examples.testhand)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1156
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1157
illust(examples.hand, "an outline of a hand using bezier curves")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1158
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1159
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1160
eg(examples.testhand2)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1161
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1162
illust(examples.hand2, "the finished hand, filled")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1163
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1164
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1165
##### FILL THEM IN
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1166
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1167
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1168
heading1("Exposing PDF Special Capabilities")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1169
disc("""PDF provides a number of features to make electronic
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1170
    document viewing more efficient and comfortable, and
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1171
    our library exposes a number of these.""")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1172
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1173
heading2("Forms")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1174
disc("""The Form feature lets you create a block of graphics and text
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1175
    once near the start of a PDF file, and then simply refer to it on
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1176
    subsequent pages.  If you are dealing with a run of 5000 repetitive
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1177
    business forms - for example, one-page invoices or payslips - you
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1178
    only need to store the backdrop once and simply draw the changing
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1179
    text on each page.  Used correctly, forms can dramatically cut
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1180
    file size and production time, and apparently even speed things
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1181
    up on the printer.
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1182
    """)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1183
disc("""Forms do not need to refer to a whole page; anything which
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1184
    might be repeated often should be placed in a form.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1185
disc("""The example below shows the basic sequence used.  A real
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1186
    program would probably define the forms up front and refer to
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1187
    them from another location.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1188
    
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1189
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1190
eg(examples.testforms)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1191
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1192
heading2("Links and Destinations")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1193
disc("""PDF supports internal hyperlinks.  There is a very wide
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1194
    range of link types, destination types and events which
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1195
    can be triggered by a click.  At the moment we just
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1196
    support the basic ability to jump from one part of a document
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1197
    to another.  """)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1198
todo("code example here...")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1199
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1200
heading2("Outline Trees")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1201
disc("""Acrobat Reader has a navigation page which can hold a
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1202
    document outline; it should normally be visible when you
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1203
    open this guide.  We provide some simple methods to add
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1204
    outline entries.  Typically, a program to make a document
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1205
    (such as this user guide) will call the method
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1206
    $canvas.addOutlineEntry(^self, title, key, level=0,