docs/userguide/ch2_graphics.py
author rgbecker
Wed, 25 Oct 2000 08:57:46 +0000
changeset 494 54257447cfe9
parent 456 66fcc7402811
child 684 2a43c747527a
permissions -rw-r--r--
Changed to indirect copyright
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
494
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 456
diff changeset
     1
#copyright ReportLab Inc. 2000
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 456
diff changeset
     2
#see license.txt for license details
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 456
diff changeset
     3
#history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/docs/userguide/ch2_graphics.py?cvsroot=reportlab
54257447cfe9 Changed to indirect copyright
rgbecker
parents: 456
diff changeset
     4
#$Header: /tmp/reportlab/docs/userguide/ch2_graphics.py,v 1.9 2000/10/25 08:57:45 rgbecker Exp $
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     5
from genuserguide import *
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     6
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     7
heading1("Graphics and Text with $pdfgen$")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     8
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
     9
heading2("Basic Concepts")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    10
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    11
The $pdfgen$ package is the lowest level interface for
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    12
generating PDF documents.  A $pdfgen$ program is essentially
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    13
a sequence of instructions for "painting" a document onto
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    14
a sequence of pages.  The interface object which provides the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    15
painting operations is the $pdfgen canvas$.  
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    16
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    17
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    18
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    19
The canvas should be thought of as a sheet of white paper
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    20
with points on the sheet identified using Cartesian ^(X,Y)^ coordinates
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    21
which by default have the ^(0,0)^ origin point at the lower
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    22
left corner of the page.  Furthermore the first coordinate ^x^
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    23
goes to the right and the second coordinate ^y^ goes up, by
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    24
default.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    25
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    26
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    27
A simple example
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    28
program that uses a canvas follows.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    29
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    30
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    31
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    32
    from reportlab.pdfgen import canvas
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    33
    c = canvas.Canvas("hello.pdf")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    34
    hello(c)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    35
    c.showPage()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    36
    c.save()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    37
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    38
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    39
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    40
The above code creates a $canvas$ object which will generate
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    41
a PDF file named $hello.pdf$ in the current working directory.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    42
It then calls the $hello$ function passing the $canvas$ as an argument.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    43
Finally the $showPage$ method saves the current page of the canvas
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    44
and the $save$ method stores the file and closes the canvas.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    45
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    46
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    47
The $showPage$ method causes the $canvas$ to stop drawing on the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    48
current page and any further operations will draw on a subsequent
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    49
page (if there are any further operations -- if not no
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    50
new page is created).  The $save$ method must be called after the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    51
construction of the document is complete -- it generates the PDF
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    52
document, which is the whole purpose of the $canvas$ object.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    53
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    54
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    55
heading2("More about the Canvas")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    56
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    57
Before describing the drawing operations, we will digress to cover
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
    58
some of the things which can be done to configure a canvas.  There
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    59
are many different settings available.  If you are new to Python
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    60
or can't wait to produce some output, you can skip ahead, but
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    61
come back later and read this!""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    62
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    63
disc("""First of all, we will look at the constructor
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    64
arguments for the canvas:""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    65
eg("""    def __init__(self,filename,
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    66
                 pagesize=(595.27,841.89),
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    67
                 bottomup = 1,
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    68
                 pageCompression=0,
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    69
                 encoding=pdfdoc.DEFAULT_ENCODING,
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    70
                 verbosity=0):
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    71
                 """)
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    72
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    73
disc("""The $filename$ argument controls the
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    74
name of the final PDF file.  You
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    75
may also pass in any open file object (such as $sys.stdout$, the python process standard output)
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    76
and the PDF document will be written to that.  Since PDF
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    77
is a binary format, you should take care when writing other
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    78
stuff before or after it; you can't deliver PDF documents
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    79
inline in the middle of an HTML page!""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    80
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    81
disc("""The $pagesize$ argument is a tuple of two numbers
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    82
in points (1/72 of an inch). The canvas defaults to $A4$ (an international standard
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    83
page size which differs from the American standard page size of $letter$),
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    84
but it is better to explicitly specify it.  Most common page
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    85
sizes are found in the library module $reportlab.lib.pagesizes$,
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    86
so you can use expressions like""")
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    87
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    88
eg("""from reportlab.lib.pagesizes import letter, A4
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    89
myCanvas = Canvas('myfile.pdf', pagesize=letter)
456
66fcc7402811 Correct size setting thanks to Werner Louche
rgbecker
parents: 406
diff changeset
    90
width, height = letter  #keep for later
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    91
""")
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    92
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    93
pencilnote()
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    94
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    95
disc("""If you have problems printing your document make sure you
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    96
are using the right page size (usually either $A4$ or $letter$).
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    97
Some printers do not work well with pages that are too large or too small.""")
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
    98
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
    99
disc("""Very often, you will want to calculate things based on
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   100
the page size.  In the example above we extracted the width and
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   101
height.  Later in the program we may use the $width$ variable to 
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   102
define a right margin as $width - inch$ rather than using
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   103
a constant.  By using variables the margin will still make sense even 
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   104
if the page size changes.""")
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   105
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   106
disc("""The $bottomup$ argument
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   107
switches coordinate systems.  Some graphics systems (like PDF
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   108
and PostScript) place (0,0) at the bottom left of the page
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   109
others (like many graphical user interfaces [GUI's]) place the origen at the top left.  The
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   110
$bottomup$ argument is deprecated and may be dropped in future""")
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   111
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   112
todo("""Need to see if it really works for all tasks, and if not
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   113
     then get rid of it""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   114
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   115
disc("""The $pageCompression$ option determines whether the stream
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   116
of PDF operations for each page is compressed.  By default
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   117
page streams are not compressed, because the compression slows the file generation process.
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   118
If output size is important set $pageCompression=1$, but remember that, compressed documents will
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   119
be smaller, but slower to generate.  Note that images are <i>always</i> compressed, and this option
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   120
will only save space if you have a very large amount of text and vector graphics
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   121
on each page.""")
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   122
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   123
disc("""The $encoding$ argument determines which font encoding
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   124
is used for the standard fonts; this should correspond to
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   125
the encoding on your system.  It has two values at present:
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   126
$pdfdoc.WINANSI_ENCODING$ or $pdfdoc.MACROMAN_ENCODING$.  The
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   127
$pdfdoc.DEFAULT_ENCODING$ above points to the former, which
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   128
is standard on Windows and many Unices (including Linux). If
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   129
you are a Mac user and want to make a global change, modify the
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   130
line at the top of <i>reportlab/pdfbase/pdfdoc.py</i> to switch it
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   131
over.""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   132
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   133
disc("""We plan to add support for encodings on a per-font
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   134
basis in future, so you can explicitly add in new fonts
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   135
and say how the data is to be encoded.  It is your responsibility
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   136
to ensure that your string data is in an encoding matching that
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   137
of the font.  If conversions are needed, the Unicode library
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   138
in Python 1.6 can be of great help.""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   139
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   140
disc("""The demo script $reportlab/demos/stdfonts.py$
347
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   141
will print out two test documents showing all code points
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   142
in all fonts, so you can look up characters.  Special
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   143
characters can be inserted into string commands with
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   144
the usual octal escape sequence; for example \\101 = 'A'.""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   145
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   146
disc("""The $verbosity$ argument determines how much log
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   147
information is printed.  By default, it is zero to assist
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   148
applications which want to capture PDF from standard output.
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   149
With a value of 1, you will get a confirmation message
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   150
each time a document is generated.  Higher numbers may
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   151
give more output in future.""")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   152
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   153
todo("to do - all the info functions and other non-drawing stuff")
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   154
     
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   155
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   156
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   157
35eda3272102 Added canvas init arguments
andy_robinson
parents: 341
diff changeset
   158
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   159
todo("""Cover all constructor arguments, and setAuthor etc.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   160
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   161
heading2("Drawing Operations")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   162
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   163
Suppose the $hello$ function referenced above is implemented as
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   164
follows (we will not explain each of the operations in detail
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   165
yet).
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   166
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   167
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   168
eg(examples.testhello)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   169
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   170
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   171
Examining this code notice that there are essentially two types
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   172
of operations performed using a canvas.  The first type draws something
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   173
on the page such as a text string or a rectangle or a line.  The second
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   174
type changes the state of the canvas such as
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   175
changing the current fill or stroke color or changing the current font
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   176
type and size.  
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   177
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   178
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   179
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   180
If we imagine the program as a painter working on
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   181
the canvas the "draw" operations apply paint to the canvas using
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   182
the current set of tools (colors, line styles, fonts, etcetera)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   183
and the "state change" operations change one of the current tools
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   184
(changing the fill color from whatever it was to blue, or changing
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   185
the current font to $Times-Roman$ in 15 points, for example).
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   186
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   187
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   188
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   189
The document generated by the "hello world" program listed above would contain
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   190
the following graphics.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   191
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   192
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   193
illust(examples.hello, '"Hello World" in pdfgen')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   194
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   195
heading3("About the demos in this document")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   196
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   197
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   198
This document contains demonstrations of the code discussed like the one shown
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   199
in the rectangle above.  These demos are drawn on a "tiny page" embedded
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   200
within the real pages of the guide.  The tiny pages are %s inches wide
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   201
and %s inches tall. The demo displays show the actual output of the demo code.
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   202
For convenience the size of the output has been reduced slightly.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   203
""" % (examplefunctionxinches, examplefunctionyinches))
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   204
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   205
heading2('The tools: the "draw" operations')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   206
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   207
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   208
This section briefly lists the tools available to the program
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   209
for painting information onto a page using the canvas interface.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   210
These will be discussed in detail in later sections.  They are listed
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   211
here for easy reference and for summary purposes.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   212
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   213
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   214
heading3("Line methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   215
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   216
eg("""canvas.line(x1,y1,x2,y2)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   217
eg("""canvas.lines(linelist)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   218
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   219
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   220
The line methods draw straight line segments on the canvas.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   221
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   222
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   223
heading3("Shape methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   224
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   225
eg("""canvas.grid(xlist, ylist) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   226
eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   227
eg("""canvas.arc(x1,y1,x2,y2) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   228
eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   229
eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   230
eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   231
eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   232
eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   233
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   234
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   235
The shape methods draw common complex shapes on the canvas.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   236
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   237
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   238
heading3("String drawing methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   239
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   240
eg("""canvas.drawString(x, y, text):""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   241
eg("""canvas.drawRightString(x, y, text) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   242
eg("""canvas.drawCentredString(x, y, text)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   243
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   244
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   245
The draw string methods draw single lines of text on the canvas.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   246
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   247
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   248
heading3("The text object methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   249
eg("""textobject = canvas.beginText(x, y) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   250
eg("""canvas.drawText(textobject) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   251
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   252
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   253
Text objects are used to format text in ways that
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   254
are not supported directly by the $canvas$ interface.
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   255
A program creates a text object from the $canvas$ using $beginText$
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   256
and then formats text by invoking $textobject$ methods.
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   257
Finally the $textobject$ is drawn onto the canvas using
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   258
$drawText$.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   259
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   260
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   261
heading3("The path object methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   262
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   263
eg("""path = canvas.beginPath() """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   264
eg("""canvas.drawPath(path, stroke=1, fill=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   265
eg("""canvas.clipPath(path, stroke=1, fill=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   266
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   267
disc("""
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   268
Path objects are similar to text objects: they provide dedicated control
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   269
for performing complex graphical drawing not directly provided by the
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   270
canvas interface.  A program creates a path object using $beginPath$
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   271
populates the path with graphics using the methods of the path object
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   272
and then draws the path on the canvas using $drawPath$.""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   273
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   274
disc("""It is also possible
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   275
to use a path as a "clipping region" using the $clipPath$ method -- for example a circular path
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   276
can be used to clip away the outer parts of a rectangular image leaving
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   277
only a circular part of the image visible on the page. 
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   278
""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   279
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   280
heading3("Image methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   281
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   282
eg("""canvas.drawInlineImage(self, image, x,y, width=None,height=None) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   283
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   284
disc("""
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   285
The $drawInlineImage$ method places an image on the canvas.
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   286
""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   287
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   288
pencilnote()
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   289
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   290
disc("""
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   291
You need the Python Imaging Library (PIL) to use images with the ReportLab package.
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   292
""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   293
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   294
heading3("Ending a page")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   295
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   296
eg("""canvas.showPage()""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   297
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   298
disc("""The $showPage$ method finishes the current page.  All additional drawing will
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   299
be done on another page.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   300
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   301
pencilnote()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   302
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   303
disc("""Warning!  All state changes (font changes, color settings, geometry transforms, etcetera)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   304
are FORGOTTEN when you advance to a new page in $pdfgen$.  Any state settings you wish to preserve
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   305
must be set up again before the program proceeds with drawing!""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   306
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   307
heading2('The toolbox: the "state change" operations')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   308
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   309
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   310
This section briefly lists the ways to switch the tools used by the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   311
program
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   312
for painting information onto a page using the $canvas$ interface.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   313
These too will be discussed in detail in later sections.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   314
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   315
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   316
heading3("Changing Colors")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   317
eg("""canvas.setFillColorCMYK(c, m, y, k) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   318
eg("""canvas.setStrikeColorCMYK(c, m, y, k) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   319
eg("""canvas.setFillColorRGB(r, g, b) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   320
eg("""canvas.setStrokeColorRGB(r, g, b) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   321
eg("""canvas.setFillColor(acolor) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   322
eg("""canvas.setStrokeColor(acolor) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   323
eg("""canvas.setFillGray(gray) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   324
eg("""canvas.setStrokeGray(gray) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   325
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   326
disc("""
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   327
PDF supports three different color models: gray level, additive (red/green/blue or RGB), and
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   328
subtractive with darkness parameter (cyan/magenta/yellow/darkness or CMYK).
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   329
The ReportLab packages also provide named colors such as $lawngreen$.  There are two
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   330
basic color parameters in the graphics state: the $Fill$ color for the interior of graphic
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   331
figures and the $Stroke$ color for the boundary of graphic figures.  The above methods
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   332
support setting the fill or stroke color using any of the four color specifications.
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   333
""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   334
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   335
heading3("Changing Fonts")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   336
eg("""canvas.setFont(psfontname, size, leading = None) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   337
374
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   338
disc("""
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   339
The $setFont$ method changes the current text font to a given type and size.
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   340
The $leading$ parameter specifies the distance down to move when advancing from
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   341
one text line to the next.
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   342
""")
1342601fdc4a minor edits, filled in some blanks
aaron_watters
parents: 364
diff changeset
   343
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   344
heading3("Changing Graphical Line Styles")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   345
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   346
eg("""canvas.setLineWidth(width) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   347
eg("""canvas.setLineCap(mode) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   348
eg("""canvas.setLineJoin(mode) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   349
eg("""canvas.setMiterLimit(limit) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   350
eg("""canvas.setDash(self, array=[], phase=0) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   351
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   352
disc("""
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   353
Lines drawn in PDF can be presented in a number of graphical styles.
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   354
Lines can have different widths, they can end in differing cap styles,
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   355
they can meet in different join styles, and they can be continuous or
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   356
they can be dotted or dashed.  The above methods adjust these various parameters.""")
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   357
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   358
heading3("Changing Geometry")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   359
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   360
eg("""canvas.setPageSize(pair) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   361
eg("""canvas.transform(a,b,c,d,e,f): """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   362
eg("""canvas.translate(dx, dy) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   363
eg("""canvas.scale(x, y) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   364
eg("""canvas.rotate(theta) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   365
eg("""canvas.skew(alpha, beta) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   366
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   367
disc("""
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   368
All PDF drawings fit into a specified page size.  Elements drawn outside of the specified
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   369
page size are not visible.  Furthermore all drawn elements are passed through an affine
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   370
transformation which may adjust their location and/or distort their appearence.  The
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   371
$setPageSize$ method adjusts the current page size.  The $transform$, $translate$, $scale$,
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   372
$rotate$, and $skew$ methods add additional transformations to the current transformation.
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   373
It is important to remember that these transformations are <i>incremental</i> -- a new
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   374
transform modifies the current transform (but does not replace it).
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   375
""")
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   376
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   377
heading3("State control")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   378
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   379
eg("""canvas.saveState() """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   380
eg("""canvas.restoreState() """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   381
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   382
disc("""
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   383
Very often it is important to save the current font, graphics transform, line styles and
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   384
other graphics state in order to restore them later. The $saveState$ method marks the
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   385
current graphics state for later restoration by a matching $restoreState$.  Note that
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   386
the save and restore method invokation must match -- a restore call restores the state to
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   387
the most recently saved state which hasn't been restored yet.  
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   388
You cannot save the state on one page and restore
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   389
it on the next, however -- no state is preserved between pages.""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   390
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   391
heading2("Other $canvas$ methods.")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   392
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   393
disc("""
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   394
Not all methods of the $canvas$ object fit into the "tool" or "toolbox"
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   395
categories.  Below are some of the misfits, included here for completeness.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   396
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   397
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   398
eg("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   399
 canvas.setAuthor()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   400
 canvas.addOutlineEntry(title, key, level=0, closed=None)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   401
 canvas.setTitle(title)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   402
 canvas.setSubject(subj)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   403
 canvas.pageHasData()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   404
 canvas.showOutline()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   405
 canvas.bookmarkPage(name)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   406
 canvas.bookmarkHorizontalAbsolute(name, yhorizontal)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   407
 canvas.doForm()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   408
 canvas.beginForm(name, lowerx=0, lowery=0, upperx=None, uppery=None)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   409
 canvas.endForm()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   410
 canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   411
 canvas.getPageNumber()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   412
 canvas.addLiteral()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   413
 canvas.getAvailableFonts()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   414
 canvas.stringWidth(self, text, fontName, fontSize, encoding=None)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   415
 canvas.setPageCompression(onoff=1)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   416
 canvas.setPageTransition(self, effectname=None, duration=1, 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   417
                        direction=0,dimension='H',motion='I')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   418
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   419
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   420
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   421
heading2('Coordinates (default user space)')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   422
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   423
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   424
By default locations on a page are identified by a pair of numbers.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   425
For example the pair $(4.5*inch, 1*inch)$ identifies the location
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   426
found on the page by starting at the lower left corner and moving to
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   427
the right 4.5 inches and up one inch.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   428
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   429
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   430
disc("""For example, the following function draws
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   431
a number of elements on a $canvas$.""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   432
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   433
eg(examples.testcoords)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   434
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   435
disc("""In the default user space the "origin" ^(0,0)^ point is at the lower
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   436
left corner.  Executing the $coords$ function in the default user space
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   437
(for the "demo minipage") we obtain the following.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   438
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   439
illust(examples.coords, 'The Coordinate System')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   440
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   441
heading3("Moving the origin: the $translate$ method")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   442
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   443
disc("""Often it is useful to "move the origin" to a new point off
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   444
the lower left corner.  The $canvas.translate(^x,y^)$ method moves the origin
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   445
for the current page to the point currently identified by ^(x,y)^.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   446
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   447
disc("""For example the following translate function first moves
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   448
the origin before drawing the same objects as shown above.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   449
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   450
eg(examples.testtranslate)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   451
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   452
disc("""This produces the following.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   453
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   454
illust(examples.translate, "Moving the origin: the $translate$ method")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   455
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   456
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   457
#illust(NOP) # execute some code
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   458
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   459
pencilnote()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   460
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   461
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   462
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   463
<i>Note:</i> As illustrated in the example it is perfectly possible to draw objects 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   464
or parts of objects "off the page".
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   465
In particular a common confusing bug is a translation operation that translates the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   466
entire drawing off the visible area of the page.  If a program produces a blank page
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   467
it is possible that all the drawn objects are off the page.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   468
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   469
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   470
heading3("Shrinking and growing: the scale operation")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   471
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   472
disc("""Another important operation is scaling.  The scaling operation $canvas.scale(^dx,dy^)$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   473
stretches or shrinks the ^x^ and ^y^ dimensions by the ^dx^, ^dy^ factors respectively.  Often
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   474
^dx^ and ^dy^ are the same -- for example to reduce a drawing by half in all dimensions use
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   475
$dx = dy = 0.5$.  However for the purposes of illustration we show an example where
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   476
$dx$ and $dy$ are different.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   477
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   478
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   479
eg(examples.testscale)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   480
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   481
disc("""This produces a "short and fat" reduced version of the previously displayed operations.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   482
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   483
illust(examples.scale, "Scaling the coordinate system")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   484
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   485
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   486
#illust(NOP) # execute some code
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   487
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   488
pencilnote()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   489
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   490
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   491
disc("""<i>Note:</i> scaling may also move objects or parts of objects off the page,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   492
or may cause objects to "shrink to nothing." """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   493
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   494
disc("""Scaling and translation can be combined, but the order of the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   495
operations are important.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   496
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   497
eg(examples.testscaletranslate)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   498
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   499
disc("""This example function first saves the current $canvas$ state
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   500
and then does a $scale$ followed by a $translate$.  Afterward the function
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   501
restores the state (effectively removing the effects of the scaling and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   502
translation) and then does the <i>same</i> operations in a different order.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   503
Observe the effect below.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   504
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   505
illust(examples.scaletranslate, "Scaling and Translating")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   506
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   507
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   508
#illust(NOP) # execute some code
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   509
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   510
pencilnote()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   511
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   512
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   513
disc("""<em>Note:</em> scaling shrinks or grows everything including line widths
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   514
so using the canvas.scale method to render a microscopic drawing in 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   515
scaled microscopic units
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   516
may produce a blob (because all line widths will get expanded a huge amount).  
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   517
Also rendering an aircraft wing in meters scaled to centimeters may cause the lines
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   518
to shrink to the point where they disappear.  For engineering or scientific purposes
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   519
such as these scale and translate
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   520
the units externally before rendering them using the canvas.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   521
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   522
heading3("Saving and restoring the $canvas$ state: $saveState$ and $restoreState$")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   523
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   524
disc("""
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   525
The $scaletranslate$ function used an important feature of the $canvas$ object:
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   526
the ability to save and restore the current parameters of the $canvas$.
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   527
By enclosing a sequence of operations in a matching pair of $canvas.saveState()$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   528
an $canvas.restoreState()$ operations all changes of font, color, line style,
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   529
scaling, translation, or other aspects of the $canvas$ graphics state can be
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   530
restored to the state at the point of the $saveState()$.  Remember that the save/restore
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   531
calls must match: a stray save or restore operation may cause unexpected
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   532
and undesirable behavior.  Also, remember that <i>no</i> $canvas$ state is
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   533
preserved across page breaks, and the save/restore mechanism does not work
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   534
across page breaks.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   535
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   536
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   537
heading3("Mirror image")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   538
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   539
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   540
It is interesting although perhaps not terribly useful to note that
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   541
scale factors can be negative.  For example the following function
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   542
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   543
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   544
eg(examples.testmirror)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   545
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   546
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   547
creates a mirror image of the elements drawn by the $coord$ function.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   548
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   549
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   550
illust(examples.mirror, "Mirror Images")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   551
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   552
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   553
Notice that the text strings are painted backwards.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   554
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   555
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   556
heading2("Colors")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   557
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   558
disc("""
406
0444ca32fb1b Bruce Eckel spotted these typos.
rgbecker
parents: 397
diff changeset
   559
There are four ways to specify colors in $pdfgen$: by name (using the $color$
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   560
module, by red/green/blue (additive, $RGB$) value,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   561
by cyan/magenta/yellow/darkness (subtractive, $CMYK$), or by gray level.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   562
The $colors$ function below exercises each of the four methods.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   563
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   564
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   565
eg(examples.testcolors)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   566
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   567
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   568
The $RGB$ or additive color specification follows the way a computer
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   569
screen adds different levels of the red, green, or blue light to make
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   570
any color, where white is formed by turning all three lights on full
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   571
$(1,1,1)$.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   572
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   573
disc("""The $CMYK$ or subtractive method follows the way a printer
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   574
mixes three pigments (cyan, magenta, and yellow) to form colors.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   575
Because mixing chemicals is more difficult than combining light there
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   576
is a fourth parameter for darkness.  For example a chemical
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   577
combination of the $CMY$ pigments generally never makes a perfect
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   578
black -- instead producing a muddy color -- so, to get black printers
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   579
don't use the $CMY$ pigments but use a direct black ink.  Because
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   580
$CMYK$ maps more directly to the way printer hardware works it may
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   581
be the case that colors specified in $CMYK$ will provide better fidelity
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   582
and better control when printed.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   583
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   584
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   585
illust(examples.colors, "Color Models")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   586
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   587
heading2('Painting back to front')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   588
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   589
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   590
Objects may be painted over other objects to good effect in $pdfgen$.  As
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   591
in painting with oils the object painted last will show up on top.  For
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   592
example, the $spumoni$ function below paints up a base of colors and then
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   593
paints a white text over the base.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   594
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   595
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   596
eg(examples.testspumoni)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   597
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   598
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   599
The word "SPUMONI" is painted in white over the colored rectangles,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   600
with the apparent effect of "removing" the color inside the body of
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   601
the word.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   602
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   603
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   604
illust(examples.spumoni, "Painting over colors")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   605
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   606
disc("""
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   607
The last letters of the word are not visible because the default $canvas$
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   608
background is white and painting white letters over a white background
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   609
leaves no visible effect.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   610
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   611
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   612
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   613
This method of building up complex paintings in layers can be done
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   614
in very many layers in $pdfgen$ -- there are fewer physical limitations
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   615
than there are when dealing with physical paints.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   616
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   617
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   618
eg(examples.testspumoni2)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   619
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   620
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   621
The $spumoni2$ function layers an ice cream cone over the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   622
$spumoni$ drawing.  Note that different parts of the cone
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   623
and scoops layer over eachother as well.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   624
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   625
illust(examples.spumoni2, "building up a drawing in layers")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   626
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   627
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   628
heading2('Fonts and text objects')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   629
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   630
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   631
Text may be drawn in many different colors, fonts, and sizes in $pdfgen$.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   632
The $textsize$ function demonstrates how to change the color and font and
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   633
size of text and how to place text on the page.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   634
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   635
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   636
eg(examples.testtextsize)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   637
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   638
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   639
The $textsize$ function generates the following page.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   640
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   641
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   642
illust(examples.textsize, "text in different fonts and sizes")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   643
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   644
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   645
A number of different fonts are always available in $pdfgen$.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   646
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   647
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   648
eg(examples.testfonts)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   649
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   650
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   651
The $fonts$ function lists the fonts that are always available.
397
d2e12adb2496 fixed typos.
dinu_gherman
parents: 374
diff changeset
   652
These don't need to be stored in a PDF document, since they
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   653
are guaranteed to be present in Acrobat Reader.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   654
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   655
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   656
illust(examples.fonts, "the 14 standard fonts")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   657
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   658
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   659
In the near future we will add the ability to embed other fonts
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   660
within a PDF file.  However, this will add a little to file size.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   661
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   662
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   663
heading2("Text object methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   664
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   665
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   666
For the dedicated presentation of text in a PDF document, use a text object.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   667
The text object interface provides detailed control of text layout parameters
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   668
not available directly at the $canvas$ level.  In addition, it results in smaller
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   669
PDF that will render faster than many separate calls to the $drawString$ methods.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   670
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   671
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   672
eg("""textobject.setTextOrigin(x,y)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   673
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   674
eg("""textobject.setTextTransform(a,b,c,d,e,f)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   675
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   676
eg("""textobject.moveCursor(dx, dy) # from start of current LINE""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   677
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   678
eg("""(x,y) = textobject.getCursor()""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   679
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   680
eg("""x = textobject.getX(); y = textobject.getY()""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   681
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   682
eg("""textobject.setFont(psfontname, size, leading = None)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   683
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   684
eg("""textobject.textOut(text)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   685
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   686
eg("""textobject.textLine(text='')""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   687
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   688
eg("""textobject.textLines(stuff, trim=1)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   689
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   690
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   691
The text object methods shown above relate to basic text geometry.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   692
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   693
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   694
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   695
A text object maintains a text cursor which moves about the page when 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   696
text is drawn.  For example the $setTextOrigin$ places the cursor
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   697
in a known position and the $textLine$ and $textLines$ methods move
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   698
the text cursor down past the lines that have been missing.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   699
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   700
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   701
eg(examples.testcursormoves1)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   702
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   703
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   704
The $cursormoves$ function relies on the automatic
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   705
movement of the text cursor for placing text after the origin
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   706
has been set.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   707
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   708
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   709
illust(examples.cursormoves1, "How the text cursor moves")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   710
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   711
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   712
It is also possible to control the movement of the cursor
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   713
more explicitly by using the $moveCursor$ method (which moves
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   714
the cursor as an offset from the start of the current <i>line</i>
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   715
NOT the current cursor, and which also has positive ^y^ offsets
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   716
move <i>down</i> (in contrast to the normal geometry where
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   717
positive ^y^ usually moves up.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   718
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   719
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   720
eg(examples.testcursormoves2)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   721
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   722
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   723
Here the $textOut$ does not move the down a line in contrast
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   724
to the $textLine$ function which does move down.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   725
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   726
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   727
illust(examples.cursormoves2, "How the text cursor moves again")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   728
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   729
heading3("Character Spacing")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   730
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   731
eg("""textobject.setCharSpace(charSpace)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   732
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   733
disc("""The $setCharSpace$ method adjusts one of the parameters of text -- the inter-character
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   734
spacing.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   735
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   736
eg(examples.testcharspace)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   737
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   738
disc("""The 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   739
$charspace$ function exercises various spacing settings.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   740
It produces the following page.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   741
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   742
illust(examples.charspace, "Adjusting inter-character spacing")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   743
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   744
heading3("Word Spacing")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   745
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   746
eg("""textobject.setWordSpace(wordSpace)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   747
406
0444ca32fb1b Bruce Eckel spotted these typos.
rgbecker
parents: 397
diff changeset
   748
disc("The $setWordSpace$ method adjusts the space between words.")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   749
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   750
eg(examples.testwordspace)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   751
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   752
disc("""The $wordspace$ function shows what various word space settings
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   753
look like below.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   754
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   755
illust(examples.wordspace, "Adjusting word spacing")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   756
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   757
heading3("Horizontal Scaling")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   758
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   759
eg("""textobject.setHorizScale(horizScale)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   760
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   761
disc("""Lines of text can be stretched or shrunken horizontally by the 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   762
$setHorizScale$ method.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   763
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   764
eg(examples.testhorizontalscale)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   765
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   766
disc("""The horizontal scaling parameter ^horizScale^
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   767
is given in percentages (with 100 as the default), so the 80 setting
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   768
shown below looks skinny.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   769
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   770
illust(examples.horizontalscale, "adjusting horizontal text scaling")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   771
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   772
heading3("Interline spacing (Leading)")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   773
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   774
eg("""textobject.setLeading(leading)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   775
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   776
disc("""The vertical offset between the point at which one
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   777
line starts and where the next starts is called the leading
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   778
offset.  The $setLeading$ method adjusts the leading offset.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   779
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   780
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   781
eg(examples.testleading)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   782
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   783
disc("""As shown below if the leading offset is set too small
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   784
characters of one line my write over the bottom parts of characters
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   785
in the previous line.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   786
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   787
illust(examples.leading, "adjusting the leading")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   788
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   789
heading3("Other text object methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   790
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   791
eg("""textobject.setTextRenderMode(mode)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   792
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   793
disc("""The $setTextRenderMode$ method allows text to be used
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   794
as a forground for clipping background drawings, for example.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   795
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   796
eg("""textobject.setRise(rise)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   797
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   798
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   799
The $setRise$ method <super>raises</super> or <sub>lowers</sub> text on the line
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   800
(for creating superscripts or subscripts, for example).
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   801
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   802
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   803
eg("""textobject.setFillColor(aColor); 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   804
textobject.setStrokeColor(self, aColor) 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   805
# and similar""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   806
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   807
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   808
These color change operations change the <font color=darkviolet>color</font> of the text and are otherwise
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   809
similar to the color methods for the $canvas$ object.""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   810
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   811
heading2('Paths and Lines')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   812
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   813
disc("""Just as textobjects are designed for the dedicated presentation
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   814
of text, path objects are designed for the dedicated construction of
397
d2e12adb2496 fixed typos.
dinu_gherman
parents: 374
diff changeset
   815
graphical figures.  When path objects are drawn onto a $canvas$ they
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   816
are drawn as one figure (like a rectangle) and the mode of drawing
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   817
for the entire figure can be adjusted: the lines of the figure can
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   818
be drawn (stroked) or not; the interior of the figure can be filled or
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   819
not; and so forth.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   820
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   821
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   822
For example the $star$ function uses a path object
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   823
to draw a star
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   824
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   825
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   826
eg(examples.teststar)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   827
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   828
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   829
The $star$ function has been designed to be useful in illustrating
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   830
various line style parameters supported by $pdfgen$.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   831
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   832
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   833
illust(examples.star, "line style parameters")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   834
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   835
heading3("Line join settings")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   836
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   837
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   838
The $setLineJoin$ method can adjust whether line segments meet in a point
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   839
a square or a rounded vertex.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   840
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   841
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   842
eg(examples.testjoins)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   843
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   844
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   845
The line join setting is only really of interest for thick lines because
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   846
it cannot be seen clearly for thin lines.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   847
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   848
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   849
illust(examples.joins, "different line join styles")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   850
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   851
heading3("Line cap settings")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   852
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   853
disc("""The line cap setting, adjusted using the $setLineCap$ method,
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   854
determines whether a terminating line
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   855
ends in a square exactly at the vertex, a square over the vertex
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   856
or a half circle over the vertex.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   857
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   858
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   859
eg(examples.testcaps)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   860
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   861
disc("""The line cap setting, like the line join setting, is only clearly
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   862
visible when the lines are thick.""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   863
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   864
illust(examples.caps, "line cap settings")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   865
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   866
heading3("Dashes and broken lines")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   867
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   868
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   869
The $setDash$ method allows lines to be broken into dots or dashes.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   870
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   871
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   872
eg(examples.testdashes)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   873
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   874
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   875
The patterns for the dashes or dots can be in a simple on/off repeating pattern
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   876
or they can be specified in a complex repeating pattern.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   877
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   878
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   879
illust(examples.dashes, "some dash patterns")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   880
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   881
heading3("Creating complex figures with path objects")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   882
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   883
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   884
Combinations of lines, curves, arcs and other figures
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   885
can be combined into a single figure using path objects.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   886
For example the function shown below constructs two path
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   887
objects using lines and curves.  
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   888
This function will be used later on as part of a
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   889
pencil icon construction.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   890
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   891
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   892
eg(examples.testpenciltip)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   893
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   894
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   895
Note that the interior of the pencil tip is filled
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   896
as one object even though it is constructed from
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   897
several lines and curves.  The pencil lead is then
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   898
drawn over it using a new path object.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   899
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   900
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   901
illust(examples.penciltip, "a pencil tip")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   902
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   903
heading2('Rectangles, circles, ellipses')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   904
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   905
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   906
The $pdfgen$ module supports a number of generally useful shapes
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   907
such as rectangles, rounded rectangles, ellipses, and circles.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   908
Each of these figures can be used in path objects or can be drawn
352
088c93328100 random modificatoins and expansions
aaron_watters
parents: 347
diff changeset
   909
directly on a $canvas$.  For example the $pencil$ function below
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   910
draws a pencil icon using rectangles and rounded rectangles with
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   911
various fill colors and a few other annotations.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   912
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   913
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   914
eg(examples.testpencil)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   915
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   916
pencilnote()
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   917
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   918
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   919
Note that this function is used to create the "margin pencil" to the left.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   920
Also note that the order in which the elements are drawn are important
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   921
because, for example, the white rectangles "erase" parts of a black rectangle
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   922
and the "tip" paints over part of the yellow rectangle.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   923
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   924
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   925
illust(examples.pencil, "a whole pencil")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   926
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   927
heading2('Bezier curves')
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   928
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   929
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   930
Programs that wish to construct figures with curving borders
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   931
generally use Bezier curves to form the borders.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   932
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   933
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   934
eg(examples.testbezier)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   935
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   936
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   937
A Bezier curve is specified by four control points 
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   938
$(x1,y1)$, $(x2,y2)$, $(x3,y3)$, $(x4,y4)$.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   939
The curve starts at $(x1,y1)$ and ends at $(x4,y4)$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   940
and the line segment from $(x1,y1)$ to $(x2,y2)$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   941
and the line segment from $(x3,y3)$ to $(x4,y4)$
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   942
both form tangents to the curve.  Furthermore the
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   943
curve is entirely contained in the convex figure with vertices
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   944
at the control points.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   945
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   946
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   947
illust(examples.bezier, "basic bezier curves")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   948
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   949
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   950
The drawing above (the output of $testbezier$) shows
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   951
a bezier curves, the tangent lines defined by the control points
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   952
and the convex figure with vertices at the control points.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   953
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   954
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   955
heading3("Smoothly joining bezier curve sequences")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   956
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   957
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   958
It is often useful to join several bezier curves to form a
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   959
single smooth curve.  To construct a larger smooth curve from
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   960
several bezier curves make sure that the tangent lines to adjacent
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   961
bezier curves that join at a control point lie on the same line.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   962
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   963
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   964
eg(examples.testbezier2)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   965
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   966
disc("""
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   967
The figure created by $testbezier2$ describes a smooth
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   968
complex curve because adjacent tangent lines "line up" as
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   969
illustrated below.
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   970
""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   971
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   972
illust(examples.bezier2, "bezier curves")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   973
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   974
heading2("Path object methods")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   975
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   976
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   977
Path objects build complex graphical figures by setting
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   978
the "pen" or "brush" at a start point on the canvas and drawing
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   979
lines or curves to additional points on the canvas.  Most operations
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   980
apply paint on the canvas starting at the end point of the last
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   981
operation and leave the brush at a new end point.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   982
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   983
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   984
eg("""pathobject.moveTo(x,y)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   985
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   986
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   987
The $moveTo$ method lifts the brush (ending any current sequence
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   988
of lines or curves if there is one) and replaces the brush at the
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   989
new ^(x,y)^ location on the canvas to start a new path sequence.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   990
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   991
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   992
eg("""pathobject.lineTo(x,y)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   993
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   994
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   995
The $lineTo$ method paints straight line segment from the current brush
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   996
location to the new ^(x,y)^ location.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   997
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
   998
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
   999
eg("""pathobject.curveTo(x1, y1, x2, y2, x3, y3) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1000
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1001
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1002
The $curveTo$ method starts painting a Bezier curve beginning at
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1003
the current brush location, using ^(x1,y1)^, ^(x2,y2)^, and ^(x3,y3)^
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1004
as the other three control points, leaving the brush on ^(x3,y3)^.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1005
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1006
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1007
eg("""pathobject.arc(x1,y1, x2,y2, startAng=0, extent=90) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1008
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1009
eg("""pathobject.arcTo(x1,y1, x2,y2, startAng=0, extent=90) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1010
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1011
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1012
The $arc$ and $arcTo$ methods paint partial ellipses.  The $arc$ method first "lifts the brush"
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1013
and starts a new shape sequence.  The $arcTo$ method joins the start of 
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1014
the partial ellipse to the current
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1015
shape sequence by line segment before drawing the partial ellipse.  The points
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1016
^(x1,y1)^ and ^(x2,y2)^ define opposite corner points of a rectangle enclosing
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1017
the ellipse.  The $startAng$ is an angle (in degrees) specifying where to begin
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1018
the partial ellipse where the 0 angle is the midpoint of the right border of the enclosing
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1019
rectangle (when ^(x1,y1)^ is the lower left corner and ^(x2,y2)^ is the upper
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1020
right corner).  The $extent$ is the angle in degrees to traverse on the ellipse.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1021
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1022
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1023
eg(examples.testarcs)
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1024
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1025
disc("""The $arcs$ function above exercises the two partial ellipse methods.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1026
It produces the following drawing.""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1027
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1028
illust(examples.arcs, "arcs in path objects")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1029
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1030
eg("""pathobject.rect(x, y, width, height) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1031
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1032
disc("""The $rect$ method draws a rectangle with lower left corner
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1033
at ^(x,y)^ of the specified ^width^ and ^height^.""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1034
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1035
eg("""pathobject.ellipse(x, y, width, height)""")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1036
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1037
disc("""The $ellipse$ method
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1038
draws an ellipse enclosed in the rectange with lower left corner
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1039
at ^(x,y)^ of the specified ^width^ and ^height^.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1040
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1041
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1042
eg("""pathobject.circle(x_cen, y_cen, r) """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1043
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1044
disc("""The $circle$ method
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1045
draws a circle centered at ^(x_cen, y_cen)^ with radius ^r^.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1046
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1047
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1048
eg(examples.testvariousshapes)
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1049
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1050
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1051
The $variousshapes$ function above shows a rectangle, circle and ellipse
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1052
placed in a frame of reference grid.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1053
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1054
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1055
illust(examples.variousshapes, "rectangles, circles, ellipses in path objects")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1056
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1057
eg("""pathobject.close() """)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1058
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1059
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1060
The $close$ method closes the current graphical figure
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1061
by painting a line segment from the last point of the figure
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1062
to the starting point of the figure (the the most
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1063
recent point where the brush was placed on the paper by $moveTo$
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1064
or $arc$ or other placement operations).
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1065
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1066
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1067
eg(examples.testclosingfigures)
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1068
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1069
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1070
The $closingfigures$ function illustrates the
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1071
effect of closing or not closing figures including a line
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1072
segment and a partial ellipse.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1073
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1074
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1075
illust(examples.closingfigures, "closing and not closing pathobject figures")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1076
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1077
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1078
Closing or not closing graphical figures effects only the stroked outline
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1079
of a figure, not the filling of the figure as illustrated above.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1080
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1081
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1082
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1083
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1084
For a more extensive example of drawing using a path object
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1085
examine the $hand$ function.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1086
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1087
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1088
eg(examples.testhand)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1089
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1090
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1091
In debug mode (the default) the $hand$ function shows the tangent line segments
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1092
to the bezier curves used to compose the figure.  Note that where the segments
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1093
line up the curves join smoothly, but where they do not line up the curves show
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1094
a "sharp edge".
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1095
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1096
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1097
illust(examples.hand, "an outline of a hand using bezier curves")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1098
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1099
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1100
Used in non-debug mode the $hand$ function only shows the
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1101
Bezier curves.  With the $fill$ parameter set the figure is
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1102
filled using the current fill color.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1103
""")
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1104
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1105
eg(examples.testhand2)
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1106
364
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1107
disc("""
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1108
Note that the "stroking" of the border draws over the interior fill where
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1109
they overlap.
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1110
""")
21f5c8641230 more text, more pdfgen examples
aaron_watters
parents: 352
diff changeset
  1111
341
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1112
illust(examples.hand2, "the finished hand, filled")
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1113
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1114
27c68d524504 Broke up the user guide into chapters.
andy_robinson
parents:
diff changeset
  1115
##### FILL THEM IN