#!/bin/env python

###############################################################################

#

#

#   Except for the change of names the spirit and intention of this

#   license is the same as that of Python

#

#

#

# All Rights Reserved

#

# Permission to use, copy, modify, and distribute this software and its

# documentation for any purpose and without fee is hereby granted, provided

# that the above copyright notice appear in all copies and that both that

# copyright notice and this permission notice appear in supporting

# documentation, and that the name of ReportLab not be used

# in advertising or publicity pertaining to distribution of the software

# without specific, written prior permission. 

# 

#

# Disclaimer

#

# ReportLab Inc. DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS

# SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS,

# IN NO EVENT SHALL ReportLab BE LIABLE FOR ANY SPECIAL, INDIRECT

# OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS

# OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR

# OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR

# PERFORMANCE OF THIS SOFTWARE. 

#

###############################################################################

#

__doc__ = """

This module contains the script for building the user guide.

"""

if _oldStyle:

else:

from reportlab.platypus.doctemplate import SimpleDocTemplate

from reportlab.platypus.flowables import Flowable

from reportlab.lib.units import inch

from reportlab.lib.pagesizes import letter

from reportlab.platypus import Paragraph, Spacer, Preformatted, PageBreak, CondPageBreak

from reportlab.lib.styles import ParagraphStyle

from reportlab.lib import colors

import examples

from reportlab.lib.corp import ReportLabLogo

LOGO = ReportLabLogo(0.25*inch, 0.25*inch, inch, 0.75*inch)

from t_parse import Template

QFcodetemplate = Template("X$X$", "X")

QFreptemplate = Template("X^X^", "X")

if _oldStyle:

else:

def quickfix(text):

    """inside text find any subsequence of form $subsequence$.

       Format the subsequence as code.  If similarly if text contains ^arg^

       format the arg as replaceable.  The escape sequence for literal

       $ is $\\$ (^ is ^\\^.

    """

    from string import join

    for (template,subst) in [(QFcodetemplate, codesubst), (QFreptemplate, QFsubst)]:

        fragment = text

        parts = []

        try:

            while fragment:

                try:

                    (matches, index) = template.PARSE(fragment)

                except: raise ValueError

                else:

                    [prefix, code] = matches

                    if code == "\\":

                        part = fragment[:index]

                    else:

                        part = subst % (prefix, code)

                    parts.append(part)

                    fragment = fragment[index:]

        except ValueError:

            parts.append(fragment)

        text = join(parts, "")

    return text

#print quickfix("$testing$ testing $one$ ^two^ $three(^four^)$")

if _oldStyle:

class Guide:

    def __init__(self):

        if _oldStyle:

            self.myannotations = PageAnnotations()

        self.story = story()

    def go(self, filename="userguide.pdf"):

        # generate the doc...

        doc = RLDocTemplate(filename,pagesize = letter)

        story = self.story

        if _oldStyle:

            doc.build(story, self.myannotations.onFirstPage, self.myannotations.onNextPage)

        else:

            doc.build(story)

H1 = styleSheet['Heading1']

H2 = styleSheet['Heading2']

B = styleSheet['BodyText']

if _oldStyle:

else:

exampletextstyle = styleSheet['Code']

# size for every example

examplefunctionxinches = 5.5

examplefunctionyinches = 3

examplefunctiondisplaysizes = (examplefunctionxinches*inch, examplefunctionyinches*inch)

# for testing

def NOP(*x,**y):

    return None

BODY = []

def story():

    return BODY

def disc(text, klass=Paragraph, style=discussiontextstyle):

    text = quickfix(text)

    P = klass(text, style)

    BODY.append(P)

def eg(text):

    BODY.append(Spacer(0.1*inch, 0.1*inch))

    disc(text, klass=Preformatted, style=exampletextstyle)

#eg("""

#this

#  is 

#    an 

#     example""")

def title(text):

    BODY.append(PageBreak())

def canvasdemo(function):

    BODY.append(Spacer(0.1*inch, 0.1*inch))

    BODY.append(OperationWrapper(function))

class OperationWrapper(Flowable):

    """wrap a drawing operation as a flowable.

       the operation should respect the examplefunctiondisplaysizes

       limitations.

       This example wraps a drawing operator f(pdfgen.canvas).

       Always enclosed in a rectangle.

    """

    def __init__(self, operation):

        self.operation = operation

    def wrap(self, aw, ah):

        return examplefunctiondisplaysizes # always the same

    def draw(self):

        canvas = self.canv

        canvas.saveState()

        (x,y) = examplefunctiondisplaysizes

        self.operation(canvas)

        canvas.restoreState()

        canvas.rect(0,0,x,y)

def pencilnote():

    BODY.append(examples.NoteAnnotation())

###### testing...

#canvasdemo(NOP)

#disc("this explains the example")

#eg("""

#this

#  is the

#    example

#      code""")

#disc("the execution of the example follows")

#canvasdemo(NOP) # execute some code

#pencilnote()

title("ReportLab User Guide")

disc("""

This document is intended to be a conversational introduction

to the use of the ReportLab packages.  Some previous programming experience

is presumed and familiarity with the Python Programming language is

recommended.

""")

#canvasdemo(NOP) # execute some code

pencilnote()

disc("""

This document is in a <em>very</em> preliminary form.

""")

disc("""

The $pdfgen$ package is the lowest level interface for

generating PDF documents.  A $pdfgen$ program is essentially

a sequence of instructions for "painting" a document onto

a sequence of pages.  The interface object which provides the

painting operations is the $pdfgen$ canvas.  

""")

disc("""

The canvas should be thought of as a sheet of white paper

with points on the sheet identified using Cartesian ^(X,Y)^ coordinates

which by default have the ^(0,0)^ origin point at the lower

left corner of the page.  Furthermore the first coordinate ^x^

goes to the right and the second coordinate ^y^ goes up, by

default.""")

disc("""

A simple example

program that uses a canvas follows.

""")

eg("""

    from reportlab.pdfgen import canvas

    c = canvas.Canvas("hello.pdf")

    hello(c)

    c.showPage()

    c.save()

""")

disc("""

The above code creates a $canvas$ object which will generate

a PDF file named $hello.pdf$ in the current working directory.

It then calls the $hello$ function passing the $canvas$ as an argument.

Finally the $showPage$ method saves the current page of the canvas

and the $save$ method stores the file and closes the canvas.""")

disc("""

The $showPage$ method causes the $canvas$ to stop drawing on the

current page and any further operations will draw on a subsequent

page (if there are any further operations -- if not no

new page is created).  The $save$ method must be called after the

construction of the document is complete -- it generates the PDF

document, which is the whole purpose of the $canvas$ object.

""")

disc("""

Suppose the $hello$ function referenced above is implemented as

follows (we will not explain each of the operations in detail

yet).

""")

eg(examples.testhello)

disc("""

Examining this code notice that there are essentially two types

of operations performed using a canvas.  The first type draws something

on the page such as a text string or a rectangle or a line.  The second

type changes the state of the canvas such as

changing the current fill or stroke color or changing the current font

type and size.  

""")

disc("""

If we imagine the program as a painter working on

the canvas the "draw" operations apply paint to the canvas using

the current set of tools (colors, line styles, fonts, etcetera)

and the "state change" operations change one of the current tools

(changing the fill color from whatever it was to blue, or changing

the current font to $Times-Roman$ in 15 points, for example).

""")

disc("""

The document generated by the "hello world" program listed above would contain

the following graphics.

""")

canvasdemo(examples.hello)

disc("""

This document contains demonstrations of the code discussed like the one shown

in the rectangle above.  These demos are drawn on a "tiny page" embedded

within the real pages of the guide.  The tiny pages are %s inches wide

and %s inches tall.  The demo displays show the actual output of the demo

code.

""" % (examplefunctionxinches, examplefunctionyinches))

disc("""

This section briefly lists the tools available to the program

for painting information onto a page using the canvas interface.

These will be discussed in detail in later sections.  They are listed

here for easy reference and for summary purposes.

""")

eg("""canvas.line(x1,y1,x2,y2)""")

eg("""canvas.lines(linelist)""")

disc("""

The line methods draw straight line segments on the canvas.

""")

eg("""canvas.grid(xlist, ylist) """)

eg("""canvas.bezier(x1, y1, x2, y2, x3, y3, x4, y4)""")

eg("""canvas.arc(x1,y1,x2,y2) """)

eg("""canvas.rect(x, y, width, height, stroke=1, fill=0) """)

eg("""canvas.ellipse(x, y, width, height, stroke=1, fill=0)""")

eg("""canvas.wedge(x1,y1, x2,y2, startAng, extent, stroke=1, fill=0) """)

eg("""canvas.circle(x_cen, y_cen, r, stroke=1, fill=0)""")

eg("""canvas.roundRect(x, y, width, height, radius, stroke=1, fill=0) """)

disc("""

The shape methods draw common complex shapes on the canvas.

""")

eg("""canvas.drawString(x, y, text):""")

eg("""canvas.drawRightString(x, y, text) """)

eg("""canvas.drawCentredString(x, y, text)""")

disc("""

The draw string methods draw single lines of text on the canvas.

""")

eg("""textobject = canvas.beginText(x, y) """)

eg("""canvas.drawText(textobject) """)

disc("""

Text objects are used to format text in ways that

are not supported directly by the canvas interface.

A program creates a text object from the canvas using beginText

and then formats text by invoking textobject methods.

Finally the textobject is drawn onto the canvas using

drawText.