docs/userguide/genuserguide.py
author andy_robinson
Fri, 07 Jul 2000 22:55:31 +0000
changeset 334 6f9c206a34c0
parent 331 df7a5344d9e3
child 336 c0fcae4341cf
permissions -rw-r--r--
Added paragraph examples and widget to User Guide
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 $
334
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
    35
#   Revision 1.21  2000/07/07 22:55:31  andy_robinson
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
    36
#   Added paragraph examples and widget to User Guide
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
    37
#
331
df7a5344d9e3 More on paragraphs
rgbecker
parents: 330
diff changeset
    38
#   Revision 1.20  2000/07/07 16:18:37  rgbecker
df7a5344d9e3 More on paragraphs
rgbecker
parents: 330
diff changeset
    39
#   More on paragraphs
df7a5344d9e3 More on paragraphs
rgbecker
parents: 330
diff changeset
    40
#
330
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
    41
#   Revision 1.19  2000/07/07 15:09:21  rgbecker
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
    42
#   Start on Paragraph
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
    43
#
328
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
    44
#   Revision 1.18  2000/07/06 15:38:15  rgbecker
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
    45
#   Started on Tables added EmbeddedCode utility
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
    46
#
323
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
    47
#   Revision 1.17  2000/07/05 16:06:01  rgbecker
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
    48
#   Platypus Start
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
    49
#
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    50
#   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
    51
#   Tidied up genuserguide.py, especially figure handling; began
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    52
#   adding PDF special features docco
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
    53
#
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    54
#   Revision 1.15  2000/07/03 16:03:31  andy_robinson
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    55
#   Changes to heading structure
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
    56
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    57
#   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
    58
#   Pushed down most existing lessons one level; added
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    59
#   functions heading1..heading3 for building story
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    60
#   unambiguously; spelled Hugh Hefner right!
314
72c75740504b abspath is 1.5.2 only
rgbecker
parents: 311
diff changeset
    61
#
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    62
#   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
    63
#   abspath is 1.5.2 only
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.12  2000/06/28 16:10:00  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    66
#   Fix unwanted 'i'
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.11  2000/06/28 14:52:43  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    69
#   Documentation changes
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.10  2000/06/27 10:09:48  rgbecker
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    72
#   Minor cosmetic changes
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.9  2000/06/23 21:09:03  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    75
#   text text and more text
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.8  2000/06/22 19:05:24  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    78
#   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
    79
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    80
#   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
    81
#   showPage resets all state parameters warning.
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.6  2000/06/22 13:35:28  aaron_watters
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    84
#   textobject and pathobject methods, among other things
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    85
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    86
#   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
    87
#   colors, line styles, more examples
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    88
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    89
#   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
    90
#   Lots of graphical examples added
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    91
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    92
#   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
    93
#   typos and more examples
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    94
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    95
#   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
    96
#   2nd try. more text
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    97
#   
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
    98
#   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
    99
#   initial checkin. user guide generation framework.
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   100
#   
334
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   101
__version__=''' $Id: genuserguide.py,v 1.21 2000/07/07 22:55:31 andy_robinson Exp $ '''
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   102
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   103
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   104
__doc__ = """
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   105
This module contains the script for building the user guide.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   106
"""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   107
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   108
import os, sys
334
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   109
import string
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   110
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   111
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
   112
from rltemplate import RLDocTemplate
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   113
from stylesheet import getStyleSheet
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   114
styleSheet = getStyleSheet()
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   115
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   116
#from reportlab.platypus.doctemplate import SimpleDocTemplate
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   117
from reportlab.lib.units import inch
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   118
from reportlab.lib.pagesizes import letter
328
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   119
from reportlab.platypus import Paragraph, Spacer, Preformatted,\
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   120
            PageBreak, CondPageBreak, Flowable, Table, TableStyle
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   121
from reportlab.lib.styles import ParagraphStyle
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   122
from reportlab.lib import colors
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   123
from reportlab.lib.sequencer import getSequencer
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   124
import examples
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   125
import platdemos
328
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   126
import StringIO
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   127
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   128
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   129
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   130
from reportlab.lib.corp import ReportLabLogo
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   131
LOGO = ReportLabLogo(0.25*inch, 0.25*inch, inch, 0.75*inch)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   132
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   133
from t_parse import Template
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   134
QFcodetemplate = Template("X$X$", "X")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   135
QFreptemplate = Template("X^X^", "X")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   136
codesubst = "%s<font name=Courier>%s</font>"
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   137
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
   138
    
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   139
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   140
def quickfix(text):
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   141
    """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
   142
       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
   143
       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
   144
       $ is $\\$ (^ is ^\\^.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   145
    """
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   146
    from string import join
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   147
    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
   148
        fragment = text
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   149
        parts = []
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   150
        try:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   151
            while fragment:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   152
                try:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   153
                    (matches, index) = template.PARSE(fragment)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   154
                except: raise ValueError
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   155
                else:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   156
                    [prefix, code] = matches
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   157
                    if code == "\\":
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   158
                        part = fragment[:index]
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   159
                    else:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   160
                        part = subst % (prefix, code)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   161
                    parts.append(part)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   162
                    fragment = fragment[index:]
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   163
        except ValueError:
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   164
            parts.append(fragment)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   165
        text = join(parts, "")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   166
    return text
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   167
#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
   168
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   169
class Guide:
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   170
    def __init__(self):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   171
        self.story = story()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   172
    def go(self, filename="userguide.pdf"):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   173
        # generate the doc...
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   174
        doc = RLDocTemplate(filename,pagesize = letter)
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   175
        story = self.story
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   176
        doc.build(story)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   177
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   178
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   179
H1 = styleSheet['Heading1']
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   180
H2 = styleSheet['Heading2']
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   181
H3 = styleSheet['Heading3']
323
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   182
H4 = styleSheet['Heading4']
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   183
B = styleSheet['BodyText']
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   184
Comment = styleSheet['Comment']
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   185
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   186
#set up numbering
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   187
seq = getSequencer()
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   188
seq.setFormat('Chapter','1')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   189
seq.setFormat('Section','1')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   190
seq.setFormat('Appendix','A')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   191
seq.chain('Chapter','Section')
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   192
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   193
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   194
lessonnamestyle = H2
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   195
discussiontextstyle = B
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   196
exampletextstyle = styleSheet['Code']
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   197
# size for every example
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   198
examplefunctionxinches = 5.5
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   199
examplefunctionyinches = 3
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   200
examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   201
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   202
# for testing
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   203
def NOP(*x,**y):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   204
    return None
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   205
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   206
BODY = []
323
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   207
def CPage(inches):
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   208
    BODY.append(CondPageBreak(inches*inch))
334
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   209
    
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   210
def newPage():
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   211
    BODY.append(PageBreak())
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   212
    
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   213
def story():
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   214
    return BODY
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   215
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   216
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
   217
    text = quickfix(text)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   218
    P = klass(text, style)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   219
    BODY.append(P)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   220
    
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   221
def eg(text):
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   222
    BODY.append(Spacer(0.1*inch, 0.1*inch))
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   223
    disc(text, klass=Preformatted, style=exampletextstyle)
328
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   224
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   225
def EmbeddedCode(code,name='t', fn='embedded.tmp'):
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   226
    eg(code)
e0122856a912 Started on Tables added EmbeddedCode utility
rgbecker
parents: 323
diff changeset
   227
    disc("produces")
330
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   228
    exec code+("\nBODY.append(%s)\n"%name)
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   229
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   230
def title(text):
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   231
    """Use this for the document title only"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   232
    disc(text,style=styleSheet['Title'])
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   233
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   234
#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
   235
#should be swapped over to using them.
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   236
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   237
def heading1(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   238
    """Use this for chapters.  Lessons within a big chapter
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   239
    should now use heading2 instead.  Chapters get numbered."""
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   240
    BODY.append(PageBreak())
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   241
    p = Paragraph('Chapter <seq id="Chapter"/> - ' + quickfix(text), H1)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   242
    BODY.append(p)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   243
    
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   244
def heading2(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   245
    """Used to be 'lesson'"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   246
    BODY.append(CondPageBreak(inch))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   247
    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
   248
    BODY.append(p)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   249
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   250
def heading3(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   251
    """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
   252
    BODY.append(CondPageBreak(inch))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   253
    p = Paragraph(quickfix(text), H3)
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   254
    BODY.append(p)
323
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   255
 
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   256
def heading4(text):
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   257
    """Used to be most of the plain old 'head' sections"""
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   258
    BODY.append(CondPageBreak(inch))
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   259
    p = Paragraph(quickfix(text), H4)
5795e28c5910 Platypus Start
rgbecker
parents: 320
diff changeset
   260
    BODY.append(p)
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   261
    
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   262
def todo(text):
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   263
    """Used for notes to ourselves"""
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   264
    BODY.append(Paragraph(quickfix(text), Comment))
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   265
    
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   266
class Illustration(platdemos.Figure):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   267
    """The examples are all presented as functions which do
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   268
    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
   269
    used.  This puts them inside a figure box with a caption."""
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   270
    
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   271
    def __init__(self, operation, caption):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   272
        stdwidth, stdheight = examplefunctiondisplaysizes
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   273
        #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
   274
        platdemos.Figure.__init__(self, stdwidth, stdheight)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   275
        self.operation = operation
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   276
        self.caption = 'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   277
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   278
    def drawFigure(self):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   279
        #shrink it a little...
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   280
        #self.canv.scale(0.75, 0.75)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   281
        self.operation(self.canv)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   282
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   283
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   284
def illust(operation, caption):
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   285
    i = Illustration(operation, caption)
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   286
    BODY.append(i)
334
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   287
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   288
class ParaBox(platdemos.Figure):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   289
    descrStyle = ParagraphStyle('description',
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   290
                                fontName='Courier',
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   291
                                fontSize=8,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   292
                                leading=9.6)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   293
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   294
    def __init__(self, text, style):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   295
        platdemos.Figure.__init__(self, 0, 0)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   296
        self.text = text
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   297
        self.style = style
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   298
        self.para = Paragraph(text, style)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   299
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   300
        styleText = self.getStyleText(style)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   301
        self.pre = Preformatted(styleText, self.descrStyle)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   302
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   303
    def wrap(self, availWidth, availHeight):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   304
        """Left 30% is for attributes, right 50% for sample,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   305
        10% gutter each side."""
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   306
        self.x0 = availWidth * 0.05  #left of box
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   307
        self.x1 = availWidth * 0.1   #left of descriptive text
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   308
        self.x2 = availWidth * 0.5   #left of para itself
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   309
        self.x3 = availWidth * 0.9   #right of para itself
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   310
        self.x4 = availWidth * 0.95  #right of box
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   311
        self.width = self.x4 - self.x0
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   312
        self.dx = 0.5 * (availWidth - self.width)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   313
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   314
        paw, self.pah = self.para.wrap(self.x3 - self.x2, availHeight)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   315
        self.pah = self.pah + self.style.spaceBefore + self.style.spaceAfter
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   316
        prw, self.prh = self.pre.wrap(self.x2 - self.x1, availHeight)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   317
        self.figureHeight = max(self.prh, self.pah) * 10.0/9.0
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   318
        return platdemos.Figure.wrap(self, availWidth, availHeight)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   319
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   320
    def getStyleText(self, style):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   321
        """Converts style to preformatted block of text"""
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   322
        lines = []
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   323
        for (key, value) in style.__dict__.items():
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   324
            lines.append('%s = %s' % (key, value))
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   325
        lines.sort()
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   326
        return string.join(lines, '\n')        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   327
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   328
    def drawFigure(self):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   329
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   330
        #now we fill in the bounding box and before/after boxes       
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   331
        self.canv.saveState()
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   332
        self.canv.setFillGray(0.95)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   333
        self.canv.setDash(1,3)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   334
        self.canv.rect(self.x2 - self.x0,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   335
                       self.figureHeight * 0.95 - self.pah,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   336
                       self.x3-self.x2, self.para.height,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   337
                       fill=1,stroke=1)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   338
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   339
        self.canv.setFillGray(0.90)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   340
        self.canv.rect(self.x2 - self.x0, #spaceBefore
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   341
                       self.figureHeight * 0.95 - self.pah + self.para.height,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   342
                       self.x3-self.x2, self.style.spaceBefore,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   343
                       fill=1,stroke=1)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   344
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   345
        self.canv.rect(self.x2 - self.x0, #spaceBefore
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   346
                       self.figureHeight * 0.95 - self.pah - self.style.spaceAfter,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   347
                       self.x3-self.x2, self.style.spaceAfter,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   348
                       fill=1,stroke=1)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   349
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   350
        self.canv.restoreState()
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   351
        #self.canv.setFillColor(colors.yellow)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   352
        self.para.drawOn(self.canv, self.x2 - self.x0,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   353
                         self.figureHeight * 0.95 - self.pah)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   354
        self.pre.drawOn(self.canv, self.x1 - self.x0,
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   355
                         self.figureHeight * 0.95 - self.prh)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   356
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   357
        
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   358
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   359
    def getStyleText(self, style):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   360
        """Converts style to preformatted block of text"""
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   361
        lines = []
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   362
        for (key, value) in style.__dict__.items():
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   363
            if key not in ('name','parent'):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   364
                lines.append('%s = %s' % (key, value))
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   365
        return string.join(lines, '\n')
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   366
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   367
def parabox(text, style, caption):
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   368
    p = ParaBox(text, style)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   369
    p.caption = 'Figure <seq template="%(Chapter)s-%(Figure+)s"/>: ' + quickfix(caption)
6f9c206a34c0 Added paragraph examples and widget to User Guide
andy_robinson
parents: 331
diff changeset
   370
    BODY.append(p)
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   371
    
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   372
def pencilnote():
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   373
    BODY.append(examples.NoteAnnotation())
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   374
        
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   375
###### testing...
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   376
#illust(NOP)
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   377
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   378
#heading2("this is a new lesson")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   379
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   380
#disc("this explains the example")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   381
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   382
#eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   383
#this
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   384
#  is the
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   385
#    example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   386
#      code""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   387
      
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   388
#disc("the execution of the example follows")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   389
      
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   390
#illust(NOP) # execute some code
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   391
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   392
#pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   393
310
cbec783cfb81 Documentation changes
rgbecker
parents: 308
diff changeset
   394
title("ReportLab User Guide")
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   395
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   396
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
   397
appear in italics like this.""")
318
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   398
todo("")
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   399
todo("""Sequencer is post-incrementing chapters, so all
03c9f114c621 Changes to heading structure
andy_robinson
parents: 317
diff changeset
   400
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
   401
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   402
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   403
heading1("Introduction")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   404
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   405
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   406
This document is intended to be a conversational introduction
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   407
to the use of the ReportLab packages.  Some previous programming experience
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   408
is presumed and familiarity with the Python Programming language is
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   409
recommended.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   410
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   411
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   412
heading2("What is PDFgen all about")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   413
todo("rationale - from Andy")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   414
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   415
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   416
heading2("About Python")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   417
todo("If they don't know Python, rave a little then tell them where to get it")
330
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   418
heading3("What is Python?")
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   419
disc("""<para lindent=+36>
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   420
<b>python</b>, (<i>Gr. Myth.</i> An enormous serpent that lurked in the cave of Mount Parnassus and was slain
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   421
by Apollo) <b>1.</b> any of a genus of large, non-poisonous snakes of Asia, Africa and Australia that
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   422
suffocate their prey to death. <b>2.</b> popularly, any large snake that crushes its prey. <b>3.</b> totally awesome,
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   423
bitchin' language that will someday crush the $'s out of certain <i>other</i> so-called VHLL's ;-)</para>
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   424
""")
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   425
disc("""
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   426
Python is an <i>interpreted, interactive, object-oriented</i> programming language. It is often compared to Tcl, Perl,
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   427
Scheme or Java. 
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   428
""")
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   429
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   430
disc("""
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   431
Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   432
dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   433
various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily written in C or C++.
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   434
Python is also usable as an extension language for applications that need a programmable interface. 
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   435
""")
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   436
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   437
disc("""
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   438
The Python implementation is portable: it runs on many brands of UNIX, on Windows, DOS, OS/2, Mac, Amiga... If
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   439
your favorite system isn't listed here, it may still be supported, if there's a C compiler for it. Ask around on
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   440
comp.lang.python -- or just try compiling Python yourself. 
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   441
""")
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   442
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   443
disc("""
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   444
Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>. 
e392b1be9211 Start on Paragraph
rgbecker
parents: 328
diff changeset
   445
""")
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   446
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   447
heading2("Installation and Setup")
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   448
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
   449
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   450
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   451
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   452
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   453
This document is in a <em>very</em> preliminary form.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   454
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   455
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   456
heading1("Graphics and Text with $pdfgen$")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   457
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   458
heading2("Basic Concepts")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   459
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   460
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
   461
generating PDF documents.  A $pdfgen$ program is essentially
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   462
a sequence of instructions for "painting" a document onto
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   463
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
   464
painting operations is the $pdfgen canvas$.  
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   465
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   466
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   467
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   468
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
   469
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
   470
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
   471
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
   472
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
   473
default.""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   474
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   475
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   476
A simple example
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   477
program that uses a canvas follows.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   478
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   479
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   480
eg("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   481
    from reportlab.pdfgen import canvas
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   482
    c = canvas.Canvas("hello.pdf")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   483
    hello(c)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   484
    c.showPage()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   485
    c.save()
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   486
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   487
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   488
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   489
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
   490
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
   491
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
   492
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
   493
and the $save$ method stores the file and closes the canvas.""")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   494
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   495
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   496
The $showPage$ method causes the $canvas$ to stop drawing on the
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   497
current page and any further operations will draw on a subsequent
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   498
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
   499
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
   500
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
   501
document, which is the whole purpose of the $canvas$ object.
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   502
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   503
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   504
heading2("More about the Canvas")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   505
disc("""
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   506
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
   507
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
   508
are many different settings available.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   509
todo("""Cover all constructor arguments, and setAuthor etc.""")
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   510
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   511
heading2("Drawing Operations")
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   512
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   513
Suppose the $hello$ function referenced above is implemented as
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   514
follows (we will not explain each of the operations in detail
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   515
yet).
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   516
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   517
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   518
eg(examples.testhello)
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   519
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   520
disc("""
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   521
Examining this code notice that there are essentially two types
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   522
of operations performed using a canvas.  The first type draws something
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   523
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
   524
type changes the state of the canvas such as
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   525
changing the current fill or stroke color or changing the current font
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   526
type and size.  
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   527
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   528
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   529
disc("""
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   530
If we imagine the program as a painter working on
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   531
the canvas the "draw" operations apply paint to the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   532
the current set of tools (colors, line styles, fonts, etcetera)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   533
and the "state change" operations change one of the current tools
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   534
(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
   535
the current font to $Times-Roman$ in 15 points, for example).
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   536
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   537
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   538
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   539
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
   540
the following graphics.
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   541
""")
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   542
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   543
illust(examples.hello, '"Hello World" in pdfgen')
273
cd705b27b6a5 initial checkin. user guide generation framework.
aaron_watters
parents:
diff changeset
   544
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   545
heading3("About the demos in this document")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   546
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   547
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   548
This document contains demonstrations of the code discussed like the one shown
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   549
in the rectangle above.  These demos are drawn on a "tiny page" embedded
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   550
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
   551
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
   552
""" % (examplefunctionxinches, examplefunctionyinches))
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   553
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   554
heading2('The tools: the "draw" operations')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   555
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   556
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   557
This section briefly lists the tools available to the program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   558
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   559
These will be discussed in detail in later sections.  They are listed
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   560
here for easy reference and for summary purposes.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   561
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   562
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   563
heading3("Line methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   564
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   565
eg("""canvas.line(x1,y1,x2,y2)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   566
eg("""canvas.lines(linelist)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   567
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   568
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   569
The line methods draw straight line segments on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   570
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   571
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   572
heading3("Shape methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   573
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   574
eg("""canvas.grid(xlist, ylist) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   575
eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   576
eg("""canvas.arc(x1,y1,x2,y2) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   577
eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   578
eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   579
eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   580
eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   581
eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   582
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   583
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   584
The shape methods draw common complex shapes on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   585
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   586
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   587
heading3("String drawing methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   588
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   589
eg("""canvas.drawString(x, y, text):""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   590
eg("""canvas.drawRightString(x, y, text) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   591
eg("""canvas.drawCentredString(x, y, text)""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   592
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   593
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   594
The draw string methods draw single lines of text on the canvas.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   595
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   596
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   597
heading3("The text object methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   598
eg("""textobject = canvas.beginText(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   599
eg("""canvas.drawText(textobject) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   600
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   601
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   602
Text objects are used to format text in ways that
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   603
are not supported directly by the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   604
A program creates a text object from the canvas using beginText
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   605
and then formats text by invoking textobject methods.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   606
Finally the textobject is drawn onto the canvas using
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   607
drawText.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   608
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   609
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   610
heading3("The path object methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   611
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   612
eg("""path = canvas.beginPath() """)
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   613
eg("""canvas.drawPath(path, stroke=1, fill=0) """)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   614
eg("""canvas.clipPath(path, stroke=1, fill=0) """)
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   615
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   616
heading3("Image methods")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   617
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   618
eg("""canvas.drawInlineImage(self, image, x,y, width=None,height=None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   619
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   620
heading3("Ending a page")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   621
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   622
eg("""canvas.showPage()""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   623
300
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   624
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
   625
be done on another page.""")
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   626
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   627
pencilnote()
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   628
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   629
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
   630
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
   631
must be set up again before the program proceeds with drawing!""")
44c954f72e2b showPage resets all state parameters warning.
aaron_watters
parents: 299
diff changeset
   632
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   633
heading2('The toolbox: the "state change" operations')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   634
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   635
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   636
This section briefly lists the ways to switch the tools used by the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   637
program
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   638
for painting information onto a page using the canvas interface.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   639
These too will be discussed in detail in later sections.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   640
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   641
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   642
heading3("Changing Colors")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   643
eg("""canvas.setFillColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   644
eg("""canvas.setStrikeColorCMYK(c, m, y, k) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   645
eg("""canvas.setFillColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   646
eg("""canvas.setStrokeColorRGB(r, g, b) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   647
eg("""canvas.setFillColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   648
eg("""canvas.setStrokeColor(acolor) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   649
eg("""canvas.setFillGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   650
eg("""canvas.setStrokeGray(gray) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   651
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   652
heading3("Changing Fonts")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   653
eg("""canvas.setFont(psfontname, size, leading = None) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   654
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   655
heading3("Changing Graphical Styles")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   656
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   657
eg("""canvas.setLineWidth(width) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   658
eg("""canvas.setLineCap(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   659
eg("""canvas.setLineJoin(mode) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   660
eg("""canvas.setMiterLimit(limit) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   661
eg("""canvas.setDash(self, array=[], phase=0) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   662
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   663
heading3("Changing Geometry")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   664
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   665
eg("""canvas.setPageSize(pair) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   666
eg("""canvas.transform(a,b,c,d,e,f): """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   667
eg("""canvas.translate(dx, dy) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   668
eg("""canvas.scale(x, y) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   669
eg("""canvas.rotate(theta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   670
eg("""canvas.skew(alpha, beta) """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   671
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   672
heading3("State control")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   673
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   674
eg("""canvas.saveState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   675
eg("""canvas.restoreState() """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   676
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   677
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   678
heading2("Other canvas methods.")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   679
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   680
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   681
Not all methods of the canvas object fit into the "tool" or "toolbox"
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   682
categories.  Below are some of the misfits, included here for completeness.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   683
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   684
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   685
eg("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   686
 canvas.setAuthor()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   687
 canvas.addOutlineEntry(title, key, level=0, closed=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   688
 canvas.setTitle(title)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   689
 canvas.setSubject(subj)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   690
 canvas.pageHasData()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   691
 canvas.showOutline()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   692
 canvas.bookmarkPage(name)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   693
 canvas.bookmarkHorizontalAbsolute(name, yhorizontal)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   694
 canvas.doForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   695
 canvas.beginForm(name, lowerx=0, lowery=0, upperx=None, uppery=None)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   696
 canvas.endForm()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   697
 canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   698
 canvas.getPageNumber()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   699
 canvas.addLiteral()
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   700
 canvas.getAvailableFonts()
308
a09abac33167 Minor cosmetic changes
rgbecker
parents: 304
diff changeset
   701
 canvas.stringWidth(self, text, fontName, fontSize, encoding=None)
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   702
 canvas.setPageCompression(onoff=1)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   703
 canvas.setPageTransition(self, effectname=None, duration=1, 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   704
                        direction=0,dimension='H',motion='I')
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   705
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   706
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   707
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   708
heading2('Coordinates (default user space)')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   709
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   710
disc("""
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   711
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
   712
For example the pair $(4.5*inch, 1*inch)$ identifies the location
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   713
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
   714
the right 4.5 inches and up one inch.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   715
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   716
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   717
disc("""For example, the following function draws
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   718
a number of elements on a canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   719
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   720
eg(examples.testcoords)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   721
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   722
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
   723
left corner.  Executing the $coords$ function in the default user space
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   724
(for the "demo minipage") we obtain the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   725
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   726
illust(examples.coords, 'The Coordinate System')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   727
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   728
heading3("Moving the origin: the $translate$ method")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   729
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   730
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
   731
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
   732
for the current page to the point currently identified by ^(x,y)^.""")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   733
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   734
disc("""For example the following translate function first moves
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   735
the origin before drawing the same objects as shown above.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   736
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   737
eg(examples.testtranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   738
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   739
disc("""This produces the following.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   740
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   741
illust(examples.translate, "Moving the origin: the $translate$ method")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   742
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   743
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   744
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   745
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   746
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   747
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   748
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   749
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   750
<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
   751
or parts of objects "off the page".
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   752
In particular a common confusing bug is a translation operation that translates the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   753
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
   754
it is possible that all the drawn objects are off the page.
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   755
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   756
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   757
heading3("Shrinking and growing: the scale operation")
283
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("""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
   760
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
   761
^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
   762
$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
   763
$dx$ and $dy$ are different.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   764
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   765
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   766
eg(examples.testscale)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   767
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   768
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
   769
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   770
illust(examples.scale, "Scaling the coordinate system")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   771
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   772
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   773
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   774
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   775
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   776
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   777
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   778
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
   779
or may cause objects to "shrink to nothing." """)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   780
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   781
disc("""Scaling and translation can be combined, but the order of the
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   782
operations are important.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   783
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   784
eg(examples.testscaletranslate)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   785
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   786
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
   787
and then does a $scale$ followed by a $translate$.  Afterward the function
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   788
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
   789
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
   790
Observe the effect below.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   791
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   792
illust(examples.scaletranslate, "Scaling and Translating")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   793
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   794
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   795
#illust(NOP) # execute some code
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   796
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   797
pencilnote()
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   798
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
   799
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   800
disc("""<em>Note:</em> scaling shrinks or grows everything including line widths
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   801
so using the canvas.scale method to render a microscopic drawing in 
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   802
scaled microscopic units
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   803
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
   804
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
   805
to shrink to the point where they disappear.  For engineering or scientific purposes
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   806
such as these scale and translate
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   807
the units externally before rendering them using the canvas.""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   808
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   809
heading3("Saving and restoring the canvas state: $saveState$ and $restoreState$")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   810
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   811
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   812
The $scaletranslate$ function used an important feature of the canvas object:
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   813
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
   814
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
   815
an $canvas.restoreState()$ operations all changes of font, color, line style,
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   816
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
   817
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
   818
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
   819
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
   820
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
   821
across page breaks.
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   822
""")
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   823
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   824
heading3("Mirror image")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   825
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   826
disc("""
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   827
It is interesting although perhaps not terribly useful to note that
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   828
scale factors can be negative.  For example the following function
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   829
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   830
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   831
eg(examples.testmirror)
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   832
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   833
disc("""
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   834
creates a mirror image of the elements drawn by the $coord$ function.
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   835
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   836
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   837
illust(examples.mirror, "Mirror Images")
293
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   838
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   839
disc("""
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   840
Notice that the text strings are painted backwards.
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   841
""")
84a2635a8c30 typos and more examples
aaron_watters
parents: 283
diff changeset
   842
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   843
heading2("Colors")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   844
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   845
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   846
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
   847
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
   848
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
   849
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
   850
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   851
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   852
eg(examples.testcolors)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   853
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   854
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   855
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
   856
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
   857
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
   858
$(1,1,1)$.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   859
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   860
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
   861
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
   862
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
   863
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
   864
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
   865
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
   866
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
   867
$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
   868
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
   869
and better control when printed.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   870
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   871
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   872
illust(examples.colors, "Color Models")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   873
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   874
heading2('Painting back to front')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   875
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   876
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   877
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
   878
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
   879
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
   880
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
   881
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   882
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   883
eg(examples.testspumoni)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   884
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   885
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   886
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
   887
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
   888
the word.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   889
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   890
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   891
illust(examples.spumoni, "Painting over colors")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   892
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   893
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   894
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
   895
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
   896
leaves no visible effect.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   897
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   898
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   899
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   900
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
   901
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
   902
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
   903
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   904
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   905
eg(examples.testspumoni2)
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   906
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   907
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   908
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
   909
$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
   910
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
   911
""")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   912
illust(examples.spumoni2, "building up a drawing in layers")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   913
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   914
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   915
heading2('Fonts and text objects')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
   916
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   917
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   918
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
   919
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
   920
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
   921
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   922
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   923
eg(examples.testtextsize)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   924
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   925
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   926
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
   927
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   928
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   929
illust(examples.textsize, "text in different fonts and sizes")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   930
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   931
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   932
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
   933
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   934
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   935
eg(examples.testfonts)
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   936
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   937
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   938
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
   939
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
   940
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
   941
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   942
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   943
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
   944
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   945
disc("""
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   946
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
   947
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
   948
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   949
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
   950
heading2("Text object methods")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
   951
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   952
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   953
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
   954
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
   955
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
   956
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
   957
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   958
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   959
eg("""textobject.setTextOrigin(x,y)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   960
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   961
eg("""textobject.setTextTransform(a,b,c,d,e,f)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   962
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   963
eg("""textobject.moveCursor(dx, dy) # from start of current LINE""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   964
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   965
eg("""(x,y) = textobject.getCursor()""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   966
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   967
eg("""x = textobject.getX(); y = textobject.getY()""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   968
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   969
eg("""textobject.setFont(psfontname, size, leading = None)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   970
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   971
eg("""textobject.textOut(text)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   972
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   973
eg("""textobject.textLine(text='')""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   974
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   975
eg("""textobject.textLines(stuff, trim=1)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   976
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   977
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   978
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
   979
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   980
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   981
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   982
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
   983
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
   984
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
   985
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
   986
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   987
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   988
eg(examples.testcursormoves1)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   989
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   990
disc("""
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
   991
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
   992
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
   993
has been set.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   994
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   995
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
   996
illust(examples.cursormoves1, "How the text cursor moves")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
   997
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   998
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
   999
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
  1000
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
  1001
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
  1002
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
  1003
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
  1004
positive ^y^ usually moves up.
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1005
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1006
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1007
eg(examples.testcursormoves2)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1008
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1009
disc("""
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1010
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
  1011
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
  1012
""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1013
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1014
illust(examples.cursormoves2, "How the text cursor moves again")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1015
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1016
heading3("Character Spacing")
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1017
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1018
eg("""textobject.setCharSpace(charSpace)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1019
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1020
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
  1021
spacing.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1022
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1023
eg(examples.testcharspace)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1024
301
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1025
disc("""The 
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1026
$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
  1027
It produces the following page.""")
5ad57f31ae75 added quickhack for font changes in paragraphs and lots of new text
aaron_watters
parents: 300
diff changeset
  1028
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1029
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
  1030
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1031
heading3("Word Spacing")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1032
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1033
eg("""textobject.setWordSpace(wordSpace)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1034
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1035
disc("The $setWordSpace$ method adjusts the space between word.")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1036
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1037
eg(examples.testwordspace)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1038
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1039
disc("""The $wordspace$ function shows what various word space settings
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1040
look like below.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1041
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1042
illust(examples.wordspace, "Adjusting word spacing")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1043
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1044
heading3("Horizontal Scaling")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1045
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1046
eg("""textobject.setHorizScale(horizScale)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1047
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1048
disc("""Lines of text can be stretched or shrunken horizontally by the 
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1049
$setHorizScale$ method.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1050
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1051
eg(examples.testhorizontalscale)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1052
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1053
disc("""The horizontal scaling parameter ^horizScale^
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1054
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
  1055
shown below looks skinny.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1056
""")
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1057
illust(examples.horizontalscale, "adjusting horizontal text scaling")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1058
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1059
heading3("Interline spacing (Leading)")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1060
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1061
eg("""textobject.setLeading(leading)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1062
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1063
disc("""The vertical offset between the point at which one
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1064
line starts and where the next starts is called the leading
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1065
offset.  The $setLeading$ method adjusts the leading offset.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1066
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1067
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1068
eg(examples.testleading)
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1069
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1070
disc("""As shown below if the leading offset is set too small
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1071
characters of one line my write over the bottom parts of characters
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1072
in the previous line.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1073
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1074
illust(examples.leading, "adjusting the leading")
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1075
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1076
heading3("Other text object methods")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1077
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1078
eg("""textobject.setTextRenderMode(mode)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1079
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1080
disc("""The $setTextRenderMode$ method allows text to be used
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1081
as a forground for clipping background drawings, for example.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1082
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1083
eg("""textobject.setRise(rise)""")
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1084
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1085
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1086
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
  1087
(for creating superscripts or subscripts, for example).
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1088
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1089
299
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1090
eg("""textobject.setFillColor(aColor); 
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1091
textobject.setStrokeColor(self, aColor) 
909b83ce750c textobject and pathobject methods, among other things
aaron_watters
parents: 298
diff changeset
  1092
# and similar""")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1093
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1094
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1095
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
  1096
similar to the color methods for the canvas object.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1097
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1098
heading2('Paths and Lines')
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1099
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1100
disc("""Just as textobjects are designed for the dedicated presentation
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1101
of text, path objects are designed for the dedicated construction of
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1102
graphical figures.  When path objects are drawn onto a canvas they are
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1103
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
  1104
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
  1105
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
  1106
not; and so forth.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1107
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1108
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1109
For example the $star$ function uses a path object
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1110
to draw a star
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1111
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1112
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1113
eg(examples.teststar)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1114
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1115
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1116
The $star$ function has been designed to be useful in illustrating
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1117
various line style parameters supported by $pdfgen$.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1118
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1119
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1120
illust(examples.star, "line style parameters")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1121
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1122
heading3("Line join settings")
304
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
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1125
The $setLineJoin$ method can adjust whether line segments meet in a point
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1126
a square or a rounded vertex.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1127
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1128
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1129
eg(examples.testjoins)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1130
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1131
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1132
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
  1133
it cannot be seen clearly for thin lines.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1134
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1135
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1136
illust(examples.joins, "different line join styles")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1137
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1138
heading3("Line cap settings")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1139
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1140
disc("""The line cap setting, adjusted using the $setLineCap$ method,
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1141
determines whether a terminating line
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1142
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
  1143
or a half circle over the vertex.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1144
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1145
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1146
eg(examples.testcaps)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1147
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1148
disc("""The line cap setting, like the line join setting, is only
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1149
visible when the lines are thick.""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1150
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1151
illust(examples.caps, "line cap settings")
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1152
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1153
heading3("Dashes and broken lines")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1154
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1155
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1156
The $setDash$ method allows lines to be broken into dots or dashes.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1157
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1158
298
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1159
eg(examples.testdashes)
0e23c189f665 colors, line styles, more examples
aaron_watters
parents: 296
diff changeset
  1160
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1161
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1162
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
  1163
or they can be specified in a complex repeating pattern.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1164
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1165
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1166
illust(examples.dashes, "some dash patterns")
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
  1167
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1168
heading3("Creating complex figures with path objects")
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1169
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1170
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1171
Combinations of lines, curves, arcs and other figures
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1172
can be combined into a single figure using path objects.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1173
For example the function shown below constructs two path
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1174
objects using lines and curves.  
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1175
This function will be used later on as part of a
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1176
pencil icon construction.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1177
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1178
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1179
eg(examples.testpenciltip)
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1180
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1181
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1182
Note that the interior of the pencil tip is filled
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1183
as one object even though it is constructed from
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1184
several lines and curves.  The pencil lead is then
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1185
drawn over it using a new path object.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1186
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1187
320
7a4ca2b5bb89 Tidied up genuserguide.py, especially figure handling; began
andy_robinson
parents: 318
diff changeset
  1188
illust(examples.penciltip, "a pencil tip")
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1189
317
fce6dad947c3 Pushed down most existing lessons one level; added
andy_robinson
parents: 314
diff changeset
  1190
heading2('Rectangles, circles, ellipses')
283
50f6c1be3e51 2nd try. more text
aaron_watters
parents: 273
diff changeset
  1191
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1192
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1193
The $pdfgen$ module supports a number of generally useful shapes
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1194
such as rectangles, rounded rectangles, ellipses, and circles.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1195
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
  1196
directly on a canvas.  For example the $pencil$ function below
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1197
draws a pencil icon using rectangles and rounded rectangles with
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1198
various fill colors and a few other annotations.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1199
""")
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1200
296
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1201
eg(examples.testpencil)
a5e584b6d61b Lots of graphical examples added
aaron_watters
parents: 293
diff changeset
  1202
304
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1203
pencilnote()
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1204
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1205
disc("""
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1206
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
  1207
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
  1208
because, for example, the white rectangles "erase" parts of a black rectangle
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1209
and the "tip" paints over part of the yellow rectangle.
3d53a0b5d429 text text and more text
aaron_watters
parents: 301
diff changeset
  1210
""")