--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/colors/colortest.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,105 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/colors/colortest.py
+import reportlab.pdfgen.canvas
+from reportlab.lib import colors
+from reportlab.lib.units import inch
+
+
+def run():
+ c = reportlab.pdfgen.canvas.Canvas('colortest.pdf')
+
+ #do a test of CMYK interspersed with RGB
+
+ #first do RGB values
+ framePage(c, 'Color Demo - RGB Space and CMYK spaces interspersed' )
+
+ y = 700
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'cyan')
+ c.setFillColorCMYK(1,0,0,0)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'red')
+ c.setFillColorRGB(1,0,0)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'magenta')
+ c.setFillColorCMYK(0,1,0,0)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'green')
+ c.setFillColorRGB(0,1,0)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'yellow')
+ c.setFillColorCMYK(0,0,1,0)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'blue')
+ c.setFillColorRGB(0,0,1)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+ c.setFillColorRGB(0,0,0)
+ c.drawString(100, y, 'black')
+ c.setFillColorCMYK(0,0,0,1)
+ c.rect(200, y, 300, 30, fill=1)
+ y = y - 40
+
+
+ c.showPage()
+
+ #do all named colors
+ framePage(c, 'Color Demo - RGB Space - page %d' % c.getPageNumber())
+
+ all_colors = reportlab.lib.colors.getAllNamedColors().items()
+ all_colors.sort() # alpha order by name
+ c.setFont('Times-Roman', 12)
+ c.drawString(72,730, 'This shows all the named colors in the HTML standard.')
+ y = 700
+ for (name, color) in all_colors:
+ c.setFillColor(colors.black)
+ c.drawString(100, y, name)
+ c.setFillColor(color)
+ c.rect(200, y-10, 300, 30, fill=1)
+ y = y - 40
+ if y < 100:
+ c.showPage()
+ framePage(c, 'Color Demo - RGB Space - page %d' % c.getPageNumber())
+ y = 700
+
+
+
+
+ c.save()
+
+def framePage(canvas, title):
+ canvas.setFont('Times-BoldItalic',20)
+ canvas.drawString(inch, 10.5 * inch, title)
+
+ canvas.setFont('Times-Roman',10)
+ canvas.drawCentredString(4.135 * inch, 0.75 * inch,
+ 'Page %d' % canvas.getPageNumber())
+
+ #draw a border
+ canvas.setStrokeColorRGB(1,0,0)
+ canvas.setLineWidth(5)
+ canvas.line(0.8 * inch, inch, 0.8 * inch, 10.75 * inch)
+ #reset carefully afterwards
+ canvas.setLineWidth(1)
+ canvas.setStrokeColorRGB(0,0,0)
+
+if __name__ == '__main__':
+ run()
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/gadflypaper/00readme.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,3 @@
+This is Aaron Watters' first script;
+it renders his paper for IPC8 into
+PDF. A fascinating read, as well.
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/gadflypaper/gfe.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,903 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/gadflypaper/gfe.py
+__version__=''' $Id$ '''
+__doc__=''
+
+#REPORTLAB_TEST_SCRIPT
+import sys
+from reportlab.platypus import *
+from reportlab.lib.styles import getSampleStyleSheet
+from reportlab.rl_config import defaultPageSize
+PAGE_HEIGHT=defaultPageSize[1]
+
+styles = getSampleStyleSheet()
+
+Title = "Integrating Diverse Data Sources with Gadfly 2"
+
+Author = "Aaron Watters"
+
+URL = "http://www.chordate.com/"
+
+email = "arw@ifu.net"
+
+Abstract = """This paper describes the primative methods underlying the implementation
+of SQL query evaluation in Gadfly 2, a database management system implemented
+in Python [Van Rossum]. The major design goals behind
+the architecture described here are to simplify the implementation
+and to permit flexible and efficient extensions to the gadfly
+engine. Using this architecture and its interfaces programmers
+can add functionality to the engine such as alternative disk based
+indexed table implementations, dynamic interfaces to remote data
+bases or or other data sources, and user defined computations."""
+
+from reportlab.lib.units import inch
+
+pageinfo = "%s / %s / %s" % (Author, email, Title)
+
+def myFirstPage(canvas, doc):
+ canvas.saveState()
+ #canvas.setStrokeColorRGB(1,0,0)
+ #canvas.setLineWidth(5)
+ #canvas.line(66,72,66,PAGE_HEIGHT-72)
+ canvas.setFont('Times-Bold',16)
+ canvas.drawString(108, PAGE_HEIGHT-108, Title)
+ canvas.setFont('Times-Roman',9)
+ canvas.drawString(inch, 0.75 * inch, "First Page / %s" % pageinfo)
+ canvas.restoreState()
+
+def myLaterPages(canvas, doc):
+ #canvas.drawImage("snkanim.gif", 36, 36)
+ canvas.saveState()
+ #canvas.setStrokeColorRGB(1,0,0)
+ #canvas.setLineWidth(5)
+ #canvas.line(66,72,66,PAGE_HEIGHT-72)
+ canvas.setFont('Times-Roman',9)
+ canvas.drawString(inch, 0.75 * inch, "Page %d %s" % (doc.page, pageinfo))
+ canvas.restoreState()
+
+def go():
+ Elements.insert(0,Spacer(0,inch))
+ doc = SimpleDocTemplate('gfe.pdf')
+ doc.build(Elements,onFirstPage=myFirstPage, onLaterPages=myLaterPages)
+
+Elements = []
+
+HeaderStyle = styles["Heading1"] # XXXX
+
+def header(txt, style=HeaderStyle, klass=Paragraph, sep=0.3):
+ s = Spacer(0.2*inch, sep*inch)
+ Elements.append(s)
+ para = klass(txt, style)
+ Elements.append(para)
+
+ParaStyle = styles["Normal"]
+
+def p(txt):
+ return header(txt, style=ParaStyle, sep=0.1)
+
+#pre = p # XXX
+
+PreStyle = styles["Code"]
+
+def pre(txt):
+ s = Spacer(0.1*inch, 0.1*inch)
+ Elements.append(s)
+ p = Preformatted(txt, PreStyle)
+ Elements.append(p)
+
+#header(Title, sep=0.1. style=ParaStyle)
+header(Author, sep=0.1, style=ParaStyle)
+header(URL, sep=0.1, style=ParaStyle)
+header(email, sep=0.1, style=ParaStyle)
+header("ABSTRACT")
+p(Abstract)
+
+header("Backgrounder")
+
+p("""\
+The term "database" usually refers to a persistent
+collection of data. Data is persistent if it continues
+to exist whether or not it is associated with a running
+process on the computer, or even if the computer is
+shut down and restarted at some future time. Database
+management systems provide support for constructing databases,
+maintaining databases, and extracting information from databases.""")
+p("""\
+Relational databases manipulate and store persistent
+table structures called relations, such as the following
+three tables""")
+
+pre("""\
+ -- drinkers who frequent bars (this is a comment)
+ select * from frequents
+
+ DRINKER | PERWEEK | BAR
+ ============================
+ adam | 1 | lolas
+ woody | 5 | cheers
+ sam | 5 | cheers
+ norm | 3 | cheers
+ wilt | 2 | joes
+ norm | 1 | joes
+ lola | 6 | lolas
+ norm | 2 | lolas
+ woody | 1 | lolas
+ pierre | 0 | frankies
+)
+""")
+pre("""\
+ -- drinkers who like beers
+ select * from likes
+
+ DRINKER | PERDAY | BEER
+ ===============================
+ adam | 2 | bud
+ wilt | 1 | rollingrock
+ sam | 2 | bud
+ norm | 3 | rollingrock
+ norm | 2 | bud
+ nan | 1 | sierranevada
+ woody | 2 | pabst
+ lola | 5 | mickies
+
+""")
+pre("""\
+ -- beers served from bars
+ select * from serves
+
+ BAR | QUANTITY | BEER
+ =================================
+ cheers | 500 | bud
+ cheers | 255 | samadams
+ joes | 217 | bud
+ joes | 13 | samadams
+ joes | 2222 | mickies
+ lolas | 1515 | mickies
+ lolas | 333 | pabst
+ winkos | 432 | rollingrock
+ frankies | 5 | snafu
+""")
+p("""
+The relational model for database structures makes
+the simplifying assumption that all data in a database
+can be represented in simple table structures
+such as these. Although this assumption seems extreme
+it provides a good foundation for defining solid and
+well defined database management systems and some
+of the most successful software companies in the
+world, such as Oracle, Sybase, IBM, and Microsoft,
+have marketed database management systems based on
+the relational model quite successfully.
+""")
+p("""
+SQL stands for Structured Query Language.
+The SQL language defines industry standard
+mechanisms for creating, querying, and modified
+relational tables. Several years ago SQL was one
+of many Relational Database Management System
+(RDBMS) query languages in use, and many would
+argue not the best on. Now, largely due
+to standardization efforts and the
+backing of IBM, SQL is THE standard way to talk
+to database systems.
+""")
+p("""
+There are many advantages SQL offers over other
+database query languages and alternative paradigms
+at this time (please see [O'Neill] or [Korth and Silberschatz]
+for more extensive discussions and comparisons between the
+SQL/relational approach and others.)
+""")
+p("""
+The chief advantage over all contenders at this time
+is that SQL and the relational model are now widely
+used as interfaces and back end data stores to many
+different products with different performance characteristics,
+user interfaces, and other qualities: Oracle, Sybase,
+Ingres, SQL Server, Access, Outlook,
+Excel, IBM DB2, Paradox, MySQL, MSQL, POSTgres, and many
+others. For this reason a program designed to use
+an SQL database as its data storage mechanism can
+easily be ported from one SQL data manager to another,
+possibly on different platforms. In fact the same
+program can seamlessly use several backends and/or
+import/export data between different data base platforms
+with trivial ease.
+No other paradigm offers such flexibility at the moment.
+""")
+p("""
+Another advantage which is not as immediately
+obvious is that the relational model and the SQL
+query language are easily understood by semi-technical
+and non-technical professionals, such as business
+people and accountants. Human resources managers
+who would be terrified by an object model diagram
+or a snippet of code that resembles a conventional
+programming language will frequently feel quite at
+ease with a relational model which resembles the
+sort of tabular data they deal with on paper in
+reports and forms on a daily basis. With a little training the
+same HR managers may be able to translate the request
+"Who are the drinkers who like bud and frequent cheers?"
+into the SQL query
+""")
+pre("""
+ select drinker
+ from frequents
+ where bar='cheers'
+ and drinker in (
+ select drinker
+ from likes
+ where beer='bud')
+""")
+p("""
+(or at least they have some hope of understanding
+the query once it is written by a technical person
+or generated by a GUI interface tool). Thus the use
+of SQL and the relational model enables communication
+between different communities which must understand
+and interact with stored information. In contrast
+many other approaches cannot be understood easily
+by people without extensive programming experience.
+""")
+p("""
+Furthermore the declarative nature of SQL
+lends itself to automatic query optimization,
+and engines such as Gadfly can automatically translate a user query
+into an optimized query plan which takes
+advantage of available indices and other data characteristics.
+In contrast more navigational techniques require the application
+program itself to optimize the accesses to the database and
+explicitly make use of indices.
+""")
+
+# HACK
+Elements.append(PageBreak())
+
+p("""
+While it must be admitted that there are application
+domains such as computer aided engineering design where
+the relational model is unnatural, it is also important
+to recognize that for many application domains (such
+as scheduling, accounting, inventory, finance, personal
+information management, electronic mail) the relational
+model is a very natural fit and the SQL query language
+make most accesses to the underlying data (even sophisticated
+ones) straightforward. """)
+
+p("""For an example of a moderately
+sophisticated query using the tables given above,
+the following query lists the drinkers who frequent lolas bar
+and like at least two beers not served by lolas
+""")
+
+if 0:
+ go()
+ sys.exit(1)
+
+pre("""
+ select f.drinker
+ from frequents f, likes l
+ where f.drinker=l.drinker and f.bar='lolas'
+ and l.beer not in
+ (select beer from serves where bar='lolas')
+ group by f.drinker
+ having count(distinct beer)>=2
+""")
+p("""
+yielding the result
+""")
+pre("""
+ DRINKER
+ =======
+ norm
+""")
+p("""
+Experience shows that queries of this sort are actually
+quite common in many applications, and are often much more
+difficult to formulate using some navigational database
+organizations, such as some "object oriented" database
+paradigms.
+""")
+p("""
+Certainly,
+SQL does not provide all you need to interact with
+databases -- in order to do "real work" with SQL you
+need to use SQL and at least one other language
+(such as C, Pascal, C++, Perl, Python, TCL, Visual Basic
+or others) to do work (such as readable formatting a report
+from raw data) that SQL was not designed to do.
+""")
+
+header("Why Gadfly 1?")
+
+p("""Gadfly 1.0 is an SQL based relational database implementation
+implemented entirely in the Python programming language, with
+optional fast data structure accellerators implemented in the
+C programming language. Gadfly is relatively small, highly portable,
+very easy to use (especially for programmers with previous experience
+with SQL databases such as MS Access or Oracle), and reasonably
+fast (especially when the kjbuckets C accellerators are used).
+For moderate sized problems Gadfly offers a fairly complete
+set of features such as transaction semantics, failure recovery,
+and a TCP/IP based client/server mode (Please see [Gadfly] for
+detailed discussion).""")
+
+
+header("Why Gadfly 2?")
+
+p("""Gadfly 1.0 also has significant limitations. An active Gadfly
+1.0 database keeps all data in (virtual) memory, and hence a Gadfly
+1.0 database is limited in size to available virtual memory. Important
+features such as date/time/interval operations, regular expression
+matching and other standard SQL features are not implemented in
+Gadfly 1.0. The optimizer and the query evaluator perform optimizations
+using properties of the equality predicate but do not optimize
+using properties of inequalities such as BETWEEN or less-than.
+It is possible to add "extension views" to a Gadfly
+1.0 database, but the mechanism is somewhat clumsy and indices
+over extension views are not well supported. The features of Gadfly
+2.0 discussed here attempt to address these deficiencies by providing
+a uniform extension model that permits addition of alternate table,
+function, and predicate implementations.""")
+
+p("""Other deficiencies, such as missing constructs like "ALTER
+TABLE" and the lack of outer joins and NULL values are not
+addressed here, although they may be addressed in Gadfly 2.0 or
+a later release. This paper also does not intend to explain
+the complete operations of the internals; it is intended to provide
+at least enough information to understand the basic mechanisms
+for extending gadfly.""")
+
+
+
+
+p("""Some concepts and definitions provided next help with the description
+of the gadfly interfaces. [Note: due to the terseness of this
+format the ensuing is not a highly formal presentation, but attempts
+to approach precision where precision is important.]""")
+
+header("The semilattice of substitutions")
+
+p("""Underlying the gadfly implementation are the basic concepts
+associated with substitutions. A substitution is a mapping
+of attribute names to values (implemented in gadfly using kjbuckets.kjDict
+objects). Here an attribute refers to some sort of "descriptive
+variable", such as NAME and a value is an assignment for that variable,
+like "Dave Ascher". In Gadfly a table is implemented as a sequence
+of substitutions, and substitutions are used in many other ways as well.
+""")
+p("""
+For example consider the substitutions""")
+
+pre("""
+ A = [DRINKER=>'sam']
+ B = [DRINKER=>'sam', BAR=>'cheers']
+ C = [DRINKER=>'woody', BEER=>'bud']
+ D = [DRINKER=>'sam', BEER=>'mickies']
+ E = [DRINKER=>'sam', BAR=>'cheers', BEER=>'mickies']
+ F = [DRINKER=>'sam', BEER=>'mickies']
+ G = [BEER=>'bud', BAR=>'lolas']
+ H = [] # the empty substitution
+ I = [BAR=>'cheers', CAPACITY=>300]""")
+
+p("""A trivial but important observation is that since substitutions
+are mappings, no attribute can assume more than one value in a
+substitution. In the operations described below whenever an operator
+"tries" to assign more than one value to an attribute
+the operator yields an "overdefined" or "inconsistent"
+result.""")
+
+header("Information Semi-order:")
+
+p("""Substitution B is said to be
+more informative than A because B agrees with all assignments
+in A (in addition to providing more information as well). Similarly
+we say that E is more informative than A, B, D, F. and H but E
+is not more informative than the others since, for example G disagrees
+with E on the value assigned to the BEER attribute and I provides
+additional CAPACITY information not provided in E.""")
+
+header("Joins and Inconsistency:")
+
+p("""A join of two substitutions
+X and Y is the least informative substitution Z such that Z is
+more informative (or equally informative) than both X and Y. For
+example B is the join of B with A, E is the join of B with D and""")
+
+pre("""
+ E join I =
+ [DRINKER=>'sam', BAR=>'cheers', BEER=>'mickies', CAPACITY=>300]""")
+
+p("""For any two substitutions either (1) they disagree on the value
+assigned to some attribute and have no join or (2) they agree
+on all common attributes (if there are any) and their join is
+the union of all (name, value) assignments in both substitutions.
+Written in terms of kjbucket.kjDict operations two kjDicts X and
+Y have a join Z = (X+Y) if and only if Z.Clean() is not None.
+Two substitutions that have no join are said to be inconsistent.
+For example I and G are inconsistent since they disagree on
+the value assigned to the BAR attribute and therefore have no
+join. The algebra of substitutions with joins technically defines
+an abstract algebraic structure called a semilattice.""")
+
+header("Name space remapping")
+
+p("""Another primitive operation over substitutions is the remap
+operation S2 = S.remap(R) where S is a substitution and R is a
+graph of attribute names and S2 is a substitution. This operation
+is defined to produce the substitution S2 such that""")
+
+pre("""
+ Name=>Value in S2 if and only if
+ Name1=>Value in S and Name<=Name1 in R
+""")
+
+p("""or if there is no such substitution S2 the remap value is said
+to be overdefined.""")
+
+p("""For example the remap operation may be used to eliminate attributes
+from a substitution. For example""")
+
+pre("""
+ E.remap([DRINKER<=DRINKER, BAR<=BAR])
+ = [DRINKER=>'sam', BAR=>'cheers']
+""")
+
+p("""Illustrating that remapping using the [DRINKER<=DRINKER,
+BAR<=BAR] graph eliminates all attributes except DRINKER and
+BAR, such as BEER. More generally remap can be used in this way
+to implement the classical relational projection operation. (See [Korth and Silberschatz]
+for a detailed discussion of the projection operator and other relational
+algebra operators such as selection, rename, difference and joins.)""")
+
+p("""The remap operation can also be used to implement "selection
+on attribute equality". For example if we are interested
+in the employee names of employees who are their own bosses we
+can use the remapping graph""")
+
+pre("""
+ R1 = [NAME<=NAME, NAME<=BOSS]
+""")
+
+p("""and reject substitutions where remapping using R1 is overdefined.
+For example""")
+
+pre("""
+ S1 = [NAME=>'joe', BOSS=>'joe']
+ S1.remap(R1) = [NAME=>'joe']
+ S2 = [NAME=>'fred', BOSS=>'joe']
+ S2.remap(R1) is overdefined.
+""")
+
+p("""The last remap is overdefined because the NAME attribute cannot
+assume both the values 'fred' and 'joe' in a substitution.""")
+
+p("""Furthermore, of course, the remap operation can be used to
+"rename attributes" or "copy attribute values"
+in substitutions. Note below that the missing attribute CAPACITY
+in B is effectively ignored in the remapping operation.""")
+
+pre("""
+ B.remap([D<=DRINKER, B<=BAR, B2<=BAR, C<=CAPACITY])
+ = [D=>'sam', B=>'cheers', B2=>'cheers']
+""")
+
+p("""More interestingly, a single remap operation can be used to
+perform a combination of renaming, projection, value copying,
+and attribute equality selection as one operation. In kjbuckets the remapper
+graph is implemented using a kjbuckets.kjGraph and the remap operation
+is an intrinsic method of kjbuckets.kjDict objects.""")
+
+header("Generalized Table Joins and the Evaluator Mainloop""")
+
+p("""Strictly speaking the Gadfly 2.0 query evaluator only uses
+the join and remap operations as its "basic assembly language"
+-- all other computations, including inequality comparisons and
+arithmetic, are implemented externally to the evaluator as "generalized
+table joins." """)
+
+p("""A table is a sequence of substitutions (which in keeping with
+SQL semantics may contain redundant entries). The join between
+two tables T1 and T2 is the sequence of all possible defined joins
+between pairs of elements from the two tables. Procedurally we
+might compute the join as""")
+
+pre("""
+ T1JoinT2 = empty
+ for t1 in T1:
+ for t2 in T2:
+ if t1 join t2 is defined:
+ add t1 join t2 to T1joinT2""")
+
+p("""In general circumstances this intuitive implementation is a
+very inefficient way to compute the join, and Gadfly almost always
+uses other methods, particularly since, as described below, a
+"generalized table" can have an "infinite"
+number of entries.""")
+
+p("""For an example of a table join consider the EMPLOYEES table
+containing""")
+
+pre("""
+ [NAME=>'john', JOB=>'executive']
+ [NAME=>'sue', JOB=>'programmer']
+ [NAME=>'eric', JOB=>'peon']
+ [NAME=>'bill', JOB=>'peon']
+""")
+
+p("""and the ACTIVITIES table containing""")
+
+pre("""
+ [JOB=>'peon', DOES=>'windows']
+ [JOB=>'peon', DOES=>'floors']
+ [JOB=>'programmer', DOES=>'coding']
+ [JOB=>'secretary', DOES=>'phone']""")
+
+p("""then the join between EMPLOYEES and ACTIVITIES must containining""")
+
+pre("""
+ [NAME=>'sue', JOB=>'programmer', DOES=>'coding']
+ [NAME=>'eric', JOB=>'peon', DOES=>'windows']
+ [NAME=>'bill', JOB=>'peon', DOES=>'windows']
+ [NAME=>'eric', JOB=>'peon', DOES=>'floors']
+ [NAME=>'bill', JOB=>'peon', DOES=>'floors']""")
+
+p("""A compiled gadfly subquery ultimately appears to the evaluator
+as a sequence of generalized tables that must be joined (in combination
+with certain remapping operations that are beyond the scope of
+this discussion). The Gadfly mainloop proceeds following the very
+loose pseudocode:""")
+
+pre("""
+ Subs = [ [] ] # the unary sequence containing "true"
+ While some table hasn't been chosen yet:
+ Choose an unchosen table with the least cost join estimate.
+ Subs = Subs joined with the chosen table
+ return Subs""")
+
+p("""[Note that it is a property of the join operation that the
+order in which the joins are carried out will not affect the result,
+so the greedy strategy of evaluating the "cheapest join next"
+will not effect the result. Also note that the treatment of logical
+OR and NOT as well as EXIST, IN, UNION, and aggregation and so
+forth are not discussed here, even though they do fit into this
+approach.]""")
+
+p("""The actual implementation is a bit more complex than this,
+but the above outline may provide some useful intuition. The "cost
+estimation" step and the implementation of the join operation
+itself are left up to the generalized table object implementation.
+A table implementation has the ability to give an "infinite"
+cost estimate, which essentially means "don't join me in
+yet under any circumstances." """)
+
+header("Implementing Functions")
+
+p("""As mentioned above operations such as arithmetic are implemented
+using generalized tables. For example the arithmetic Add operation
+is implemented in Gadfly internally as an "infinite generalized
+table" containing all possible substitutions""")
+
+pre("""
+ ARG0=>a, ARG1=>b, RESULT=>a+b]
+""")
+
+p("""Where a and b are all possible values which can be summed.
+Clearly, it is not possible to enumerate this table, but given
+a sequence of substitutions with defined values for ARG0 and ARG1
+such as""")
+
+pre("""
+ [ARG0=>1, ARG1=-4]
+ [ARG0=>2.6, ARG1=50]
+ [ARG0=>99, ARG1=1]
+""")
+
+p("""it is possible to implement a "join operation" against
+this sequence that performs the same augmentation as a join with
+the infinite table defined above:""")
+
+pre("""
+ [ARG0=>1, ARG1=-4, RESULT=-3]
+ [ARG0=>2.6, ARG1=50, RESULT=52.6]
+ [ARG0=>99, ARG1=1, RESULT=100]
+""")
+
+p("""Furthermore by giving an "infinite estimate" for
+all attempts to evaluate the join where ARG0 and ARG1 are not
+available the generalized table implementation for the addition
+operation can refuse to compute an "infinite join." """)
+
+p("""More generally all functions f(a,b,c,d) are represented in
+gadfly as generalized tables containing all possible relevant
+entries""")
+
+pre("""
+ [ARG0=>a, ARG1=>b, ARG2=>c, ARG3=>d, RESULT=>f(a,b,c,d)]""")
+
+p("""and the join estimation function refuses all attempts to perform
+a join unless all the arguments are provided by the input substitution
+sequence.""")
+
+header("Implementing Predicates")
+
+p("""Similarly to functions, predicates such as less-than and BETWEEN
+and LIKE are implemented using the generalized table mechanism.
+For example the "x BETWEEN y AND z" predicate is implemented
+as a generalized table "containing" all possible""")
+
+pre("""
+ [ARG0=>a, ARG1=>b, ARG2=>c]""")
+
+p("""where b<a<c. Furthermore joins with this table are not
+permitted unless all three arguments are available in the sequence
+of input substitutions.""")
+
+header("Some Gadfly extension interfaces")
+
+p("""A gadfly database engine may be extended with user defined
+functions, predicates, and alternative table and index implementations.
+This section snapshots several Gadfly 2.0 interfaces, currently under
+development and likely to change before the package is released.""")
+
+p("""The basic interface for adding functions and predicates (logical tests)
+to a gadfly engine are relatively straightforward. For example to add the
+ability to match a regular expression within a gadfly query use the
+following implementation.""")
+
+pre("""
+ from re import match
+
+ def addrematch(gadflyinstance):
+ gadflyinstance.add_predicate("rematch", match)
+""")
+p("""
+Then upon connecting to the database execute
+""")
+pre("""
+ g = gadfly(...)
+ ...
+ addrematch(g)
+""")
+p("""
+In this case the "semijoin operation" associated with the new predicate
+"rematch" is automatically generated, and after the add_predicate
+binding operation the gadfly instance supports queries such as""")
+pre("""
+ select drinker, beer
+ from likes
+ where rematch('b*', beer) and drinker not in
+ (select drinker from frequents where rematch('c*', bar))
+""")
+p("""
+By embedding the "rematch" operation within the query the SQL
+engine can do "more work" for the programmer and reduce or eliminate the
+need to process the query result externally to the engine.
+""")
+p("""
+In a similar manner functions may be added to a gadfly instance,""")
+pre("""
+ def modulo(x,y):
+ return x % y
+
+ def addmodulo(gadflyinstance):
+ gadflyinstance.add_function("modulo", modulo)
+
+ ...
+ g = gadfly(...)
+ ...
+ addmodulo(g)
+""")
+p("""
+Then after the binding the modulo function can be used whereever
+an SQL expression can occur.
+""")
+p("""
+Adding alternative table implementations to a Gadfly instance
+is more interesting and more difficult. An "extension table" implementation
+must conform to the following interface:""")
+
+pre("""
+ # get the kjbuckets.kjSet set of attribute names for this table
+ names = table.attributes()
+
+ # estimate the difficulty of evaluating a join given known attributes
+ # return None for "impossible" or n>=0 otherwise with larger values
+ # indicating greater difficulty or expense
+ estimate = table.estimate(known_attributes)
+
+ # return the join of the rows of the table with
+ # the list of kjbuckets.kjDict mappings as a list of mappings.
+ resultmappings = table.join(listofmappings)
+""")
+p("""
+In this case add the table to a gadfly instance using""")
+pre("""
+ gadflyinstance.add_table("table_name", table)
+""")
+p("""
+For example to add a table which automatically queries filenames
+in the filesystems of the host computer a gadfly instance could
+be augmented with a GLOB table implemented using the standard
+library function glob.glob as follows:""")
+pre("""
+ import kjbuckets
+
+ class GlobTable:
+ def __init__(self): pass
+
+ def attributes(self):
+ return kjbuckets.kjSet("PATTERN", "NAME")
+
+ def estimate(self, known_attributes):
+ if known_attributes.member("PATTERN"):
+ return 66 # join not too difficult
+ else:
+ return None # join is impossible (must have PATTERN)
+
+ def join(self, listofmappings):
+ from glob import glob
+ result = []
+ for m in listofmappings:
+ pattern = m["PATTERN"]
+ for name in glob(pattern):
+ newmapping = kjbuckets.kjDict(m)
+ newmapping["NAME"] = name
+ if newmapping.Clean():
+ result.append(newmapping)
+ return result
+
+ ...
+ gadfly_instance.add_table("GLOB", GlobTable())
+""")
+p("""
+Then one could formulate queries such as "list the files in directories
+associated with packages installed by guido"
+""")
+pre("""
+ select g.name as filename
+ from packages p, glob g
+ where p.installer = 'guido' and g.pattern=p.root_directory
+""")
+p("""
+Note that conceptually the GLOB table is an infinite table including
+all filenames on the current computer in the "NAME" column, paired with
+a potentially infinite number of patterns.
+""")
+p("""
+More interesting examples would allow queries to remotely access
+data served by an HTTP server, or from any other resource.
+""")
+p("""
+Furthermore an extension table can be augmented with update methods
+""")
+pre("""
+ table.insert_rows(listofmappings)
+ table.update_rows(oldlist, newlist)
+ table.delete_rows(oldlist)
+""")
+p("""
+Note: at present the implementation does not enforce recovery or
+transaction semantics for updates to extension tables, although this
+may change in the final release.
+""")
+p("""
+The table implementation is free to provide its own implementations of
+indices which take advantage of data provided by the join argument.
+""")
+
+header("Efficiency Notes")
+
+p("""The following thought experiment attempts to explain why the
+Gadfly implementation is surprisingly fast considering that it
+is almost entirely implemented in Python (an interpreted programming
+language which is not especially fast when compared to alternatives).
+Although Gadfly is quite complex, at an abstract level the process
+of query evaluation boils down to a series of embedded loops.
+Consider the following nested loops:""")
+
+pre("""
+ iterate 1000:
+ f(...) # fixed cost of outer loop
+ iterate 10:
+ g(...) # fixed cost of middle loop
+ iterate 10:
+ # the real work (string parse, matrix mul, query eval...)
+ h(...)""")
+
+p("""In my experience many computations follow this pattern where
+f, g, are complex, dynamic, special purpose and h is simple, general
+purpose, static. Some example computations that follow this pattern
+include: file massaging (perl), matrix manipulation (python, tcl),
+database/cgi page generation, and vector graphics/imaging.""")
+
+p("""Suppose implementing f, g, h in python is easy but result in
+execution times10 times slower than a much harder implementation
+in C, choosing arbitrary and debatable numbers assume each function
+call consumes 1 tick in C, 5 ticks in java, 10 ticks in python
+for a straightforward implementation of each function f, g, and
+h. Under these conditions we get the following cost analysis,
+eliminating some uninteresting combinations, of implementing the
+function f, g, and h in combinations of Python, C and java:""")
+
+pre("""
+COST | FLANG | GLANG | HLANG
+==================================
+111000 | C | C | C
+115000 | java | C | C
+120000 | python | C | C
+155000 | java | java | C
+210000 | python | python | C
+555000 | java | java | java
+560000 | python | java | java
+610000 | python | python | java
+1110000 | python | python | python
+""")
+
+p("""Note that moving only the innermost loop to C (python/python/C)
+speeds up the calculation by half an order of magnitude compared
+to the python-only implementation and brings the speed to within
+a factor of 2 of an implementation done entirely in C.""")
+
+p("""Although this artificial and contrived thought experiment is
+far from conclusive, we may be tempted to draw the conclusion
+that generally programmers should focus first on obtaining a working
+implementation (because as John Ousterhout is reported to have
+said "the biggest performance improvement is the transition
+from non-working to working") using the methodology that
+is most likely to obtain a working solution the quickest (Python). Only then if the performance
+is inadequate should the programmer focus on optimizing
+the inner most loops, perhaps moving them to a very efficient
+implementation (C). Optimizing the outer loops will buy little
+improvement, and should be done later, if ever.""")
+
+p("""This was precisely the strategy behind the gadfly implementations,
+where most of the inner loops are implemented in the kjbuckets
+C extension module and the higher level logic is all in Python.
+This also explains why gadfly appears to be "slower"
+for simple queries over small data sets, but seems to be relatively
+"faster" for more complex queries over larger data sets,
+since larger queries and data sets take better advantage of the
+optimized inner loops.""")
+
+header("A Gadfly variant for OLAP?")
+
+p("""In private correspondence Andy Robinson points out that the
+basic logical design underlying Gadfly could be adapted to provide
+Online Analytical Processing (OLAP) and other forms of data warehousing
+and data mining. Since SQL is not particularly well suited for
+the kinds of requests common in these domains the higher level
+interfaces would require modification, but the underlying logic
+of substitutions and name mappings seems to be appropriate.""")
+
+header("Conclusion")
+
+p("""The revamped query engine design in Gadfly 2 supports
+a flexible and general extension methodology that permits programmers
+to extend the gadfly engine to include additional computations
+and access to remote data sources. Among other possibilities this
+will permit the gadfly engine to make use of disk based indexed
+tables and to dynamically retrieve information from remote data
+sources (such as an Excel spreadsheet or an Oracle database).
+These features will make gadfly a very useful tool for data manipulation
+and integration.""")
+
+header("References")
+
+p("""[Van Rossum] Van Rossum, Python Reference Manual, Tutorial, and Library Manuals,
+please look to http://www.python.org
+for the latest versions, downloads and links to printed versions.""")
+
+p("""[O'Neill] O'Neill, P., Data Base Principles, Programming, Performance,
+Morgan Kaufmann Publishers, San Francisco, 1994.""")
+
+p("""[Korth and Silberschatz] Korth, H. and Silberschatz, A. and Sudarshan, S.
+Data Base System Concepts, McGraw-Hill Series in Computer Science, Boston,
+1997""")
+
+p("""[Gadfly]Gadfly: SQL Relational Database in Python,
+http://www.chordate.com/kwParsing/gadfly.html""")
+
+go()
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/odyssey/00readme.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,56 @@
+This contains a number of benchmarks and demos
+based on Homer's Odyssey (which is widely available
+in plain, line-oriented text format). There are a large
+selection of online books at:
+ http://classics.mit.edu/
+
+
+Our distribution ships with just the first chapter
+in odyssey.txt. For a more meaningful speed test,
+download the full copy from
+ http://www.reportlab.com/ftp/odyssey.full.zip
+or
+ ftp://ftp.reportlab.com/odyssey.full.zip
+and unzip to extract odyssey.full.txt (608kb).
+
+Benchmark speed depends quite critically
+on the presence of our accelerator module,
+_rl_accel, which is a C (or Java) extension.
+Serious users ought to compile or download this!
+
+The times quoted are from one machine (Andy Robinson's
+home PC, approx 1.2Ghz 128Mb Ram, Win2k in Sep 2003)
+in order to give a rough idea of what features cost
+what performance.
+
+
+The tests are as follows:
+
+(1) odyssey.py (produces odyssey.pdf)
+This demo takes a large volume of text and prints it
+in the simplest way possible. It is a demo of the
+basic technique of looping down a page manually and
+breaking at the bottom. On my 1.2 Ghz machine this takes
+1.91 seconds (124 pages per second)
+
+(2) fodyssey.py (produces fodyssey.pdf)
+This is a 'flowing document' we parse the file and
+throw away line breaks to make proper paragraphs.
+The Platypus framework renders these. This necessitates
+measuring the width of every word in every paragraph
+for wrapping purposes.
+
+This takes 3.27 seconds on the same machine. Paragraph
+wrapping basically doubles the work. The text is more
+compact with about 50% more words per page. Very roughly,
+we can wrap 40 pages of ten-point text per second and save
+to PDF.
+
+(3) dodyssey.py (produced dodyssey.pdf)
+This is a slightly fancier version which uses different
+page templates (one column for first page in a chapter,
+two column for body poages). The additional layout logic
+adds about 15%, going up to 3.8 seconds. This is probably
+a realistic benchmark for a simple long text document
+with a single pass. Documents doing cross-references
+and a table of contents might need twice as long.
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/odyssey/dodyssey.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,254 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/odyssey/dodyssey.py
+__version__=''' $Id$ '''
+__doc__=''
+
+#REPORTLAB_TEST_SCRIPT
+import sys, copy, string, os
+from reportlab.platypus import *
+_NEW_PARA=os.environ.get('NEW_PARA','0')[0] in ('y','Y','1')
+_REDCAP=int(os.environ.get('REDCAP','0'))
+_CALLBACK=os.environ.get('CALLBACK','0')[0] in ('y','Y','1')
+if _NEW_PARA:
+ def Paragraph(s,style):
+ from rlextra.radxml.para import Paragraph as PPPP
+ return PPPP(s,style)
+
+from reportlab.lib.units import inch
+from reportlab.lib.styles import getSampleStyleSheet
+from reportlab.lib.enums import TA_LEFT, TA_RIGHT, TA_CENTER, TA_JUSTIFY
+
+import reportlab.rl_config
+reportlab.rl_config.invariant = 1
+
+styles = getSampleStyleSheet()
+
+Title = "The Odyssey"
+Author = "Homer"
+
+def myTitlePage(canvas, doc):
+ canvas.saveState()
+ canvas.restoreState()
+
+def myLaterPages(canvas, doc):
+ canvas.saveState()
+ canvas.setFont('Times-Roman',9)
+ canvas.drawString(inch, 0.75 * inch, "Page %d" % doc.page)
+ canvas.restoreState()
+
+def go():
+ def myCanvasMaker(fn,**kw):
+ from reportlab.pdfgen.canvas import Canvas
+ canv = apply(Canvas,(fn,),kw)
+ # attach our callback to the canvas
+ canv.myOnDrawCB = myOnDrawCB
+ return canv
+
+ doc = BaseDocTemplate('dodyssey.pdf',showBoundary=0)
+
+ #normal frame as for SimpleFlowDocument
+ frameT = Frame(doc.leftMargin, doc.bottomMargin, doc.width, doc.height, id='normal')
+
+ #Two Columns
+ frame1 = Frame(doc.leftMargin, doc.bottomMargin, doc.width/2-6, doc.height, id='col1')
+ frame2 = Frame(doc.leftMargin+doc.width/2+6, doc.bottomMargin, doc.width/2-6,
+ doc.height, id='col2')
+ doc.addPageTemplates([PageTemplate(id='First',frames=frameT, onPage=myTitlePage),
+ PageTemplate(id='OneCol',frames=frameT, onPage=myLaterPages),
+ PageTemplate(id='TwoCol',frames=[frame1,frame2], onPage=myLaterPages),
+ ])
+ doc.build(Elements,canvasmaker=myCanvasMaker)
+
+Elements = []
+
+ChapterStyle = copy.deepcopy(styles["Heading1"])
+ChapterStyle.alignment = TA_CENTER
+ChapterStyle.fontsize = 14
+InitialStyle = copy.deepcopy(ChapterStyle)
+InitialStyle.fontsize = 16
+InitialStyle.leading = 20
+PreStyle = styles["Code"]
+
+def newPage():
+ Elements.append(PageBreak())
+
+chNum = 0
+def myOnDrawCB(canv,kind,label):
+ print 'myOnDrawCB(%s)'%kind, 'Page number=', canv.getPageNumber(), 'label value=', label
+
+def chapter(txt, style=ChapterStyle):
+ global chNum
+ Elements.append(NextPageTemplate('OneCol'))
+ newPage()
+ chNum = chNum + 1
+ if _NEW_PARA or not _CALLBACK:
+ Elements.append(Paragraph(('chap %d'%chNum)+txt, style))
+ else:
+ Elements.append(Paragraph(('foo<onDraw name="myOnDrawCB" label="chap %d"/> '%chNum)+txt, style))
+ Elements.append(Spacer(0.2*inch, 0.3*inch))
+ if useTwoCol:
+ Elements.append(NextPageTemplate('TwoCol'))
+
+def fTitle(txt,style=InitialStyle):
+ Elements.append(Paragraph(txt, style))
+
+ParaStyle = copy.deepcopy(styles["Normal"])
+ParaStyle.spaceBefore = 0.1*inch
+if 'right' in sys.argv:
+ ParaStyle.alignment = TA_RIGHT
+elif 'left' in sys.argv:
+ ParaStyle.alignment = TA_LEFT
+elif 'justify' in sys.argv:
+ ParaStyle.alignment = TA_JUSTIFY
+elif 'center' in sys.argv or 'centre' in sys.argv:
+ ParaStyle.alignment = TA_CENTER
+else:
+ ParaStyle.alignment = TA_JUSTIFY
+
+useTwoCol = 'notwocol' not in sys.argv
+
+def spacer(inches):
+ Elements.append(Spacer(0.1*inch, inches*inch))
+
+def p(txt, style=ParaStyle):
+ if _REDCAP:
+ fs, fe = '<font color="red" size="+2">', '</font>'
+ n = len(txt)
+ for i in xrange(n):
+ if 'a'<=txt[i]<='z' or 'A'<=txt[i]<='Z':
+ txt = (txt[:i]+(fs+txt[i]+fe))+txt[i+1:]
+ break
+ if _REDCAP>=2 and n>20:
+ j = i+len(fs)+len(fe)+1+int((n-1)/2)
+ while not ('a'<=txt[j]<='z' or 'A'<=txt[j]<='Z'): j += 1
+ txt = (txt[:j]+('<b><i><font size="+2" color="blue">'+txt[j]+'</font></i></b>'))+txt[j+1:]
+
+ if _REDCAP==3 and n>20:
+ n = len(txt)
+ fs = '<font color="green" size="+1">'
+ for i in xrange(n-1,-1,-1):
+ if 'a'<=txt[i]<='z' or 'A'<=txt[i]<='Z':
+ txt = txt[:i]+((fs+txt[i]+fe)+txt[i+1:])
+ break
+
+ Elements.append(Paragraph(txt, style))
+
+firstPre = 1
+def pre(txt, style=PreStyle):
+ global firstPre
+ if firstPre:
+ Elements.append(NextPageTemplate('OneCol'))
+ newPage()
+ firstPre = 0
+
+ spacer(0.1)
+ p = Preformatted(txt, style)
+ Elements.append(p)
+
+def parseOdyssey(fn):
+ from time import time
+ E = []
+ t0=time()
+ L = open(fn,'r').readlines()
+ t1 = time()
+ print "open(%s,'r').readlines() took %.4f seconds" %(fn,t1-t0)
+ for i in xrange(len(L)):
+ if L[i][-1]=='\012':
+ L[i] = L[i][:-1]
+ t2 = time()
+ print "Removing all linefeeds took %.4f seconds" %(t2-t1)
+ L.append('')
+ L.append('-----')
+
+ def findNext(L, i):
+ while 1:
+ if string.strip(L[i])=='':
+ del L[i]
+ kind = 1
+ if i<len(L):
+ while string.strip(L[i])=='':
+ del L[i]
+
+ if i<len(L):
+ kind = L[i][-1]=='-' and L[i][0]=='-'
+ if kind:
+ del L[i]
+ if i<len(L):
+ while string.strip(L[i])=='':
+ del L[i]
+ break
+ else:
+ i = i + 1
+
+ return i, kind
+
+ f = s = 0
+ while 1:
+ f, k = findNext(L,0)
+ if k: break
+
+ E.append([spacer,2])
+ E.append([fTitle,'<font color="red">%s</font>' % Title, InitialStyle])
+ E.append([fTitle,'<font size="-4">by</font> <font color="green">%s</font>' % Author, InitialStyle])
+
+ while 1:
+ if f>=len(L): break
+
+ if string.upper(L[f][0:5])=='BOOK ':
+ E.append([chapter,L[f]])
+ f=f+1
+ while string.strip(L[f])=='': del L[f]
+ style = ParaStyle
+ func = p
+ else:
+ style = PreStyle
+ func = pre
+
+ while 1:
+ s=f
+ f, k=findNext(L,s)
+ sep= (func is pre) and '\012' or ' '
+ E.append([func,string.join(L[s:f],sep),style])
+ if k: break
+ t3 = time()
+ print "Parsing into memory took %.4f seconds" %(t3-t2)
+ del L
+ t4 = time()
+ print "Deleting list of lines took %.4f seconds" %(t4-t3)
+ for i in xrange(len(E)):
+ apply(E[i][0],E[i][1:])
+ t5 = time()
+ print "Moving into platypus took %.4f seconds" %(t5-t4)
+ del E
+ t6 = time()
+ print "Deleting list of actions took %.4f seconds" %(t6-t5)
+ go()
+ t7 = time()
+ print "saving to PDF took %.4f seconds" %(t7-t6)
+ print "Total run took %.4f seconds"%(t7-t0)
+
+ import md5
+ print 'file digest: %s' % md5.md5(open('dodyssey.pdf','rb').read()).hexdigest()
+
+def run():
+ for fn in ('odyssey.full.txt','odyssey.txt'):
+ if os.path.isfile(fn):
+ parseOdyssey(fn)
+ break
+
+def doProf(profname,func,*args,**kwd):
+ import hotshot, hotshot.stats
+ prof = hotshot.Profile(profname)
+ prof.runcall(func)
+ prof.close()
+ stats = hotshot.stats.load(profname)
+ stats.strip_dirs()
+ stats.sort_stats('time', 'calls')
+ stats.print_stats(20)
+
+if __name__=='__main__':
+ if '--prof' in sys.argv:
+ doProf('dodyssey.prof',run)
+ else:
+ run()
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/odyssey/fodyssey.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,165 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/odyssey/fodyssey.py
+__version__=''' $Id$ '''
+__doc__=''
+
+#REPORTLAB_TEST_SCRIPT
+import sys, copy, string, os
+from reportlab.platypus import *
+from reportlab.lib.units import inch
+from reportlab.lib.styles import getSampleStyleSheet
+from reportlab.lib.enums import TA_LEFT, TA_RIGHT, TA_CENTER, TA_JUSTIFY
+
+styles = getSampleStyleSheet()
+
+Title = "The Odyssey"
+Author = "Homer"
+
+def myFirstPage(canvas, doc):
+ canvas.saveState()
+ canvas.restoreState()
+
+def myLaterPages(canvas, doc):
+ canvas.saveState()
+ canvas.setFont('Times-Roman',9)
+ canvas.drawString(inch, 0.75 * inch, "Page %d" % doc.page)
+ canvas.restoreState()
+
+def go():
+ doc = SimpleDocTemplate('fodyssey.pdf',showBoundary='showboundary' in sys.argv)
+ doc.allowSplitting = not 'nosplitting' in sys.argv
+ doc.build(Elements,myFirstPage,myLaterPages)
+
+Elements = []
+
+ChapterStyle = copy.copy(styles["Heading1"])
+ChapterStyle.alignment = TA_CENTER
+ChapterStyle.fontsize = 16
+InitialStyle = copy.deepcopy(ChapterStyle)
+InitialStyle.fontsize = 16
+InitialStyle.leading = 20
+PreStyle = styles["Code"]
+
+def newPage():
+ Elements.append(PageBreak())
+
+def chapter(txt, style=ChapterStyle):
+ newPage()
+ Elements.append(Paragraph(txt, style))
+ Elements.append(Spacer(0.2*inch, 0.3*inch))
+
+def fTitle(txt,style=InitialStyle):
+ Elements.append(Paragraph(txt, style))
+
+ParaStyle = copy.deepcopy(styles["Normal"])
+ParaStyle.spaceBefore = 0.1*inch
+if 'right' in sys.argv:
+ ParaStyle.alignment = TA_RIGHT
+elif 'left' in sys.argv:
+ ParaStyle.alignment = TA_LEFT
+elif 'justify' in sys.argv:
+ ParaStyle.alignment = TA_JUSTIFY
+elif 'center' in sys.argv or 'centre' in sys.argv:
+ ParaStyle.alignment = TA_CENTER
+else:
+ ParaStyle.alignment = TA_JUSTIFY
+
+def spacer(inches):
+ Elements.append(Spacer(0.1*inch, inches*inch))
+
+def p(txt, style=ParaStyle):
+ Elements.append(Paragraph(txt, style))
+
+def pre(txt, style=PreStyle):
+ spacer(0.1)
+ p = Preformatted(txt, style)
+ Elements.append(p)
+
+def parseOdyssey(fn):
+ from time import time
+ E = []
+ t0=time()
+ L = open(fn,'r').readlines()
+ t1 = time()
+ print "open(%s,'r').readlines() took %.4f seconds" %(fn,t1-t0)
+ for i in xrange(len(L)):
+ if L[i][-1]=='\012':
+ L[i] = L[i][:-1]
+ t2 = time()
+ print "Removing all linefeeds took %.4f seconds" %(t2-t1)
+ L.append('')
+ L.append('-----')
+
+ def findNext(L, i):
+ while 1:
+ if string.strip(L[i])=='':
+ del L[i]
+ kind = 1
+ if i<len(L):
+ while string.strip(L[i])=='':
+ del L[i]
+
+ if i<len(L):
+ kind = L[i][-1]=='-' and L[i][0]=='-'
+ if kind:
+ del L[i]
+ if i<len(L):
+ while string.strip(L[i])=='':
+ del L[i]
+ break
+ else:
+ i = i + 1
+
+ return i, kind
+
+ f = s = 0
+ while 1:
+ f, k = findNext(L,0)
+ if k: break
+
+ E.append([spacer,2])
+ E.append([fTitle,'<font color=red>%s</font>' % Title, InitialStyle])
+ E.append([fTitle,'<font size=-4>by</font> <font color=green>%s</font>' % Author, InitialStyle])
+
+ while 1:
+ if f>=len(L): break
+
+ if string.upper(L[f][0:5])=='BOOK ':
+ E.append([chapter,L[f]])
+ f=f+1
+ while string.strip(L[f])=='': del L[f]
+ style = ParaStyle
+ func = p
+ else:
+ style = PreStyle
+ func = pre
+
+ while 1:
+ s=f
+ f, k=findNext(L,s)
+ sep= (func is pre) and '\012' or ' '
+ E.append([func,string.join(L[s:f],sep),style])
+ if k: break
+ t3 = time()
+ print "Parsing into memory took %.4f seconds" %(t3-t2)
+ del L
+ t4 = time()
+ print "Deleting list of lines took %.4f seconds" %(t4-t3)
+ for i in xrange(len(E)):
+ apply(E[i][0],E[i][1:])
+ t5 = time()
+ print "Moving into platypus took %.4f seconds" %(t5-t4)
+ del E
+ t6 = time()
+ print "Deleting list of actions took %.4f seconds" %(t6-t5)
+ go()
+ t7 = time()
+ print "saving to PDF took %.4f seconds" %(t7-t6)
+ print "Total run took %.4f seconds"%(t7-t0)
+
+for fn in ('odyssey.full.txt','odyssey.txt'):
+ if os.path.isfile(fn):
+ break
+if __name__=='__main__':
+ parseOdyssey(fn)
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/odyssey/odyssey.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,151 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/odyssey/odyssey.py
+__version__=''' $Id$ '''
+___doc__=''
+#odyssey.py
+#
+#Demo/benchmark of PDFgen rendering Homer's Odyssey.
+
+
+
+#results on my humble P266 with 64MB:
+# Without page compression:
+# 239 pages in 3.76 seconds = 77 pages per second
+
+# With textOut rather than textLine, i.e. computing width
+# of every word as we would for wrapping:
+# 239 pages in 10.83 seconds = 22 pages per second
+
+# With page compression and textLine():
+# 239 pages in 39.39 seconds = 6 pages per second
+
+from reportlab.pdfgen import canvas
+import time, os, sys
+
+#find out what platform we are on and whether accelerator is
+#present, in order to print this as part of benchmark info.
+try:
+ import _rl_accel
+ ACCEL = 1
+except ImportError:
+ ACCEL = 0
+
+
+
+
+from reportlab.lib.units import inch, cm
+from reportlab.lib.pagesizes import A4
+
+#precalculate some basics
+top_margin = A4[1] - inch
+bottom_margin = inch
+left_margin = inch
+right_margin = A4[0] - inch
+frame_width = right_margin - left_margin
+
+
+def drawPageFrame(canv):
+ canv.line(left_margin, top_margin, right_margin, top_margin)
+ canv.setFont('Times-Italic',12)
+ canv.drawString(left_margin, top_margin + 2, "Homer's Odyssey")
+ canv.line(left_margin, top_margin, right_margin, top_margin)
+
+
+ canv.line(left_margin, bottom_margin, right_margin, bottom_margin)
+ canv.drawCentredString(0.5*A4[0], 0.5 * inch,
+ "Page %d" % canv.getPageNumber())
+
+
+
+def run(verbose=1):
+ if sys.platform[0:4] == 'java':
+ impl = 'Jython'
+ else:
+ impl = 'Python'
+ verStr = '%d.%d' % (sys.version_info[0:2])
+ if ACCEL:
+ accelStr = 'with _rl_accel'
+ else:
+ accelStr = 'without _rl_accel'
+ print 'Benchmark of %s %s %s' % (impl, verStr, accelStr)
+
+ started = time.time()
+ canv = canvas.Canvas('odyssey.pdf', invariant=1)
+ canv.setPageCompression(1)
+ drawPageFrame(canv)
+
+ #do some title page stuff
+ canv.setFont("Times-Bold", 36)
+ canv.drawCentredString(0.5 * A4[0], 7 * inch, "Homer's Odyssey")
+
+ canv.setFont("Times-Bold", 18)
+ canv.drawCentredString(0.5 * A4[0], 5 * inch, "Translated by Samuel Burton")
+
+ canv.setFont("Times-Bold", 12)
+ tx = canv.beginText(left_margin, 3 * inch)
+ tx.textLine("This is a demo-cum-benchmark for PDFgen. It renders the complete text of Homer's Odyssey")
+ tx.textLine("from a text file. On my humble P266, it does 77 pages per secondwhile creating a 238 page")
+ tx.textLine("document. If it is asked to computer text metrics, measuring the width of each word as ")
+ tx.textLine("one would for paragraph wrapping, it still manages 22 pages per second.")
+ tx.textLine("")
+ tx.textLine("Andy Robinson, Robinson Analytics Ltd.")
+ canv.drawText(tx)
+
+ canv.showPage()
+ #on with the text...
+ drawPageFrame(canv)
+
+ canv.setFont('Times-Roman', 12)
+ tx = canv.beginText(left_margin, top_margin - 0.5*inch)
+
+ for fn in ('odyssey.full.txt','odyssey.txt'):
+ if os.path.isfile(fn):
+ break
+
+ data = open(fn,'r').readlines()
+ for line in data:
+ #this just does it the fast way...
+ tx.textLine(line)
+ #this forces it to do text metrics, which would be the slow
+ #part if we were wrappng paragraphs.
+ #canv.textOut(line)
+ #canv.textLine('')
+
+ #page breaking
+ y = tx.getY() #get y coordinate
+ if y < bottom_margin + 0.5*inch:
+ canv.drawText(tx)
+ canv.showPage()
+ drawPageFrame(canv)
+ canv.setFont('Times-Roman', 12)
+ tx = canv.beginText(left_margin, top_margin - 0.5*inch)
+
+ #page
+ pg = canv.getPageNumber()
+ if verbose and pg % 10 == 0:
+ print 'formatted page %d' % canv.getPageNumber()
+
+ if tx:
+ canv.drawText(tx)
+ canv.showPage()
+ drawPageFrame(canv)
+
+ if verbose:
+ print 'about to write to disk...'
+
+ canv.save()
+
+ finished = time.time()
+ elapsed = finished - started
+ pages = canv.getPageNumber()-1
+ speed = pages / elapsed
+ fileSize = os.stat('odyssey.pdf')[6] / 1024
+ print '%d pages in %0.2f seconds = %0.2f pages per second, file size %d kb' % (
+ pages, elapsed, speed, fileSize)
+ import md5
+ print 'file digest: %s' % md5.md5(open('odyssey.pdf','rb').read()).hexdigest()
+
+if __name__=='__main__':
+ quiet = ('-q' in sys.argv)
+ run(verbose = not quiet)
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/odyssey/odyssey.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,207 @@
+Provided by The Internet Classics Archive.
+See bottom for copyright. Available online at
+ http://classics.mit.edu//Homer/odyssey.html
+
+The Odyssey
+By Homer
+
+
+Translated by Samuel Butler
+
+----------------------------------------------------------------------
+
+BOOK I
+<bullet indent="-18"><font name="courier" size="13" color="blue">I</font></bullet><font color="green"><b><i>Tell</i></b></font> me, O muse, of that ingenious hero who travelled far and wide
+ a b c &| & | <b>A</b>' <b>A</b> ' after he had sacked the famous town of <font color="red" size="12"><b>Troy</b></font>. Many cities did he visit,
+and many were the nations with whose manners and customs he was acquainted;
+moreover he suffered much by sea while trying to save his own life
+and bring his men safely home; but do what he might he could not
+save<super><font color="red">1</font></super>
+his men, for they perished through their own sheer folly in eating
+the cattle of the Sun-god Hyperion; so the god prevented them from
+ever reaching home. Tell me, too, about all these things, O daughter
+of Jove, from whatsoever source you may know them.
+
+So now all who escaped death in battle or by shipwreck had got safely
+home except Ulysses, and he, though he was longing to return to his
+wife and country, was detained by the goddess Calypso, who had got
+him into a large cave and wanted to marry him. But as years went by,
+there came a time when the gods settled that he should go back to
+Ithaca; even then, however, when he was among his own people, his
+troubles were not yet over; nevertheless all the gods had now begun
+to pity him except Neptune, who still persecuted him without ceasing
+and would not let him get home.
+
+<font color="green">Now Neptune had gone off to the Ethiopians, who are at the world's
+end, and lie in two halves, the one looking West and the other East.
+He had gone there to accept a hecatomb of sheep and oxen, and was
+enjoying himself at his festival; but the other gods met in the house
+of Olympian Jove, and the sire of gods and men spoke first. At that
+moment he was thinking of Aegisthus, who had been killed by Agamemnon's
+son Orestes; so he said to the other gods:</font>
+
+"See now, how men lay blame upon us gods for what is after all nothing
+but their own folly. Look at Aegisthus; he must needs make love to
+Agamemnon's wife unrighteously and then kill Agamemnon, though he
+knew it would be the death of him; for I sent Mercury to warn him
+not to do either of these things, inasmuch as Orestes would be sure
+to take his revenge when he grew up and wanted to return home. Mercury
+told him this in all good will but he would not listen, and now he
+has paid for everything in full."
+
+Then Minerva said, "Father, son of Saturn, King of kings, it served
+Aegisthus right, and so it would any one else who does as he did;
+but Aegisthus is neither here nor there; it is for Ulysses that my
+heart bleeds, when I think of his sufferings in that lonely sea-girt
+island, far away, poor man, from all his friends. It is an island
+covered with forest, in the very middle of the sea, and a goddess
+lives there, daughter of the magician Atlas, who looks after the bottom
+of the ocean, and carries the great columns that keep heaven and earth
+asunder. This daughter of Atlas has got hold of poor unhappy Ulysses,
+and keeps trying by every kind of blandishment to make him forget
+his home, so that he is tired of life, and thinks of nothing but how
+he may once more see the smoke of his own chimneys. You, sir, take
+no heed of this, and yet when Ulysses was before Troy did he not propitiate
+you with many a burnt sacrifice? Why then should you keep on being
+so angry with him?"
+
+And Jove said, "My child, what are you talking about? How can I forget
+Ulysses than whom there is no more capable man on earth, nor more
+liberal in his offerings to the immortal gods that live in heaven?
+Bear in mind, however, that Neptune is still furious with Ulysses
+for having blinded an eye of Polyphemus king of the Cyclopes. Polyphemus
+is son to Neptune by the nymph Thoosa, daughter to the sea-king Phorcys;
+therefore though he will not kill Ulysses outright, he torments him
+by preventing him from getting home. Still, let us lay our heads together
+and see how we can help him to return; Neptune will then be pacified,
+for if we are all of a mind he can hardly stand out against us."
+
+And Minerva said, "Father, son of Saturn, King of kings, if, then,
+the gods now mean that Ulysses should get home, we should first send
+Mercury to the Ogygian island to tell Calypso that we have made up
+our minds and that he is to return. In the meantime I will go to Ithaca,
+to put heart into Ulysses' son Telemachus; I will embolden him to
+call the Achaeans in assembly, and speak out to the suitors of his
+mother Penelope, who persist in eating up any number of his sheep
+and oxen; I will also conduct him to Sparta and to Pylos, to see if
+he can hear anything about the return of his dear father- for this
+will make people speak well of him."
+
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+Ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis ellipsis.
+
+"Men of Ithaca, it is all your own fault that things have turned out
+as they have; you would not listen to me, nor yet to Mentor, when
+we bade you check the folly of your sons who were doing much wrong
+in the wantonness of their hearts- wasting the substance and dishonouring
+the wife of a chieftain who they thought would not return. Now, however,
+let it be as I say, and do as I tell you. Do not go out against Ulysses,
+or you may find that you have been drawing down evil on your own heads."
+
+This was what he said, and more than half raised a loud shout, and
+at once left the assembly. But the rest stayed where they were, for
+the speech of Halitherses displeased them, and they sided with Eupeithes;
+they therefore hurried off for their armour, and when they had armed
+themselves, they met together in front of the city, and Eupeithes
+led them on in their folly. He thought he was going to avenge the
+murder of his son, whereas in truth he was never to return, but was
+himself to perish in his attempt.
+
+Then Minerva said to Jove, "Father, son of Saturn, king of kings,
+answer me this question- What do you propose to do? Will you set them
+fighting still further, or will you make peace between them?"
+
+And Jove answered, "My child, why should you ask me? Was it not by
+your own arrangement that Ulysses came home and took his revenge upon
+the suitors? Do whatever you like, but I will tell you what I think
+will be most reasonable arrangement. Now that Ulysses is revenged,
+let them swear to a solemn covenant, in virtue of which he shall continue
+to rule, while we cause the others to forgive and forget the massacre
+of their sons and brothers. Let them then all become friends as heretofore,
+and let peace and plenty reign."
+
+This was what Minerva was already eager to bring about, so down she
+darted from off the topmost summits of Olympus.
+
+Now when Laertes and the others had done dinner, Ulysses began by
+saying, "Some of you go out and see if they are not getting close
+up to us." So one of Dolius's sons went as he was bid. Standing on
+the threshold he could see them all quite near, and said to Ulysses,
+"Here they are, let us put on our armour at once."
+
+They put on their armour as fast as they could- that is to say Ulysses,
+his three men, and the six sons of Dolius. Laertes also and Dolius
+did the same- warriors by necessity in spite of their grey hair. When
+they had all put on their armour, they opened the gate and sallied
+forth, Ulysses leading the way.
+
+Then Jove's daughter Minerva came up to them, having assumed the form
+and voice of Mentor. Ulysses was glad when he saw her, and said to
+his son Telemachus, "Telemachus, now that are about to fight in an
+engagement, which will show every man's mettle, be sure not to disgrace
+your ancestors, who were eminent for their strength and courage all
+the world over."
+
+"You say truly, my dear father," answered Telemachus, "and you shall
+see, if you will, that I am in no mind to disgrace your family."
+
+Laertes was delighted when he heard this. "Good heavens, he exclaimed,
+"what a day I am enjoying: I do indeed rejoice at it. My son and grandson
+are vying with one another in the matter of valour."
+
+On this Minerva came close up to him and said, "Son of Arceisius-
+best friend I have in the world- pray to the blue-eyed damsel, and
+to Jove her father; then poise your spear and hurl it."
+
+As she spoke she infused fresh vigour into him, and when he had prayed
+to her he poised his spear and hurled it. He hit Eupeithes' helmet,
+and the spear went right through it, for the helmet stayed it not,
+and his armour rang rattling round him as he fell heavily to the ground.
+Meantime Ulysses and his son fell the front line of the foe and smote
+them with their swords and spears; indeed, they would have killed
+every one of them, and prevented them from ever getting home again,
+only Minerva raised her voice aloud, and made every one pause. "Men
+of Ithaca," she cried, cease this dreadful war, and settle the matter
+at once without further bloodshed."
+
+On this pale fear seized every one; they were so frightened that their
+arms dropped from their hands and fell upon the ground at the sound
+of the goddess's voice, and they fled back to the city for their lives.
+But Ulysses gave a great cry, and gathering himself together swooped
+down like a soaring eagle. Then the son of Saturn sent a thunderbolt
+of fire that fell just in front of Minerva, so she said to Ulysses,
+"Ulysses, noble son of Laertes, stop this warful strife, or Jove will
+be angry with you."
+
+Thus spoke Minerva, and Ulysses obeyed her gladly. Then Minerva assumed
+the form and voice of Mentor, and presently made a covenant of peace
+between the two contending parties.
+
+THE END
+
+----------------------------------------------------------------------
+
+Copyright statement:
+The Internet Classics Archive by Daniel C. Stevenson, Web Atomics.
+World Wide Web presentation is copyright (C) 1994-1998, Daniel
+C. Stevenson, Web Atomics.
+All rights reserved under international and pan-American copyright
+conventions, including the right of reproduction in whole or in part
+in any form. Direct permission requests to classics@classics.mit.edu.
+Translation of "The Deeds of the Divine Augustus" by Augustus is
+copyright (C) Thomas Bushnell, BSG.
+
+
+To really test that reportlab can produce pages quickly download the
+complete version of the test from http://classics.mit.edu//Homer/odyssey.html
+and copy it to this directory as odyssey.full.txt.
+
+A zipped version of the full text is available for download at
+ftp://ftp.reportlab.com/odyssey.full.zip
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/rlzope/readme.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,73 @@
+# rlzope : an external Zope method to show people how to use
+# the ReportLab toolkit from within Zope.
+#
+# this method searches an image named 'logo' in the
+# ZODB then prints it at the top of a simple PDF
+# document made with ReportLab
+#
+# the resulting PDF document is returned to the
+# user's web browser and, if possible, it is
+# simultaneously saved into the ZODB.
+#
+# this method illustrates how to use both the platypus
+# and canvas frameworks.
+#
+# License : The ReportLab Toolkit's license (similar to BSD)
+#
+# Author : Jerome Alet - alet@unice.fr
+#
+
+Installation instructions :
+===========================
+
+ 0 - If not installed then install Zope.
+
+ 1 - Install reportlab in the Zope/lib/python/Shared directory by unpacking
+ the tarball and putting a reportlabs.pth file in site-packages for the Zope
+ used with Python. The path value in the reportlabs.pth file must be
+ relative. For a typical Zope installation, the path is "../../python/Shared".
+ Remember to restart Zope so the new path is instantiated.
+
+ 2 - Install PIL in the Zope/lib/python/Shared directory. You need to
+ ensure that the _imaging.so or .pyd is also installed appropriately.
+ It should be compatible with the python running the zope site.
+
+ 3 - Copy rlzope.py to your Zope installation's "Extensions"
+ subdirectory, e.g. /var/lib/zope/Extensions/ under Debian GNU/Linux.
+
+ 4 - From within Zope's management interface, add an External Method with
+ these parameters :
+
+ Id : rlzope
+ Title : rlzope
+ Module Name : rlzope
+ Function Name : rlzope
+
+ 5 - From within Zope's management interface, add an image called "logo"
+ in the same Folder than rlzope, or somewhere above in the Folder
+ hierarchy. For example you can use ReportLab's logo which you
+ can find in reportlab/docs/images/replogo.gif
+
+ 6 - Point your web browser to rlzope, e.g. on my laptop under
+ Debian GNU/Linux :
+
+ http://localhost:9673/rlzope
+
+ This will send a simple PDF document named 'dummy.pdf' to your
+ web browser, and if possible save it as a File object in the
+ Zope Object DataBase, with this name. Note, however, that if
+ an object with the same name already exists then it won't
+ be replaced for security reasons.
+
+ You can optionally add a parameter called 'name' with
+ a filename as the value, to specify another filename,
+ e.g. :
+logo
+ http://localhost:9673/rlzope?name=sample.pdf
+
+ 7 - Adapt it to your own needs.
+
+ 8 - Enjoy !
+
+Send comments or bug reports at : alet@unice.fr
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/rlzope/rlzope.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,169 @@
+#
+# Using the ReportLab toolkit from within Zope
+#
+# WARNING : The MyPDFDoc class deals with ReportLab's platypus framework,
+# while the MyPageTemplate class directly deals with ReportLab's
+# canvas, this way you know how to do with both...
+#
+# License : the ReportLab Toolkit's one
+# see : http://www.reportlab.com
+#
+# Author : Jerome Alet - alet@unice.fr
+#
+#
+
+import string, cStringIO
+try :
+ from Shared.reportlab.platypus.paragraph import Paragraph
+ from Shared.reportlab.platypus.doctemplate import *
+ from Shared.reportlab.lib.units import inch
+ from Shared.reportlab.lib import styles
+ from Shared.reportlab.lib.utils import ImageReader
+except ImportError :
+ from reportlab.platypus.paragraph import Paragraph
+ from reportlab.platypus.doctemplate import *
+ from reportlab.lib.units import inch
+ from reportlab.lib import styles
+ from reportlab.lib.utils import ImageReader
+
+class MyPDFDoc :
+ class MyPageTemplate(PageTemplate) :
+ """Our own page template."""
+ def __init__(self, parent) :
+ """Initialise our page template."""
+ #
+ # we must save a pointer to our parent somewhere
+ self.parent = parent
+
+ # Our doc is made of a single frame
+ content = Frame(0.75 * inch, 0.5 * inch, parent.document.pagesize[0] - 1.25 * inch, parent.document.pagesize[1] - (1.5 * inch))
+ PageTemplate.__init__(self, "MyTemplate", [content])
+
+ # get all the images we need now, in case we've got
+ # several pages this will save some CPU
+ self.logo = self.getImageFromZODB("logo")
+
+ def getImageFromZODB(self, name) :
+ """Retrieves an Image from the ZODB, converts it to PIL,
+ and makes it 0.75 inch high.
+ """
+ try :
+ # try to get it from ZODB
+ logo = getattr(self.parent.context, name)
+ except AttributeError :
+ # not found !
+ return None
+
+ # Convert it to PIL
+ image = ImageReader(cStringIO.StringIO(str(logo.data)))
+ (width, height) = image.getSize()
+
+ # scale it to be 0.75 inch high
+ multi = ((height + 0.0) / (0.75 * inch))
+ width = int(width / multi)
+ height = int(height / multi)
+
+ return ((width, height), image)
+
+ def beforeDrawPage(self, canvas, doc) :
+ """Draws a logo and an contribution message on each page."""
+ canvas.saveState()
+ if self.logo is not None :
+ # draws the logo if it exists
+ ((width, height), image) = self.logo
+ canvas.drawImage(image, inch, doc.pagesize[1] - inch, width, height)
+ canvas.setFont('Times-Roman', 10)
+ canvas.drawCentredString(inch + (doc.pagesize[0] - (1.5 * inch)) / 2, 0.25 * inch, "Contributed by Jerome Alet - alet@unice.fr")
+ canvas.restoreState()
+
+ def __init__(self, context, filename) :
+ # save some datas
+ self.context = context
+ self.built = 0
+ self.objects = []
+
+ # we will build an in-memory document
+ # instead of creating an on-disk file.
+ self.report = cStringIO.StringIO()
+
+ # initialise a PDF document using ReportLab's platypus
+ self.document = BaseDocTemplate(self.report)
+
+ # add our page template
+ # (we could add more than one, but I prefer to keep it simple)
+ self.document.addPageTemplates(self.MyPageTemplate(self))
+
+ # get the default style sheets
+ self.StyleSheet = styles.getSampleStyleSheet()
+
+ # then build a simple doc with ReportLab's platypus
+ sometext = "A sample script to show how to use ReportLab from within Zope"
+ url = self.escapexml(context.absolute_url())
+ urlfilename = self.escapexml(context.absolute_url() + '/%s' % filename)
+ self.append(Paragraph("Using ReportLab from within Zope", self.StyleSheet["Heading3"]))
+ self.append(Spacer(0, 10))
+ self.append(Paragraph("You launched it from : %s" % url, self.StyleSheet['Normal']))
+ self.append(Spacer(0, 40))
+ self.append(Paragraph("If possible, this report will be automatically saved as : %s" % urlfilename, self.StyleSheet['Normal']))
+
+ # generation du document PDF
+ self.document.build(self.objects)
+ self.built = 1
+
+ def __str__(self) :
+ """Returns the PDF document as a string of text, or None if it's not ready yet."""
+ if self.built :
+ return self.report.getvalue()
+ else :
+ return None
+
+ def append(self, object) :
+ """Appends an object to our platypus "story" (using ReportLab's terminology)."""
+ self.objects.append(object)
+
+ def escapexml(self, s) :
+ """Escape some xml entities."""
+ s = string.strip(s)
+ s = string.replace(s, "&", "&")
+ s = string.replace(s, "<", "<")
+ return string.replace(s, ">", ">")
+
+def rlzope(self) :
+ """A sample external method to show people how to use ReportLab from within Zope."""
+ try:
+ #
+ # which file/object name to use ?
+ # append ?name=xxxxx to rlzope's url to
+ # choose another name
+ filename = self.REQUEST.get("name", "dummy.pdf")
+ if filename[-4:] != '.pdf' :
+ filename = filename + '.pdf'
+
+ # tell the browser we send some PDF document
+ # with the requested filename
+
+ # get the document's content itself as a string of text
+ content = str(MyPDFDoc(self, filename))
+
+ # we will return it to the browser, but before that we also want to
+ # save it into the ZODB into the current folder
+ try :
+ self.manage_addFile(id = filename, file = content, title = "A sample PDF document produced with ReportLab", precondition = '', content_type = "application/pdf")
+ except :
+ # it seems an object with this name already exists in the ZODB:
+ # it's more secure to not replace it, since we could possibly
+ # destroy an important PDF document of this name.
+ pass
+ self.REQUEST.RESPONSE.setHeader('Content-Type', 'application/pdf')
+ self.REQUEST.RESPONSE.setHeader('Content-Disposition', 'attachment; filename=%s' % filename)
+ except:
+ import traceback, sys, cgi
+ content = sys.stdout = sys.stderr = cStringIO.StringIO()
+ self.REQUEST.RESPONSE.setHeader('Content-Type', 'text/html')
+ traceback.print_exc()
+ sys.stdout = sys.__stdout__
+ sys.stderr = sys.__stderr__
+ content = '<html><head></head><body><pre>%s</pre></body></html>' % cgi.escape(content.getvalue())
+
+ # then we also return the PDF content to the browser
+ return content
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/stdfonts/00readme.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,7 @@
+This lists out the standard 14 fonts
+in a very plain and simple fashion.
+
+Notably, the output is huge - it makes
+two separate text objects for each glyph.
+Smarter programming would make tighter
+PDF, but more lines of Python!
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/stdfonts/stdfonts.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,74 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/stdfonts/stdfonts.py
+__version__=''' $Id$ '''
+__doc__="""
+This generates tables showing the 14 standard fonts in both
+WinAnsi and MacRoman encodings, and their character codes.
+Supply an argument of 'hex' or 'oct' to get code charts
+in those encodings; octal is what you need for \\n escape
+sequences in Python literals.
+
+usage: standardfonts.py [dec|hex|oct]
+"""
+import sys
+from reportlab.pdfbase import pdfmetrics
+from reportlab.pdfgen import canvas
+import string
+
+label_formats = {'dec':('%d=', 'Decimal'),
+ 'oct':('%o=','Octal'),
+ 'hex':('0x%x=', 'Hexadecimal')}
+
+def run(mode):
+
+ label_formatter, caption = label_formats[mode]
+
+ for enc in ['MacRoman', 'WinAnsi']:
+ canv = canvas.Canvas(
+ 'StandardFonts_%s.pdf' % enc,
+ )
+ canv.setPageCompression(0)
+
+ for faceName in pdfmetrics.standardFonts:
+ if faceName in ['Symbol', 'ZapfDingbats']:
+ encLabel = faceName+'Encoding'
+ else:
+ encLabel = enc + 'Encoding'
+
+ fontName = faceName + '-' + encLabel
+ pdfmetrics.registerFont(pdfmetrics.Font(fontName,
+ faceName,
+ encLabel)
+ )
+
+ canv.setFont('Times-Bold', 18)
+ canv.drawString(80, 744, fontName)
+ canv.setFont('Times-BoldItalic', 12)
+ canv.drawRightString(515, 744, 'Labels in ' + caption)
+
+
+ #for dingbats, we need to use another font for the numbers.
+ #do two parallel text objects.
+ for byt in range(32, 256):
+ col, row = divmod(byt - 32, 32)
+ x = 72 + (66*col)
+ y = 720 - (18*row)
+ canv.setFont('Helvetica', 14)
+ canv.drawString(x, y, label_formatter % byt)
+ canv.setFont(fontName, 14)
+ canv.drawString(x+44, y, chr(byt).decode(encLabel,'ignore').encode('utf8'))
+ canv.showPage()
+ canv.save()
+
+if __name__ == '__main__':
+ if len(sys.argv)==2:
+ mode = string.lower(sys.argv[1])
+ if mode not in ['dec','oct','hex']:
+ print __doc__
+
+ elif len(sys.argv) == 1:
+ mode = 'dec'
+ run(mode)
+ else:
+ print __doc__
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/demos/tests/testdemos.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,14 @@
+#!/bin/env python
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/demos/tests/testdemos.py
+__version__=''' $Id$ '''
+__doc__='Test all demos'
+_globals=globals().copy()
+import os, sys
+from reportlab import pdfgen
+
+for p in ('pythonpoint/pythonpoint.py','stdfonts/stdfonts.py','odyssey/odyssey.py', 'gadflypaper/gfe.py'):
+ fn = os.path.normcase(os.path.normpath(os.path.join(os.path.dirname(pdfgen.__file__),'..','demos',p)))
+ os.chdir(os.path.dirname(fn))
+ execfile(fn,_globals.copy())
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/00readme.txt Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,7 @@
+Thid directory holds documentation. For end users,
+it should contain a number of PDF manuals. For
+people working with the source, this directory will
+be the destination for any manuals built.
+
+If you don't see the pdf manual you expected or you wich to
+ensure an up to date copy run the script tools/genAll.py!
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/genAll.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,37 @@
+#!/bin/env python
+import os, sys, traceback
+def _genAll(d=None,verbose=1):
+ if not d: d = '.'
+ if not os.path.isabs(d):
+ d = os.path.normpath(os.path.join(os.getcwd(),d))
+ L = ['reference/genreference.py',
+ 'userguide/genuserguide.py',
+ 'graphguide/gengraphguide.py',
+ '../tools/docco/graphdocpy.py',
+ ]
+ if os.path.isdir('../rl_addons'):
+ L = L + ['../rl_addons/pyRXP/docs/PyRXP_Documentation.rml']
+ elif os.path.isdir('../../rl_addons'):
+ L = L + ['../../rl_addons/pyRXP/docs/PyRXP_Documentation.rml']
+ for p in L:
+ os.chdir(d)
+ os.chdir(os.path.dirname(p))
+ if p[-4:]=='.rml':
+ try:
+ from rlextra.rml2pdf.rml2pdf import main
+ main(exe=0,fn=[os.path.basename(p)], quiet=not verbose, outDir=d)
+ except:
+ if verbose: traceback.print_exc()
+ else:
+ cmd = '%s %s %s' % (sys.executable,os.path.basename(p), not verbose and '-s' or '')
+ if verbose: print cmd
+ os.system(cmd)
+
+"""Runs the manual-building scripts"""
+if __name__=='__main__':
+ #need a quiet mode for the test suite
+ if '-s' in sys.argv: # 'silent
+ verbose = 0
+ else:
+ verbose = 1
+ _genAll(os.path.dirname(sys.argv[0]),verbose)
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/ch1_intro.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,105 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch1_intro.py
+from reportlab.tools.docco.rl_doc_utils import *
+import reportlab
+
+title("Graphics Guide")
+centred('ReportLab Version ' + reportlab.Version)
+
+nextTemplate("Normal")
+
+########################################################################
+#
+# Chapter 1
+#
+########################################################################
+
+
+heading1("Introduction")
+
+
+heading2("About this document")
+disc("""
+This document is intended to be a helpful and reasonably full
+introduction to the use of the ReportLab Graphics sub-package.
+Starting with simple drawings and shapes, we will take you through the
+slightly more complex reusable widgets all the way through to our
+powerful and flexible chart library. You will see examples of using
+reportlab/graphics to make bar charts, line charts, line plots, pie
+charts... and a smiley face.
+""")
+
+disc("""
+We presume that you have already installed both the Python programming
+language and the core ReportLab library. If you have not done either
+of these, look in the ReportLab User Guide where chapter one
+talks you through all the required steps.
+""")
+
+disc("""
+We recommend that you read some or all of the User Guide and have at
+least a basic understanding of how the ReportLab library works before
+you start getting to grips with ReportLab Graphics.
+""")
+
+disc("")
+todo("""
+Be warned! This document is in a <em>very</em> preliminary form. We need
+your help to make sure it is complete and helpful. Please send any
+feedback to our user mailing list, reportlab-users@reportlab.com.
+""")
+
+heading2("What is ReportLab?")
+disc("""ReportLab is a software library that lets you directly
+create documents in Adobe's Portable Document Format (PDF) using
+the Python programming language. """)
+
+disc("""The ReportLab library directly creates PDF based on
+your graphics commands. There are no intervening steps. Your applications
+can generate reports extremely fast - sometimes orders
+of magnitude faster than traditional report-writing
+tools.""")
+
+heading2("What is ReportLab Graphics?")
+disc("""
+ReportLab Graphics is one of the sub-packages to the ReportLab
+library. It started off as a stand-alone set of programs, but is now a
+fully integrated part of the ReportLab toolkit that allows you to use
+its powerful charting and graphics features to improve your PDF forms
+and reports.
+""")
+
+heading2("Getting Involved")
+disc("""ReportLab is an Open Source project. Although we are
+a commercial company we provide the core PDF generation
+sources freely, even for commercial purposes, and we make no income directly
+from these modules. We also welcome help from the community
+as much as any other Open Source project. There are many
+ways in which you can help:""")
+
+bullet("""General feedback on the core API. Does it work for you?
+Are there any rough edges? Does anything feel clunky and awkward?""")
+
+bullet("""New objects to put in reports, or useful utilities for the library.
+We have an open standard for report objects, so if you have written a nice
+chart or table class, why not contribute it?""")
+
+bullet("""Demonstrations and Case Studies: If you have produced some nice
+output, send it to us (with or without scripts). If ReportLab solved a
+problem for you at work, write a little 'case study' and send it in.
+And if your web site uses our tools to make reports, let us link to it.
+We will be happy to display your work (and credit it with your name
+and company) on our site!""")
+
+bullet("""Working on the core code: we have a long list of things
+to refine or to implement. If you are missing some features or
+just want to help out, let us know!""")
+
+disc("""The first step for anyone wanting to learn more or
+get involved is to join the mailing list. To Subscribe visit
+$http://two.pairlist.net/mailman/listinfo/reportlab-users$.
+From there you can also browse through the group's archives
+and contributions. The mailing list is
+the place to report bugs and get support. """)
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/ch2_concepts.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,376 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch2_concepts.py
+from reportlab.tools.docco.rl_doc_utils import *
+
+heading1("General Concepts")
+
+disc("""
+In this chapter we will present some of the more fundamental principles of
+the graphics library, which will show-up later in various places.
+""")
+
+
+heading2("Drawings and Renderers")
+
+disc("""
+A <i>Drawing</i> is a platform-independent description of a collection of
+shapes.
+It is not directly associated with PDF, Postscript or any other output
+format.
+Fortunately, most vector graphics systems have followed the Postscript
+model and it is possible to describe shapes unambiguously.
+""")
+
+disc("""
+A drawing contains a number of primitive <i>Shapes</i>.
+Normal shapes are those widely known as rectangles, circles, lines,
+etc.
+One special (logic) shape is a <i>Group</i>, which can hold other
+shapes and apply a transformation to them.
+Groups represent composites of shapes and allow to treat the
+composite as if it were a single shape.
+Just about anything can be built up from a small number of basic
+shapes.
+""")
+
+disc("""
+The package provides several <i>Renderers</i> which know how to draw a
+drawing into different formats.
+These include PDF (of course), Postscript, and bitmap output.
+The bitmap renderer uses Raph Levien's <i>libart</i> rasterizer
+and Fredrik Lundh's <i>Python Imaging Library</i> (PIL).
+Very recently, an experimental SVG renderer was also added.
+It makes use of Python's standard library XML modules, so you don't
+need to install the XML-SIG's additional package named PyXML.
+If you have the right extensions installed, you can generate drawings
+in bitmap form for the web as well as vector form for PDF documents,
+and get "identical output".
+""")
+
+disc("""
+The PDF renderer has special "privileges" - a Drawing object is also
+a <i>Flowable</i> and, hence, can be placed directly in the story
+of any Platypus document, or drawn directly on a <i>Canvas</i> with
+one line of code.
+In addition, the PDF renderer has a utility function to make
+a one-page PDF document quickly.
+""")
+
+disc("""
+The SVG renderer is special as it is still pretty experimental.
+The SVG code it generates is not really optimised in any way and
+maps only the features available in ReportLab Graphics (RLG) to
+SVG. This means there is no support for SVG animation, interactivity,
+scripting or more sophisticated clipping, masking or graduation
+shapes.
+So, be careful, and please report any bugs you find!
+""")
+
+disc("""
+We expect to add both input and output filters for many vector
+graphics formats in future.
+SVG was the most prominent first one to start with for which there
+is now an output filter in the graphics package.
+An SVG input filter will probably become available in Summer 2002
+as an additional module.
+GUIs will be able to obtain screen images from the bitmap output
+filter working with PIL, so a chart could appear in a Tkinter
+GUI window.
+""")
+
+
+heading2("Coordinate System")
+
+disc("""
+The Y-direction in our X-Y coordinate system points from the
+bottom <i>up</i>.
+This is consistent with PDF, Postscript and mathematical notation.
+It also appears to be more natural for people, especially when
+working with charts.
+Note that in other graphics models (such as SVG) the Y-coordinate
+points <i>down</i>.
+For the SVG renderer this is actually no problem as it will take
+your drawings and flip things as needed, so your SVG output looks
+just as expected.
+""")
+
+disc("""
+The X-coordinate points, as usual, from left to right.
+So far there doesn't seem to be any model advocating the opposite
+direction - at least not yet (with interesting exceptions, as it
+seems, for Arabs looking at time series charts...).
+""")
+
+
+heading2("Getting Started")
+
+disc("""
+Let's create a simple drawing containing the string "Hello World",
+displayed on top of a coloured rectangle.
+After creating it we will save the drawing to a standalone PDF file.
+""")
+
+eg("""
+ from reportlab.lib import colors
+ from reportlab.graphics.shapes import *
+
+ d = Drawing(400, 200)
+ d.add(Rect(50, 50, 300, 100, fillColor=colors.yellow))
+ d.add(String(150,100, 'Hello World',
+ fontSize=18, fillColor=colors.red))
+
+ from reportlab.graphics import renderPDF
+ renderPDF.drawToFile(d, 'example1.pdf', 'My First Drawing')
+""")
+
+disc("This will produce a PDF file containing the following graphic:")
+
+from reportlab.graphics.shapes import *
+from reportlab.graphics import testshapes
+t = testshapes.getDrawing01()
+draw(t, "'Hello World'")
+
+disc("""
+Each renderer is allowed to do whatever is appropriate for its format,
+and may have whatever API is needed.
+If it refers to a file format, it usually has a $drawToFile$ function,
+and that's all you need to know about the renderer.
+Let's save the same drawing in Encapsulated Postscript format:
+""")
+
+##eg("""
+## from reportlab.graphics import renderPS
+## renderPS.drawToFile(D, 'example1.eps', 'My First Drawing')
+##""")
+eg("""
+ from reportlab.graphics import renderPS
+ renderPS.drawToFile(d, 'example1.eps')
+""")
+
+disc("""
+This will produce an EPS file with the identical drawing, which
+may be imported into publishing tools such as Quark Express.
+If we wanted to generate the same drawing as a bitmap file for
+a website, say, all we need to do is write code like this:
+""")
+
+eg("""
+ from reportlab.graphics import renderPM
+ renderPM.drawToFile(d, 'example1.png', 'PNG')
+""")
+
+disc("""
+Many other bitmap formats, like GIF, JPG, TIFF, BMP and PPN are
+genuinely available, making it unlikely you'll need to add external
+postprocessing steps to convert to the final format you need.
+""")
+
+disc("""
+To produce an SVG file containing the identical drawing, which
+may be imported into graphical editing tools such as Illustrator
+all we need to do is write code like this:
+""")
+
+eg("""
+ from reportlab.graphics import renderSVG
+ renderSVG.drawToFile(d, 'example1.svg')
+""")
+
+
+heading2("Attribute Verification")
+
+disc("""
+Python is very dynamic and lets us execute statements at run time that
+can easily be the source for unexpected behaviour.
+One subtle 'error' is when assigning to an attribute that the framework
+doesn't know about because the used attribute's name contains a typo.
+Python lets you get away with it (adding a new attribute to an object,
+say), but the graphics framework will not detect this 'typo' without
+taking special counter-measures.
+""")
+
+disc("""
+There are two verification techniques to avoid this situation.
+The default is for every object to check every assignment at run
+time, such that you can only assign to 'legal' attributes.
+This is what happens by default.
+As this imposes a small performance penalty, this behaviour can
+be turned off when you need it to be.
+""")
+
+eg("""
+>>> r = Rect(10,10,200,100, fillColor=colors.red)
+>>>
+>>> r.fullColor = colors.green # note the typo
+>>> r.x = 'not a number' # illegal argument type
+>>> del r.width # that should confuse it
+""")
+
+disc("""
+These statements would be caught by the compiler in a statically
+typed language, but Python lets you get away with it.
+The first error could leave you staring at the picture trying to
+figure out why the colors were wrong.
+The second error would probably become clear only later, when
+some back-end tries to draw the rectangle.
+The third, though less likely, results in an invalid object that
+would not know how to draw itself.
+""")
+
+eg("""
+>>> r = shapes.Rect(10,10,200,80)
+>>> r.fullColor = colors.green
+Traceback (most recent call last):
+ File "<interactive input>", line 1, in ?
+ File "C:\code\users\andy\graphics\shapes.py", line 254, in __setattr__
+ validateSetattr(self,attr,value) #from reportlab.lib.attrmap
+ File "C:\code\users\andy\lib\attrmap.py", line 74, in validateSetattr
+ raise AttributeError, "Illegal attribute '%s' in class %s" % (name, obj.__class__.__name__)
+AttributeError: Illegal attribute 'fullColor' in class Rect
+>>>
+""")
+
+disc("""
+This imposes a performance penalty, so this behaviour can be turned
+off when you need it to be.
+To do this, you should use the following lines of code before you
+first import reportlab.graphics.shapes:
+""")
+
+eg("""
+>>> import reportlab.rl_config
+>>> reportlab.rl_config.shapeChecking = 0
+>>> from reportlab.graphics import shapes
+>>>
+""")
+
+disc("""
+Once you turn off $shapeChecking$, the classes are actually built
+without the verification hook; code should get faster, then.
+Currently the penalty seems to be about 25% on batches of charts,
+so it is hardly worth disabling.
+However, if we move the renderers to C in future (which is eminently
+possible), the remaining 75% would shrink to almost nothing and
+the saving from verification would be significant.
+""")
+
+disc("""
+Each object, including the drawing itself, has a $verify()$ method.
+This either succeeds, or raises an exception.
+If you turn off automatic verification, then you should explicitly
+call $verify()$ in testing when developing the code, or perhaps
+once in a batch process.
+""")
+
+
+heading2("Property Editing")
+
+disc("""
+A cornerstone of the reportlab/graphics which we will cover below is
+that you can automatically document widgets.
+This means getting hold of all of their editable properties,
+including those of their subcomponents.
+""")
+
+disc("""
+Another goal is to be able to create GUIs and config files for
+drawings.
+A generic GUI can be built to show all editable properties
+of a drawing, and let you modify them and see the results.
+The Visual Basic or Delphi development environment are good
+examples of this kind of thing.
+In a batch charting application, a file could list all the
+properties of all the components in a chart, and be merged
+with a database query to make a batch of charts.
+""")
+
+disc("""
+To support these applications we have two interfaces, $getProperties$
+and $setProperties$, as well as a convenience method $dumpProperties$.
+The first returns a dictionary of the editable properties of an
+object; the second sets them en masse.
+If an object has publicly exposed 'children' then one can recursively
+set and get their properties too.
+This will make much more sense when we look at <i>Widgets</i> later on,
+but we need to put the support into the base of the framework.
+""")
+
+eg("""
+>>> r = shapes.Rect(0,0,200,100)
+>>> import pprint
+>>> pprint.pprint(r.getProperties())
+{'fillColor': Color(0.00,0.00,0.00),
+ 'height': 100,
+ 'rx': 0,
+ 'ry': 0,
+ 'strokeColor': Color(0.00,0.00,0.00),
+ 'strokeDashArray': None,
+ 'strokeLineCap': 0,
+ 'strokeLineJoin': 0,
+ 'strokeMiterLimit': 0,
+ 'strokeWidth': 1,
+ 'width': 200,
+ 'x': 0,
+ 'y': 0}
+>>> r.setProperties({'x':20, 'y':30, 'strokeColor': colors.red})
+>>> r.dumpProperties()
+fillColor = Color(0.00,0.00,0.00)
+height = 100
+rx = 0
+ry = 0
+strokeColor = Color(1.00,0.00,0.00)
+strokeDashArray = None
+strokeLineCap = 0
+strokeLineJoin = 0
+strokeMiterLimit = 0
+strokeWidth = 1
+width = 200
+x = 20
+y = 30
+>>> """)
+
+disc("""
+<i>Note: $pprint$ is the standard Python library module that allows
+you to 'pretty print' output over multiple lines rather than having
+one very long line.</i>
+""")
+
+disc("""
+These three methods don't seem to do much here, but as we will see
+they make our widgets framework much more powerful when dealing with
+non-primitive objects.
+""")
+
+
+heading2("Naming Children")
+
+disc("""
+You can add objects to the $Drawing$ and $Group$ objects.
+These normally go into a list of contents.
+However, you may also give objects a name when adding them.
+This allows you to refer to and possibly change any element
+of a drawing after constructing it.
+""")
+
+eg("""
+>>> d = shapes.Drawing(400, 200)
+>>> s = shapes.String(10, 10, 'Hello World')
+>>> d.add(s, 'caption')
+>>> s.caption.text
+'Hello World'
+>>>
+""")
+
+disc("""
+Note that you can use the same shape instance in several contexts
+in a drawing; if you choose to use the same $Circle$ object in many
+locations (e.g. a scatter plot) and use different names to access
+it, it will still be a shared object and the changes will be
+global.
+""")
+
+disc("""
+This provides one paradigm for creating and modifying interactive
+drawings.
+""")
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/ch3_shapes.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,416 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch3_shapes.py
+
+from reportlab.tools.docco.rl_doc_utils import *
+from reportlab.graphics.shapes import *
+
+heading1("Shapes")
+
+disc("""
+This chapter describes the concept of shapes and their importance
+as building blocks for all output generated by the graphics library.
+Some properties of existing shapes and their relationship to
+diagrams are presented and the notion of having different renderers
+for different output formats is briefly introduced.
+""")
+
+heading2("Available Shapes")
+
+disc("""
+Drawings are made up of Shapes.
+Absolutely anything can be built up by combining the same set of
+primitive shapes.
+The module $shapes.py$ supplies a number of primitive shapes and
+constructs which can be added to a drawing.
+They are:
+""")
+
+bullet("Rect")
+bullet("Circle")
+bullet("Ellipse")
+bullet("Wedge (a pie slice)")
+bullet("Polygon")
+bullet("Line")
+bullet("PolyLine")
+bullet("String")
+bullet("Group")
+bullet("Path (<i>not implemented yet, but will be added in the future</i>)")
+
+disc("""
+The following drawing, taken from our test suite, shows most of the
+basic shapes (except for groups).
+Those with a filled green surface are also called <i>solid shapes</i>
+(these are $Rect$, $Circle$, $Ellipse$, $Wedge$ and $Polygon$).
+""")
+
+from reportlab.graphics import testshapes
+
+t = testshapes.getDrawing06()
+draw(t, "Basic shapes")
+
+
+heading2("Shape Properties")
+
+disc("""
+Shapes have two kinds of properties - some to define their geometry
+and some to define their style.
+Let's create a red rectangle with 3-point thick green borders:
+""")
+
+eg("""
+>>> from reportlab.graphics.shapes import Rect
+>>> from reportlab.lib.colors import red, green
+>>> r = Rect(5, 5, 200, 100)
+>>> r.fillColor = red
+>>> r.strokeColor = green
+>>> r.strokeWidth = 3
+>>>
+""")
+
+from reportlab.graphics.shapes import Rect
+from reportlab.lib.colors import red, green
+d = Drawing(220, 120)
+r = Rect(5, 5, 200, 100)
+r.fillColor = red
+r.strokeColor = green
+r.strokeWidth = 3
+d.add(r)
+draw(d, "red rectangle with green border")
+
+disc("""
+<i>Note: In future examples we will omit the import statements.</i>
+""")
+
+disc("""
+All shapes have a number of properties which can be set.
+At an interactive prompt, we can use their <i>dumpProperties()</i>
+method to list these.
+Here's what you can use to configure a Rect:
+""")
+
+eg("""
+>>> r.dumpProperties()
+fillColor = Color(1.00,0.00,0.00)
+height = 100
+rx = 0
+ry = 0
+strokeColor = Color(0.00,0.50,0.00)
+strokeDashArray = None
+strokeLineCap = 0
+strokeLineJoin = 0
+strokeMiterLimit = 0
+strokeWidth = 3
+width = 200
+x = 5
+y = 5
+>>>
+""")
+
+disc("""
+Shapes generally have <i>style properties</i> and <i>geometry
+properties</i>.
+$x$, $y$, $width$ and $height$ are part of the geometry and must
+be provided when creating the rectangle, since it does not make
+much sense without those properties.
+The others are optional and come with sensible defaults.
+""")
+
+disc("""
+You may set other properties on subsequent lines, or by passing them
+as optional arguments to the constructor.
+We could also have created our rectangle this way:
+""")
+
+eg("""
+>>> r = Rect(5, 5, 200, 100,
+ fillColor=red,
+ strokeColor=green,
+ strokeWidth=3)
+""")
+
+disc("""
+Let's run through the style properties. $fillColor$ is obvious.
+$stroke$ is publishing terminology for the edge of a shape;
+the stroke has a color, width, possibly a dash pattern, and
+some (rarely used) features for what happens when a line turns
+a corner.
+$rx$ and $ry$ are optional geometric properties and are used to
+define the corner radius for a rounded rectangle.
+""")
+
+disc("All the other solid shapes share the same style properties.")
+
+
+heading2("Lines")
+
+disc("""
+We provide single straight lines, PolyLines and curves.
+Lines have all the $stroke*$ properties, but no $fillColor$.
+Here are a few Line and PolyLine examples and the corresponding
+graphics output:
+""")
+
+eg("""
+ Line(50,50, 300,100,
+ strokeColor=colors.blue, strokeWidth=5)
+ Line(50,100, 300,50,
+ strokeColor=colors.red,
+ strokeWidth=10,
+ strokeDashArray=[10, 20])
+ PolyLine([120,110, 130,150, 140,110, 150,150, 160,110,
+ 170,150, 180,110, 190,150, 200,110],
+ strokeWidth=2,
+ strokeColor=colors.purple)
+""")
+
+d = Drawing(400, 200)
+d.add(Line(50,50, 300,100,strokeColor=colors.blue, strokeWidth=5))
+d.add(Line(50,100, 300,50,
+ strokeColor=colors.red,
+ strokeWidth=10,
+ strokeDashArray=[10, 20]))
+d.add(PolyLine([120,110, 130,150, 140,110, 150,150, 160,110,
+ 170,150, 180,110, 190,150, 200,110],
+ strokeWidth=2,
+ strokeColor=colors.purple))
+draw(d, "Line and PolyLine examples")
+
+
+heading2("Strings")
+
+disc("""
+The ReportLab Graphics package is not designed for fancy text
+layout, but it can place strings at desired locations and with
+left/right/center alignment.
+Let's specify a $String$ object and look at its properties:
+""")
+
+eg("""
+>>> s = String(10, 50, 'Hello World')
+>>> s.dumpProperties()
+fillColor = Color(0.00,0.00,0.00)
+fontName = Times-Roman
+fontSize = 10
+text = Hello World
+textAnchor = start
+x = 10
+y = 50
+>>>
+""")
+
+disc("""
+Strings have a textAnchor property, which may have one of the
+values 'start', 'middle', 'end'.
+If this is set to 'start', x and y relate to the start of the
+string, and so on.
+This provides an easy way to align text.
+""")
+
+disc("""
+Strings use a common font standard: the Type 1 Postscript fonts
+present in Acrobat Reader.
+We can thus use the basic 14 fonts in ReportLab and get accurate
+metrics for them.
+We have recently also added support for extra Type 1 fonts
+and the renderers all know how to render Type 1 fonts.
+""")
+
+##Until now we have worked with bitmap renderers which have to use
+##TrueType fonts and which make some substitutions; this could lead
+##to differences in text wrapping or even the number of labels on
+##a chart between renderers.
+
+disc("""
+Here is a more fancy example using the code snippet below.
+Please consult the ReportLab User Guide to see how non-standard
+like 'LettErrorRobot-Chrome' fonts are being registered!
+""")
+
+eg("""
+ d = Drawing(400, 200)
+ for size in range(12, 36, 4):
+ d.add(String(10+size*2, 10+size*2, 'Hello World',
+ fontName='Times-Roman',
+ fontSize=size))
+
+ d.add(String(130, 120, 'Hello World',
+ fontName='Courier',
+ fontSize=36))
+
+ d.add(String(150, 160, 'Hello World',
+ fontName='LettErrorRobot-Chrome',
+ fontSize=36))
+""")
+
+from reportlab.pdfbase import pdfmetrics
+from reportlab import rl_config
+rl_config.warnOnMissingFontGlyphs = 0
+afmFile, pfbFile = getJustFontPaths()
+T1face = pdfmetrics.EmbeddedType1Face(afmFile, pfbFile)
+T1faceName = 'LettErrorRobot-Chrome'
+pdfmetrics.registerTypeFace(T1face)
+T1font = pdfmetrics.Font(T1faceName, T1faceName, 'WinAnsiEncoding')
+pdfmetrics.registerFont(T1font)
+
+d = Drawing(400, 200)
+for size in range(12, 36, 4):
+ d.add(String(10+size*2, 10+size*2, 'Hello World',
+ fontName='Times-Roman',
+ fontSize=size))
+
+d.add(String(130, 120, 'Hello World',
+ fontName='Courier',
+ fontSize=36))
+
+d.add(String(150, 160, 'Hello World',
+ fontName='LettErrorRobot-Chrome',
+ fontSize=36))
+
+draw(d, 'fancy font example')
+
+
+heading2("""Paths""")
+
+disc("""
+Postscript paths are a widely understood concept in graphics.
+They are not implemented in $reportlab/graphics$ as yet, but they
+will be, soon.
+""")
+
+# NB This commented out section is for 'future compatibility' - paths haven't
+# been implemented yet, but when they are we can uncomment this back in.
+
+ ##disc("""Postscript paths are a widely understood concept in graphics. A Path
+ ## is a way of defining a region in space. You put an imaginary pen down,
+ ## draw straight and curved segments, and even pick the pen up and move
+ ## it. At the end of this you have described a region, which may consist
+ ## of several distinct close shapes or unclosed lines. At the end, this
+ ## 'path' is 'stroked and filled' according to its properties. A Path has
+ ## the same style properties as a solid shape. It can be used to create
+ ## any irregular shape.""")
+ ##
+ ##disc("""In Postscript-based imaging models such as PDF, Postscript and SVG,
+ ## everything is done with paths. All the specific shapes covered above
+ ## are instances of paths; even text strings (which are shapes in which
+ ## each character is an outline to be filled). Here we begin creating a
+ ## path with a straight line and a bezier curve:""")
+ ##
+ ##eg("""
+ ##>>> P = Path(0,0, strokeWidth=3, strokeColor=red)
+ ##>>> P.lineTo(0, 50)
+ ##>>> P.curveTo(10,50,80,80,100,30)
+ ##>>>
+ ##""")
+
+ ##disc("""As well as being the only way to draw complex shapes, paths offer some
+ ## performance advantages in renderers which support them. If you want to
+ ## create a scatter plot with 5000 blue circles of different sizes, you
+ ## can create 5000 circles, or one path object. With the latter, you only
+ ## need to set the color and line width once. PINGO just remembers the
+ ## drawing sequence, and writes it out into the file. In renderers which
+ ## do not support paths, the renderer will still have to decompose it
+ ## into 5000 circles so you won't save anything.""")
+ ##
+ ##disc("""<b>Note that our current path implementation is an approximation; it
+ ## should be finished off accurately for PDF and PS.</b>""")
+
+
+heading2("Groups")
+
+disc("""
+Finally, we have Group objects.
+A group has a list of contents, which are other nodes.
+It can also apply a transformation - its contents can be rotated,
+scaled or shifted.
+If you know the math, you can set the transform directly.
+Otherwise it provides methods to rotate, scale and so on.
+Here we make a group which is rotated and translated:
+""")
+
+eg("""
+>>> g =Group(shape1, shape2, shape3)
+>>> g.rotate(30)
+>>> g.translate(50, 200)
+""")
+
+disc("""
+Groups provide a tool for reuse.
+You can make a bunch of shapes to represent some component - say,
+a coordinate system - and put them in one group called "Axis".
+You can then put that group into other groups, each with a different
+translation and rotation, and you get a bunch of axis.
+It is still the same group, being drawn in different places.
+""")
+
+disc("""Let's do this with some only slightly more code:""")
+
+eg("""
+ d = Drawing(400, 200)
+
+ Axis = Group(
+ Line(0,0,100,0), # x axis
+ Line(0,0,0,50), # y axis
+ Line(0,10,10,10), # ticks on y axis
+ Line(0,20,10,20),
+ Line(0,30,10,30),
+ Line(0,40,10,40),
+ Line(10,0,10,10), # ticks on x axis
+ Line(20,0,20,10),
+ Line(30,0,30,10),
+ Line(40,0,40,10),
+ Line(50,0,50,10),
+ Line(60,0,60,10),
+ Line(70,0,70,10),
+ Line(80,0,80,10),
+ Line(90,0,90,10),
+ String(20, 35, 'Axes', fill=colors.black)
+ )
+
+ firstAxisGroup = Group(Axis)
+ firstAxisGroup.translate(10,10)
+ d.add(firstAxisGroup)
+
+ secondAxisGroup = Group(Axis)
+ secondAxisGroup.translate(150,10)
+ secondAxisGroup.rotate(15)
+
+ d.add(secondAxisGroup)
+
+ thirdAxisGroup = Group(Axis,
+ transform=mmult(translate(300,10),
+ rotate(30)))
+ d.add(thirdAxisGroup)
+""")
+
+d = Drawing(400, 200)
+Axis = Group(
+ Line(0,0,100,0), # x axis
+ Line(0,0,0,50), # y axis
+ Line(0,10,10,10), # ticks on y axis
+ Line(0,20,10,20),
+ Line(0,30,10,30),
+ Line(0,40,10,40),
+ Line(10,0,10,10), # ticks on x axis
+ Line(20,0,20,10),
+ Line(30,0,30,10),
+ Line(40,0,40,10),
+ Line(50,0,50,10),
+ Line(60,0,60,10),
+ Line(70,0,70,10),
+ Line(80,0,80,10),
+ Line(90,0,90,10),
+ String(20, 35, 'Axes', fill=colors.black)
+ )
+firstAxisGroup = Group(Axis)
+firstAxisGroup.translate(10,10)
+d.add(firstAxisGroup)
+secondAxisGroup = Group(Axis)
+secondAxisGroup.translate(150,10)
+secondAxisGroup.rotate(15)
+d.add(secondAxisGroup)
+thirdAxisGroup = Group(Axis,
+ transform=mmult(translate(300,10),
+ rotate(30)))
+d.add(thirdAxisGroup)
+draw(d, "Groups examples")
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/ch4_widgets.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,422 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch4_widgets.py
+
+from reportlab.tools.docco.rl_doc_utils import *
+from reportlab.graphics.shapes import *
+from reportlab.graphics.widgets import signsandsymbols
+
+heading1("Widgets")
+
+disc("""
+We now describe widgets and how they relate to shapes.
+Using many examples it is shown how widgets make reusable
+graphics components.
+""")
+
+
+heading2("Shapes vs. Widgets")
+
+disc("""Up until now, Drawings have been 'pure data'. There is no code in them
+ to actually do anything, except assist the programmer in checking and
+ inspecting the drawing. In fact, that's the cornerstone of the whole
+ concept and is what lets us achieve portability - a renderer only
+ needs to implement the primitive shapes.""")
+
+disc("""We want to build reusable graphic objects, including a powerful chart
+ library. To do this we need to reuse more tangible things than
+ rectangles and circles. We should be able to write objects for other
+ to reuse - arrows, gears, text boxes, UML diagram nodes, even fully
+ fledged charts.""")
+
+disc("""
+The Widget standard is a standard built on top of the shapes module.
+Anyone can write new widgets, and we can build up libraries of them.
+Widgets support the $getProperties()$ and $setProperties()$ methods,
+so you can inspect and modify as well as document them in a uniform
+way.
+""")
+
+bullet("A widget is a reusable shape ")
+bullet("""it can be initialized with no arguments
+ when its $draw()$ method is called it creates a primitive Shape or a
+ Group to represent itself""")
+bullet("""It can have any parameters you want, and they can drive the way it is
+ drawn""")
+bullet("""it has a $demo()$ method which should return an attractively drawn
+ example of itself in a 200x100 rectangle. This is the cornerstone of
+ the automatic documentation tools. The $demo()$ method should also have
+ a well written docstring, since that is printed too!""")
+
+disc("""Widgets run contrary to the idea that a drawing is just a bundle of
+ shapes; surely they have their own code? The way they work is that a
+ widget can convert itself to a group of primitive shapes. If some of
+ its components are themselves widgets, they will get converted too.
+ This happens automatically during rendering; the renderer will not see
+ your chart widget, but just a collection of rectangles, lines and
+ strings. You can also explicitly 'flatten out' a drawing, causing all
+ widgets to be converted to primitives.""")
+
+
+heading2("Using a Widget")
+
+disc("""
+Let's imagine a simple new widget.
+We will use a widget to draw a face, then show how it was implemented.""")
+
+eg("""
+>>> from reportlab.lib import colors
+>>> from reportlab.graphics import shapes
+>>> from reportlab.graphics import widgetbase
+>>> from reportlab.graphics import renderPDF
+>>> d = shapes.Drawing(200, 100)
+>>> f = widgetbase.Face()
+>>> f.skinColor = colors.yellow
+>>> f.mood = "sad"
+>>> d.add(f)
+>>> renderPDF.drawToFile(d, 'face.pdf', 'A Face')
+""")
+
+from reportlab.graphics import widgetbase
+d = Drawing(200, 120)
+f = widgetbase.Face()
+f.x = 50
+f.y = 10
+f.skinColor = colors.yellow
+f.mood = "sad"
+d.add(f)
+draw(d, 'A sample widget')
+
+disc("""
+Let's see what properties it has available, using the $setProperties()$
+method we have seen earlier:
+""")
+
+eg("""
+>>> f.dumpProperties()
+eyeColor = Color(0.00,0.00,1.00)
+mood = sad
+size = 80
+skinColor = Color(1.00,1.00,0.00)
+x = 10
+y = 10
+>>>
+""")
+
+disc("""
+One thing which seems strange about the above code is that we did not
+set the size or position when we made the face.
+This is a necessary trade-off to allow a uniform interface for
+constructing widgets and documenting them - they cannot require
+arguments in their $__init__()$ method.
+Instead, they are generally designed to fit in a 200 x 100
+window, and you move or resize them by setting properties such as
+x, y, width and so on after creation.
+""")
+
+disc("""
+In addition, a widget always provides a $demo()$ method.
+Simple ones like this always do something sensible before setting
+properties, but more complex ones like a chart would not have any
+data to plot.
+The documentation tool calls $demo()$ so that your fancy new chart
+class can create a drawing showing what it can do.
+""")
+
+disc("""
+Here are a handful of simple widgets available in the module
+<i>signsandsymbols.py</i>:
+""")
+
+from reportlab.graphics.shapes import Drawing
+from reportlab.graphics.widgets import signsandsymbols
+
+d = Drawing(230, 230)
+
+ne = signsandsymbols.NoEntry()
+ds = signsandsymbols.DangerSign()
+fd = signsandsymbols.FloppyDisk()
+ns = signsandsymbols.NoSmoking()
+
+ne.x, ne.y = 10, 10
+ds.x, ds.y = 120, 10
+fd.x, fd.y = 10, 120
+ns.x, ns.y = 120, 120
+
+d.add(ne)
+d.add(ds)
+d.add(fd)
+d.add(ns)
+
+draw(d, 'A few samples from signsandsymbols.py')
+
+disc("""
+And this is the code needed to generate them as seen in the drawing above:
+""")
+
+eg("""
+from reportlab.graphics.shapes import Drawing
+from reportlab.graphics.widgets import signsandsymbols
+
+d = Drawing(230, 230)
+
+ne = signsandsymbols.NoEntry()
+ds = signsandsymbols.DangerSign()
+fd = signsandsymbols.FloppyDisk()
+ns = signsandsymbols.NoSmoking()
+
+ne.x, ne.y = 10, 10
+ds.x, ds.y = 120, 10
+fd.x, fd.y = 10, 120
+ns.x, ns.y = 120, 120
+
+d.add(ne)
+d.add(ds)
+d.add(fd)
+d.add(ns)
+""")
+
+
+heading2("Compound Widgets")
+
+disc("""Let's imagine a compound widget which draws two faces side by side.
+ This is easy to build when you have the Face widget.""")
+
+eg("""
+>>> tf = widgetbase.TwoFaces()
+>>> tf.faceOne.mood
+'happy'
+>>> tf.faceTwo.mood
+'sad'
+>>> tf.dumpProperties()
+faceOne.eyeColor = Color(0.00,0.00,1.00)
+faceOne.mood = happy
+faceOne.size = 80
+faceOne.skinColor = None
+faceOne.x = 10
+faceOne.y = 10
+faceTwo.eyeColor = Color(0.00,0.00,1.00)
+faceTwo.mood = sad
+faceTwo.size = 80
+faceTwo.skinColor = None
+faceTwo.x = 100
+faceTwo.y = 10
+>>>
+""")
+
+disc("""The attributes 'faceOne' and 'faceTwo' are deliberately exposed so you
+ can get at them directly. There could also be top-level attributes,
+ but there aren't in this case.""")
+
+
+heading2("Verifying Widgets")
+
+disc("""The widget designer decides the policy on verification, but by default
+ they work like shapes - checking every assignment - if the designer
+ has provided the checking information.""")
+
+
+heading2("Implementing Widgets")
+
+disc("""We tried to make it as easy to implement widgets as possible. Here's
+ the code for a Face widget which does not do any type checking:""")
+
+eg("""
+class Face(Widget):
+ \"\"\"This draws a face with two eyes, mouth and nose.\"\"\"
+
+ def __init__(self):
+ self.x = 10
+ self.y = 10
+ self.size = 80
+ self.skinColor = None
+ self.eyeColor = colors.blue
+ self.mood = 'happy'
+
+ def draw(self):
+ s = self.size # abbreviate as we will use this a lot
+ g = shapes.Group()
+ g.transform = [1,0,0,1,self.x, self.y]
+ # background
+ g.add(shapes.Circle(s * 0.5, s * 0.5, s * 0.5,
+ fillColor=self.skinColor))
+ # CODE OMITTED TO MAKE MORE SHAPES
+ return g
+""")
+
+disc("""We left out all the code to draw the shapes in this document, but you
+ can find it in the distribution in $widgetbase.py$.""")
+
+disc("""By default, any attribute without a leading underscore is returned by
+ setProperties. This is a deliberate policy to encourage consistent
+ coding conventions.""")
+
+disc("""Once your widget works, you probably want to add support for
+ verification. This involves adding a dictionary to the class called
+ $_verifyMap$, which map from attribute names to 'checking functions'.
+ The $widgetbase.py$ module defines a bunch of checking functions with names
+ like $isNumber$, $isListOfShapes$ and so on. You can also simply use $None$,
+ which means that the attribute must be present but can have any type.
+ And you can and should write your own checking functions. We want to
+ restrict the "mood" custom attribute to the values "happy", "sad" or
+ "ok". So we do this:""")
+
+eg("""
+class Face(Widget):
+ \"\"\"This draws a face with two eyes. It exposes a
+ couple of properties to configure itself and hides
+ all other details\"\"\"
+ def checkMood(moodName):
+ return (moodName in ('happy','sad','ok'))
+ _verifyMap = {
+ 'x': shapes.isNumber,
+ 'y': shapes.isNumber,
+ 'size': shapes.isNumber,
+ 'skinColor':shapes.isColorOrNone,
+ 'eyeColor': shapes.isColorOrNone,
+ 'mood': checkMood
+ }
+""")
+
+disc("""This checking will be performed on every attribute assignment; or, if
+ $config.shapeChecking$ is off, whenever you call $myFace.verify()$.""")
+
+
+heading2("Documenting Widgets")
+
+disc("""
+We are working on a generic tool to document any Python package or
+module; this is already checked into ReportLab and will be used to
+generate a reference for the ReportLab package.
+When it encounters widgets, it adds extra sections to the
+manual including:""")
+
+bullet("the doc string for your widget class ")
+bullet("the code snippet from your <i>demo()</i> method, so people can see how to use it")
+bullet("the drawing produced by the <i>demo()</i> method ")
+bullet("the property dump for the widget in the drawing. ")
+
+disc("""
+This tool will mean that we can have guaranteed up-to-date
+documentation on our widgets and charts, both on the web site
+and in print; and that you can do the same for your own widgets,
+too!
+""")
+
+
+heading2("Widget Design Strategies")
+
+disc("""We could not come up with a consistent architecture for designing
+ widgets, so we are leaving that problem to the authors! If you do not
+ like the default verification strategy, or the way
+ $setProperties/getProperties$ works, you can override them yourself.""")
+
+disc("""For simple widgets it is recommended that you do what we did above:
+ select non-overlapping properties, initialize every property on
+ $__init__$ and construct everything when $draw()$ is called. You can
+ instead have $__setattr__$ hooks and have things updated when certain
+ attributes are set. Consider a pie chart. If you want to expose the
+ individual wedges, you might write code like this:""")
+
+eg("""
+from reportlab.graphics.charts import piecharts
+pc = piecharts.Pie()
+pc.defaultColors = [navy, blue, skyblue] #used in rotation
+pc.data = [10,30,50,25]
+pc.slices[7].strokeWidth = 5
+""")
+#removed 'pc.backColor = yellow' from above code example
+
+disc("""The last line is problematic as we have only created four wedges - in
+ fact we might not have created them yet. Does $pc.wedges[7]$ raise an
+ error? Is it a prescription for what should happen if a seventh wedge
+ is defined, used to override the default settings? We dump this
+ problem squarely on the widget author for now, and recommend that you
+ get a simple one working before exposing 'child objects' whose
+ existence depends on other properties' values :-)""")
+
+disc("""We also discussed rules by which parent widgets could pass properties
+ to their children. There seems to be a general desire for a global way
+ to say that 'all wedges get their lineWidth from the lineWidth of
+ their parent' without a lot of repetitive coding. We do not have a
+ universal solution, so again leave that to widget authors. We hope
+ people will experiment with push-down, pull-down and pattern-matching
+ approaches and come up with something nice. In the meantime, we
+ certainly can write monolithic chart widgets which work like the ones
+ in, say, Visual Basic and Delphi.""")
+
+disc("""For now have a look at the following sample code using an early
+ version of a pie chart widget and the output it generates:""")
+
+eg("""
+from reportlab.lib.colors import *
+from reportlab.graphics import shapes,renderPDF
+from reportlab.graphics.charts.piecharts import Pie
+
+d = Drawing(400,200)
+d.add(String(100,175,"Without labels", textAnchor="middle"))
+d.add(String(300,175,"With labels", textAnchor="middle"))
+
+pc = Pie()
+pc.x = 25
+pc.y = 50
+pc.data = [10,20,30,40,50,60]
+pc.slices[0].popout = 5
+d.add(pc, 'pie1')
+
+pc2 = Pie()
+pc2.x = 150
+pc2.y = 50
+pc2.data = [10,20,30,40,50,60]
+pc2.labels = ['a','b','c','d','e','f']
+d.add(pc2, 'pie2')
+
+pc3 = Pie()
+pc3.x = 275
+pc3.y = 50
+pc3.data = [10,20,30,40,50,60]
+pc3.labels = ['a','b','c','d','e','f']
+pc3.wedges.labelRadius = 0.65
+pc3.wedges.fontName = "Helvetica-Bold"
+pc3.wedges.fontSize = 16
+pc3.wedges.fontColor = colors.yellow
+d.add(pc3, 'pie3')
+""")
+
+# Hack to force a new paragraph before the todo() :-(
+disc("")
+
+from reportlab.lib.colors import *
+from reportlab.graphics import shapes,renderPDF
+from reportlab.graphics.charts.piecharts import Pie
+
+d = Drawing(400,200)
+d.add(String(100,175,"Without labels", textAnchor="middle"))
+d.add(String(300,175,"With labels", textAnchor="middle"))
+
+pc = Pie()
+pc.x = 25
+pc.y = 50
+pc.data = [10,20,30,40,50,60]
+pc.slices[0].popout = 5
+d.add(pc, 'pie1')
+
+pc2 = Pie()
+pc2.x = 150
+pc2.y = 50
+pc2.data = [10,20,30,40,50,60]
+pc2.labels = ['a','b','c','d','e','f']
+d.add(pc2, 'pie2')
+
+pc3 = Pie()
+pc3.x = 275
+pc3.y = 50
+pc3.data = [10,20,30,40,50,60]
+pc3.labels = ['a','b','c','d','e','f']
+pc3.slices.labelRadius = 0.65
+pc3.slices.fontName = "Helvetica-Bold"
+pc3.slices.fontSize = 16
+pc3.slices.fontColor = colors.yellow
+d.add(pc3, 'pie3')
+
+draw(d, 'Some sample Pies')
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/ch5_charts.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,1229 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/ch5_charts.py
+
+from reportlab.tools.docco.rl_doc_utils import *
+from reportlab.graphics.shapes import *
+
+heading1("Charts")
+
+disc("""
+The motivation for much of this is to create a flexible chart
+package.
+This chapter presents a treatment of the ideas behind our charting
+model, what the design goals are and what components of the chart
+package already exist.
+""")
+
+
+heading2("Design Goals")
+
+disc("Here are some of the design goals: ")
+
+disc("<i>Make simple top-level use really simple </i>")
+disc("""<para lindent=+36>It should be possible to create a simple chart with minimum lines of
+ code, yet have it 'do the right things' with sensible automatic
+ settings. The pie chart snippets above do this. If a real chart has
+ many subcomponents, you still should not need to interact with them
+ unless you want to customize what they do.""")
+
+disc("<i>Allow precise positioning </i>")
+disc("""<para lindent=+36>An absolute requirement in publishing and graphic design is to control
+ the placing and style of every element. We will try to have properties
+ that specify things in fixed sizes and proportions of the drawing,
+ rather than having automatic resizing. Thus, the 'inner plot
+ rectangle' will not magically change when you make the font size of
+ the y labels bigger, even if this means your labels can spill out of
+ the left edge of the chart rectangle. It is your job to preview the
+ chart and choose sizes and spaces which will work.""")
+
+disc("""<para lindent=+36>Some things do need to be automatic. For example, if you want to fit N
+ bars into a 200 point space and don't know N in advance, we specify
+ bar separation as a percentage of the width of a bar rather than a
+ point size, and let the chart work it out. This is still deterministic
+ and controllable.""")
+
+disc("<i>Control child elements individually or as a group</i>")
+disc("""<para lindent=+36>We use smart collection classes that let you customize a group of
+ things, or just one of them. For example you can do this in our
+ experimental pie chart:""")
+
+eg("""
+d = Drawing(400,200)
+pc = Pie()
+pc.x = 150
+pc.y = 50
+pc.data = [10,20,30,40,50,60]
+pc.labels = ['a','b','c','d','e','f']
+pc.slices.strokeWidth=0.5
+pc.slices[3].popout = 20
+pc.slices[3].strokeWidth = 2
+pc.slices[3].strokeDashArray = [2,2]
+pc.slices[3].labelRadius = 1.75
+pc.slices[3].fontColor = colors.red
+d.add(pc, '')
+""")
+
+disc("""<para lindent=+36>pc.slices[3] actually lazily creates a little object which holds
+ information about the slice in question; this will be used to format a
+ fourth slice at draw-time if there is one.""")
+
+disc("<i>Only expose things you should change </i>")
+disc("""<para lindent=+36>It would be wrong from a statistical viewpoint to let you directly
+ adjust the angle of one of the pie wedges in the above example, since
+ that is determined by the data. So not everything will be exposed
+ through the public properties. There may be 'back doors' to let you
+ violate this when you really need to, or methods to provide advanced
+ functionality, but in general properties will be orthogonal.""")
+
+disc("<i>Composition and component based </i>")
+disc("""<para lindent=+36>Charts are built out of reusable child widgets. A Legend is an
+ easy-to-grasp example. If you need a specialized type of legend (e.g.
+ circular colour swatches), you should subclass the standard Legend
+ widget. Then you could either do something like...""")
+
+eg("""
+c = MyChartWithLegend()
+c.legend = MyNewLegendClass() # just change it
+c.legend.swatchRadius = 5 # set a property only relevant to the new one
+c.data = [10,20,30] # and then configure as usual...
+""")
+
+disc("""<para lindent=+36>...or create/modify your own chart or drawing class which creates one
+ of these by default. This is also very relevant for time series
+ charts, where there can be many styles of x axis.""")
+
+disc("""<para lindent=+36>Top level chart classes will create a number of such components, and
+ then either call methods or set private properties to tell them their
+ height and position - all the stuff which should be done for you and
+ which you cannot customise. We are working on modelling what the
+ components should be and will publish their APIs here as a consensus
+ emerges.""")
+
+disc("<i>Multiples </i>")
+disc("""<para lindent=+36>A corollary of the component approach is that you can create diagrams
+ with multiple charts, or custom data graphics. Our favourite example
+ of what we are aiming for is the weather report in our gallery
+ contributed by a user; we'd like to make it easy to create such
+ drawings, hook the building blocks up to their legends, and feed that
+ data in a consistent way.""")
+disc("""<para lindent=+36>(If you want to see the image, it is available on our website at
+<font color=blue>http://www.reportlab.com/demos/provencio.pdf</font>)""")
+
+
+##heading2("Key Concepts and Components")
+heading2("Overview")
+
+disc("""A chart or plot is an object which is placed on a drawing; it is not
+ itself a drawing. You can thus control where it goes, put several on
+ the same drawing, or add annotations.""")
+
+disc("""Charts have two axes; axes may be Value or Category axes. Axes in turn
+ have a Labels property which lets you configure all text labels or
+ each one individually. Most of the configuration details which vary
+ from chart to chart relate to axis properties, or axis labels.""")
+
+disc("""Objects expose properties through the interfaces discussed in the
+ previous section; these are all optional and are there to let the end
+ user configure the appearance. Things which must be set for a chart to
+ work, and essential communication between a chart and its components,
+ are handled through methods.""")
+
+disc("""You can subclass any chart component and use your replacement instead
+ of the original provided you implement the essential methods and
+ properties.""")
+
+
+heading2("Labels")
+
+disc("""
+A label is a string of text attached to some chart element.
+They are used on axes, for titles or alongside axes, or attached
+to individual data points.
+Labels may contain newline characters, but only one font.
+""")
+
+disc("""The text and 'origin' of a label are typically set by its parent
+ object. They are accessed by methods rather than properties. Thus, the
+ X axis decides the 'reference point' for each tickmark label and the
+ numeric or date text for each label. However, the end user can set
+ properties of the label (or collection of labels) directly to affect
+ its position relative to this origin and all of its formatting.""")
+
+eg("""
+from reportlab.graphics import shapes
+from reportlab.graphics.charts.textlabels import Label
+
+d = Drawing(200, 100)
+
+# mark the origin of the label
+d.add(Circle(100,90, 5, fillColor=colors.green))
+
+lab = Label()
+lab.setOrigin(100,90)
+lab.boxAnchor = 'ne'
+lab.angle = 45
+lab.dx = 0
+lab.dy = -20
+lab.boxStrokeColor = colors.green
+lab.setText('Some\nMulti-Line\nLabel')
+
+d.add(lab)
+""")
+
+
+from reportlab.graphics import shapes
+from reportlab.graphics.charts.textlabels import Label
+
+d = Drawing(200, 100)
+
+# mark the origin of the label
+d.add(Circle(100,90, 5, fillColor=colors.green))
+
+lab = Label()
+lab.setOrigin(100,90)
+lab.boxAnchor = 'ne'
+lab.angle = 45
+lab.dx = 0
+lab.dy = -20
+lab.boxStrokeColor = colors.green
+lab.setText('Some\nMulti-Line\nLabel')
+
+d.add(lab)
+
+draw(d, 'Label example')
+
+
+
+disc("""
+In the drawing above, the label is defined relative to the green blob.
+The text box should have its north-east corner ten points down from
+the origin, and be rotated by 45 degrees about that corner.
+""")
+
+disc("""
+At present labels have the following properties, which we believe are
+sufficient for all charts we have seen to date:
+""")
+
+disc("")
+
+data=[["Property", "Meaning"],
+ ["dx", """The label's x displacement."""],
+ ["dy", """The label's y displacement."""],
+ ["angle", """The angle of rotation (counterclockwise) applied to the label."""],
+ ["boxAnchor", "The label's box anchor, one of 'n', 'e', 'w', 's', 'ne', 'nw', 'se', 'sw'."],
+ ["textAnchor", """The place where to anchor the label's text, one of 'start', 'middle', 'end'."""],
+ ["boxFillColor", """The fill color used in the label's box."""],
+ ["boxStrokeColor", "The stroke color used in the label's box."],
+ ["boxStrokeWidth", """The line width of the label's box."""],
+ ["fontName", """The label's font name."""],
+ ["fontSize", """The label's font size."""],
+ ["leading", """The leading value of the label's text lines."""],
+ ["x", """The X-coordinate of the reference point."""],
+ ["y", """The Y-coordinate of the reference point."""],
+ ["width", """The label's width."""],
+ ["height", """The label's height."""]
+ ]
+t=Table(data, colWidths=(100,330))
+t.setStyle(TableStyle([
+ ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
+ ('FONT',(0,1),(0,-1),'Courier',8,8),
+ ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
+ ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
+ ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
+ ('BOX', (0,0), (-1,-1), 0.25, colors.black),
+ ]))
+getStory().append(t)
+caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Label properties""")
+
+disc("""
+To see many more examples of $Label$ objects with different
+combinations of properties, please have a look into the
+ReportLab test suite in the folder $reportlab/test$, run the
+script $test_charts_textlabels.py$ and look at the PDF document
+it generates!
+""")
+
+
+
+heading2("Axes")
+
+disc("""
+We identify two basic kinds of axes - <i>Value</i> and <i>Category</i>
+ones.
+Both come in horizontal and vertical flavors.
+Both can be subclassed to make very specific kinds of axis.
+For example, if you have complex rules for which dates to display
+in a time series application, or want irregular scaling, you override
+the axis and make a new one.
+""")
+
+disc("""
+Axes are responsible for determining the mapping from data to image
+coordinates; transforming points on request from the chart; drawing
+themselves and their tickmarks, gridlines and axis labels.
+""")
+
+disc("""
+This drawing shows two axes, one of each kind, which have been created
+directly without reference to any chart:
+""")
+
+
+from reportlab.graphics import shapes
+from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis
+
+drawing = Drawing(400, 200)
+
+data = [(10, 20, 30, 40), (15, 22, 37, 42)]
+
+xAxis = XCategoryAxis()
+xAxis.setPosition(75, 75, 300)
+xAxis.configure(data)
+xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']
+xAxis.labels.boxAnchor = 'n'
+xAxis.labels[3].dy = -15
+xAxis.labels[3].angle = 30
+xAxis.labels[3].fontName = 'Times-Bold'
+
+yAxis = YValueAxis()
+yAxis.setPosition(50, 50, 125)
+yAxis.configure(data)
+
+drawing.add(xAxis)
+drawing.add(yAxis)
+
+draw(drawing, 'Two isolated axes')
+
+
+disc("Here is the code that created them: ")
+
+eg("""
+from reportlab.graphics import shapes
+from reportlab.graphics.charts.axes import XCategoryAxis,YValueAxis
+
+drawing = Drawing(400, 200)
+
+data = [(10, 20, 30, 40), (15, 22, 37, 42)]
+
+xAxis = XCategoryAxis()
+xAxis.setPosition(75, 75, 300)
+xAxis.configure(data)
+xAxis.categoryNames = ['Beer', 'Wine', 'Meat', 'Cannelloni']
+xAxis.labels.boxAnchor = 'n'
+xAxis.labels[3].dy = -15
+xAxis.labels[3].angle = 30
+xAxis.labels[3].fontName = 'Times-Bold'
+
+yAxis = YValueAxis()
+yAxis.setPosition(50, 50, 125)
+yAxis.configure(data)
+
+drawing.add(xAxis)
+drawing.add(yAxis)
+""")
+
+disc("""
+Remember that, usually, you won't have to create axes directly;
+when using a standard chart, it comes with ready-made axes.
+The methods are what the chart uses to configure it and take care
+of the geometry.
+However, we will talk through them in detail below.
+The orthogonally dual axes to those we describe have essentially
+the same properties, except for those refering to ticks.
+""")
+
+
+heading3("XCategoryAxis class")
+
+disc("""
+A Category Axis doesn't really have a scale; it just divides itself
+into equal-sized buckets.
+It is simpler than a value axis.
+The chart (or programmer) sets its location with the method
+$setPosition(x, y, length)$.
+The next stage is to show it the data so that it can configure
+itself.
+This is easy for a category axis - it just counts the number of
+data points in one of the data series. The $reversed$ attribute (if 1)
+indicates that the categories should be reversed.
+When the drawing is drawn, the axis can provide some help to the
+chart with its $scale()$ method, which tells the chart where
+a given category begins and ends on the page.
+We have not yet seen any need to let people override the widths
+or positions of categories.
+""")
+
+disc("An XCategoryAxis has the following editable properties:")
+
+disc("")
+
+data=[["Property", "Meaning"],
+ ["visible", """Should the axis be drawn at all? Sometimes you don't want
+to display one or both axes, but they still need to be there as
+they manage the scaling of points."""],
+ ["strokeColor", "Color of the axis"],
+ ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.
+Defaults to None"""],
+ ["strokeWidth", "Width of axis in points"],
+ ["tickUp", """How far above the axis should the tick marks protrude?
+(Note that making this equal to chart height gives you a gridline)"""],
+ ["tickDown", """How far below the axis should the tick mark protrude?"""],
+ ["categoryNames", """Either None, or a list of strings. This should have the
+same length as each data series."""],
+ ["labels", """A collection of labels for the tick marks. By default the 'north'
+of each text label (i.e top centre) is positioned 5 points down
+from the centre of each category on the axis. You may redefine
+any property of the whole label group or of any one label. If
+categoryNames=None, no labels are drawn."""],
+ ["title", """Not Implemented Yet. This needs to be like a label, but also
+lets you set the text directly. It would have a default
+location below the axis."""]]
+t=Table(data, colWidths=(100,330))
+t.setStyle(TableStyle([
+ ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
+ ('FONT',(0,1),(0,-1),'Courier',8,8),
+ ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
+ ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
+ ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
+ ('BOX', (0,0), (-1,-1), 0.25, colors.black),
+ ]))
+getStory().append(t)
+caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - XCategoryAxis properties""")
+
+
+heading3("YValueAxis")
+
+disc("""
+The left axis in the diagram is a YValueAxis.
+A Value Axis differs from a Category Axis in that each point along
+its length corresponds to a y value in chart space.
+It is the job of the axis to configure itself, and to convert Y values
+from chart space to points on demand to assist the parent chart in
+plotting.
+""")
+
+disc("""
+$setPosition(x, y, length)$ and $configure(data)$ work exactly as
+for a category axis.
+If you have not fully specified the maximum, minimum and tick
+interval, then $configure()$ results in the axis choosing suitable
+values.
+Once configured, the value axis can convert y data values to drawing
+space with the $scale()$ method.
+Thus:
+""")
+
+eg("""
+>>> yAxis = YValueAxis()
+>>> yAxis.setPosition(50, 50, 125)
+>>> data = [(10, 20, 30, 40),(15, 22, 37, 42)]
+>>> yAxis.configure(data)
+>>> yAxis.scale(10) # should be bottom of chart
+50.0
+>>> yAxis.scale(40) # should be near the top
+167.1875
+>>>
+""")
+
+disc("""By default, the highest data point is aligned with the top of the
+ axis, the lowest with the bottom of the axis, and the axis choose
+ 'nice round numbers' for its tickmark points. You may override these
+ settings with the properties below. """)
+
+disc("")
+
+data=[["Property", "Meaning"],
+ ["visible", """Should the axis be drawn at all? Sometimes you don't want
+to display one or both axes, but they still need to be there as
+they manage the scaling of points."""],
+ ["strokeColor", "Color of the axis"],
+ ["strokeDashArray", """Whether to draw axis with a dash and, if so, what kind.
+Defaults to None"""],
+ ["strokeWidth", "Width of axis in points"],
+ ["tickLeft", """How far to the left of the axis should the tick marks protrude?
+(Note that making this equal to chart height gives you a gridline)"""],
+ ["tickRight", """How far to the right of the axis should the tick mark protrude?"""],
+
+ ["valueMin", """The y value to which the bottom of the axis should correspond.
+Default value is None in which case the axis sets it to the lowest
+actual data point (e.g. 10 in the example above). It is common to set
+this to zero to avoid misleading the eye."""],
+ ["valueMax", """The y value to which the top of the axis should correspond.
+Default value is None in which case the axis sets it to the highest
+actual data point (e.g. 42 in the example above). It is common to set
+this to a 'round number' so data bars do not quite reach the top."""],
+ ["valueStep", """The y change between tick intervals. By default this is
+None, and the chart tries to pick 'nice round numbers' which are
+just wider than the minimumTickSpacing below."""],
+
+ ["valueSteps", """A list of numbers at which to place ticks."""],
+
+ ["minimumTickSpacing", """This is used when valueStep is set to None, and ignored
+otherwise. The designer specified that tick marks should be no
+closer than X points apart (based, presumably, on considerations
+of the label font size and angle). The chart tries values of the
+type 1,2,5,10,20,50,100... (going down below 1 if necessary) until
+it finds an interval which is greater than the desired spacing, and
+uses this for the step."""],
+ ["labelTextFormat", """This determines what goes in the labels. Unlike a category
+axis which accepts fixed strings, the labels on a ValueAxis are
+supposed to be numbers. You may provide either a 'format string'
+like '%0.2f' (show two decimal places), or an arbitrary function
+which accepts a number and returns a string. One use for the
+latter is to convert a timestamp to a readable year-month-day
+format."""],
+ ["title", """Not Implemented Yet. This needs to be like a label, but also
+lets you set the text directly. It would have a default
+location below the axis."""]]
+t=Table(data, colWidths=(100,330))
+t.setStyle(TableStyle([
+ ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
+ ('FONT',(0,1),(0,-1),'Courier',8,8),
+ ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
+ ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
+ ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
+ ('BOX', (0,0), (-1,-1), 0.25, colors.black),
+ ]))
+getStory().append(t)
+caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - YValueAxis properties""")
+
+disc("""
+The $valueSteps$ property lets you explicitly specify the
+tick mark locations, so you don't have to follow regular intervals.
+Hence, you can plot month ends and month end dates with a couple of
+helper functions, and without needing special time series chart
+classes.
+The following code show how to create a simple $XValueAxis$ with special
+tick intervals. Make sure to set the $valueSteps$ attribute before calling
+the configure method!
+""")
+
+eg("""
+from reportlab.graphics.shapes import Drawing
+from reportlab.graphics.charts.axes import XValueAxis
+
+drawing = Drawing(400, 100)
+
+data = [(10, 20, 30, 40)]
+
+xAxis = XValueAxis()
+xAxis.setPosition(75, 50, 300)
+xAxis.valueSteps = [10, 15, 20, 30, 35, 40]
+xAxis.configure(data)
+xAxis.labels.boxAnchor = 'n'
+
+drawing.add(xAxis)
+""")
+
+
+from reportlab.graphics import shapes
+from reportlab.graphics.charts.axes import XValueAxis
+
+drawing = Drawing(400, 100)
+
+data = [(10, 20, 30, 40)]
+
+xAxis = XValueAxis()
+xAxis.setPosition(75, 50, 300)
+xAxis.valueSteps = [10, 15, 20, 30, 35, 40]
+xAxis.configure(data)
+xAxis.labels.boxAnchor = 'n'
+
+drawing.add(xAxis)
+
+draw(drawing, 'An axis with non-equidistant tick marks')
+
+
+disc("""
+In addition to these properties, all axes classes have three
+properties describing how to join two of them to each other.
+Again, this is interesting only if you define your own charts
+or want to modify the appearance of an existing chart using
+such axes.
+These properties are listed here only very briefly for now,
+but you can find a host of sample functions in the module
+$reportlab/graphics/axes.py$ which you can examine...
+""")
+
+disc("""
+One axis is joined to another, by calling the method
+$joinToAxis(otherAxis, mode, pos)$ on the first axis,
+with $mode$ and $pos$ being the properties described by
+$joinAxisMode$ and $joinAxisPos$, respectively.
+$'points'$ means to use an absolute value, and $'value'$
+to use a relative value (both indicated by the the
+$joinAxisPos$ property) along the axis.
+""")
+
+disc("")
+
+data=[["Property", "Meaning"],
+ ["joinAxis", """Join both axes if true."""],
+ ["joinAxisMode", """Mode used for connecting axis ('bottom', 'top', 'left', 'right', 'value', 'points', None)."""],
+ ["joinAxisPos", """Position at which to join with other axis."""],
+ ]
+t=Table(data, colWidths=(100,330))
+t.setStyle(TableStyle([
+ ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
+ ('FONT',(0,1),(0,-1),'Courier',8,8),
+ ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
+ ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
+ ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
+ ('BOX', (0,0), (-1,-1), 0.25, colors.black),
+ ]))
+getStory().append(t)
+caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - Axes joining properties""")
+
+
+heading2("Bar Charts")
+
+disc("""
+This describes our current $VerticalBarChart$ class, which uses the
+axes and labels above.
+We think it is step in the right direction but is is
+far from final.
+Note that people we speak to are divided about 50/50 on whether to
+call this a 'Vertical' or 'Horizontal' bar chart.
+We chose this name because 'Vertical' appears next to 'Bar', so
+we take it to mean that the bars rather than the category axis
+are vertical.
+""")
+
+disc("""
+As usual, we will start with an example:
+""")
+
+from reportlab.graphics.shapes import Drawing
+from reportlab.graphics.charts.barcharts import VerticalBarChart
+
+drawing = Drawing(400, 200)
+
+data = [
+ (13, 5, 20, 22, 37, 45, 19, 4),
+ (14, 6, 21, 23, 38, 46, 20, 5)
+ ]
+
+bc = VerticalBarChart()
+bc.x = 50
+bc.y = 50
+bc.height = 125
+bc.width = 300
+bc.data = data
+bc.strokeColor = colors.black
+
+bc.valueAxis.valueMin = 0
+bc.valueAxis.valueMax = 50
+bc.valueAxis.valueStep = 10
+
+bc.categoryAxis.labels.boxAnchor = 'ne'
+bc.categoryAxis.labels.dx = 8
+bc.categoryAxis.labels.dy = -2
+bc.categoryAxis.labels.angle = 30
+bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
+ 'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
+
+drawing.add(bc)
+
+draw(drawing, 'Simple bar chart with two data series')
+
+
+eg("""
+ # code to produce the above chart
+
+ from reportlab.graphics.shapes import Drawing
+ from reportlab.graphics.charts.barcharts import VerticalBarChart
+
+ drawing = Drawing(400, 200)
+
+ data = [
+ (13, 5, 20, 22, 37, 45, 19, 4),
+ (14, 6, 21, 23, 38, 46, 20, 5)
+ ]
+
+ bc = VerticalBarChart()
+ bc.x = 50
+ bc.y = 50
+ bc.height = 125
+ bc.width = 300
+ bc.data = data
+ bc.strokeColor = colors.black
+
+ bc.valueAxis.valueMin = 0
+ bc.valueAxis.valueMax = 50
+ bc.valueAxis.valueStep = 10
+
+ bc.categoryAxis.labels.boxAnchor = 'ne'
+ bc.categoryAxis.labels.dx = 8
+ bc.categoryAxis.labels.dy = -2
+ bc.categoryAxis.labels.angle = 30
+ bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
+ 'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
+
+ drawing.add(bc)
+""")
+
+disc("""
+Most of this code is concerned with setting up the axes and
+labels, which we have already covered.
+Here are the top-level properties of the $VerticalBarChart$ class:
+""")
+
+disc("")
+
+data=[["Property", "Meaning"],
+ ["data", """This should be a "list of lists of numbers" or "list of
+tuples of numbers". If you have just one series, write it as
+data = [(10,20,30,42),]"""],
+ ["x, y, width, height", """These define the inner 'plot rectangle'. We
+highlighted this with a yellow border above. Note that it is
+your job to place the chart on the drawing in a way which leaves
+room for all the axis labels and tickmarks. We specify this 'inner
+rectangle' because it makes it very easy to lay out multiple charts
+in a consistent manner."""],
+ ["strokeColor", """Defaults to None. This will draw a border around the
+plot rectangle, which may be useful in debugging. Axes will
+overwrite this."""],
+ ["fillColor", """Defaults to None. This will fill the plot rectangle with
+a solid color. (Note that we could implement dashArray etc.
+as for any other solid shape)"""],
+ ["barLabelFormat", """This is a format string or function used for displaying
+labels above each bar. They are positioned automatically
+above the bar for positive values and below for negative ones."""],
+ ["useAbsolute", """Defaults to 0. If 1, the three properties below are
+absolute values in points (which means you can make a chart
+where the bars stick out from the plot rectangle); if 0,
+they are relative quantities and indicate the proportional
+widths of the elements involved."""],
+ ["barWidth", """As it says. Defaults to 10."""],
+ ["groupSpacing", """Defaults to 5. This is the space between each group of
+bars. If you have only one series, use groupSpacing and not
+barSpacing to split them up. Half of the groupSpacing is used
+before the first bar in the chart, and another half at the end."""],
+ ["barSpacing", """Defaults to 0. This is the spacing between bars in each
+group. If you wanted a little gap between green and red bars in
+the example above, you would make this non-zero."""],
+ ["barLabelFormat", """Defaults to None. As with the YValueAxis, if you supply
+a function or format string then labels will be drawn next
+to each bar showing the numeric value."""],
+ ["barLabels", """A collection of labels used to format all bar labels. Since
+this is a two-dimensional array, you may explicitly format the
+third label of the second series using this syntax:
+ chart.barLabels[(1,2)].fontSize = 12"""],
+ ["valueAxis", """The value axis, which may be formatted as described
+previously."""],
+ ["categoryAxis", """The category axis, which may be formatted as described
+previously."""],
+
+ ["title", """Not Implemented Yet. This needs to be like a label, but also
+lets you set the text directly. It would have a default
+location below the axis."""]]
+t=Table(data, colWidths=(100,330))
+t.setStyle(TableStyle([
+ ('FONT',(0,0),(-1,0),'Times-Bold',10,12),
+ ('FONT',(0,1),(0,-1),'Courier',8,8),
+ ('FONT',(1,1),(1,-1),'Times-Roman',10,12),
+ ('VALIGN',(0,0),(-1,-1),'MIDDLE'),
+ ('INNERGRID', (0,0), (-1,-1), 0.25, colors.black),
+ ('BOX', (0,0), (-1,-1), 0.25, colors.black),
+ ]))
+getStory().append(t)
+caption("""Table <seq template="%(Chapter)s-%(Table+)s"/> - VerticalBarChart properties""")
+
+
+disc("""
+From this table we deduce that adding the following lines to our code
+above should double the spacing between bar groups (the $groupSpacing$
+attribute has a default value of five points) and we should also see
+some tiny space between bars of the same group ($barSpacing$).
+""")
+
+eg("""
+ bc.groupSpacing = 10
+ bc.barSpacing = 2.5
+""")
+
+disc("""
+And, in fact, this is exactly what we can see after adding these
+lines to the code above.
+Notice how the width of the individual bars has changed as well.
+This is because the space added between the bars has to be 'taken'
+from somewhere as the total chart width stays unchanged.
+""")
+
+from reportlab.graphics.shapes import Drawing
+from reportlab.graphics.charts.barcharts import VerticalBarChart
+
+drawing = Drawing(400, 200)
+
+data = [
+ (13, 5, 20, 22, 37, 45, 19, 4),
+ (14, 6, 21, 23, 38, 46, 20, 5)
+ ]
+
+bc = VerticalBarChart()
+bc.x = 50
+bc.y = 50
+bc.height = 125
+bc.width = 300
+bc.data = data
+bc.strokeColor = colors.black
+
+bc.groupSpacing = 10
+bc.barSpacing = 2.5
+
+bc.valueAxis.valueMin = 0
+bc.valueAxis.valueMax = 50
+bc.valueAxis.valueStep = 10
+
+bc.categoryAxis.labels.boxAnchor = 'ne'
+bc.categoryAxis.labels.dx = 8
+bc.categoryAxis.labels.dy = -2
+bc.categoryAxis.labels.angle = 30
+bc.categoryAxis.categoryNames = ['Jan-99','Feb-99','Mar-99',
+ 'Apr-99','May-99','Jun-99','Jul-99','Aug-99']
+
+drawing.add(bc)
+
+draw(drawing, 'Like before, but with modified spacing')
+
+disc("""
+Bars labels are automatically displayed for negative values
+<i>below</i> the lower end of the bar for positive values
+<i>above</i> the upper end of the other ones.
+""")
+
+
+##Property Value
+##data This should be a "list of lists of numbers" or "list of tuples of numbers". If you have just one series, write it as
+##data = [(10,20,30,42),]
+##
+##x, y, width, height These define the inner 'plot rectangle'. We highlighted this with a yellow border above. Note that it is your job to place the chart on the drawing in a way which leaves room for all the axis labels and tickmarks. We specify this 'inner rectangle' because it makes it very easy to lay out multiple charts in a consistent manner.
+##strokeColor Defaults to None. This will draw a border around the plot rectangle, which may be useful in debugging. Axes will overwrite this.
+##fillColor Defaults to None. This will fill the plot rectangle with a solid color. (Note that we could implement dashArray etc. as for any other solid shape)
+##barLabelFormat This is a format string or function used for displaying labels above each bar. We're working on ways to position these labels so that they work for positive and negative bars.
+##useAbsolute Defaults to 0. If 1, the three properties below are absolute values in points (which means you can make a chart where the bars stick out from the plot rectangle); if 0, they are relative quantities and indicate the proportional widths of the elements involved.
+##barWidth As it says. Defaults to 10.
+##groupSpacing Defaults to 5. This is the space between each group of bars. If you have only one series, use groupSpacing and not barSpacing to split them up. Half of the groupSpacing is used before the first bar in the chart, and another half at the end.
+##barSpacing Defaults to 0. This is the spacing between bars in each group. If you wanted a little gap between green and red bars in the example above, you would make this non-zero.
+##barLabelFormat Defaults to None. As with the YValueAxis, if you supply a function or format string then labels will be drawn next to each bar showing the numeric value.
+##barLabels A collection of labels used to format all bar labels. Since this is a two-dimensional array, you may explicitly format the third label of the second series using this syntax:
+## chart.barLabels[(1,2)].fontSize = 12
+##
+##valueAxis The value axis, which may be formatted as described previously
+##categoryAxis The categoryAxis, which may be formatted as described previously
+##title, subTitle Not implemented yet. These would be label-like objects whose text could be set directly and which would appear in sensible locations. For now, you can just place extra strings on the drawing.
+
+
+heading2("Line Charts")
+
+disc("""
+We consider "Line Charts" to be essentially the same as
+"Bar Charts", but with lines instead of bars.
+Both share the same pair of Category/Value axes pairs.
+This is in contrast to "Line Plots", where both axes are
+<i>Value</i> axes.
+""")
+
+disc("""
+The following code and its output shall serve as a simple
+example.
+More explanation will follow.
+For the time being you can also study the output of running
+the tool $reportlab/lib/graphdocpy.py$ withough any arguments
+and search the generated PDF document for examples of
+Line Charts.
+""")
+
+eg("""
+from reportlab.graphics.charts.linecharts import HorizontalLineChart
+
+drawing = Drawing(400, 200)
+
+data = [
+ (13, 5, 20, 22, 37, 45, 19, 4),
+ (5, 20, 46, 38, 23, 21, 6, 14)
+]
+
+lc = HorizontalLineChart()
+lc.x = 50
+lc.y = 50
+lc.height = 125
+lc.width = 300
+lc.data = data
+lc.joinedLines = 1
+catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
+lc.categoryAxis.categoryNames = catNames
+lc.categoryAxis.labels.boxAnchor = 'n'
+lc.valueAxis.valueMin = 0
+lc.valueAxis.valueMax = 60
+lc.valueAxis.valueStep = 15
+lc.lines[0].strokeWidth = 2
+lc.lines[1].strokeWidth = 1.5
+drawing.add(lc)
+""")
+
+from reportlab.graphics.charts.linecharts import HorizontalLineChart
+
+drawing = Drawing(400, 200)
+
+data = [
+ (13, 5, 20, 22, 37, 45, 19, 4),
+ (5, 20, 46, 38, 23, 21, 6, 14)
+]
+
+lc = HorizontalLineChart()
+lc.x = 50
+lc.y = 50
+lc.height = 125
+lc.width = 300
+lc.data = data
+lc.joinedLines = 1
+catNames = string.split('Jan Feb Mar Apr May Jun Jul Aug', ' ')
+lc.categoryAxis.categoryNames = catNames
+lc.categoryAxis.labels.boxAnchor = 'n'
+lc.valueAxis.valueMin = 0
+lc.valueAxis.valueMax = 60
+lc.valueAxis.valueStep = 15
+lc.lines[0].strokeWidth = 2
+lc.lines[1].strokeWidth = 1.5
+drawing.add(lc)
+
+draw(drawing, 'HorizontalLineChart sample')
+
+
+disc("")
+todo("Add properties table.")
+
+
+heading2("Line Plots")
+
+disc("""
+Below we show a more complex example of a Line Plot that
+also uses some experimental features like line markers
+placed at each data point.
+""")
+
+eg("""
+from reportlab.graphics.charts.lineplots import LinePlot
+from reportlab.graphics.widgets.markers import makeMarker
+
+drawing = Drawing(400, 200)
+
+data = [
+ ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
+ ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
+]
+
+lp = LinePlot()
+lp.x = 50
+lp.y = 50
+lp.height = 125
+lp.width = 300
+lp.data = data
+lp.joinedLines = 1
+lp.lines[0].symbol = makeMarker('FilledCircle')
+lp.lines[1].symbol = makeMarker('Circle')
+lp.lineLabelFormat = '%2.0f'
+lp.strokeColor = colors.black
+lp.xValueAxis.valueMin = 0
+lp.xValueAxis.valueMax = 5
+lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
+lp.xValueAxis.labelTextFormat = '%2.1f'
+lp.yValueAxis.valueMin = 0
+lp.yValueAxis.valueMax = 7
+lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
+
+drawing.add(lp)
+""")
+
+
+from reportlab.graphics.charts.lineplots import LinePlot
+from reportlab.graphics.widgets.markers import makeMarker
+
+drawing = Drawing(400, 200)
+
+data = [
+ ((1,1), (2,2), (2.5,1), (3,3), (4,5)),
+ ((1,2), (2,3), (2.5,2), (3.5,5), (4,6))
+]
+
+lp = LinePlot()
+lp.x = 50
+lp.y = 50
+lp.height = 125
+lp.width = 300
+lp.data = data
+lp.joinedLines = 1
+lp.lines[0].symbol = makeMarker('FilledCircle')
+lp.lines[1].symbol = makeMarker('Circle')
+lp.lineLabelFormat = '%2.0f'
+lp.strokeColor = colors.black
+lp.xValueAxis.valueMin = 0
+lp.xValueAxis.valueMax = 5
+lp.xValueAxis.valueSteps = [1, 2, 2.5, 3, 4, 5]
+lp.xValueAxis.labelTextFormat = '%2.1f'
+lp.yValueAxis.valueMin = 0
+lp.yValueAxis.valueMax = 7
+lp.yValueAxis.valueSteps = [1, 2, 3, 5, 6]
+
+drawing.add(lp)
+
+draw(drawing, 'LinePlot sample')
+
+
+
+disc("")
+todo("Add properties table.")
+
+
+
+heading2("Pie Charts")
+
+disc("""
+We've already seen a pie chart example above.
+This is provisional but seems to do most things.
+At the very least we need to change the name.
+For completeness we will cover it here.
+""")
+
+eg("""
+from reportlab.graphics.charts.piecharts import Pie
+
+d = Drawing(200, 100)
+
+pc = Pie()
+pc.x = 65
+pc.y = 15
+pc.width = 70
+pc.height = 70
+pc.data = [10,20,30,40,50,60]
+pc.labels = ['a','b','c','d','e','f']
+
+pc.slices.strokeWidth=0.5
+pc.slices[3].popout = 10
+pc.slices[3].strokeWidth = 2
+pc.slices[3].strokeDashArray = [2,2]
+pc.slices[3].labelRadius = 1.75
+pc.slices[3].fontColor = colors.red
+
+d.add(pc)
+""")
+
+from reportlab.graphics.charts.piecharts import Pie
+
+d = Drawing(200, 100)
+
+pc = Pie()
+pc.x = 65
+pc.y = 15
+pc.width = 70
+pc.height = 70
+pc.data = [10,20,30,40,50,60]
+pc.labels = ['a','b','c','d','e','f']
+
+pc.slices.strokeWidth=0.5
+pc.slices[3].popout = 10
+pc.slices[3].strokeWidth = 2
+pc.slices[3].strokeDashArray = [2,2]
+pc.slices[3].labelRadius = 1.75
+pc.slices[3].fontColor = colors.red
+
+d.add(pc)
+
+draw(d, 'A bare bones pie chart')
+
+disc("""
+Properties are covered below.
+The pie has a 'wedges' collection and we document wedge properties
+in the same table.
+This was invented before we finished the $Label$ class and will
+probably be reworked to use such labels shortly.
+""")
+
+disc("")
+todo("Add properties table.")
+
+##Property Value
+##data a list or tuple of numbers
+##x, y, width, height Bounding box of the pie. Note that x and y do NOT specify the centre but the bottom left corner, and that width and height do not have to be equal; pies may be elliptical and wedges will be drawn correctly.
+##labels None, or a list of strings. Make it None if you don't want labels around the edge of the pie. Since it is impossible to know the size of slices, we generally discourage placing labels in or around pies; it is much better to put them in a legend alongside.
+##startAngle Where is the start angle of the first pie slice? The default is '90' which is twelve o'clock.
+##direction Which direction do slices progress in? The default is 'clockwise'.
+##wedges Collection of wedges. This lets you customise each wedge, or individual ones. See below
+##wedges.strokeWidth Border width for wedge
+##wedges.strokeColor Border color
+##wedges.strokeDashArray Solid or dashed line configuration for
+##wedges.popout How far out should the slice(s) stick from the centre of
+##the pie? default is zero.
+##wedges.fontName
+##wedges.fontSize
+##wedges.fontColor Used for text labels
+##wedges.labelRadius This controls the anchor point for a text label. It
+##is a fraction of the radius; 0.7 will place the text inside the pie,
+##1.2 will place it slightly outside. (note that if we add labels, we
+##will keep this to specify their anchor point)
+##
+
+
+heading2("Legends")
+
+disc("""
+Various preliminary legend classes can be found but need a
+cleanup to be consistent with the rest of the charting
+model.
+Legends are the natural place to specify the colors and line
+styles of charts; we propose that each chart is created with
+a $legend$ attribute which is invisible.
+One would then do the following to specify colors:
+""")
+
+eg("""
+myChart.legend.defaultColors = [red, green, blue]
+""")
+
+disc("""
+One could also define a group of charts sharing the same legend:
+""")
+
+eg("""
+myLegend = Legend()
+myLegend.defaultColor = [red, green.....] #yuck!
+myLegend.columns = 2
+# etc.
+chart1.legend = myLegend
+chart2.legend = myLegend
+chart3.legend = myLegend
+""")
+
+# Hack to force a new paragraph before the todo() :-(
+disc("")
+
+todo("""Does this work? Is it an acceptable complication over specifying chart
+colors directly?""")
+
+
+
+heading2("Remaining Issues")
+
+disc("""
+There are several issues that are <i>almost</i> solved, but for which
+is is a bit too early to start making them really public.
+Nevertheless, here is a list of things that are under way:
+""")
+
+list("""
+Color specification - right now the chart has an undocumented property
+$defaultColors$, which provides a list of colors to cycle through,
+such that each data series gets its own color.
+Right now, if you introduce a legend, you need to make sure it shares
+the same list of colors.
+Most likely, this will be replaced with a scheme to specify a kind
+of legend containing attributes with different values for each data
+series.
+This legend can then also be shared by several charts, but need not
+be visible itself.
+""")
+
+list("""
+Additional chart types - when the current design will have become
+more stable, we expect to add variants of bar charts to deal with stacked
+and percentile bars as well as the side-by-side variant seen here.
+""")
+
+
+heading2("Outlook")
+
+disc("""
+It will take some time to deal with the full range of chart types.
+We expect to finalize bars and pies first and to produce trial
+implementations of more general plots, thereafter.
+""")
+
+
+heading3("X-Y Plots")
+
+disc("""
+Most other plots involve two value axes and directly plotting
+x-y data in some form.
+The series can be plotted as lines, marker symbols, both, or
+custom graphics such as open-high-low-close graphics.
+All share the concepts of scaling and axis/title formatting.
+At a certain point, a routine will loop over the data series and
+'do something' with the data points at given x-y locations.
+Given a basic line plot, it should be very easy to derive a
+custom chart type just by overriding a single method - say,
+$drawSeries()$.
+""")
+
+
+heading3("Marker customisation and custom shapes")
+
+disc("""
+Well known plotting packages such as excel, Mathematica and Excel
+offer ranges of marker types to add to charts.
+We can do better - you can write any kind of chart widget you
+want and just tell the chart to use it as an example.
+""")
+
+
+heading4("Combination plots")
+
+disc("""
+Combining multiple plot types is really easy.
+You can just draw several charts (bar, line or whatever) in
+the same rectangle, suppressing axes as needed.
+So a chart could correlate a line with Scottish typhoid cases
+over a 15 year period on the left axis with a set of bars showing
+inflation rates on the right axis.
+If anyone can remind us where this example came from we'll
+attribute it, and happily show the well-known graph as an
+example.
+""")
+
+
+heading3("Interactive editors")
+
+disc("""
+One principle of the Graphics package is to make all 'interesting'
+properties of its graphic components accessible and changeable by
+setting apropriate values of corresponding public attributes.
+This makes it very tempting to build a tool like a GUI editor that
+that helps you with doing that interactively.
+""")
+
+disc("""
+ReportLab has built such a tool using the Tkinter toolkit that
+loads pure Python code describing a drawing and records your
+property editing operations.
+This "change history" is then used to create code for a subclass
+of that chart, say, that can be saved and used instantly just
+like any other chart or as a new starting point for another
+interactive editing session.
+""")
+
+disc("""
+This is still work in progress, though, and the conditions for
+releasing this need to be further elaborated.
+""")
+
+
+heading3("Misc.")
+
+disc("""
+This has not been an exhaustive look at all the chart classes.
+Those classes are constantly being worked on.
+To see exactly what is in the current distribution, use the
+$graphdocpy.py$ utility.
+By default, it will run on reportlab/graphics, and produce a full
+report.
+(If you want to run it on other modules or packages,
+$graphdocpy.py -h$ prints a help message that will tell you
+how.)
+""")
+
+disc("""
+This is the tool that was mentioned in the section on 'Documenting
+Widgets'.
+""")
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/graphguide/gengraphguide.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,59 @@
+#!/bin/env python
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/graphguide/gengraphguide.py
+__version__=''' $Id$ '''
+__doc__ = """
+This module contains the script for building the graphics guide.
+"""
+def run(pagesize=None, verbose=1, outDir=None):
+ import os
+ from reportlab.tools.docco.rl_doc_utils import setStory, getStory, RLDocTemplate, defaultPageSize
+ from reportlab.tools.docco import rl_doc_utils
+ from reportlab.lib.utils import open_and_read, _RL_DIR
+ if not outDir: outDir = os.path.join(_RL_DIR,'docs')
+ destfn = os.path.join(outDir,'graphguide.pdf')
+ doc = RLDocTemplate(destfn,pagesize = pagesize or defaultPageSize)
+
+ #this builds the story
+ setStory()
+ G = {}
+ exec 'from reportlab.tools.docco.rl_doc_utils import *' in G, G
+ doc = RLDocTemplate(destfn,pagesize = pagesize or defaultPageSize)
+ for f in (
+ 'ch1_intro',
+ 'ch2_concepts',
+ 'ch3_shapes',
+ 'ch4_widgets',
+ 'ch5_charts',
+ ):
+ exec open_and_read(f+'.py',mode='t') in G, G
+ del G
+
+ story = getStory()
+ if verbose: print 'Built story contains %d flowables...' % len(story)
+ doc.build(story)
+ if verbose: print 'Saved "%s"' % destfn
+
+def makeSuite():
+ "standard test harness support - run self as separate process"
+ from reportlab.test.utils import ScriptThatMakesFileTest
+ return ScriptThatMakesFileTest('../docs/graphguide', 'gengraphguide.py', 'graphguide.pdf')
+
+def main():
+ import sys
+ verbose = '-s' not in sys.argv
+ if not verbose: sys.argv.remove('-s')
+ if len(sys.argv) > 1:
+ try:
+ pagesize = eval(sys.argv[1])
+ except:
+ print 'Expected page size in argument 1', sys.argv[1]
+ raise
+ print 'set page size to',sys.argv[1]
+ else:
+ pagesize = None
+ run(pagesize,verbose)
+
+if __name__=="__main__":
+ main()
Binary file docs/images/Edit_Prefs.gif has changed
Binary file docs/images/Python_21.gif has changed
Binary file docs/images/Python_21_HINT.gif has changed
Binary file docs/images/fileExchange.gif has changed
Binary file docs/images/jpn.gif has changed
Binary file docs/images/jpnchars.jpg has changed
Binary file docs/images/lj8100.jpg has changed
Binary file docs/images/redsquare.png has changed
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/images/replogo.a85 Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,439 @@
+BI
+/W 283 /H 181 /BPC 8 /CS /RGB /F [/A85 /Fl]
+ID
+Gb"/lGEc'<R`9K?ST/gccciOJc<4e(<bO6Z:4`rg,Y/Cp6(efX#nfXW*Hb1H
+&OfM-Pamra&k""R8@/E>,,kl8"&2NBd%Kaogum165&NYZBITmkcQDo:\lEnA
+GJETphXmY&(BXdG&0O5g!!*-(#S8+DJ,fTO":,P]5_&h8!X&eu$f\(VI^5_q
+jm)jbosgIBN01+GE&G/,0E`$J,.ogcq?_*e\?bYbO$E4*_M&A1cC@I!9Dd\'
++4<JpceXMW:S/-3%Sg@m:0f)>?4QDr'3BbF=2qLTa,V3(b)tC;HhK!DHiEs=
+#e!]_gC"9\WeUZ]%d_rZDm+pZHhMjerV*pJn(tTrkH8+&G'_fGA&n<1gUDI\
+)T%dl>;gEVr7uSSD=[2`\)2)Y\8d.Vp$:55>ISM;g9k_IXBE5_odUJ&4fhbj
++t4u*CCeUS/R,f.kn4Mb(GB+%B[KmgIC4%Q_Cr\%1,1M'_1Dj^kKfbZDr.!E
+F(WairP]R[bk1DXB:hnj5(2_GWLnY9BgP/'PUTNpnM"tB`!I)(N#O]nba:,[
+7un]KC=L=e,=d\00l5LHTgOSF))>aLTKrYb%NI015l^i^qt9:L_$;(Sl-nh/
+pYP5l]D"DU][No_Y;b?do<#LYHN!Ng-V^$t+XoX`J[UDW6NstgiU^:#aXJYf
+@T/-h#kbk9#UMApV<$^um2e#j'7`g:&J1#=2rAubQ**M!it6f3,*@pVZY%I6
+6o/H!J4.k`9lkR_-;U4ln3a&Bj2[3$3u/IFT]*eDlR2scpu.!iLu\C$^CPtn
+H@SNS^AI?QDnk,W"$D00h*&FIlDn4&G3't(Uo5[]m!,=p/AQ+U,=dd\o,oLh
+`[7$Kifm(afHdLC\5iol9&c'@AXlrl+e2TcVCt*"D43P1/tBd4IK''*Z:Y1g
+&tsE#;eD`AXDo:8;HP?kPAJ]<++5EP`)3&A0_Gc=bj+0GNAo^=jcrnRI.>2-
+?@.[$o*RI.f9aJ`&3E/CRVaf0!I//;.6.N@dhWJ":#_Dm4P7SLk/f_K3$fY"
+@lB&<Ha6I;-o4cM4MW0dOj"KZ#pDR1Yo[/:choqG8q9ig4MWML'j_uP_D&eT
+fr<8f4$thGNQ*)+Mfaj\\>>=ZT!#RpKMq"Z6@j)ODfZ2)o?9+0oW[2)q0V"P
+i5SJT2Aq@18&2N,MORue((.$!o41l.*at,LGSoZG'&i)k+<?5^(d*$sCsl0%
+TKio3:;J7p.=$?[:u/^*Hhlcis6p!eY>_>o\;RS\8iUnSbf.@["h4W^daDC<
+[+g5DH18l\"e-&NZV?P&#\?tUg#Q>8N;^H/+c'&47a2<,ZndtDk/m0)o'Y9I
+"Af)p(^a#(U5qJ$"NO<.;GoitP^.[:Han@R-<rae6mU=%"(\3,<62Ukk;'3j
+J8R*"'.6O_PqZ""f(6jTifp8^JCuAY/jbZCkH[Ypb0gkk-"GD*+ddO1:J[AF
+6%f;38gK(_r17IFK[Cs1b9qdXYQm/LVYK6:5p]/rr:?Q\KM?DX(()r39Q@pt
+-n"irbC8u%rSmof*/>"EJk':6\TnrLq,.c]R(i1M-HV6>$DWiJn<kX[9Ho]=
+-M`!\n]=,n#c/6->Wu`pbXf8^#tsp$Blf[o2f0&&E8Fj;UkH;2KPeTN'9<-`
+_E>O(dS$eNYO@/]?Jm>IbNhuC)(3i7QGjt[o_n[]],>Y46C;2%ZOfU,n6RL6
+pQXGh.Ts48AWn&r=TE#APblWI!jfTH5qs'iZ7I([Rcm#)4]s3/IWG@.!hl8%
+k"5Ai2hk31"fITC&?Wl%R3r7DZT<9r#jE`;DgM?VnOPTHJ6NEF=DX0oV=;jR
+N"ee-'gN(,,1IMA,*\r!P!#ZJb/Yi%P$?h-bS)ApoF1$2S`.D2UXU#ifa/5t
+gE^EM\-Jt.FMpZj7&UVY^aA_J@B/D`\QM+D5?Y%:r8SkQX)mILmG#,5Qa$@m
+8\`%IN+JM>F2lkn-6bE9+'C"P4$:%88J]Hko.1njrgkG16n$[KbII#_p%Qu7
+AE+ku0`TXT)a,W-TbqN<#jU93V[&HNckm'+eCt(+$2Wka!3/NpDgDtsPjuY!
+&Osl;iABPJ;B\[/"UG*'SN<VH-9&JJ!>M&U8$BW">.&+qW`H6*^OH,o4LAeL
+6:XCa%o6PiB$Hd`4)!?TBp0l<RU-?(2"pE<#`Tf\CtPsX#k]jiP>=C<`"Pp/
+m\$/,\foSn:tn@>>.&+rXN:c=IYfebFG+3NbiMdW>Wh$%Tb9lJ,Z=l?0N&Gh
+%hOq[K8PLeJg*I1A&jUDW1GZEB0I@H?K&bTn$qD<]C*82Gk'c!.Um,ORPB1S
+X.(7fr^"6`JoT&6a&>e<rVQ>Uf-b?fn#),:EYL950ZtXh\U7\pG(iO\9lOq#
+XrZT?%Us\o*&sSo7H!XR3"?ul#`4f!Zb])99lfrHjSo#-^]+6,^OPUTa&(g]
+,XjL"\_WnqMA+tu)_%J0.!LUQk"/iU(.j?`YBf'ePuh98R"@p`^A)0l[V`R2
+gPKuukg6#2UgK&_!SG#.Y9G=NE!Qjc;%hIeB-:05)Dr'p+snP*bJ%1&<a&H-
+d2;tLNJt8rI#=V><!lpKq*ZV^P`gLqn=[E9NZXdCFAo)4?+kRWdA'4V2?cQ"
+#''Y?Gm#\OTi1HX*Ot!Vs#lg`@)7Fce;=tkcCI&kdqoTOHN*j<QmB4io(Ot;
+ehV]m8eigT:`-&!&shVmQ)n2I@ttO7i"S,?3HHMS-S6o%d]FE1@eeo;+(13'
+3`u]j''#Ki^Q=kX7>i@((p'?IgAp1[a)GE\GTFH2IL`l^S2o(A6m?6E<2l$L
+;Y'R(,(@?ZKiF0"q<+@tT&PK,F%g#(oSZil5CQj_]O[q`Br_?MX^AjBUQ7T"
+@`4'cHhKk=]U=<Bo^jkJ`aG&9HE[l.fdY]@]YS4)Rb`8PSbLra?^irj/Cu8Q
+c\<To:*/p$0N&I>,@T<#7>mE&],fEsJ/^mkC9$&OG7q&6HTG<AG3snm51lMo
+K24`1oZ3.>\$(lqac@H(VP3,j+0.uF2VMDhWa371^%^Af^3o`WX]fl=THUV8
+;J-N15UCZnZ$lNCS@!1iRd72#ac[r!.4H&c>e#3_/&6:Xk!k\T$ULAU46i)h
+KH%IBj[)gcEr,Fm8/F9"JG-bqWJ=P0'Sa_a8O+\a'e<<9=gB:gLMs_T<?eHK
+8.*orJ-,WQ2A&<m->H*TS32)&7f!:AMCG&[J)1AofJl$\;g^ZSq!^Cknt;Dc
+rq^D)=Ld1@AECt!d)V]q@7Ekg^RdT8Q7,V)DV_mO20\KDKS0K@4tMr8-me_+
+6ALSS;34Fo$;PSrC"&qrfWZNdMAT:eiJ/N9h/.>n:)McoCDR=<?bUp+k'W,J
+,td=ERtjQRjM;IW,*Y-3iCdE\>g&EbB?cmQGOOBGCXu1L3)ObU2-@^S6cq05
+nc5;/mQ%?`p.hBGdaHQ]G81hMC-X9k5CORVD$e$*2eaH?-X<`[^HO@dZM4=l
+hab9!R=Or%o^Ut^'0p7ELITD^<^"<p,DLe3;l35k\od2,3HN3")ooGD]6@>+
+Y!l5XU?A.u?="`9krB9aJ"#6+F6Cj4:db>5(9+:4@Z;6SRum`F3</-1Dp"@t
+>IA4r#nnWs&Oa4CR=Gqu:(/!q"AuW/k>2KVoY(R4ecMKT7N&8fNoIBR'&aTu
+_%a8nlP$gt1hjg.A&aJ$<eK?EYlH<h7L.MsTEnDO'2?O*I.?48\T6du2J17)
+H0Wm.pV4G+gBG35ml!)WpcUWa&5$Go1dk@P+))q3AL')`eqWcF@;^>sW.\U=
+KOa]?e`5]MM*PY*DnCl6E32BB-7:0ra%\H4"(mN22(Eh<gdh^pEgKV4IDo^P
+\ojA`d74\<dX"0rc?02dZreESV(X\/>njW*?28pfK@J`[[!MH!B8[HQK"!jf
+o&R]D%nHJm"5F<T3HIZ]T'Pj5H!7t3rJhm[:s4.TjMA`:]6<T/9-OJAY[G9K
+NKLGMKV5#/(.N#&X<tn*M>eBE%?@jo3S$g"8jar0l.N@RCY?!>0pJlFiV":,
+&g1[(4*Jhq4I[qd=t#2]@%_3GZgHMV8%Q>l$=k!K4DE4hF[E))8cG<U-`H*$
+K+_uu+jaaJq0j6(oV)S%q9/s%Udg=^3HO?DH;[X=0Ma/fOIDUFG@6N6P.S5]
+B&.q-br=b,Q)e0#o&.?:p[-]Ol1/EfdaHQu%3&m]@R"g>MmOmSJk?qlY!GSG
+'_ngSBXG<dP7i9`EK?enfs5/s'I^bFW)t"$HSI3J;%8+g&Lr/7AM*klB[NRP
+q=?O]fPoigM+<UJNHBG%!@]HHRKb&NR:28VB?MC]ME\c75rf;JIb62sI2Xl7
+'VB3*@OP!/(+oC06P!W)G4!uul'Dm!1P#)'D;-sNj',d-ep<$Wj2[5,Pq*Y#
+GP:CV;(s9slbGS3<jMZ*6n8`-dlK(HYBVu/A!9r]^h,$4me05_Mi:MCH1U1#
+=gR8SdA%3n4;d>W%WF4CmbBfH-3VQK-:?/N?Na1r%YB8a/6fP63Waj9$Pl!n
++l7<N)f[,bjj)KnKB2T;SX.kj=GN-QoVFP/``"Hm["sWuCYH/[Zt\"E^4lVb
+N74\#qc56<mGbKuoB)>j>8A\fLp2K7U;6T>E8cDG6!4WXc7"?Hb4Wk7fh,^l
+Gu-2k?<out[ZIS+RrJ9bJ)Z;4YjD.6nFu;&Z]T_*!&k"u6jf/`q"CA[=0E[]
+ouA/(S=H)hl1/EfIe_lWTgOTm39K8S"p+"-Z<a2@oe?(+\oEpSk*GEKZYYFK
+-P\.4,kg;3.or_W"s(Ygp@$lLCYWLn<em?]S<bg8%\$;'6rL"`WKAfO-3,\8
+P6##/2f;mF6e/2:FVGng:o-c!4&uib;Pd"4UdBbB%3%4ToI+(%Ph:YO_EsM9
+;5.$h;UEl>3!Y7cm+Skj[`5QE>n)0T9M@!8U^1;abaC7_SidkoJoUefH/9?E
+m[7^Z+i%f8.H9CJ_lri9)WY8p75:$OAAe5ELDN`>?bUp7P;"RLL(age=oA'T
+O+^%JPcaC(_^&i&\OMW$?*I^&jCHZ47FAA,!\WBYV+\4^X;sfD#_(f_`)u%D
+ioZYkE\3NqppFke.P<?V;56So-VfV\iPYaPJ.)mLo#?Y.f7`'7l*"+cq3F"7
+B[NQmj*Vdd]:Z!tV=!'K;tKsk$!Q@pM\]cGYY+K\ZuqUUprZuQ`H(+bft)=l
+cThFlQsCOR3-!p\4E>j4>CKh1_F!5H&-r[]0L18NU;5m^/LH4?c?Q`Oc+.f>
+e'lc1r:!(0,K&T&5#R9!O*0a;.9*5W'_;b]%M6T=E8Z8c8n+!r1V8tF-R:'I
++$4X^F::4AG[id#s#kMi'IFbKBbr[3@`!<Mi)lsVV$A)iYZJ#7dF$PWi+df*
+"-;79S)!D,3@6("&jS<lgj$ht)97aX],3sPl:12lbGRXSRU`:d\`'BO?G]#l
+r:%T=.T@6EE+!e[2$E\W+B4ggD1Y&;o43A_P9s#HOX!B.G4!$Ank3Hf8/F:M
+ESWu^W>p_(!L,Yf9&7*"3cmV!eZ2bigph@OdFSrfZ>_)pa+!F0[?c:Jha3e$
+Wb9YLH1U1ceu]n+M;lM9Y4]K4f5O5c]&>)%37YT_leK$l5PsfR1M=uAFuG9k
+S2bN*&eV9`ZAkZR>FRNf$5=o8Vb`p:>IHrQH3h7\I94<8qod?[6Y2su'8LFG
+A#!QR2/8@+="a7_215o7IMTF;cpp)Z910VdA>cG-X&c)k)<>H!hS%<OSur_"
+qIsYXn%A7P"s*Xe"C%<*n?I<4lF;4[^A2BjoJHdH=mXkM9;t&*dp'+gM)N'/
+4>ARq=Ku>CCY/RHP>@o_)Usb^#_d/Y<H?-M>Q.l\.UBW-ac[tIp$9)0ldcnS
+7'Q`g\Me<Y"HUbb_'!S<X_lb%5%Vm$S2kXKCY!=igpt6FN<V^BCm-3bgH\p!
+3\?_s`u]SDo]X\"e(5-R"$hk<oQ7_X&^&oig@gTI%t+--GOsn;e#?7n^;Y#I
+AO<rr5&8_#\7;R5.+`,1:]sV^g9o+i/K8,_oecl.HCR*C&h8`%"O;qCY\M^g
+[Vab_nA#,sc@ucIU+@O/h1/Y'7ZG8+g"Jsa#1f6Vqt/?5a2Q$*DVZ5'3VrRj
+!aHM?WN!0q_P.SWL;:bhFm9MG]`8!.4*Ku#(_p>f2ib4WcY?R`Dh*LdI@Sfe
+<D0qR&>'.EM&=(sh7GC/YXT4glkDrBMHTQ5bpueo<4-Jk7ZJI6i4snO\K1c?
+oYqhgpuXipp4\#IjiWi=;P_CgDniu2oB(rc?XlqA[q3$bf`Gq?"eh]Y"fM.j
+l)109b*<A',p=Gj`/,->/G:ZL[;4B'K.OcM)%!,a1qTu2iPK0LQMp$BO&AkR
+/d?ud!>#gE>IRAG0akrjfr;0hqML2`"qA_A0-B`WJcuO6Y"?Od\T>#Gm\6$d
+cGr?W:`VT=aI+hsh7@aLN>lMG0*e#)8m"T5H@!.X'&cYVJo?#.k^fU"@(uX:
+lQ?`MW4E9K-9rP&dNX0:*P9Hb5c^2&>@u-K(!AdN`f,_TFEH?aGskaV*NJ8_
+acl#'21JE1amp(+#hr=aABE]AHY^aP8/M(<`0K13r&T_6?b_'DD+tcQ._2#c
+o!)N7HFV*<4*ID<,IQUdD*b#^J?&%QJHP[iQI+[i9+RQQi,QW!3d'^eXB<k.
+@>RT]<fl*p5&IK^"TFunNjUajD7_4A.o`HDY[Bc"XBrS$JqA=AO1suXhFp='
+^2(cL*JoW0@MAB*oDk.ujN=Q,Zc\L]e"B!Zace)BrK=&r==E'.]6E^mn%JHV
+GOF8!H1M4]lIW6>Uk^<a^oX;h`f;(/P*-G,$+\4Ah?r"e6iidmL(,*[%VBC:
+"'I#amF+iqc''MNldi1Nc^l/H9:fIuIF"KJ91?Plo#oR`<NC'fb*Od-Z!=h[
+:i+dg@Ap7uM99s*m^<mFiT@lV:V:Z*6;g^Eq0;K)k0KZ\D;mNnhE5>G:S0iH
+o&W5ZLp3V&4To+BADdNcV57$RIJ`_dl`IXBHI-,gm`DtYj)C0""m(6!\CCq3
+i@8gGr-=;eL(N$>3.:Y1m#fWIRhrr),tg)R[!1uqfWqG_nl-8MBbrl$iF5@C
+NZC3iG3rI-+1#t+2O05B^=p>O^Up#Z`Q1X;<R1*F'uY.=Sit8`0=Rd/gm*Ju
+i/*c."1CN4%ACHm[r1#Z#!6e^^ki^P;#WD'N#XQL@Mn6SJ5%"<>6G,+9:,YQ
+j,\EPgj,*AG8$(0Sj%Adh!*:cc^6EhkB;`8:HV=@30E-=bEaa7[r3X3;R5`7
+R58(f4aQaf0k3\3(kH$Q1^)QTJ3Rr+[Z,e(h7GW*].20N4aQaFrUndSGOM[u
+BYh"Q0>-ekW)9=7_;s\<eC;tR%bH@V<;Y1E;e_Ja1M7?;'5Pg[1IiA?6@1^l
+)U+tXR_fi2j%ZX[[uT'k=Z<\XWFlso2,Efan2_(Er,C2d<MO0nAKMC&3eZ8=
+.g4T7i6=4<jJXr[]63EDA]B`NMf)KQ>Y7VGG1>&==R1G$g9n!4?>eAt*TB,#
+jN'oV->hJDaXhe7gqRRPVJ16(:s-\.*_MYF;7q-n^;?q#m^_LoAV=2P?_iVp
+:/O>E_@-qdlLW=ds5Jqi+OjX,MFZGE`PR+IS*G[1THSel[VQhbF8Yh'S)[bU
+?b`1!;RQ`=.'j9,3I3Z'hRnge2s.e1kic&gZYpDE2fI9eC4`kuE;9[k[Vboc
+1XGPBIYD+#'3"Ji%Yi\`6YP>h3IetT7EVpJR1Lnro[/!OO$<E=E[K_,7ij*X
+VTdrtrcalo\om>uh@C\l>b5[ub)Ft?"Pa)^W6[TA$TKFo,u/Hu&4g%\!A:pA
+@aL!>i[8[qI)UO2pANF:$>#.)cU3-+Sk@9YE8J?Zru=%>Zu=ini^MrU/8-`)
+@XApFT'o-$9GJaQZY%HJK*GI;*3BO4ZtZqmKX/#1TiK-n*O,cBRP_iI7<ZRm
+fbt,+CW*!RA]os!!ZhWfOsNa6.AI%8HQtLTP=K,SW&+o/[%]8,<\Xtp8[Pc'
+hn"09$e7`tEJfJi2f9U1+Ir#5$CQgZZo"^5Z5`*i;W]Vp:gb1c:S'[>$Qa$S
+X`VMIn<spOI1P%<c.uff,;ddV6!@F7P4L>3,=hshgs0.:8h45VC=NY[UjX;d
+Y9?emeEPG[)`26$AA5J[JQ&jK!(([Qi.2,Rk0/Z'5S>9>3Urpn9UINUK*[0Z
+JQ!QY!+i8H<Cp4;]!>9"8C\;1=fB:]Bh+V.jiWkVW`,>B(2-I^H:gJB0&'oi
+U-/,7f.U+%&2H_&*V!*/VLpfo',!ZHB.2C%':WAFd1Ff@e#!Qh,&/6=r8(^<
+9P_X_W>;T\JH2aS!=Kb7^4oq*G#b_P*?Jqp*F(eL,uXuL0Me3Lc^qghiPK74
+c.e+T'5u[9ER^paY&0>IZ?V8%B_An@R4SHeQ!LW877>&l)_bY"TeV$BT).OQ
+UN1Dj'dJWA&M>N929>m$:pk&g0k855HU^C4TqKE0@DfIiRd9+X6I>p`Ctc71
+JH?"J$,JCHi8"nb4S[K3Dn0Y;Bm3kM!=JUZBEe4m5-jMk,<?M>c)g-Nh:#!a
+TBm94\@=MYf]Z&!2Vn9D)K=+oN#7,$L-\-'OA&e*V.""_0]12>](l\nEWS+-
+!V#iM?@$>Ti5*>kmUcorgDi_D*20=L7ocQgOZu\A;Gb8,4RiQnYeL*mO7gY#
+Uo(#(QYLA?BXCYS"e3#"]68&.Gu6peHGbIHBQ?`Jg.o7^/,=NGMi\'-V<Vm7
+pBXe?X\<018Xq>rg00.2G^[*0]]nqE_tWNNF#2#%!mQAY;hhPea$M1s=<r,&
+VduBL=Jdd%NX,1S/?>X-9,IC)KVG`]rlZUg+VY*tq7"U!Q2&mO*aKaGEocZE
+]Cl%L@$"bLo%eNIaktPon)BIib4Tb=1+0:`C7k[:)jL$U\D+`-TjE!&"oQ'&
+2/=BKiQZRfWmQ7;7j!0OcpJ?>`^cH?#P]'$2/CbOdBtC_ju54b4oQLU6L*JC
+[>2LbOlZKjOcD/jjs_l/'qISlRH#Z,5oIkN><%87U<.'bmUKa.I)$K8V'c`s
+NoN(q4OAK&K^7UQ`8NZ6a&k\fBQ?B^.FQM444Sn2m+ATAqtKDBr/p063-!r5
+++C^<J(s^Mo^m8)bMBZCKh!HK6ud]mnX21G\=m-tn=*crVuK1=)!;K8[r-m-
+HhZs)bX`,,A+s?AF=Ae^V>MCTmbPM8mpW)-=XmJP_A1I+Enb$ISZrRV[V_Kk
+CY&:UGkEq!P@Wt!4H#ktE+[Y#<SP!$a5<b7O>hR:C[H0(pTP_,\,hi<P;i_<
+PUMYMB27Ls>sWP5?b[YE^epm9ZqHjCn:o4n`c3rk#fQt@#VkiF-;9f"(drO>
+[%^q;)`G@hN]Z[?l`MF#MELR];lC'_N0<XB_rl+eN1tH`2fHu)PEV3d&MKM?
+j;G-g.7)T63p9Tg,CqQJ#uX1'-mJ@FCn)VLCY#T7.X_/#4^sk\X)mQlMT%\p
+hRo7SnLhJ:ln<Mk;;pLnhg>OdW:QY+nFK&$!SQDVfPZr"3"KL^n=&,J$7"O)
+nB_rmGCrD03[>6d=;3@+Bi)o3iU=E@omid3JT0lY%NO-9It*oDVt7XfUu7S%
+g:"$dg@1X`U):lX-\3*Albe/?aU]@N^n$=$D;?o!.@[B=/0BA`Pq,qJG3sOs
+2,/%eEG7CWrTpl:@P=>D^^6a\.o861[VXpiW.-oR.SX,"Nq>"L"H&'^:fQLS
+$A@tXOt;+rVi4c+otUY?'J!4CVmL?tRZJBtOH651Q,7bhKL:J&J_IK%`9EVp
+>\hroV:n05puA&8L[lY%eEG;T,pD7a@Y=/Hk.C)rRhnBTnOrdp)cInqjb?jr
+"`="nM_?u%d"!)++sI^&L@cYor.Vmi5F84YAaF#S^sD'ja?9$MIR=TnofuW4
+%.fs&*orQ7l9R$QD_u%J'Q0aXKi*[K9_O"2k"WBWOgnU"X']<bd'VS,]5;Sa
+EY&Q;'Gma^@Ddii:d4GT6kN.6o]T.Z:'N5DJN\WJ;#-V+iQ0bD*bZ,m7QnX!
+IPBCV5N<u_hQpijT$ED%5$0"QcZd3g''e!n9&^1*OG.b5c0Os9!>H>1Z!eB5
+56lus/g"=c6<n(=%ei"Vnr5Tb&<E9+B\^*Pk:#Efp$6*6T6oudlA$/6>h`m1
+>dD.s:7XFC$-3+XQYNU&X]d"]qLNFXFMnN-;5O]pYB9$WYXo5Z(+N:^@)7GJ
+=3q;nMfud7RsXhD5gU:R(IlOQ29(9F.C]HXGt4)?6A89e23M;-eWm`X$Y6]a
+'IrhH`ujJFl:f.U,I_QJ@nm;W'Urp[PIS`ZjbTYQ0f5h$f1p2<\5@tbLj_=A
+@N5tuatEt@i7b`$G2ihK.TOaBnZ4@tIt86j0@Z%_No9>).lAj?=XW!gB2N0;
+=kCaSKM^Vp085dlImFbC`G[`fa?%_+qF@][H0,un8XV;;>i@+&Uja`F.A\B@
++iT:?"&5A9qIp(t]CAb3:1fu3%5CT2Ppl4\/+!NUStNmc[VXV0qXB^b/QuNu
+["C8c,:?2J4Se'%>j(>_%8PID:tl*B>)aFXGer[qX)irH'U8lsd8A1(4_TcW
+-^Jk[6m$qR%soug4o!rf]EK"u^a+A&Fj\R7kf`\thB:"g4NK"PN2P#fU6W/L
+<fR5i6]KR)H1L$ArqY^hF\%(d7e`YH/IcCXFI-%L[]2dplkjW]bO=i=mSX"l
+/A7^JAPNdd7$LkDY[)U8&Q`T_&<E]C+Icrt&Y!=)1ji9Seb-qo+?AY5*Wc"@
+hiDEDd&7E(M3NtcO`?8aWR?/F6gTqPF`>5IlenYmLp[/XUJXpBU+O<e@31AI
+R#h1@o=&JbM?:j$m,u1d.+(OaZ48=+7:D.dG3t/'KL\Etis0%SI%7L=@W<uE
+&13%micerV6Ilnh19;#)Ja]g7S'/G@cHBUP;uAm=$O>h9&0CRBf)l58i.;ml
+r7mfGKeI>\gkHl8%7.[)lJ^jC`qsJk+.SLnW`?)8Q&iLGXbCu%h&rDIa(Z@>
+QTPMA7_ZH=&[a'HldDV&[VXVn>kn5A01:1#:(pnf9@c]u<YUonTM_XfcM7i;
+LL457(.ZQigVm;=fL7NZ59_6b"sWNn^L&#f8)ae13bE\;.N`Y8o;$;%'^h'!
+j;A,]n7,;MeV:&HA7"-lp^k@p+;TbF7L`XcX[dJqA:@,"K2tjkTe1_arR,(s
+bofeXXrt%+TgK'b'S3.^1mX;O$C"eB`)1"iGdOE&8&pb#+Ddr5\YhMm>8nC4
+FrOV33A)pZ':c7<mH'Rs'S7-',;oQtGaoVhFjWf4isL!r/(gdtUP9i./8S?M
+%i?*,\<gNJ$0?d`_P4je\VTO.P-pIhP,WJiV%`j&5nmq>?l#7V\3lPn*o`""
+Fo80CW@o1/fL0R,9d01#gJQqZ!uJ4=K_];(%HnO3EE++`^\DB\NZGH:ab&&t
+"ZEp,r'O>BF8hnRK4^qG/,MJ7UDW3-,SPr3]ioX^r'c[te#am)QCCt'7:"kb
+@Zq.;IDPK4GTr0?U)p$YAK)=V$K@;q'g7t%)LEoDXcRhP!VaW#,t<McPR"LQ
+%)G8N4.#Cf%oBCDml<lndBo,O1?(3JCNB5a5)u.S@UYL7V%AK)*%L_SX@/2^
+LHrqU"XUOQK[LPs.!t[SD;)@j*Ii6k">@_%+sF'T^p5)iE!d5o.IICs6m$qf
+&o4/$lk/EjI%9-o@6q+rLje7!KddiG%CM7`#_T-XX_M:2`Dc&]&q,^8Z;rks
+<o[fR#NGW#*IU8dj*P>)#UQ!Ie2"U.h1+!(kX0HeS..?Y['<e;=UW4/apQ9I
+'G+-h.S#L=3/T+XCm-pb_bS,O(rR/W!1>G9R<`[BJ7qt4e5N9.\odU5h+Fmk
+L$g(a,W;X#^2XiPSHT9NoLEdR`39suS$1>2+MPAEP"pB=0Gi$O."+K.+lmm\
+Qrh4Y)p5QHlXgpTG[sc/6?,EG&/_@a\$XQ'*]S^O>l;qNA8tm=BLSc>=s6Wh
+C4<t/\oa3qd/4CHlJh\\K!.r!N2a[urp5jMe/`o[H@eZ5KHRJE%A4VpTH&Y;
+>60/j0*h``GXkL_:O:K<qtAu#F7HM.!OH$+Pm]n=&sZ_>A6rX5il.T@V5!7@
+/R*u.c,AIRoFHs%Q)QgBo$u8#Xd!pJj(1j`MFXD(Gtf'ME9+H,l(*%TM.u*b
+E("_!,NWqQ'>r'&'I`I_hu2u7Hg\^m(T1f5P\Mn-ORh=2:k86)f.1&28)4$6
+SbS^9;+Wc2Yts6qS+Ja<VLA@8Lgjh&imFMkQRl9kg_tfqYsoO@P"%NPNKb$:
+F+b<1MC5-:OUr*mf`n!d71?I/\)2.VEl1&uoaq^o"Q50=P)YJuIa>*Y:#(7M
+b3$MSbS,Ol/IRW(b-TJ-2?9^tkK^Se80``,cYTb>%sF([PFGrG=upmd"JmI+
+rY\*Y@oe3nPQh7)&r.,5;:VR>SK\-;i^#],*.m9#6n%AedVr?KSUaG#nIr%_
+'SPIH]H+gZ-LT/HS^?.K1aZP+?d,65Uth1fOqT6rA`=u'O]e+9!4de.[-ugp
+hu/<pr.-q>SnosAn]3%`_9Kanm;I4(EQ>84rG*mYD;2K)][&SP!BK=_\.]R5
+)TM)q<]j6)#'U?FSVU#2(qGLL,`,#,'Bodr&3M$1h07cHXhC]:,s)@%lWKaV
+B$=G8H?N%(.M]16p$-\ceu:F\)6tlmP]#$XUr7?s=p1mW5k7d\$#6E^M$iDo
+HXm/A#c50U5NBG=;C%Ypas>)"a[3Od;U>b/+fH)Z]..&WIP-@1HO?5"NWLU9
+agjMs=X?gf2#a'YVnNB>9lfsgmr="3pYUHbIn+="$8i5dWd:lLb(^sO*f$R@
+D#Ch<ld1;QbP6W47>gRj!]7iJ(X0Bfi9Gm^6%u)#1oH^u'q;:K6QVmoQ.!;l
+2C;_\=+um5q2nnRgL'sN(H=`=,!Q@2H"@b+=aCVq"W^%ne(i`B]C?i.,g4ni
+)?MjKEG/=a^=:Y3JkG?4ZI$^d.m+`FL/WZ3Pl1D8J7rNWgn2BSIk=d,J/>Sr
+XNS]o&/V=6kF[6qpmi'W.:KbNX!k!.![-G0(G8+n+OV#InWg\[e@Wa]-iAZ*
+_&/kIX&lKb)PL$,=9O8BU)s(=V?GkUBuDGZVe8Z(d&+mal#!5PB&tVUKciH'
+$Y@cqnTtWZ/4cUCG/JNrK1*gi&G8<(e_1+D.Z2WT@MXtGi>Y2CT$YWc&-d4R
+A>(D$/g&5qlGDN@V'$7S."mbGP.tYRi^h:Y2/?6Qr)XSrKp(J/S._r#(S"=&
+e2*OLZUSi1UnjZABK37g/ftOXkFeDjUj[auAc/>aJ`O`Y_\G,X=M,PO_V%<,
+Cu;sTf</C9MP]#XHXK"@*7Y@L&[@G<c$N[/:5$JWLEI-;`PPtMA/j-/#mZkG
+:8mkJ4T+lUJ*k[\Mm@VG*+Zail?>T.d'T>4>]]Di/=]B<jJ%OU[aNM02U+.j
+!Khs_RLaC<('S'jMW*"1$m3.]c#8'Kc2[HDrtPQ"Bd73m*KXt&gpt'Z21s\Y
+$#(XG+5V$Gb8*AZm[ulj?o0Sj*&Rh`hJduFn4V$^J6&n,i0X>9oJ3#8GPq5U
+]Q@Hh*[qoa=t=lBYUOMI]G(@FaIPE%fOWj0W8o;L\Y>#cKj:rr%DaU'JQu@A
+Uu](\-_71Z5dkL^po#a9AL*45ErQhI!N8^[CtuNTZf[N_51%:f+__]a?0>l]
+V.9U[;N=(`Ym)YfrA)G&3fUVDm=+`/?h&:RFj$(&(VM!d;W\bib?A'F_RO4)
+=-c1[n40-oBKO<.mC1uaSt>CX4:[K@0PEl>\QH+G-t+Mh@4W=;j^0B_X%Y1M
+7VR:`E.<`BUVjVuTc^:e3lFo)%mdrb"/H2:)+,-8Ec/$pe.55=M5m)=oC'Be
+?:t4[5Q;TMV>a>0MM@5^_hSb420a>)Dc'\6,:1j3CW#s-U?&iqKu=ee/%eU3
+&tTJHCr:Hoan"VF)T\6u+8Y0$YJ0QR_.9-R,TbD/S-'.i`%55_,P%p:i1A8A
+BG:M&PWV38>uSt!J5Cbt5URX9GYhm"WdBhi13*D5X8?PUSm<@OmUTX!e0/E&
+T%J]en2MnZ=3)p#779Ul;/]Xl)G[9@6A1MmOp<TaKks:`bX..e>f#HcFCCX6
+0D2!\a1[V1Ab7\nc=S^:DHbA8i!sH4I:r\N8b;8YX`&n8H]"Cc*E"A%O4&LU
+p"*:N,F$k"=-@hFPUGJOVAI6W$L%dFME;J!;BG.GPKm#P_-K5qYp["LQ8!0q
+15hOTKUrf$h#'rtqNEu>@)9-[b;?h0&N!"\'1cjlP4e+o:ik;@c?UG;*4hRh
+P+8nd1tn;YQCi(/F_rL&:2nO@2\[eI,3/H-rquSj+Cu_?a0X!Bn6c4g?bB-b
+!X0tn9gG,3Mm+bD]KT!bTqF)ME/1HG9l&@`jW+,1pk0h?QVdG4G9?S*R564J
+Ab"d!Zp$t%VT,*pB1""j23*n+]2)inDr.!e(5c.Y#=Wa3)4F_/7k7lg"6>sh
+62=W*Hq6Rt>pF\%(mX^Ihu4B9`>)@NlC[3k-C?L=d's.\5s[E7cF$8:*V_62
+ba<aA!7'Ga,ti>mbCR9f%OW61(]8$ll^g7d:7XF7dtfI56ElCO(HI%F1`93-
+X2u*`,_Kl/\2baTf3NUZT:j)_*'&U`9C\fs$mL`.O#TEH+;FS"5R7fF;?5ga
+O&DZZ@0+mg"d%ngkK]V\H1Jb%"'2\i4D`c\N>@XJP!'Gf,!p:$B]6Ut[$-Z9
+Ukb.tPI6eRAQ*u6Up(>J&=Y2hGZgsj<'EKu3IB>XCBGi<U]9h=5N%AaI-u_=
+5V^,&R3s^^.<IP'D1YU2R/j6YP:#')H]$B#8tu#oGc2[8aG%^kF3d#5F2X=N
+_$*P,9Z.p;$,N,p2p2Gf%1#BABdSGFe?u/#m.[`IC.GPeol]WR&YDcRM8Uk.
+>[;pYJ>XnlAA4ZMXNN.5Pd]WHBMMcZJ4>;jLleEV63ra%BLRjFASF=0E%*2n
+9Pm1Tgh^7aL1qP-aY1F,dUe3%%uWiK)![6udj!\!s#lOE1q3]WD@EHWA=EqX
+^`Eku/73&J>H.rDa'3%;&6(W#_d\&nSd:$2im(LY[hYB3H^5g6Rmm"uf!IUD
+caY&=o7>2R6YKtkA?aRg9+.JOO[bp[agr3;<bTdjD7:ZacaM:k$m5W,8#a?S
+NRgq77*-,<R@5<c!MGK7F"ItIW!<Yr@6:uZGs-KGW73eiX@.`LXE?sOK'?-%
+JnP`.icQB"YmDJn4NU>AFUpV(!)GnN1dqZnjK386(E]d?rY7(m*00&l+s]*,
+e]WE#l)3fC.9$JY#H_ZW@U9M&PY6OmiuS0[5Q1cRh1gS3#O!Ke?l?h3V*dmP
+D^d+ane4hQW$@]a>I22>.)7SBe;WZ.h$"12Xp.Hqq5S(fZiZ<8GQSDDPs)DR
+F`.,o'hX/aV>sd8e[gVh$Xk.Q0t6/_Zjr@O\Zp,^EcKp'"aU_EUE11'>e"qB
+<\1-=2T?,KKEL>S!Q^lt58DB%1euB\k&s15B9Z)U/6Pg'G`ir*hF+0q!IMOH
+jtmjT5r);']\refqt2V"C/+V@#SoR;mY6b7+I]aP#:-*^gU:tQ[,Hfq_P?/j
+Zmdker,C%Q8#RM%VFk?XC=]K.I;nnaj&?iHBh(,0B0&u&'L.TP<82X@6F]f&
+VeudSOgMWGE/2K]7^Or$BPDN"b/PG>Tf@)ms8CjTV/2AG;\lsB;5dn,P114O
+E6XU!KS#qdjF0?QotP:RNTM7kOoR1N8u$h3mC.s`:S0h10;i?m0+>*_VF?@V
+_.6JAq"#CWb!h=Q!Z%hnq24<eI67uILi(*7Jtu!Z=>jB9;;FN"Y1^,NX#A_L
+L+)9+L^,MifP</F(L;2$>\9\=\KMbh)\tfoi,F7fdJDXd[i"@(DUOTBn-=9d
+X::cBqk?2ePRM.IaYSKfEpse+qA*dr>VI?S/e2BB;_@<cU8,)!kt#)W4Zk.E
+B+m6!J_;SYoF`8Nig4t[1p!Eoldk'aS*O!ZJtnJk:lIm)a,67c@i*cG5%Q"D
+)F]Q"`@4,$i.p7-nJdFL)aIO:Y;1Qo@#jdpi<p966dXX4'B]'U=DA[+&Xl@_
+>W$Z[]i!,u2jIIA.]B'X?[P__CIr_IX,:#)4.]3BaAH"saW:%%R6a.^)AS93
+i*!&T1tKrM)8<X)U'(.cH>-+!;4d:)k)=7J@]t_IJ)kL7"5&:0F(\1*E^jjA
+7e2@'iPSK/(k[q\mUXY8SbhO(%3%3]K5Qa5%$MVPa[:-?,!42.+PCYnSA:Q4
+Q!:1>-Q+T7Z&Y'(Wm7(m0<KapQU1>%YG`jR6,GR$:I??<HYs!!#V/aE;K;V4
+K8W,&bO=[`EO6]MGgsifGU1j*)9@hh5X]<D*bQ>sZUu.NV_27Lfmkr#1ZZZi
+WH,Q>k(iF\?bUnU7T9Yr%UfrV)4N0oY,NC;8SN5b,GBB\[ap*9pfVdW-?T1M
+:Ob^G;>@hOpKeqi"Eu1)4su&^&uZ6g)>!\U39?YGTnIed1V)@r#1F'$JFL?H
+>)J[NJ_/s`g_+/;bs/hGD;u1<36$WK%(hhE685!e!+YSujL&dTg9`(`Rk8>5
+Id-"[06UhOG?g7/"aL]=hu2te8A_ZDb75LOJCeGIDs"e`]carRNYE*H1br=u
+gO]p,70W\a\%bAa:^EqJ`26t0JtaGO-o#:l1XMGdDB<>`ok`#0%4h`h6km0H
+@W-$8'4mg^h0!1DGe%'CnVDA<rpOHae:0&16*V*!+I39508N2OBGq6Dp-<?A
+KSK*7/8UN0jb%#79"<rFT21l]B$H4D6)-dHji`ulo5N@sT63](DqB6p:5r?;
+>b&Z%EPr=#qsM)l08A4%pNq=sao4a-o*Vd"e<TS;e>*?r8"'e/OWt)a:8>=o
+_UO1Ora01Be&Hft$FD="U9p:eP8:K'1,ku@\N^u`-Z`YtHc,t'#giZg8-@8F
+#iUmj7kfN5X_g2njhShXRr.,-k.7.U$9#bjXS4sZo07a#b?oM+K*Mo"]\lVS
+B.M-W\Tm1=-'#9$k.IZs-k)C:lX0Z1O.Dn?Cp#:hj+dA^6K"A'7m-QI)=f;c
+1=U7J*P%r+C]G)GL\tO%[qs_A06-[MeJKW-K<dVMCSu!VQ7a5s.G>J>[IYM&
+V5[AB)mr)/LhM;P=Y]`!`\0uYbAnb'@[<k8XWIo0i/I2M]Pa7EC"&rq'HH7=
+[;'F2/EbtZ-HolNe9E4)jrR^P'\3*Xhu=`*`Oi(LoL]7sH7I$[:eN2A9rR-l
+dEb]JkTZ.I>/aBLJ,-%Z@lDhDIIS6HVfpR7>!>ibS7@or+$PWaeC6TK`EYS]
+CLe:+^0!UdA7!.d:g=Mnn,R<fPa"T35Pse'L%+&U8Ukge`VG7*%gu*cYilVk
+d>iG+E<g@i-0P9k`im,Qapf*Am"%JKF6[SYMa!TOes6:7n,MOqk[(9@Ro<B@
+mf_Yb*5NrZa-^SObuXs)=q_%oAM)g0?u%FUh@R+o"1G)Xm+J_=$m\_iA><S@
+b`Q_*PcCmR_*T1oN'^_;NF>+>63=TV#@W@O2HQX!#+:B8(,=LP5$9D4c/!gs
+BSGNB_g1IoV+YM..S;/(C*EAb5'PsFXb3Ddb#/mjQ4J"Uo/lERZZ+m?";a!P
+EPiT6V5C,)pkSDoW"CLICdR)WDq#q1c&38h?5sSlre5G45(dN[S<>8'@C5rp
+Atl;Lm+@GlSrT815(,K'g'uI^ql5R?*-7;DAoo_)#T/hWV1r,dX]),mBm>Ap
+<7-]kQ#Xc0)i`ElZi)L6\.q>Nf3NSLRAlTTfN,j;DGJ<5I=h"@HB)5H:2^8*
+Pc;H4VrVebqA)!oU7$.F8!WBbFc3?L*/'MiBk\GAk^isGW-MU.`Hn:q[9/@t
+.L8VCiNVQ]G:JeGe1,i&V(HDafnCW4ki;:2d-'d`J-Bq4EC^IKTTsdOacFG4
+fRS#hcY]=+Os\poaZURc@JN&M,&[Vl'L97.J)gi;Jifnm%$S8s1g!)D$&fHd
+S%pOVkiAm+Te#U<htu=1mGE0AN2Ih+/$71iP`>7Wpprp%';O8K43:_O<9r/>
+s8)&bjXQXgd[1C;m2Th435p#Weq!0Lj^H]><H*`%p8t&s!Ji7u-D_^Dmnm.)
+K7V[rj$hi8%kW9>-a$<6Srj0$AP.&'$ZKVgA::\R8/F/-,A:uDj?NY=,7uXR
+%hFp`csJt[TFP*tJ.H\9UCh5<,4u3aEYlDa"H<r$),-L;A2Dmf-N],tJ5kPK
+]&!*E5=F9`$Y=`(b"E!sU/q(Zm);[+^i..9)]dmTrbag4$X/upCf1[1bA'>j
+4F-Me@p0YJ''A\-V=I#&Rh)?'asIrLC%uLbo5$UTfVF(Gb",o4W,m>i*,jn:
+Cm*DJ'C4D,<lcYAE_#lWeD3V7E07Y+%?9[E(k1L]E^:,ZUFAEbJhh,)Z52"F
+>#BEq[$2[&i9_opc"BBmTG=1LhbP`LneG+f(H"ql-*q[U:-:AeRbta)]$@/,
+?,Ifm^a:+XZI6N`=r)DY.C9D>1<_?m/M>LS3!*;j"MU8HkCu<L"La0=q=C6Y
+bTlTaeu`/#dE1.9$A^Z\]dPeuC0&l]Q+L"XjWuah;<.&S3DW_[*"5gXX@jjn
+T,Nb\naL?&(+b9U_P>:^ef.W*j4*1$>=$q1$oni%QCPruZ!rEQaIkP,25QcV
+3n_A$[bZ\^P8l\%UaSLa:HF&6G`maf(#j3mZ"M@PiCM4'TqG3V!$iF/H$tJ^
+A5puQrgng@10_D?[VXW9lF>gCj2X)rg^&`ZNfQeQr+*?OB_7%BkI1#Z)(A\k
+fYjOB8/OPr%?S,:!ji$Z6?tEV=NodlG]CtBUF)rX'G2'H@!M%jYsX9V+ff:*
+R_T3*G`',TF]Y"u".?#[R6jme7\OHqY$?fQjd3=mUiQdqR%H9![*g:dM5@!H
+n%%U&C>drqmmU71?7Lc^Z=V57`O/qe:+dE6s35J2K/u=EXQR[qhTBt+!T%!I
+TM(S%l)S?Kn9aot?*n8Ws&JR6D)G/.2+El6Q]oP;LjX1beTUlC`fY/mZq8G<
+C-7,C=1<6gY3A(H-@F$ub:,!AL,%F,@+MNWc47"MY)=#F7WWtOh01=N"pLkP
+FQsc2k7F;Lndc_fV6W__8FnTQC'K4ZLb#<uIOGrF;ds2[AVNp@`<I@9?jWnL
+Pf]IX2f8i:VM/1>BN[OcPVNj_%1S7/_!fgT%6)8H8X0j3a8c(`s.m*^Md/>:
+S'1Pi[GoT@numN8.rIOro&NJO4cC=X"/mFmYKT*u<\m6V+-#!=)1fU^8RpdC
+5ROM*9u9tX4"6.-+](TU0j$e>:K;0P?;?Sa-jJoMTYX5'5_D)I\&DE>,L+8'
+rq<h96&5@*]8mk_!fCcp*q7*YU"iJc!]5APc2[RZ5A&$#KteiglCjO-,(<dj
+h,.tfnh:"EB6aZnfuqqZ5q=[A`]2onWOGVqgUW=[pIBu]"um@)n%\o"^Io/9
+::DGS(;N"")HXt"<pK4Yjah/7%+%$0H`'Z3^3Jau'?UdU8n#(fONEt`SU;UE
+5V(IkF32PGe=14*k.4`RbSIf(Caji!ee+,sK9A'i4E,$A>qoj/%%<>,WioGm
+#@X9Ar.V"9ltI%?)<*rM-#tn4>sa?Z6`t)L\RYg]W!F6<YAA<]NQ4Cr&>*um
+,ndbj]?WFOjBGlC]C3HQ=+M0=Vn^S^HrtkT2HiWPj3qG0GZZBHUeu(I]f>uF
+Dnd;WIQWn;=7Hd],R]ttfWfDS6<iF3U=Td@R[Ug"bo1+$iCASGSGX45d\'Qq
+"tgOMC-b1dKbcuLD2C[pEYR+QT6qhU&T43$EDZpYcS#(];C,2S,.<D(.D
+.8kh4S`\i;L@qj1c<7R8>bQp]*85ptL/!gKj<'MZeL7t3QACABP)R6q'3^1<
+D*Bf)e>Z@i<)X$>2*uBF#<VL_MkV?3M\e%$HL@GD[im^sDnm]DX9Eoap?^I;
+Qf51!]p^t.heaEu$bM2r_2WOEWL^4)=%kMU&J#,D;qk7]Fb8M2"ei&4*K!7C
+Qs1t+VVD@<r/j(f,-!S:%%a2E/\,<=JZYQ&`utsQ;>cR-TnI(o#XtNX:rEZD
+6#'(OrfXI)1CI:oW1i<C7UH2CNAt_>eu]]dn?6-0G/8thQ`fc?%Yl"b9od,Q
+@?Q"`76$!&N97s56E\\cBQujRUqN<$Zn=ZK6(k$.TD@nBI'(3hQ6e<pAI/BZ
+,Lm'hW+t)lCmMA51lXsV,#kL>b,GQM19P%6bj,gKBkpQe"Ojn#79*6M@WP>`
+Rl@'BM7bYr_$=:ZqXj#iSQk9_eXj`A#%-&4$EY1@Lh_cChq^+!"N0NZnH9U$
+`>;n6-tTl[cGo&%+I:F#68\*js+9gUKJQ5]+qaD(q/@";!KBJ4i.6d&PV6=R
+'ELHV\[OG!dSXdtQjQ9I_%_*6NDJCZ$q*:(n/u04S2kZ#8@-`$3"3/%mOMkA
+l"A;3W>46=$"r_$-efQhJYSfa"_cM+o2tY*UIUC)!epZt]u"VBfR96Di7fhf
+[Nm.F+eRsT>LuMhI^t9.Vi&?X)-7\(Q+B\,#b:GfqP]3>3?Q=24]=6WOkR73
+^JljMPq>)^NZP`/NU]&C9?]He#SESm7'e=G*2+t921<:>kdrXYLOuhCo$sOJ
+2hs1D]O5!\Mt9r\misd#J[IDr"52.HP>nhG8XUM!kAUm2LYgs%1kET_$H\,G
+Z$Z65bGkrM#[N3iM`u\m[&bTN;c2>9lP+t9L)8SOXQ=6-O4>2@X]o;omu&-8
+7.EoL#?M2]GnHXH=[J@(7rr=8`P:qOHbR,6gpepWNlu>3VsD'hKn$c%6f"[3
+K#@rKEC5XPEIn6^jD[sOhR%mC[e9,q=Bs/YhP6(S7jh]!0JV9+K.C-@s#MW.
+;j1T)2bA#)7sC^/X4ZpV>K)>hr93+FQ$+lU"r*L%Rd?ctPi;X/>hs,)QI\u\
+*2(^b$lGZ)'sqjMpha;N^[+$[Z*Z&MTNZ#0g/Kq>H7?MZG%Z"GUO1B9PJ46U
+7mee+Z&'-TcCgl76NAmU_i<P-'CjPJauk=6d+k"2/a_cMap@\6gMc8sPD;C-
+Q0\9/iOA[:B4W]#q$_c(caJ0)Rd+YQ%5WtgA:7.B*-ChGiFc=d'S3pn)Ru4k
+>Xs?pM)MrBU;d8ARB-T(C,mVNQIa:#bsNuOk08eg`bE2NXcGd+kUO+m$`+><
+%5EH5*$J:8$5HaQCl)5`nYi>c;#kS:-X<u$X?T\U<GhVi_1MtOC!reRTgIB\
+m<okq,Vi1,b1PH6#Rr;iDHtKIj5]aoc`d;r1EQ3'+DO.iU]j?Nj2otQpSa'r
+Y>V2hWD]Ps%NK08f)S49]mB@W%UA%V7RTKcY10CIUN#2/\9t>XXnq.&(_:RY
+@K$&q]mKM)gdW6h4YR$:4m8cg+9DR&FW]Wd:B0KAs(V96GOhF'ft"&\%@ZU&
+Xo!5F\4o7kUi!s[!6p4Fku+m,hnD@,!c?Yu=h&FE"rd]TkcL.e;_p7h>XpSP
+*BJ;hEo/*3NkE2"X9!2`*'Sapo&Rp;Rl@g1!o3U=3bd0HR4Y+OnI!D$=Ms<o
+Iu[lKe(\`WGD0!-$5Jd]B?iu+)C6XSfW`Ht;%L=LM%_8r]kE(s_;s[B='h:M
+A]hiA#:!O&>6q0iiPUF<-o:'FJ'\U)I!g=mXBAc8C,Kqd]YLhn%e)q'04(09
+R&F<QI6\X8/6N%D0&*oSZT*$g%">M:l_M$^@?f&Qe>SKkGAd%Npt2JEd>I#G
+AF1>7;.jB+Rr[5WA>;VR;D18LZlq[8cpF+<ZV?aPYbW@2S7c<0GMdi#k'@/f
+.(V_A@[4=lN`NQ9dt;6lC3goP[2m&a=gNpX!g+&FXBC/nP%3iJ:NH@iKXF@5
+,(uS@"qB!'q259IU)gW0Ue-bVHgN[fWFlM1Yue,8`)b-O2+(,NcC>bo9cCb@
+if!NtgY39'X_4K<=d1ISh7@a3>e+V#XGQ1+FQcPsb8]AOi9].'++3R/(-&^e
+:3A0NKtGdGH1R1F9;6QcUk5a@5oC!R0%&s'3jCQ&+B3`9HsBo]-E]u]i78.%
+'/S^p]@Rt<2YF\+n(s<[="[UZ+CD6X^HNJ=.A2Kq2l6:cd#gClJeMr6(5h"B
+Lk:RRN*tDKD6J<5RS35DCh45J;FK*tb*D;M^V=\"DCj9%^juTL8?"_R)I_rq
+gQHPfbEa_ZW6hTK^8fSAOY1[)Rt6hT<tYRJ"VQI/V.6uPh22pt<i8]`;56V6
+:(mZZY$J*%H:jQ?I^'Yrd2FS*X*F0oV+R$$im3`>Dh+;[/U;*N8.5FL_HGTj
+,@A04/R#NK5(.a=1H3OI2c%&dBK9Wi+1:rSX&c?CkK[A8>.(%kLP@=R=>oSE
+%/c2!,=ZeBg/ZmZ=Qj;K#sPe8h)^&br2AV/$Q!,`(RS;,F;QoP(c>erG*p$W
++.n#Ykq#uC1i:rgb*4=mmnXt^G!ri4r5i0$!..+9D2U5c!F)[VWqA7lJ,Ji2
+7>l36G+&\uSt8]j6(C]:_UdTH[;4C>Sio/9D!p)hQX)-d5SV"(X*sm=C&FPl
+le-.f>4n,<=K%)l/!_eng3/p@<69&-*'8>F9:%:!16o9cm^(5'X.:caQS4D2
+V](mT?QLVi(r<4PWt5^,$u>0L)m][k'7ms_dA)?I#Gt:[PERS!ZHSn(En%\C
+b"02Bm^jDsD@@4VN'O][?4K97PI@ta=7?E8jiU"7TN.`h_%;cmP&0;.gB5<[
+"Y`gX$PogI[Hc,46[.qO($Y8npncnY"HbRQeD7K&4L,unEF\"fiXhKq`5H'1
+OT@n(G=U14@WGs,*M7W>)>q0;N>bN]3&,e:oDha=E8u!4lrcY#/O6>pB=:a+
+3/%T>[r1$W\T?g+X^&F-qUXG[8rOTAJlkSk8\<EX#ltconVWBgc]]^eFpdM?
+C!!a_d/b1J["&+)9G0Beo66-og9t=%M@((J'J<Y#GOOCX2fB2YoM]G&fH*2%
+BLd(\.?;_9J7#^!e\^Fsp&mUlTR).C([gq2<NB0JoQ'YAp47%DdLf`>:$'N_
+,7qA^'cNhdLCYIrs/<7qCpK09(.hA;,taEceZ7<up$:H4h#]tdN#+9^beQHJ
+jl6ab9HbcDF69Q*YMS?^P@Jll7\;#Y,MFHgZK9fJ;`bDrB[MF8MA.L;^3o`B
+K*L_qYp3/c%e*-/*@UpIO$=*l1'C0F*,YR%]<jm_2#C\Sm+FZoiaSkOk004q
+EAV(Lh(B.W)6NJlc!.)@Saka\B?Gt8!H*>DfY@F^lNi#aV3D(W/q3<u,DA\L
+cCGn9[=%f@)#%6>,;j5cW92?o_]Ua5Z;X`"1(m<N2FS4ONb6S,)%8Q`DO=h-
+VP`A<,66GedeY7!==DEXGiOcB2Jh"W"AhF2H@#>Rh5,qO2X-aSKNXgYd#g6-
+p?hSg+Bl$beLI@]4)!AVBnb1`'^%oC(4G8+8,DoE[r^`X8=0'O!O3n>>U_iU
+)=+k`S=k]/kKf25>.8BT0^'oSnC_HH`Q-$B0H"\"APNdIr&p;3Y[PF#&;XIN
+AM:c3djA1,Z')C(mZt$nW=g79pu$d4&bt"pi5(%cooY-p6BJf'^aZD4a>"h]
++UA2ZoB+:BJ84,;[0,\*MWN$JYB&aI,=ddL[r5WLb8]AOi7tka0>IFj'"g+@
+9bp>Z$\,?\X]egT4MV+.('N*Z%+(eQZY#LT[tM<3R=ch\RUjO'V.%8re##hI
+k$pkDIL9rV.pXX*,YhKQXhiFsb*4>WY[FqXh3*qa@Q_VBTH8FQm&<.s73_$D
+[S>q<O*0a;acReQ'cSQqW.ut#]Of8%3WIO4E`\Ln'=g(O>.!K\%mAF?:EQ<c
+8/FCOE.agI-Vn3`WB(nA=f%E-5V"=jI/3>YoB,Go[Hi\b.fr-R,?VU'0qO4-
+,pT7*TN)9=$0J3j[;&'`%,&=@GGNE/X'j\jD43mA7:\b1TT[M7(JBu@JM)97
+Xg_+p5t3%fOH>RnjHE@`$mlqQO`aS8-KN:4#LZ><4?;&I`@uf@r2*2XWno;G
+f/s1"Em0k'hkQ5r3cO#m4aZlj]"A&mEQIJ3gUHVb:HT42*tN?B"99&IbYs,u
+%3SW^G4"G;SSNk<!e!.Jgpj8RHHQ.K<L;>`$e;b,j)!DSTrc7o*NQT7K1_&J
+S3(qt9:%7f3j"IWKiZc[,2#4\W`5rqW)00h??p,Xo&[^S"%3+frRKLBgLN!)
+4oY6:EH-!FD8qMP_)/)-!La\>e>Q4h,EuuAA>)V\.TNcbakj^XJ,AWB_31_5
+KaS^.FmDMVM*'^ZC/!eg7(@VJE\/,M'I-.@9#<]I:ddl!P[LAg5_0!%.THi,
+6Z@&;kYZ_8ji2][^E?M/Z=Sq//(UIcO4C:4#Dsqp+b)[!+e_Ab)FR0ildp(-
+YT_5*kb56dIE\9G45Wf%1eARA+:nMl2f=kgOZbJ+DVd.m_Q9(S=0>oFITs:!
+NHBFJr3EQK:jr67Khqp(cprcK]TEHHMEp,!qsT%&\`[SNSfIq8!qhkHQq704
+nR+4DFZgH@[Q]3?r3^=l*]7\38kM^OM]CYei;EEBGke[]eWPUf%6PaP10@(<
+`JPCOjN,`F9:)JJQNe<6_oRrbW@3Zch7us4$;OH:>b='"C+N/"NY0?!*BJ9J
+imar+LG6jsPkfd,hr;V5UM8V7qe^IM#6*IJYP*d2Pi?aS7p+oD,IRnFFm@H_
+>8F<R*$\Rj@Kl`PKR1Lf#hA-:'J3Lq;Pctf"q9.g@Da5n`)DGo&K1N.8m`SK
+iE@=F*Q>W/*'AK8aH7]op?ZMFY+9,l3Q?D2s1gCM>U4VF:nU)JmbLsH=qs_`
+M@nd+i6aiha$YrdB>G;[JnUZ)5AVcX2bU6G!mcVZNjWihJCoZ)_+"ab%SG&S
+$JSh-5$e]$oG;^)N6D4W*P88T_&5qhi!!*qb48[f_SB6lMA=SsW*g54fKnE/
+I4J9qJ9+Vl?G3pmlZ0r<K2'Kc.(H\gKsAjUP3iT&KVff<K.\EinqC=@\t[j:
+;HO:[#TGrr_KE55!u3BAApm%\451<Iqj1M^hiE17EW+_f;V'ZsHGE<G=UcH:
+gbsNj&Db,46##B)iUt_0TiS:!(bC]O%#SK"?l;F+7'l;2;+;0E.5I<57F&;G
+G/X[#RA_'9>_;a0SLo1$DYWQ'4sT'I=nOMp-&u8NWFlC@hq2_%W\/Lk7U3o!
+7:j`4PtF\?8-gs`0`n'X-r[Zsjm!n%G]9&s:-g;=JqBInfAI"4Ngkcr_+QE"
+>QM8F9dZ1o(akq)nT!#(RZWE$H"EE_l$@78ML"bQD3l+^>CGZe+6D4e4l(#5
+\(DrI)9YiKEH-!rGM]uX_3/RgK%6o'=8#IuC=R(LWejP9*W\&mn-J$P\(=<=
+6-N5NE4?Q0Q<fe!G%0%@[;1qQ4#,L>b(4?:>_g[s9OYrj-i"a1mUc07AZ+<J
+>!9q]DB+82o)fusgpqKMmbBfO.4Np=4[q,RqXcOSb2DI#W@Ar1HgEJSAHo3$
+#=VahQ)3'L]7<2"&<q)lK-`Ft>+'M0$t@f1JhR(#*u1BWGn46^AOaVPEnP)4
+\HB]#S`4\7kU+k"f3F<o;T9.eD7l1^NOooY?G'[^Jj"GP#Y%%u%R0g[_Zq92
+Y\FHJ#p.4A;^>ApK:Rfs7Oqu7jX]*l.pNdR`3>;SfejF9Y*eSa+06FLqjHR:
+)5cnZa\@Nb7b#&dTX*Ip*IAeAVF>/q,9PTuVc"$#oB/VH;8Y[h,'M>@CY+=_
+H:VA7b`dE==X]YkOfIdL:732;ek0mAjdu@*-?J<1LU'E6V_S0KR)s<b.q=A#
+VmX$VnZJd\KcSs"^2Bt.noF/*HsrRK7Q2oulhZMg"P<1=*jTA#7ZEBF1Zl"7
+0nV$'o\nT9EsMu'.T`cXq=<VhIItoZPq!ZX'N1@Z-T7BlZIm<YPWV*QjH<.a
+bJP9a_?hMHfiQE<=<>6ujE%0$gaL:26ZDFTBP%3d$g&5TCo*95[BmT`q<%-C
+7JG\h5NgLm9fmL_<2?!E^s0Zg6\hm9\0ZgSO*Z=QYXuPN8$U1;Q0aa)VNC90
+H@VNt,;(O='#dP"9.%1dIQ,+0)F$$ajk;A[9lVaX3(GODYrngN6bYh3jgb1D
+[m*V8ekbJc8hB"`.&`XrF1,l9DS^o._<AoV_=H^299^jpnA>d[4=N,gQ,KZe
+%[9VQOg8@%(`-F=(![(DO>jAhkNVdHQhkab^4'D?a(p.gCjhXTc(+SDQGX6Z
+Hi&Q+\i4`[(XG),7CWYFZ\HJ,ISd=\aT;VQ]_^ooX&c?[F?9`;8_CCae&sDZ
+$mSB2/mYhtd:+/SH[ocU0?&Pb8qg)&KSMmER"'<V`k`lC\EBOOV'pNk^iqm1
+SK$q9);OC9i%(CiW:8b1YkKVFU^5+Rd\KINju'CG>`lR<kJ$H&$^dM(f7N9h
+LWf\fZ58ALPRIkR^:gA9,$jGu!EL6d21GJu@$AWu_VrCf'+tq(p[8":HggXt
+d'mrN4oqeo<egab.:?)UiR"8cX&lLEaoB?_kMHEP@AlBan)#4k.FrIp_hAI7
+FHW5em^j+i3hU5p8e,MLb6V99EtQo7bTaB^hX2&uOq?,1J,fTO":,P]5_&h8
+!X&c?+M]Rhrs*>,Oe2~>
+EI
Binary file docs/images/replogo.gif has changed
Binary file docs/images/testimg.gif has changed
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/reference/build.bat Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,3 @@
+del reference.pdf
+python ..\tools\yaml2pdf.py reference.yml
+start reference.pdf
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/reference/genreference.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,29 @@
+#!/bin/env python
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/reference/genreference.py
+__version__=''' $Id$ '''
+__doc__ = """
+This module contains the script for building the reference.
+"""
+def run(verbose=None, outDir=None):
+ import os, sys, shutil
+ from reportlab.tools.docco import yaml2pdf
+ from reportlab.lib.utils import _RL_DIR
+ if verbose is None: verbose=('-s' not in sys.argv)
+ yaml2pdf.run('reference.yml','reference.pdf')
+ if verbose: print 'Saved reference.pdf'
+ docdir = os.path.join(_RL_DIR,'docs')
+ if outDir: docDir = outDir
+ destfn = docdir + os.sep + 'reference.pdf'
+ shutil.copyfile('reference.pdf', destfn)
+ if verbose: print 'copied to %s' % destfn
+
+def makeSuite():
+ "standard test harness support - run self as separate process"
+ from reportlab.test.utils import ScriptThatMakesFileTest
+ return ScriptThatMakesFileTest('../docs/reference', 'genreference.py', 'reference.pdf')
+
+
+if __name__=='__main__':
+ run()
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/reference/reference.yml Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,217 @@
+.t ReportLab API Reference
+
+.nextPageTemplate Normal
+
+.h1 Introduction
+
+This is the API reference for the ReportLab library. All public
+classes, functions and methods are documented here.
+
+Most of the reference text is built automatically from the
+documentation strings in each class, method and function.
+That's why it uses preformatted text and doesn't look very
+pretty.
+
+Please note the following points:
+.bu <seqdefault id='list'/><bullet>(<seq/>)</bullet>Items with one leading underscore are considered private
+to the modules they are defined in; they are not documented
+here and we make no commitment to their maintenance.
+.bu <bullet>(<seq/>)</bullet>Items ending in a digit (usually zero) are experimental;
+they are released to allow widespread testing, but are
+guaranteed to be broken in future (if only by dropping the
+zero). By all means play with these and give feedback, but
+do not use them in production scripts.
+
+.h2 Package Architecture
+
+The reportlab package is broken into a number of subpackages.
+These are as follows:
+
+.df <font name="Courier"><b>reportlab.pdfgen</b></font>
+- this is the programming
+interface to the PDF file format. The Canvas (and its co-workers,
+TextObject and PathObject) provide everything you need to
+create PDF output working at a low level - individual shapes
+and lines of text. Internally, it constructs blocks of
+<i>page marking operators</i> which match your drawing commands,
+and hand them over to the <font name="Courier">pdfbase</font>
+package for drawing.
+
+.df <font name="Courier"><b>reportlab.pdfbase</b></font>
+- this is not part of the
+public interface. It contains code to handle the 'outer
+structure' of PDF files, and utilities to handle text metrics
+and compressed streams.
+
+.df <font name="Courier"><b>reportlab.platypus</b></font>
+- PLATYPUS stands for
+"Page Layout and Typography Using Scripts". It provides a
+higher level of abstraction dealing with paragraphs, frames
+on the page, and document templates. This is used for multi-
+page documents such as this reference.
+
+.df <font name="Courier"><b>reportlab.lib</b></font>
+- this contains code of
+interest to application developers which cuts across
+both of our libraries, such as standard colors, units, and
+page sizes. It will also contain more drawable and flowable
+objects in future.
+
+There is also a demos directory containing various demonstrations,
+and a docs directory. These can be accessed with package
+notation but should not be thought of as packages.
+
+Each package is documented in turn.
+
+.pageBreak
+.h1 <i>reportlab.pdfgen</i> subpackage
+
+This package contains three modules, canvas.py, textobject.py
+and pathobject.py, which define three classes of corresponding
+names. The only class users should construct directly is
+the Canvas, defined in reportlab.pdfgen.canvas; it provides
+methods to obtain PathObjects and TextObjects.
+
+
+.getClassDoc reportlab.pdfgen.canvas Canvas
+.pageBreak
+The method Canvas.beginPath allows users to construct
+a PDFPathObject, which is defined in reportlab/pdfgen/pathobject.py.
+
+.getClassDoc reportlab.pdfgen.pathobject PDFPathObject
+.pageBreak
+The method Canvas.beginText allows users to construct
+a PDFTextObject, which is defined in reportlab/pdfgen/textobject.py.
+
+.getClassDoc reportlab.pdfgen.textobject PDFTextObject
+
+.pageBreak
+.h1 <i>reportlab.platypus</i> subpackage
+
+The platypus package defines our high-level page layout API.
+The division into modules is far from final and has been
+based more on balancing the module lengths than on any
+particular programming interface. The __init__ module
+imports the key classes into the top level of the package.
+
+.h2 Overall Structure
+
+Abstractly Platypus currently can be thought of has having four
+levels: documents, pages, frames and flowables (things which can fit into frames in some way).
+In practice there is a fifth level, the canvas, so that if you want
+you can do anything that pdfgen's canvas allows.
+
+.h2 Document Templates
+.h3 BaseDocTemplate
+
+The basic document template class; it provides for initialisation and
+rendering of documents. A whole bunch of methods
+<b><font name=courier>handle_XXX</font></b> handle document
+rendering events. These event routines all contain some
+significant semantics so while these may be overridden that
+may require some detailed knowledge. Some other methods are
+completely virtual and are designed to be overridden.
+.h3 BaseDocTemplate
+.getClassDoc reportlab.platypus.doctemplate BaseDocTemplate
+
+.pageBreak
+A simple document processor can be made using derived class,
+<b><font name=courier>SimpleDocTemplate</font></b>.
+
+.pageBreak
+.h3 SimpleDocTemplate
+.getClassDoc reportlab.platypus.doctemplate SimpleDocTemplate
+
+.pageBreak
+.h2 Flowables
+.getClassDoc reportlab.platypus.paragraph Paragraph
+.getClassDoc reportlab.platypus.flowables Flowable
+.getClassDoc reportlab.platypus.flowables XBox
+.getClassDoc reportlab.platypus.flowables Preformatted
+.getClassDoc reportlab.platypus.flowables Image
+.getClassDoc reportlab.platypus.flowables Spacer
+.getClassDoc reportlab.platypus.flowables PageBreak
+.getClassDoc reportlab.platypus.flowables CondPageBreak
+.getClassDoc reportlab.platypus.flowables KeepTogether
+.getClassDoc reportlab.platypus.flowables Macro
+.getClassDoc reportlab.platypus.xpreformatted XPreformatted
+.getClassDoc reportlab.platypus.xpreformatted PythonPreformatted
+
+.pageBreak
+.h1 <i>reportlab.lib</i> subpackage
+
+This package contains a number of modules which either add utility
+to pdfgen and platypus, or which are of general use in graphics
+applications.
+
+.h2 <i>reportlab.lib.colors</i> module
+.getModuleDoc reportlab.lib.colors
+
+.h2 <i>reportlab.lib.corp</i> module
+.getModuleDoc reportlab.lib.corp
+
+.h2 <i>reportlab.lib.enums</i> module
+.getModuleDoc reportlab.lib.enums
+
+.h2 <i>reportlab.lib.fonts</i> module
+.getModuleDoc reportlab.lib.fonts
+
+.h2 <i>reportlab.lib.pagesizes</i> module
+.getModuleDoc reportlab.lib.pagesizes
+
+.h2 <i>reportlab.lib.sequencer</i> module
+.getModuleDoc reportlab.lib.sequencer
+
+
+
+
+.pageBreak
+.h1 Appendix A - CVS Revision History
+.beginPre Code
+$Log: reference.yml,v $
+Revision 1.1 2001/10/05 12:33:33 rgbecker
+Moved from original project docs, history lost
+
+Revision 1.13 2001/08/30 10:32:38 dinu_gherman
+Added missing flowables.
+
+Revision 1.12 2001/07/11 09:21:27 rgbecker
+Typo fix from Jerome Alet
+
+Revision 1.11 2000/07/10 23:56:09 andy_robinson
+Paragraphs chapter pretty much complete. Fancy cover.
+
+Revision 1.10 2000/07/03 15:39:51 rgbecker
+Documentation fixes
+
+Revision 1.9 2000/06/28 14:52:43 rgbecker
+Documentation changes
+
+Revision 1.8 2000/06/19 23:52:31 andy_robinson
+rltemplate now simple, based on UserDocTemplate
+
+Revision 1.7 2000/06/17 07:46:45 andy_robinson
+Small text changes
+
+Revision 1.6 2000/06/14 21:22:52 andy_robinson
+Added docs for library
+
+Revision 1.5 2000/06/12 11:26:34 andy_robinson
+Numbered list added
+
+Revision 1.4 2000/06/12 11:13:09 andy_robinson
+Added sequencer tags to paragraph parser
+
+Revision 1.3 2000/06/09 01:44:24 aaron_watters
+added automatic generation for pathobject and textobject modules.
+
+Revision 1.2 2000/06/07 13:39:22 andy_robinson
+Added some text to the first page of reference, and a build batch file
+
+Revision 1.1.1.1 2000/06/05 16:39:04 andy_robinson
+initial import
+
+.endPre
+
+
+
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/userguide/app_demos.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,113 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/app_demos.py
+from reportlab.tools.docco.rl_doc_utils import *
+
+Appendix1("ReportLab Demos")
+disc("""In the subdirectories of $reportlab/demos$ there are a number of working examples showing
+almost all aspects of reportlab in use.""")
+
+heading2("""Odyssey""")
+disc("""
+The three scripts odyssey.py, dodyssey.py and fodyssey.py all take the file odyssey.txt
+and produce PDF documents. The included odyssey.txt is short; a longer and more testing version
+can be found at ftp://ftp.reportlab.com/odyssey.full.zip.
+""")
+eg("""
+Windows
+cd reportlab\\demos\\odyssey
+python odyssey.py
+start odyssey.pdf
+
+Linux
+cd reportlab/demos/odyssey
+python odyssey.py
+acrord odyssey.pdf
+""")
+disc("""Simple formatting is shown by the odyssey.py script. It runs quite fast,
+but all it does is gather the text and force it onto the canvas pages. It does no paragraph
+manipulation at all so you get to see the XML < & > tags.
+""")
+disc("""The scripts fodyssey.py and dodyssey.py handle paragraph formatting so you get
+to see colour changes etc. Both scripts
+use the document template class and the dodyssey.py script shows the ability to do dual column
+layout and uses multiple page templates.
+""")
+
+heading2("""Standard Fonts and Colors""")
+disc("""In $reportlab/demos/stdfonts$ the script stdfonts.py can be used to illustrate
+ReportLab's standard fonts. Run the script using""")
+eg("""
+cd reportlab\\demos\\stdfonts
+python stdfonts.py
+""")
+disc("""
+to produce two PDF documents, StandardFonts_MacRoman.pdf &
+StandardFonts_WinAnsi.pdf which show the two most common built in
+font encodings.
+""")
+disc("""The colortest.py script in $reportlab/demos/colors$ demonstrates the different ways in which
+reportlab can set up and use colors.""")
+disc("""Try running the script and viewing the output document, colortest.pdf. This shows
+different color spaces and a large selection of the colors which are named
+in the $reportlab.lib.colors$ module.
+""")
+heading2("""Py2pdf""")
+disc("""Dinu Gherman (<gherman@europemail.com>) contributed this useful script
+which uses reportlab to produce nicely colorized PDF documents from Python
+scripts including bookmarks for classes, methods and functions.
+To get a nice version of the main script try""")
+eg("""
+cd reportlab/demos/py2pdf
+python py2pdf.py py2pdf.py
+acrord py2pdf.pdf
+""")
+disc("""i.e. we used py2pdf to produce a nice version of py2pdf.py in
+the document with the same rootname and a .pdf extension.
+""")
+disc("""
+The py2pdf.py script has many options which are beyond the scope of this
+simple introduction; consult the comments at the start of the script.
+""")
+heading2("Gadflypaper")
+disc("""
+The Python script, gfe.py, in $reportlab/demos/gadflypaper$ uses an inline style of
+document preparation. The script almost entirely produced by Aaron Watters produces a document
+describing Aaron's $gadfly$ in memory database for Python. To generate the document use
+""")
+eg("""
+cd reportlab\\gadflypaper
+python gfe.py
+start gfe.pdf
+""")
+disc("""
+everything in the PDF document was produced by the script which is why this is an inline style
+of document production. So, to produce a header followed by some text the script uses functions
+$header$ and $p$ which take some text and append to a global story list.
+""")
+eg('''
+header("Conclusion")
+
+p("""The revamped query engine design in Gadfly 2 supports
+..........
+and integration.""")
+''')
+heading2("""Pythonpoint""")
+disc("""Andy Robinson has refined the pythonpoint.py script (in $reportlab\\demos\\pythonpoint$)
+until it is a really useful script. It takes an input file containing an XML markup
+and uses an xmllib style parser to map the tags into PDF slides. When run in its own directory
+pythonpoint.py takes as a default input the file pythonpoint.xml and produces pythonpoint.pdf
+which is documentation for Pythonpoint! You can also see it in action with an older paper
+""")
+eg("""
+cd reportlab\\demos\\pythonpoint
+python pythonpoint.py monterey.xml
+start monterey.pdf
+""")
+disc("""
+Not only is pythonpoint self documenting, but it also demonstrates reportlab and PDF. It uses
+many features of reportlab (document templates, tables etc).
+Exotic features of PDF such as fadeins and bookmarks are also shown to good effect. The use of
+an XML document can be contrasted with the <i>inline</i> style of the gadflypaper demo; the
+content is completely separate from the formatting
+""")
\ No newline at end of file
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/userguide/ch1_intro.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,693 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch1_intro.py
+from reportlab.tools.docco.rl_doc_utils import *
+import reportlab
+
+title("ReportLab PDF Library")
+title("User Guide")
+centred('ReportLab Version ' + reportlab.Version)
+
+nextTemplate("Normal")
+
+########################################################################
+#
+# Chapter 1
+#
+########################################################################
+
+
+heading1("Introduction")
+
+
+heading2("About this document")
+disc("""This document is an introduction to the ReportLab PDF library.
+Some previous programming experience
+is presumed and familiarity with the Python Programming language is
+recommended. If you are new to Python, we tell you in the next section
+where to go for orientation.
+""")
+
+disc("""
+This manual does not cover 100% of the features, but should explain all
+the main concepts and help you get started, and point you at other
+learning resources.
+After working your way through this, you should be ready to begin
+writing programs to produce sophisticated reports.
+""")
+
+disc("""In this chapter, we will cover the groundwork:""")
+bullet("What is ReportLab all about, and why should I use it?")
+bullet("What is Python?")
+bullet("How do I get everything set up and running?")
+
+todo("""
+We need your help to make sure this manual is complete and helpful.
+Please send any feedback to our user mailing list,
+which is signposted from <a href="http://www.reportlab.org/">www.reportlab.org</a>.
+""")
+
+heading2("What is the ReportLab PDF Library?")
+disc("""This is a software library that lets you directly
+create documents in Adobe's Portable Document Format (PDF) using
+the Python programming language. It also creates charts and data graphics
+in various bitmap and vector formats as well as PDF.""")
+
+disc("""PDF is the global standard for electronic documents. It
+supports high-quality printing yet is totally portable across
+platforms, thanks to the freely available Acrobat Reader. Any
+application which previously generated hard copy reports or driving a printer
+can benefit from making PDF documents instead; these can be archived,
+emailed, placed on the web, or printed out the old-fashioned way.
+However, the PDF file format is a complex
+indexed binary format which is impossible to type directly.
+The PDF format specification is more than 600 pages long and
+PDF files must provide precise byte offsets -- a single extra
+character placed anywhere in a valid PDF document can render it
+invalid. This makes it harder to generate than HTML.""")
+
+disc("""Most of the world's PDF documents have been produced
+by Adobe's Acrobat tools, or rivals such as JAWS PDF Creator, which act
+as 'print drivers'. Anyone wanting to automate PDF production would
+typically use a product like Quark, Word or Framemaker running in a loop
+with macros or plugins, connected to Acrobat. Pipelines of several
+languages and products can be slow and somewhat unwieldy.
+""")
+
+
+disc("""The ReportLab library directly creates PDF based on
+your graphics commands. There are no intervening steps. Your applications
+can generate reports extremely fast - sometimes orders
+of magnitude faster than traditional report-writing
+tools. This approach is shared by several other libraries - PDFlib for C,
+iText for Java, iTextSharp for .NET and others. However, The ReportLab library
+differs in that it can work at much higher levels, with a full featured engine
+for laying out documents complete with tables and charts. """)
+
+
+disc("""In addition, because you are writing a program
+in a powerful general purpose language, there are no
+restrictions at all on where you get your data from,
+how you transform it, and the kind of output
+you can create. And you can reuse code across
+whole families of reports.""")
+
+disc("""The ReportLab library is expected to be useful
+in at least the following contexts:""")
+bullet("Dynamic PDF generation on the web")
+bullet("High-volume corporate reporting and database publishing")
+bullet("""An embeddable print engine for other applications, including
+a 'report language' so that users can customize their own reports. <i>
+This is particularly relevant to cross-platform apps which cannot
+rely on a consistent printing or previewing API on each operating
+system</i>.""")
+bullet("""A 'build system' for complex documents with charts, tables
+and text such as management accounts, statistical reports and
+scientific papers """)
+bullet("""Going from XML to PDF in one step!""")
+
+
+
+
+heading2("What is Python?")
+disc("""
+Python is an <i>interpreted, interactive, object-oriented</i> programming language. It is often compared to Tcl, Perl,
+Scheme or Java.
+""")
+
+disc("""
+Python combines remarkable power with very clear syntax. It has modules, classes, exceptions, very high level
+dynamic data types, and dynamic typing. There are interfaces to many system calls and libraries, as well as to
+various windowing systems (X11, Motif, Tk, Mac, MFC). New built-in modules are easily written in C or C++.
+Python is also usable as an extension language for applications that need a programmable interface.
+""")
+
+
+disc("""
+Python is as old as Java and has been growing steadily in popularity for 13 years; since our
+library first came out it has entered the mainstream. Many ReportLab library users are
+already Python devotees, but if you are not, we feel that the language is an excellent
+choice for document-generation apps because of its expressiveness and ability to get
+data from anywhere.
+""")
+
+disc("""
+Python is copyrighted but <b>freely usable and distributable, even for commercial use</b>.
+""")
+
+heading2("Acknowledgements")
+disc("""Many people have contributed to ReportLab. We would like to thank
+in particular (in approximately chronological order) Chris Lee, Magnus Lie Hetland,
+Robert Kern, Jeff Bauer (who contributed normalDate.py); Jerome Alet (numerous patches
+and the rlzope demo), Andre Reitz, Max M, Albertas Agejevas, T Blatter, Ron Peleg,
+Gary Poster, Steve Halasz, Andrew Mercer, Paul McNett, Chad Miller, Tim Roberts,
+Jorge Godoy and Benn B.""")
+
+disc("""Special thanks go to Just van Rossum for his valuable assistance with
+font technicalities and the LettErrorRobot-Chrome type 1 font.""")
+
+disc("""Marius Gedminas deserves a big hand for contributing the work on TrueType fonts and we
+are glad to include these in the toolkit. Finally we thank Bigelow & Holmes Inc ($design@bigelowandholmes.com$)
+for Luxi Serif Regular and Ray Larabie ($http://www.larabiefonts.com$) for the Rina TrueType font.""")
+
+heading2("Installation and Setup")
+
+disc("""
+Below we provide an abbreviated setup procedure for Python experts and a more
+verbose procedure for people who are new to Python.
+""")
+
+heading3("Installation for experts")
+disc("""First of all, we'll give you the high-speed version for experienced
+Python developers:""")
+list("""Install Python 2.3 or later (2.4 recommended). ReportLab 2.x uses
+ Python 2.3 features and will use 2.4 going forwards. We also maintain
+ a 1.x branch which works back to Python 2.1.
+ """)
+list("""If you want to produce compressed PDF files (recommended),
+check that zlib is installed.""")
+list("""If you want to work with bitmap images, install and
+test the Python Imaging Library""")
+list("""Unpack the reportlab package (reportlab.zip
+or reportlab.tgz) into a directory on your path. (You can also use ^python setup.py install^ if you wish)""")
+list("""Unpack the rl_addons package and build the C extensions with distutils; or grab the
+corresponding .pyd files from our download page. """)
+
+
+list("""$cd$ to ^reportlab/test^ and execute $runAll.py$.
+This will create many PDF files. """)
+list("""You may also want to download and run the ^rl_check.py^ on our site, which
+health-checks an installation and reports on any missing options. """)
+disc(" ")
+disc("""If you have any problems, check the 'Detailed Instructions' section below.""")
+
+heading3("A note on available versions")
+disc("""The $reportlab$ library can be found at $ftp.reportlab.com$ in
+the top-level directory or at http://www.reportlab.com/ftp/.
+Each successive version is stored in both zip
+and tgz format, but the contents are identical apart from line endings.
+Versions are numbered: $ReportLab_1_00.zip$, $ReportLab_1_01.zip$ and so on. The
+latest stable version is also available as just $reportlab.zip$ (or
+$reportlab.tgz$), which is actually a symbolic link to the latest
+numbered version. Finally, daily snapshots off the trunk are available as
+$current.zip$ (or $current.tgz$).
+""")
+
+
+heading3("Instructions for novices: Windows")
+
+
+
+disc("""This section assumes you
+don't know much about Python. We cover all of the steps for three
+common platforms, including how to verify that each one is complete.
+While this may seem like a long list, everything takes 5 minutes if
+you have the binaries at hand.""")
+
+
+restartList()
+
+list("""Get and install Python from $http://www.python.org/.$
+Reportlab 2.x works with Python 2.3 upwards but we strongly recommend to use
+the latest stable version of Python (2.4.3 at the time of writing).
+Follow the links to 'Download' and get the latest
+official version. This will install itself into $C:\Python24$
+After installing, you should be able to run the
+'Python (command line)' option from the Start Menu.""")
+
+list("""If on Windows, we strongly recommend installing the Python Windows
+Extensions, which let you use access all the Windows data sources, and provide
+a very nice IDE. This can be found at ^http://sourceforge.net/projects/pywin32/^.
+Once this is installed, you can start
+Pythonwin from the Start Menu and get a GUI application.""")
+
+list("""The next step is optional and only necessary if you want to
+include images in your reports; it can also be carried out later. However
+we always recommend a full installation if time permits.""")
+
+list("""Install the Python Imaging Library ($PIL$) from $http://www.pythonware.com/products/pil/$.
+""")
+
+
+list("""Now you are ready to install reportlab itself. Unzip the archive straight into
+your Python directory; it creates a subdirectory named
+$reportlab$. You should now be able to go to a Python
+command line interpreter and type $import reportlab$ without getting
+an error message.""")
+
+list("""Download the zip file of precompiled DLLs for your Python version from
+the bottom of the ^http://www.reportlab.org/downloads.html^ downloads page, and unzip
+them into ^C:\Python24\lib\site-packages^ (or its equivalent for other Python versions""")
+
+list("""Open up a $MS-DOS$ command prompt and CD to
+"$..\\reportlab\\test$". Enter "$runAll.py$". You should see lots of dots
+and no error messages. This will also create many PDF files and generate
+the manuals in ^reportlab/docs^ (including this one). """)
+
+list("""
+Finally, we recommend you download and run the script ^rl_check.py^ from
+^^http://www.reportlab.org/ftp/^. This will health-check all the above
+steps and warn you if anything is missing or mismatched.""")
+
+heading3("Instructions for Python novices: Unix")
+
+restartList()
+list("""On a large number of Unix and Linux distributions, Python is already installed,
+or is avaialable as a standard package you can install with the relevant package manager.""")
+
+list("""If you want to compile from
+source download the latest
+sources from http://www.python.org (currently the latest source is
+in http://www.python.org/ftp/python/2.4.3/Python-2.4.3.tgz). If you wish to use
+binaries
+get the latest RPM or DEB or whatever package and install (or get your
+super user (system administrator) to do the work).""")
+
+list("""If you are building Python yourself, unpack the sources into a
+temporary directory using a tar command e.g. $tar xzvf Python-2.4.3.tgz$;
+this will create a subdirectory called Python-2.4.3 (or whatever). cd
+into this directory. Then read the file $README$! It contains the
+latest information on how to install Python.""")
+
+list("""If your system has the gzip libz library installed
+check that the zlib extension will be installed by default by editing
+the file Modules/Setup.in and ensuring that (near line 405) the line
+containing zlib zlibmodule.c is uncommented i.e. has no hash '#' character at the
+beginning. You also need to decide if you will be installing in the default location
+(/usr/local/) or in some other place.
+The zlib module is needed if you want compressed PDF and for some images.""")
+
+list("""Invoke the command $./configure --prefix=/usr/local$ this should configure
+the source directory for building. Then you can build the binaries with
+a $make$ command. If your $make$ command is not up to it try building
+with $make MAKE=make$. If all goes well install with $make install$.""")
+
+list("""If all has gone well and python is in the execution search path
+you should now be able to type $python$ and see a <b>Python</b> prompt.""")
+
+list("""
+Once you can do that it's time to try and install ReportLab.
+First get the latest reportlab.tgz.
+If ReportLab is to be available to all then the reportlab archive should be unpacked in
+the lib/site-python directory (typically /usr/local/lib/site-python) if necessary by
+a superuser.
+Otherwise unpack in a directory of your choice and arrange for that directory to be on your
+$PYTHONPATH$ variable.
+""")
+eg("""
+#put something like this in your
+#shell rcfile
+PYTHONPATH=$HOME/mypythonpackages
+export PYTHONPATH
+""",after=0.1)
+
+list("""You should now be able to run python and execute the python statement
+""",doBullet=0)
+eg("""import reportlab""",after=0.1)
+list("""If you want to use images you should certainly consider
+getting & installing the Python Imaging Library - follow the
+directions from
+$http://www.python.org/sigs/image-sig/index.html$ or get it directly from
+$http://www.pythonware.com/products/pil/$.""")
+
+
+heading3("Instructions for Python novices: Mac")
+disc("""
+This is much, much easier with Mac OS X since Python (usually 2.3) is installed on your
+system as standard. Just follow the instructions for installing the ReportLab archive
+above.
+""")
+
+
+heading3("Instructions for Jython (Java implementation of Python) users")
+
+disc("""
+A port to Java was done in 2004. This involved some changes to the framework
+and creating Java equivalents of the C extensions. At the end of this work
+the entire output of the test suite produced byte-for-byte identical output.
+However, we have not been testng against Jython since, because (a) as far as
+we know no one used it, and (b) Jython has not kept up with Python features
+which we need to use. We suggest you use ReportLab v1.19 or v1.20 which
+were Python-2.1 compatible. We'd welcome test reports and/or a volunteer to
+refresh things now that Jython is progressing.""")
+
+disc("""
+The Jython version was tested under Sun's J2SDK 1.3.1. It is known that under
+J2SDK 1.4.0_01 $test_pdfbase_ttfonts.py$ fails horribly with an outOfMemory
+exception, probably caused by a JVM bug.
+""")
+
+
+
+
+restartList()
+
+list("""
+Before installing Jython, make sure you have a supported version of
+Java Virtual Machine installed. For the list of supported JVM's see
+$http://www.jython.org/platform.html$
+""")
+
+list("""
+To install Jython, download the setup package from $www.jython.org$ and
+follow installation instructions.
+""")
+
+list("""
+To set ReportLab toolkit under Jython PATH, edit $JYTHON_HOME/registry$ file
+and include line that tells Jython where to look for packages. To include
+ReportLab toolkit under Jython PATH, directory that contains Reportlab
+should be included: $python.path=REPORTLAB_HOME_PARENT_DIR$
+For example, if your Reportlab toolkit is installed under $C:\code\\reportlab$
+the path line should be: $python.path=C:\\\\code$ (note two backslashes!)
+""")
+
+heading3("Instructions for IronPython (Python for .NET) users")
+
+disc("""
+We haven't tackled this yet officially, but IronPython can apparently
+run much of our code. We do need to go through the same exercises we did for Jython
+- finding the .NET equivalents of _rl_accel, pyRXP, _renderPM and PIL -
+to get 100% managed code. Hopefully this will happen soon and we'd be
+delighted to work with anyone on this.
+""")
+
+
+heading2("Getting Involved")
+disc("""ReportLab is an Open Source project. Although we are
+a commercial company we provide the core PDF generation
+sources freely, even for commercial purposes, and we make no income directly
+from these modules. We also welcome help from the community
+as much as any other Open Source project. There are many
+ways in which you can help:""")
+
+bullet("""General feedback on the core API. Does it work for you?
+Are there any rough edges? Does anything feel clunky and awkward?""")
+
+bullet("""New objects to put in reports, or useful utilities for the library.
+We have an open standard for report objects, so if you have written a nice
+chart or table class, why not contribute it?""")
+
+bullet("""Demonstrations and Case Studies: If you have produced some nice
+output, send it to us (with or without scripts). If ReportLab solved a
+problem for you at work, write a little 'case study' and send it in.
+And if your web site uses our tools to make reports, let us link to it.
+We will be happy to display your work (and credit it with your name
+and company) on our site!""")
+
+bullet("""Working on the core code: we have a long list of things
+to refine or to implement. If you are missing some features or
+just want to help out, let us know!""")
+
+disc("""The first step for anyone wanting to learn more or
+get involved is to join the mailing list. To Subscribe visit
+$http://two.pairlist.net/mailman/listinfo/reportlab-users$.
+From there you can also browse through the group's archives
+and contributions. The mailing list is
+the place to report bugs and get support. """)
+
+
+heading2("Site Configuration")
+disc("""There are a number of options which most likely need to be configured globally for a site.
+The python script module $reportlab/rl_config.py$ may be edited to change the values of several
+important sitewide properties.""")
+bullet("""verbose: set to integer values to control diagnostic output.""")
+bullet("""shapeChecking: set this to zero to turn off a lot of error checking in the graphics modules""")
+bullet("""defaultEncoding: set this to WinAnsiEncoding or MacRomanEncoding.""")
+bullet("""defaultPageSize: set this to one of the values defined in reportlab/lib/pagesizes.py; as delivered
+it is set to pagesizes.A4; other values are pagesizes.letter etc.""")
+bullet("""defaultImageCaching: set to zero to inhibit the creation of .a85 files on your
+hard-drive. The default is to create these preprocessed PDF compatible image files for faster loading""")
+bullet("""T1SearchPath: this is a python list of strings representing directories that
+may be queried for information on Type 1 fonts""")
+bullet("""TTFSearchPath: this is a python list of strings representing directories that
+may be queried for information on TrueType fonts""")
+bullet("""CMapSearchPath: this is a python list of strings representing directories that
+may be queried for information on font code maps.""")
+bullet("""showBoundary: set to non-zero to get boundary lines drawn.""")
+bullet("""ZLIB_WARNINGS: set to non-zero to get warnings if the Python compression extension is not found.""")
+bullet("""pageComression: set to non-zero to try and get compressed PDF.""")
+bullet("""allowtableBoundsErrors: set to 0 to force an error on very large Platypus table elements""")
+bullet("""emptyTableAction: Controls behaviour for empty tables, can be 'error' (default), 'indicate' or 'ignore'.""")
+
+
+
+heading2("Learning More About Python")
+
+disc("""
+If you are a total beginner to Python, you should check out one or more from the
+growing number of resources on Python programming. The following are freely
+available on the web:
+""")
+
+
+bullet("""<b>Introductory Material on Python. </b>
+A list of tutorials on the Python.org web site.
+$http://www.python.org/doc/Intros.html$
+""")
+
+
+bullet("""<b>Python Tutorial. </b>
+The official Python Tutorial by Guido van Rossum (edited by Fred L. Drake, Jr.)
+$http://www.python.org/doc/tut/$
+""")
+
+
+bullet("""<b>Learning to Program. </b>
+A tutorial on programming by Alan Gauld. Has a heavy emphasis on
+Python, but also uses other languages.
+$http://www.freenetpages.co.uk/hp/alan.gauld/$
+""")
+
+
+bullet("""<b>How to think like a computer scientist</b> (Python version)</b>.
+$http://www.ibiblio.org/obp/thinkCSpy/$
+""")
+
+
+bullet("""<b>Instant Python</b>.
+A 6-page minimal crash course by Magnus Lie Hetland.
+$http://www.hetland.org/python/instant-python.php$
+""")
+
+
+bullet("""<b>Dive Into Python</b>.
+A free Python tutorial for experienced programmers.
+$http://diveintopython.org/$
+""")
+
+
+from reportlab.lib.codecharts import SingleByteEncodingChart
+from reportlab.tools.docco.stylesheet import getStyleSheet
+styles = getStyleSheet()
+indent0_style = styles['Indent0']
+indent1_style = styles['Indent1']
+
+heading2("What's New in ReportLab 2.0")
+disc("""
+Many new features have been added, foremost amongst which is the support
+for unicode. This page documents what has changed since version 1.20.""")
+
+disc("""
+Adding full unicode support meant that we had to break backwards-compatibility,
+so old code written for ReportLab 1 will sometimes need changes before it will
+run correctly with ReportLab 2. Now that we have made the clean break to
+introduce this important new feature, we intend to keep the API
+backwards-compatible throughout the 2.* series.
+""")
+heading3("Goals for the 2.x series")
+disc("""
+The main rationale for 2.0 was an incompatible change at the character level:
+to properly support Unicode input. Now that it's out we will maintain compatibility
+with 2.0. There are no pressing feature wishlists and new features will be driven,
+as always, by contributions and the demands of projects.""")
+
+disc("""
+Our 1.x code base is still Python 2.1 compatible. The new version lets us move forwards
+with a baseline of Python 2.4 (2.3 will work too, for the moment, but we don't promise
+that going forwards) so we can use newer language features freely in our development.""")
+
+disc("""
+One area where we do want to make progress from release to release is with documentation
+and installability. We'll be looking into better support for distutils, setuptools,
+eggs and so on; and into better examples and tools to help people learn what's in the
+(substantial) code base.""")
+
+disc("""
+Bigger ideas and more substantial rewrites are deferred to Version 3.0, with no particular
+target dates.
+""")
+
+heading3("Contributions")
+disc("""Thanks to everybody who has contributed to the open-source toolkit in the run-up
+to the 2.0 release, whether by reporting bugs, sending patches, or contributing to the
+reportlab-users mailing list. Thanks especially to the following people, who contributed
+code that has gone into 2.0: Andre Reitz, Max M, Albertas Agejevas, T Blatter, Ron Peleg,
+Gary Poster, Steve Halasz, Andrew Mercer, Paul McNett, Chad Miller.
+""")
+todo("""If we missed you, please let us know!""")
+
+heading3("Unicode support")
+disc("""
+This is the Big One, and the reason some apps may break. You must now pass in text either
+in UTF-8 or as unicode string objects. The library will handle everything to do with output
+encoding. There is more information on this below.
+Since this is the biggest change, we'll start by reviewing how it worked in the past.""")
+
+disc("""
+In ReportLab 1.x, any string input you passed to our APIs was supposed to be in the same
+encoding as the font you selected for output. If using the default fonts in Acrobat Reader
+(Helvetica/Times/Courier), you would have implicitly used WinAnsi encoding, which is almost
+exactly the same as Latin-1. However, if using TrueType fonts, you would have been using UTF-8.""")
+
+disc("""For Asian fonts, you had a wide choice of encodings but had to specify which one
+(e.g Shift-JIS or EUC for Japanese). This state of affairs meant that you had
+to make sure that every piece of text input was in the same encoding as the font used
+to display it.""")
+
+
+
+disc("""Input text encoding is UTF-8 or Python Unicode strings""")
+disc("""
+Any text you pass to a canvas API (drawString etc.), Paragraph or other flowable
+constructor, into a table cell, or as an attribute of a graphic (e.g. chart.title.text),
+is supposed to be unicode. If you use a traditional Python string, it is assumed to be UTF-8.
+If you pass a Unicode object, we know it's unicode.""", style=indent1_style)
+
+disc("""Font encodings""")
+disc("""
+Fonts still work in different ways, and the built-in ones will still use WinAnsi or MacRoman
+internally while TrueType will use UTF-8. However, the library hides this from you; it converts
+as it writes out the PDF file. As before, it's still your job to make sure the font you use has
+the characters you need, or you may get either a traceback or a visible error character.""",style=indent1_style)
+
+disc("""Asian CID fonts""")
+disc("""
+You no longer need to specify the encoding for the built-in Asian fonts, just the face name.
+ReportLab knows about the standard fonts in Adobe's Asian Language Packs
+""", style=indent1_style)
+
+disc("""Asian Truetype fonts""")
+disc("""
+The standard Truetype fonts differ slightly for Asian languages (e.g msmincho.ttc).
+These can now be read and used, albeit somewhat inefficiently.
+""", style=indent1_style)
+
+disc("""Asian word wrapping""")
+disc("""
+Previously we could display strings in Asian languages, but could not properly
+wrap paragraphs as there are no gaps between the words. We now have a basic word wrapping
+algorithm.
+""", style=indent1_style)
+
+disc("""unichar tag""")
+disc("""
+A convenience tag, <unichar/> has also been added. You can now do <unichar code="0xfc"/>
+or <unichar name='LATIN SMALL LETTER U WITH DIAERESIS'/> and
+get a lowercase u umlaut. Names should be those in the Unicode Character Database.
+""", style=indent1_style)
+
+disc("""Accents, greeks and symbols""")
+disc("""
+The correct way to refer to all non-ASCII characters is to use their unicode representation.
+This can be literal Unicode or UTF-8. Special symbols and Greek letters (collectively, "greeks")
+inserted in paragraphs using the greek tag (e.g. <greek>lambda</greek>) or using the entity
+references (e.g. λ) are now processed in a different way than in version 1.""", style=indent1_style)
+disc("""
+Previously, these were always rendered using the Zapf Dingbats font. Now they are always output
+in the font you specified, unless that font does not support that character. If the font does
+not support the character, and the font you specified was an Adobe Type 1 font, Zapf Dingbats
+is used as a fallback. However, at present there is no fallback in the case of TTF fonts.
+Note that this means that documents that contain greeks and specify a TTF font may need
+changing to explicitly specify the font to use for the greek character, or you will see a black
+square in place of that character when you view your PDF output in Acrobat Reader.
+""", style=indent1_style)
+
+# Other New Features Section #######################
+heading3("Other New Features")
+disc("""PDF""")
+disc("""Improved low-level annotation support for PDF "free text annotations"
+""", style=indent0_style)
+disc("""FreeTextAnnotation allows showing and hiding of an arbitrary PDF "form"
+(reusable chunk of PDF content) depending on whether the document is printed or
+viewed on-screen, or depending on whether the mouse is hovered over the content, etc.
+""", style=indent1_style)
+
+disc("""TTC font collection files are now readable"
+""", style=indent0_style)
+disc("""ReportLab now supports using TTF fonts packaged in .TTC files""", style=indent1_style)
+
+disc("""East Asian font support (CID and TTF)""", style=indent0_style)
+disc("""You no longer need to specify the encoding for the built-in Asian fonts,
+just the face name. ReportLab knows about the standard fonts in Adobe's Asian Language Packs.
+""", style=indent1_style)
+
+disc("""Native support for JPEG CMYK images""", style=indent0_style)
+disc("""ReportLab now takes advantage of PDF's native JPEG CMYK image support,
+so that JPEG CMYK images are no longer (lossily) converted to RGB format before including
+them in PDF.""", style=indent1_style)
+
+
+disc("""Platypus""")
+disc("""Link support in paragraphs""", style=indent0_style)
+disc("""
+Platypus paragraphs can now contain link elements, which support both internal links
+to the same PDF document, links to other local PDF documents, and URL links to pages on
+the web. Some examples:""", style=indent1_style)
+disc("""Web links:""", style=indent1_style)
+disc("""<link href="http://www.reportlab.com/">ReportLab<link>""", style=styles['Link'])
+
+disc("""Internal link to current PDF document:""", style=indent1_style)
+disc("""<link href="summary">ReportLab<link>""", style=styles['Link'])
+
+disc("""External link to a PDF document on the local filesystem:""", style=indent1_style)
+disc("""<link href="pdf:C:/john/report.pdf">ReportLab<link>""", style=styles['Link'])
+
+disc("""Improved wrapping support""", style=indent0_style)
+disc("""Support for wrapping arbitrary sequence of flowables around an image, using
+reportlab.platypus.flowables.ImageAndFlowables (similar to ParagraphAndImage)."""
+,style=indent1_style)
+
+disc("""KeepInFrame""", style=indent0_style)
+disc("""Sometimes the length of a piece of text you'd like to include in a fixed piece
+of page "real estate" is not guaranteed to be constrained to a fixed maximum length.
+In these cases, KeepInFrame allows you to specify an appropriate action to take when
+the text is too long for the space allocated for it. In particular, it can shrink the text
+to fit, mask (truncate) overflowing text, allow the text to overflow into the rest of the document,
+or raise an error.""",style=indent1_style)
+
+
+disc("""Improved convenience features for inserting unicode symbols and other characters
+""", style=indent0_style)
+disc("""<unichar/> lets you conveniently insert unicode characters using the standard long name
+or code point. Characters inserted with the <greek> tags (e.g. <greek>lambda</greek>) or corresponding
+entity references (e.g. λ) support arbitrary fonts (rather than only Zapf Dingbats).""",style=indent1_style)
+
+disc("""Improvements to Legending""", style=indent0_style)
+disc("""Instead of manual placement, there is now a attachment point (N, S, E, W, etc.), so that
+the legend is always automatically positioned correctly relative to the chart. Swatches (the small
+sample squares of colour / pattern fill sometimes displayed in the legend) can now be automatically
+created from the graph data. Legends can now have automatically-computed totals (useful for
+financial applications).""",style=indent1_style)
+
+disc("""More and better ways to place piechart labels""", style=indent0_style)
+disc("""New smart algorithms for automatic pie chart label positioning have been added.
+You can now produce nice-looking labels without manual positioning even for awkward cases in
+big runs of charts.""",style=indent1_style)
+
+disc("""Adjustable piechart slice ordering""", style=indent0_style)
+disc("""For example. pie charts with lots of small slices can be configured to alternate thin and
+thick slices to help the lagel placememt algorithm work better.""",style=indent1_style)
+disc("""Improved spiderplots""", style=indent0_style)
+
+
+# Noteworthy bug fixes Section #######################
+heading3("Noteworthy bug fixes")
+disc("""Fixes to TTF splitting (patch from Albertas Agejevas)""")
+disc("""This affected some documents using font subsetting""", style=indent0_style)
+
+disc("""Tables with spans improved splitting""")
+disc("""Splitting of tables across pages did not work correctly when the table had
+row/column spans""", style=indent0_style)
+
+disc("""Fix runtime error affecting keepWithNext""")
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/userguide/ch2_graphics.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,1181 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch2_graphics.py
+from reportlab.tools.docco.rl_doc_utils import *
+from reportlab.lib.codecharts import SingleByteEncodingChart
+
+heading1("Graphics and Text with $pdfgen$")
+
+heading2("Basic Concepts")
+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
+ def hello(c):
+ c.drawString(100,100,"Hello World")
+ 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.
+""")
+
+heading2("More about the Canvas")
+disc("""
+Before describing the drawing operations, we will digress to cover
+some of the things which can be done to configure a canvas. There
+are many different settings available. If you are new to Python
+or can't wait to produce some output, you can skip ahead, but
+come back later and read this!""")
+
+disc("""First of all, we will look at the constructor
+arguments for the canvas:""")
+eg(""" def __init__(self,filename,
+ pagesize=(595.27,841.89),
+ bottomup = 1,
+ pageCompression=0,
+ encoding=rl_config.defaultEncoding,
+ verbosity=0):
+ """)
+
+disc("""The $filename$ argument controls the
+name of the final PDF file. You
+may also pass in any open file object (such as $sys.stdout$, the python process standard output)
+and the PDF document will be written to that. Since PDF
+is a binary format, you should take care when writing other
+stuff before or after it; you can't deliver PDF documents
+inline in the middle of an HTML page!""")
+
+disc("""The $pagesize$ argument is a tuple of two numbers
+in points (1/72 of an inch). The canvas defaults to $A4$ (an international standard
+page size which differs from the American standard page size of $letter$),
+but it is better to explicitly specify it. Most common page
+sizes are found in the library module $reportlab.lib.pagesizes$,
+so you can use expressions like""")
+
+eg("""from reportlab.lib.pagesizes import letter, A4
+myCanvas = Canvas('myfile.pdf', pagesize=letter)
+width, height = letter #keep for later
+""")
+
+pencilnote()
+
+disc("""If you have problems printing your document make sure you
+are using the right page size (usually either $A4$ or $letter$).
+Some printers do not work well with pages that are too large or too small.""")
+
+disc("""Very often, you will want to calculate things based on
+the page size. In the example above we extracted the width and
+height. Later in the program we may use the $width$ variable to
+define a right margin as $width - inch$ rather than using
+a constant. By using variables the margin will still make sense even
+if the page size changes.""")
+
+disc("""The $bottomup$ argument
+switches coordinate systems. Some graphics systems (like PDF
+and PostScript) place (0,0) at the bottom left of the page
+others (like many graphical user interfaces [GUI's]) place the origen at the top left. The
+$bottomup$ argument is deprecated and may be dropped in future""")
+
+todo("""Need to see if it really works for all tasks, and if not
+ then get rid of it""")
+
+disc("""The $pageCompression$ option determines whether the stream
+of PDF operations for each page is compressed. By default
+page streams are not compressed, because the compression slows the file generation process.
+If output size is important set $pageCompression=1$, but remember that, compressed documents will
+be smaller, but slower to generate. Note that images are <i>always</i> compressed, and this option
+will only save space if you have a very large amount of text and vector graphics
+on each page.""")
+
+disc("""The $encoding$ argument is largely obsolete in version 2.0 and can
+probably be omitted by 99% of users. Its default value is fine unless you
+very specifically need to use one of the 25 or so characters which are present
+in MacRoman and not in Winansi. A useful reference to these is here:
+<font color="blue"><u><a href="http://www.alanwood.net/demos/charsetdiffs.html">http://www.alanwood.net/demos/charsetdiffs.html</a></u></font>.
+
+The parameter determines which font encoding is used for the
+standard Type 1 fonts; this should correspond to the encoding on your system.
+Note that this is the encoding used <i>internally by the font</i>; text you
+pass to the ReportLab toolkit for rendering should always either be a Python
+unicode string object or a UTF-8 encoded byte string (see the next chapter)!
+The font encoding has two values at present: $'WinAnsiEncoding'$ or
+$'MacRomanEncoding'$. The variable $rl_config.defaultEncoding$ above points
+to the former, which is standard on Windows, Mac OS X and many Unices
+(including Linux). If you are Mac user and don't have OS X, you may want to
+make a global change: modify the line at the top of
+<i>reportlab/pdfbase/pdfdoc.py</i> to switch it over. Otherwise, you can
+probably just ignore this argument completely and never pass it. For all TTF
+and the commonly-used CID fonts, the encoding you pass in here is ignored,
+since the reportlab library itself knows the right encodings in those
+cases.""")
+
+disc("""The demo script $reportlab/demos/stdfonts.py$
+will print out two test documents showing all code points
+in all fonts, so you can look up characters. Special
+characters can be inserted into string commands with
+the usual Python escape sequences; for example \\101 = 'A'.""")
+
+disc("""The $verbosity$ argument determines how much log
+information is printed. By default, it is zero to assist
+applications which want to capture PDF from standard output.
+With a value of 1, you will get a confirmation message
+each time a document is generated. Higher numbers may
+give more output in future.""")
+
+todo("to do - all the info functions and other non-drawing stuff")
+
+
+
+
+
+todo("""Cover all constructor arguments, and setAuthor etc.""")
+
+heading2("Drawing Operations")
+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.
+""")
+
+illust(examples.hello, '"Hello World" in pdfgen')
+
+heading3("About the demos in this document")
+
+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.
+For convenience the size of the output has been reduced slightly.
+""" % (examplefunctionxinches, examplefunctionyinches))
+
+heading2('The tools: the "draw" operations')
+
+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.
+""")
+
+heading3("Line methods")
+
+eg("""canvas.line(x1,y1,x2,y2)""")
+eg("""canvas.lines(linelist)""")
+
+disc("""
+The line methods draw straight line segments on the canvas.
+""")
+
+heading3("Shape methods")
+
+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(x1,y1, x2,y2, 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.
+""")
+
+heading3("String drawing methods")
+
+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.
+""")
+
+heading3("The text object methods")
+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$.
+""")
+
+heading3("The path object methods")
+
+eg("""path = canvas.beginPath() """)
+eg("""canvas.drawPath(path, stroke=1, fill=0) """)
+eg("""canvas.clipPath(path, stroke=1, fill=0) """)
+
+disc("""
+Path objects are similar to text objects: they provide dedicated control
+for performing complex graphical drawing not directly provided by the
+canvas interface. A program creates a path object using $beginPath$
+populates the path with graphics using the methods of the path object
+and then draws the path on the canvas using $drawPath$.""")
+
+disc("""It is also possible
+to use a path as a "clipping region" using the $clipPath$ method -- for example a circular path
+can be used to clip away the outer parts of a rectangular image leaving
+only a circular part of the image visible on the page.
+""")
+
+heading3("Image methods")
+pencilnote()
+disc("""
+You need the Python Imaging Library (PIL) to use images with the ReportLab package.
+Examnples of the techniques below can be found by running the script $test_pdfgen_general.py$
+in our $test$ subdirectory and looking at page 7 of the output.
+""")
+
+disc("""
+There are two similar-sounding ways to draw images. The preferred one is
+the $drawImage$ method. This implements a caching system so you can
+define an image once and draw it many times; it will only be
+stored once in the PDF file. $drawImage$ also exposes one advanced parameter,
+a transparency mask, and will expose more in future. The older technique,
+$drawInlineImage$, stores bitmaps within the page stream and is thus very
+inefficient if you use the same image more than once in a document; but can result
+in PDFs which render faster if the images are very small and not repeated. We'll
+discuss the oldest one first:
+""")
+
+eg("""canvas.drawInlineImage(self, image, x,y, width=None,height=None) """)
+
+disc("""
+The $drawInlineImage$ method places an image on the canvas. The $image$
+parameter may be either a PIL Image object or an image filename. Many common
+file formats are accepted including GIF and JPEG. It returns the size of the actual
+image in pixels as a (width, height) tuple.
+""")
+
+eg("""canvas.drawImage(self, image, x,y, width=None,height=None,mask=None) """)
+disc("""
+The arguments and return value work as for $drawInlineImage$. However, we use a caching
+system; a given image will only be stored the first time it is used, and just referenced
+on subsequent use. If you supply a filename, it assumes that the same filename
+means the same image. If you supply a PIL image, it tests if the content
+has actually changed before re-embedding.""")
+
+disc("""
+The $mask$ parameter lets you create transparent images. It takes 6 numbers
+and defines the range of RGB values which will be masked out or treated as
+transparent. For example with [0,2,40,42,136,139], it will mask out any pixels
+with a Red value from 0 or 1, Green from 40 or 41 and Blue of 136, 137 or 138
+(on a scale of 0-255). It's currently your job to know which color is the
+'transparent' or background one.""")
+
+disc("""PDF allows for many image features and we will expose more of the over
+time, probably with extra keyword arguments to $drawImage$.""")
+
+heading3("Ending a page")
+
+eg("""canvas.showPage()""")
+
+disc("""The $showPage$ method finishes the current page. All additional drawing will
+be done on another page.""")
+
+pencilnote()
+
+disc("""Warning! All state changes (font changes, color settings, geometry transforms, etcetera)
+are FORGOTTEN when you advance to a new page in $pdfgen$. Any state settings you wish to preserve
+must be set up again before the program proceeds with drawing!""")
+
+heading2('The toolbox: the "state change" operations')
+
+disc("""
+This section briefly lists the ways to switch the tools used by the
+program
+for painting information onto a page using the $canvas$ interface.
+These too will be discussed in detail in later sections.
+""")
+
+heading3("Changing Colors")
+eg("""canvas.setFillColorCMYK(c, m, y, k) """)
+eg("""canvas.setStrikeColorCMYK(c, m, y, k) """)
+eg("""canvas.setFillColorRGB(r, g, b) """)
+eg("""canvas.setStrokeColorRGB(r, g, b) """)
+eg("""canvas.setFillColor(acolor) """)
+eg("""canvas.setStrokeColor(acolor) """)
+eg("""canvas.setFillGray(gray) """)
+eg("""canvas.setStrokeGray(gray) """)
+
+disc("""
+PDF supports three different color models: gray level, additive (red/green/blue or RGB), and
+subtractive with darkness parameter (cyan/magenta/yellow/darkness or CMYK).
+The ReportLab packages also provide named colors such as $lawngreen$. There are two
+basic color parameters in the graphics state: the $Fill$ color for the interior of graphic
+figures and the $Stroke$ color for the boundary of graphic figures. The above methods
+support setting the fill or stroke color using any of the four color specifications.
+""")
+
+heading3("Changing Fonts")
+eg("""canvas.setFont(psfontname, size, leading = None) """)
+
+disc("""
+The $setFont$ method changes the current text font to a given type and size.
+The $leading$ parameter specifies the distance down to move when advancing from
+one text line to the next.
+""")
+
+heading3("Changing Graphical Line Styles")
+
+eg("""canvas.setLineWidth(width) """)
+eg("""canvas.setLineCap(mode) """)
+eg("""canvas.setLineJoin(mode) """)
+eg("""canvas.setMiterLimit(limit) """)
+eg("""canvas.setDash(self, array=[], phase=0) """)
+
+disc("""
+Lines drawn in PDF can be presented in a number of graphical styles.
+Lines can have different widths, they can end in differing cap styles,
+they can meet in different join styles, and they can be continuous or
+they can be dotted or dashed. The above methods adjust these various parameters.""")
+
+heading3("Changing Geometry")
+
+eg("""canvas.setPageSize(pair) """)
+eg("""canvas.transform(a,b,c,d,e,f): """)
+eg("""canvas.translate(dx, dy) """)
+eg("""canvas.scale(x, y) """)
+eg("""canvas.rotate(theta) """)
+eg("""canvas.skew(alpha, beta) """)
+
+disc("""
+All PDF drawings fit into a specified page size. Elements drawn outside of the specified
+page size are not visible. Furthermore all drawn elements are passed through an affine
+transformation which may adjust their location and/or distort their appearence. The
+$setPageSize$ method adjusts the current page size. The $transform$, $translate$, $scale$,
+$rotate$, and $skew$ methods add additional transformations to the current transformation.
+It is important to remember that these transformations are <i>incremental</i> -- a new
+transform modifies the current transform (but does not replace it).
+""")
+
+heading3("State control")
+
+eg("""canvas.saveState() """)
+eg("""canvas.restoreState() """)
+
+disc("""
+Very often it is important to save the current font, graphics transform, line styles and
+other graphics state in order to restore them later. The $saveState$ method marks the
+current graphics state for later restoration by a matching $restoreState$. Note that
+the save and restore method invokation must match -- a restore call restores the state to
+the most recently saved state which hasn't been restored yet.
+You cannot save the state on one page and restore
+it on the next, however -- no state is preserved between pages.""")
+
+heading2("Other $canvas$ methods.")
+
+disc("""
+Not all methods of the $canvas$ object fit into the "tool" or "toolbox"
+categories. Below are some of the misfits, included here for completeness.
+""")
+
+eg("""
+ canvas.setAuthor()
+ canvas.addOutlineEntry(title, key, level=0, closed=None)
+ canvas.setTitle(title)
+ canvas.setSubject(subj)
+ canvas.pageHasData()
+ canvas.showOutline()
+ canvas.bookmarkPage(name)
+ canvas.bookmarkHorizontalAbsolute(name, yhorizontal)
+ canvas.doForm()
+ canvas.beginForm(name, lowerx=0, lowery=0, upperx=None, uppery=None)
+ canvas.endForm()
+ canvas.linkAbsolute(contents, destinationname, Rect=None, addtopage=1, name=None, **kw)
+ canvas.linkRect(contents, destinationname, Rect=None, addtopage=1, relative=1, name=None, **kw)
+ canvas.getPageNumber()
+ canvas.addLiteral()
+ canvas.getAvailableFonts()
+ canvas.stringWidth(self, text, fontName, fontSize, encoding=None)
+ canvas.setPageCompression(onoff=1)
+ canvas.setPageTransition(self, effectname=None, duration=1,
+ direction=0,dimension='H',motion='I')
+""")
+
+
+heading2('Coordinates (default user space)')
+
+disc("""
+By default locations on a page are identified by a pair of numbers.
+For example the pair $(4.5*inch, 1*inch)$ identifies the location
+found on the page by starting at the lower left corner and moving to
+the right 4.5 inches and up one inch.
+""")
+
+disc("""For example, the following function draws
+a number of elements on a $canvas$.""")
+
+eg(examples.testcoords)
+
+disc("""In the default user space the "origin" ^(0,0)^ point is at the lower
+left corner. Executing the $coords$ function in the default user space
+(for the "demo minipage") we obtain the following.""")
+
+illust(examples.coords, 'The Coordinate System')
+
+heading3("Moving the origin: the $translate$ method")
+
+disc("""Often it is useful to "move the origin" to a new point off
+the lower left corner. The $canvas.translate(^x,y^)$ method moves the origin
+for the current page to the point currently identified by ^(x,y)^.""")
+
+disc("""For example the following translate function first moves
+the origin before drawing the same objects as shown above.""")
+
+eg(examples.testtranslate)
+
+disc("""This produces the following.""")
+
+illust(examples.translate, "Moving the origin: the $translate$ method")
+
+
+#illust(NOP) # execute some code
+
+pencilnote()
+
+
+disc("""
+<i>Note:</i> As illustrated in the example it is perfectly possible to draw objects
+or parts of objects "off the page".
+In particular a common confusing bug is a translation operation that translates the
+entire drawing off the visible area of the page. If a program produces a blank page
+it is possible that all the drawn objects are off the page.
+""")
+
+heading3("Shrinking and growing: the scale operation")
+
+disc("""Another important operation is scaling. The scaling operation $canvas.scale(^dx,dy^)$
+stretches or shrinks the ^x^ and ^y^ dimensions by the ^dx^, ^dy^ factors respectively. Often
+^dx^ and ^dy^ are the same -- for example to reduce a drawing by half in all dimensions use
+$dx = dy = 0.5$. However for the purposes of illustration we show an example where
+$dx$ and $dy$ are different.
+""")
+
+eg(examples.testscale)
+
+disc("""This produces a "short and fat" reduced version of the previously displayed operations.""")
+
+illust(examples.scale, "Scaling the coordinate system")
+
+
+#illust(NOP) # execute some code
+
+pencilnote()
+
+
+disc("""<i>Note:</i> scaling may also move objects or parts of objects off the page,
+or may cause objects to "shrink to nothing." """)
+
+disc("""Scaling and translation can be combined, but the order of the
+operations are important.""")
+
+eg(examples.testscaletranslate)
+
+disc("""This example function first saves the current $canvas$ state
+and then does a $scale$ followed by a $translate$. Afterward the function
+restores the state (effectively removing the effects of the scaling and
+translation) and then does the <i>same</i> operations in a different order.
+Observe the effect below.""")
+
+illust(examples.scaletranslate, "Scaling and Translating")
+
+
+#illust(NOP) # execute some code
+
+pencilnote()
+
+
+disc("""<em>Note:</em> scaling shrinks or grows everything including line widths
+so using the canvas.scale method to render a microscopic drawing in
+scaled microscopic units
+may produce a blob (because all line widths will get expanded a huge amount).
+Also rendering an aircraft wing in meters scaled to centimeters may cause the lines
+to shrink to the point where they disappear. For engineering or scientific purposes
+such as these scale and translate
+the units externally before rendering them using the canvas.""")
+
+heading3("Saving and restoring the $canvas$ state: $saveState$ and $restoreState$")
+
+disc("""
+The $scaletranslate$ function used an important feature of the $canvas$ object:
+the ability to save and restore the current parameters of the $canvas$.
+By enclosing a sequence of operations in a matching pair of $canvas.saveState()$
+an $canvas.restoreState()$ operations all changes of font, color, line style,
+scaling, translation, or other aspects of the $canvas$ graphics state can be
+restored to the state at the point of the $saveState()$. Remember that the save/restore
+calls must match: a stray save or restore operation may cause unexpected
+and undesirable behavior. Also, remember that <i>no</i> $canvas$ state is
+preserved across page breaks, and the save/restore mechanism does not work
+across page breaks.
+""")
+
+heading3("Mirror image")
+
+disc("""
+It is interesting although perhaps not terribly useful to note that
+scale factors can be negative. For example the following function
+""")
+
+eg(examples.testmirror)
+
+disc("""
+creates a mirror image of the elements drawn by the $coord$ function.
+""")
+
+illust(examples.mirror, "Mirror Images")
+
+disc("""
+Notice that the text strings are painted backwards.
+""")
+
+heading2("Colors")
+
+disc("""
+There are four ways to specify colors in $pdfgen$: by name (using the $color$
+module, by red/green/blue (additive, $RGB$) value,
+by cyan/magenta/yellow/darkness (subtractive, $CMYK$), or by gray level.
+The $colors$ function below exercises each of the four methods.
+""")
+
+eg(examples.testcolors)
+
+disc("""
+The $RGB$ or additive color specification follows the way a computer
+screen adds different levels of the red, green, or blue light to make
+any color, where white is formed by turning all three lights on full
+$(1,1,1)$.""")
+
+disc("""The $CMYK$ or subtractive method follows the way a printer
+mixes three pigments (cyan, magenta, and yellow) to form colors.
+Because mixing chemicals is more difficult than combining light there
+is a fourth parameter for darkness. For example a chemical
+combination of the $CMY$ pigments generally never makes a perfect
+black -- instead producing a muddy color -- so, to get black printers
+don't use the $CMY$ pigments but use a direct black ink. Because
+$CMYK$ maps more directly to the way printer hardware works it may
+be the case that colors specified in $CMYK$ will provide better fidelity
+and better control when printed.
+""")
+
+illust(examples.colors, "Color Models")
+
+heading2('Painting back to front')
+
+disc("""
+Objects may be painted over other objects to good effect in $pdfgen$. As
+in painting with oils the object painted last will show up on top. For
+example, the $spumoni$ function below paints up a base of colors and then
+paints a white text over the base.
+""")
+
+eg(examples.testspumoni)
+
+disc("""
+The word "SPUMONI" is painted in white over the colored rectangles,
+with the apparent effect of "removing" the color inside the body of
+the word.
+""")
+
+illust(examples.spumoni, "Painting over colors")
+
+disc("""
+The last letters of the word are not visible because the default $canvas$
+background is white and painting white letters over a white background
+leaves no visible effect.
+""")
+
+disc("""
+This method of building up complex paintings in layers can be done
+in very many layers in $pdfgen$ -- there are fewer physical limitations
+than there are when dealing with physical paints.
+""")
+
+eg(examples.testspumoni2)
+
+disc("""
+The $spumoni2$ function layers an ice cream cone over the
+$spumoni$ drawing. Note that different parts of the cone
+and scoops layer over eachother as well.
+""")
+illust(examples.spumoni2, "building up a drawing in layers")
+
+
+heading2('Standard fonts and text objects')
+
+disc("""
+Text may be drawn in many different colors, fonts, and sizes in $pdfgen$.
+The $textsize$ function demonstrates how to change the color and font and
+size of text and how to place text on the page.
+""")
+
+eg(examples.testtextsize)
+
+disc("""
+The $textsize$ function generates the following page.
+""")
+
+illust(examples.textsize, "text in different fonts and sizes")
+
+disc("""
+A number of different fonts are always available in $pdfgen$.
+""")
+
+eg(examples.testfonts)
+
+disc("""
+The $fonts$ function lists the fonts that are always available.
+These don't need to be stored in a PDF document, since they
+are guaranteed to be present in Acrobat Reader.
+""")
+
+illust(examples.fonts, "the 14 standard fonts")
+
+disc("""
+For information on how to use arbitrary fonts, see the next chapter.
+""")
+
+
+heading2("Text object methods")
+
+disc("""
+For the dedicated presentation of text in a PDF document, use a text object.
+The text object interface provides detailed control of text layout parameters
+not available directly at the $canvas$ level. In addition, it results in smaller
+PDF that will render faster than many separate calls to the $drawString$ methods.
+""")
+
+eg("""textobject.setTextOrigin(x,y)""")
+eg("""textobject.setTextTransform(a,b,c,d,e,f)""")
+eg("""textobject.moveCursor(dx, dy) # from start of current LINE""")
+eg("""(x,y) = textobject.getCursor()""")
+eg("""x = textobject.getX(); y = textobject.getY()""")
+eg("""textobject.setFont(psfontname, size, leading = None)""")
+eg("""textobject.textOut(text)""")
+eg("""textobject.textLine(text='')""")
+eg("""textobject.textLines(stuff, trim=1)""")
+
+disc("""
+The text object methods shown above relate to basic text geometry.
+""")
+
+disc("""
+A text object maintains a text cursor which moves about the page when
+text is drawn. For example the $setTextOrigin$ places the cursor
+in a known position and the $textLine$ and $textLines$ methods move
+the text cursor down past the lines that have been missing.
+""")
+
+eg(examples.testcursormoves1)
+
+disc("""
+The $cursormoves$ function relies on the automatic
+movement of the text cursor for placing text after the origin
+has been set.
+""")
+
+illust(examples.cursormoves1, "How the text cursor moves")
+
+disc("""
+It is also possible to control the movement of the cursor
+more explicitly by using the $moveCursor$ method (which moves
+the cursor as an offset from the start of the current <i>line</i>
+NOT the current cursor, and which also has positive ^y^ offsets
+move <i>down</i> (in contrast to the normal geometry where
+positive ^y^ usually moves up.
+""")
+
+eg(examples.testcursormoves2)
+
+disc("""
+Here the $textOut$ does not move the down a line in contrast
+to the $textLine$ function which does move down.
+""")
+
+illust(examples.cursormoves2, "How the text cursor moves again")
+
+heading3("Character Spacing")
+
+eg("""textobject.setCharSpace(charSpace)""")
+
+disc("""The $setCharSpace$ method adjusts one of the parameters of text -- the inter-character
+spacing.""")
+
+eg(examples.testcharspace)
+
+disc("""The
+$charspace$ function exercises various spacing settings.
+It produces the following page.""")
+
+illust(examples.charspace, "Adjusting inter-character spacing")
+
+heading3("Word Spacing")
+
+eg("""textobject.setWordSpace(wordSpace)""")
+
+disc("The $setWordSpace$ method adjusts the space between words.")
+
+eg(examples.testwordspace)
+
+disc("""The $wordspace$ function shows what various word space settings
+look like below.""")
+
+illust(examples.wordspace, "Adjusting word spacing")
+
+heading3("Horizontal Scaling")
+
+eg("""textobject.setHorizScale(horizScale)""")
+
+disc("""Lines of text can be stretched or shrunken horizontally by the
+$setHorizScale$ method.""")
+
+eg(examples.testhorizontalscale)
+
+disc("""The horizontal scaling parameter ^horizScale^
+is given in percentages (with 100 as the default), so the 80 setting
+shown below looks skinny.
+""")
+illust(examples.horizontalscale, "adjusting horizontal text scaling")
+
+heading3("Interline spacing (Leading)")
+
+eg("""textobject.setLeading(leading)""")
+
+disc("""The vertical offset between the point at which one
+line starts and where the next starts is called the leading
+offset. The $setLeading$ method adjusts the leading offset.
+""")
+
+eg(examples.testleading)
+
+disc("""As shown below if the leading offset is set too small
+characters of one line my write over the bottom parts of characters
+in the previous line.""")
+
+illust(examples.leading, "adjusting the leading")
+
+heading3("Other text object methods")
+
+eg("""textobject.setTextRenderMode(mode)""")
+
+disc("""The $setTextRenderMode$ method allows text to be used
+as a forground for clipping background drawings, for example.""")
+
+eg("""textobject.setRise(rise)""")
+
+disc("""
+The $setRise$ method <super>raises</super> or <sub>lowers</sub> text on the line
+(for creating superscripts or subscripts, for example).
+""")
+
+eg("""textobject.setFillColor(aColor);
+textobject.setStrokeColor(self, aColor)
+# and similar""")
+
+disc("""
+These color change operations change the <font color=darkviolet>color</font> of the text and are otherwise
+similar to the color methods for the $canvas$ object.""")
+
+heading2('Paths and Lines')
+
+disc("""Just as textobjects are designed for the dedicated presentation
+of text, path objects are designed for the dedicated construction of
+graphical figures. When path objects are drawn onto a $canvas$ they
+are drawn as one figure (like a rectangle) and the mode of drawing
+for the entire figure can be adjusted: the lines of the figure can
+be drawn (stroked) or not; the interior of the figure can be filled or
+not; and so forth.""")
+
+disc("""
+For example the $star$ function uses a path object
+to draw a star
+""")
+
+eg(examples.teststar)
+
+disc("""
+The $star$ function has been designed to be useful in illustrating
+various line style parameters supported by $pdfgen$.
+""")
+
+illust(examples.star, "line style parameters")
+
+heading3("Line join settings")
+
+disc("""
+The $setLineJoin$ method can adjust whether line segments meet in a point
+a square or a rounded vertex.
+""")
+
+eg(examples.testjoins)
+
+disc("""
+The line join setting is only really of interest for thick lines because
+it cannot be seen clearly for thin lines.
+""")
+
+illust(examples.joins, "different line join styles")
+
+heading3("Line cap settings")
+
+disc("""The line cap setting, adjusted using the $setLineCap$ method,
+determines whether a terminating line
+ends in a square exactly at the vertex, a square over the vertex
+or a half circle over the vertex.
+""")
+
+eg(examples.testcaps)
+
+disc("""The line cap setting, like the line join setting, is only clearly
+visible when the lines are thick.""")
+
+illust(examples.caps, "line cap settings")
+
+heading3("Dashes and broken lines")
+
+disc("""
+The $setDash$ method allows lines to be broken into dots or dashes.
+""")
+
+eg(examples.testdashes)
+
+disc("""
+The patterns for the dashes or dots can be in a simple on/off repeating pattern
+or they can be specified in a complex repeating pattern.
+""")
+
+illust(examples.dashes, "some dash patterns")
+
+heading3("Creating complex figures with path objects")
+
+disc("""
+Combinations of lines, curves, arcs and other figures
+can be combined into a single figure using path objects.
+For example the function shown below constructs two path
+objects using lines and curves.
+This function will be used later on as part of a
+pencil icon construction.
+""")
+
+eg(examples.testpenciltip)
+
+disc("""
+Note that the interior of the pencil tip is filled
+as one object even though it is constructed from
+several lines and curves. The pencil lead is then
+drawn over it using a new path object.
+""")
+
+illust(examples.penciltip, "a pencil tip")
+
+heading2('Rectangles, circles, ellipses')
+
+disc("""
+The $pdfgen$ module supports a number of generally useful shapes
+such as rectangles, rounded rectangles, ellipses, and circles.
+Each of these figures can be used in path objects or can be drawn
+directly on a $canvas$. For example the $pencil$ function below
+draws a pencil icon using rectangles and rounded rectangles with
+various fill colors and a few other annotations.
+""")
+
+eg(examples.testpencil)
+
+pencilnote()
+
+disc("""
+Note that this function is used to create the "margin pencil" to the left.
+Also note that the order in which the elements are drawn are important
+because, for example, the white rectangles "erase" parts of a black rectangle
+and the "tip" paints over part of the yellow rectangle.
+""")
+
+illust(examples.pencil, "a whole pencil")
+
+heading2('Bezier curves')
+
+disc("""
+Programs that wish to construct figures with curving borders
+generally use Bezier curves to form the borders.
+""")
+
+eg(examples.testbezier)
+
+disc("""
+A Bezier curve is specified by four control points
+$(x1,y1)$, $(x2,y2)$, $(x3,y3)$, $(x4,y4)$.
+The curve starts at $(x1,y1)$ and ends at $(x4,y4)$
+and the line segment from $(x1,y1)$ to $(x2,y2)$
+and the line segment from $(x3,y3)$ to $(x4,y4)$
+both form tangents to the curve. Furthermore the
+curve is entirely contained in the convex figure with vertices
+at the control points.
+""")
+
+illust(examples.bezier, "basic bezier curves")
+
+disc("""
+The drawing above (the output of $testbezier$) shows
+a bezier curves, the tangent lines defined by the control points
+and the convex figure with vertices at the control points.
+""")
+
+heading3("Smoothly joining bezier curve sequences")
+
+disc("""
+It is often useful to join several bezier curves to form a
+single smooth curve. To construct a larger smooth curve from
+several bezier curves make sure that the tangent lines to adjacent
+bezier curves that join at a control point lie on the same line.
+""")
+
+eg(examples.testbezier2)
+
+disc("""
+The figure created by $testbezier2$ describes a smooth
+complex curve because adjacent tangent lines "line up" as
+illustrated below.
+""")
+
+illust(examples.bezier2, "bezier curves")
+
+heading2("Path object methods")
+
+disc("""
+Path objects build complex graphical figures by setting
+the "pen" or "brush" at a start point on the canvas and drawing
+lines or curves to additional points on the canvas. Most operations
+apply paint on the canvas starting at the end point of the last
+operation and leave the brush at a new end point.
+""")
+
+eg("""pathobject.moveTo(x,y)""")
+
+disc("""
+The $moveTo$ method lifts the brush (ending any current sequence
+of lines or curves if there is one) and replaces the brush at the
+new ^(x,y)^ location on the canvas to start a new path sequence.
+""")
+
+eg("""pathobject.lineTo(x,y)""")
+
+disc("""
+The $lineTo$ method paints straight line segment from the current brush
+location to the new ^(x,y)^ location.
+""")
+
+eg("""pathobject.curveTo(x1, y1, x2, y2, x3, y3) """)
+
+disc("""
+The $curveTo$ method starts painting a Bezier curve beginning at
+the current brush location, using ^(x1,y1)^, ^(x2,y2)^, and ^(x3,y3)^
+as the other three control points, leaving the brush on ^(x3,y3)^.
+""")
+
+eg("""pathobject.arc(x1,y1, x2,y2, startAng=0, extent=90) """)
+
+eg("""pathobject.arcTo(x1,y1, x2,y2, startAng=0, extent=90) """)
+
+disc("""
+The $arc$ and $arcTo$ methods paint partial ellipses. The $arc$ method first "lifts the brush"
+and starts a new shape sequence. The $arcTo$ method joins the start of
+the partial ellipse to the current
+shape sequence by line segment before drawing the partial ellipse. The points
+^(x1,y1)^ and ^(x2,y2)^ define opposite corner points of a rectangle enclosing
+the ellipse. The $startAng$ is an angle (in degrees) specifying where to begin
+the partial ellipse where the 0 angle is the midpoint of the right border of the enclosing
+rectangle (when ^(x1,y1)^ is the lower left corner and ^(x2,y2)^ is the upper
+right corner). The $extent$ is the angle in degrees to traverse on the ellipse.
+""")
+
+eg(examples.testarcs)
+
+disc("""The $arcs$ function above exercises the two partial ellipse methods.
+It produces the following drawing.""")
+
+illust(examples.arcs, "arcs in path objects")
+
+eg("""pathobject.rect(x, y, width, height) """)
+
+disc("""The $rect$ method draws a rectangle with lower left corner
+at ^(x,y)^ of the specified ^width^ and ^height^.""")
+
+eg("""pathobject.ellipse(x, y, width, height)""")
+
+disc("""The $ellipse$ method
+draws an ellipse enclosed in the rectange with lower left corner
+at ^(x,y)^ of the specified ^width^ and ^height^.
+""")
+
+eg("""pathobject.circle(x_cen, y_cen, r) """)
+
+disc("""The $circle$ method
+draws a circle centered at ^(x_cen, y_cen)^ with radius ^r^.
+""")
+
+eg(examples.testvariousshapes)
+
+disc("""
+The $variousshapes$ function above shows a rectangle, circle and ellipse
+placed in a frame of reference grid.
+""")
+
+illust(examples.variousshapes, "rectangles, circles, ellipses in path objects")
+
+eg("""pathobject.close() """)
+
+disc("""
+The $close$ method closes the current graphical figure
+by painting a line segment from the last point of the figure
+to the starting point of the figure (the the most
+recent point where the brush was placed on the paper by $moveTo$
+or $arc$ or other placement operations).
+""")
+
+eg(examples.testclosingfigures)
+
+disc("""
+The $closingfigures$ function illustrates the
+effect of closing or not closing figures including a line
+segment and a partial ellipse.
+""")
+
+illust(examples.closingfigures, "closing and not closing pathobject figures")
+
+disc("""
+Closing or not closing graphical figures effects only the stroked outline
+of a figure, not the filling of the figure as illustrated above.
+""")
+
+
+disc("""
+For a more extensive example of drawing using a path object
+examine the $hand$ function.
+""")
+
+eg(examples.testhand)
+
+disc("""
+In debug mode (the default) the $hand$ function shows the tangent line segments
+to the bezier curves used to compose the figure. Note that where the segments
+line up the curves join smoothly, but where they do not line up the curves show
+a "sharp edge".
+""")
+
+illust(examples.hand, "an outline of a hand using bezier curves")
+
+disc("""
+Used in non-debug mode the $hand$ function only shows the
+Bezier curves. With the $fill$ parameter set the figure is
+filled using the current fill color.
+""")
+
+eg(examples.testhand2)
+
+disc("""
+Note that the "stroking" of the border draws over the interior fill where
+they overlap.
+""")
+
+illust(examples.hand2, "the finished hand, filled")
+
+
+
+heading2("Further Reading: The ReportLab Graphics Library")
+
+disc("""
+So far the graphics we have seen was created on a fairly low level.
+It should be noted, though, that there is another way of creating
+much more sophisticated graphics using the emerging dedicated
+high-level <i>ReportLab Graphics Library</i>.
+""")
+
+disc("""
+It can be used to produce high-quality, platform-independant,
+reusable graphics for different output formats (vector and bitmap)
+like PDF, EPS and soon others like SVG.
+""")
+
+disc("""
+A thorough description of its philsophy and features is beyond the
+scope of this general user guide and the reader is recommended to
+continue with the <i>"ReportLab Graphics Guide"</i>.
+There she will find information about the existing components and
+how to create customized ones.
+""")
+
+disc("""
+Also, the graphics guide contains a presentation of an emerging
+charting package and its components (labels, axes, legends and
+different types of charts like bar, line and pie charts) that
+builds directly on the graphics library.
+""")
+
+
+##### FILL THEM IN
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/userguide/ch2a_fonts.py Wed Sep 03 16:05:15 2008 +0000
@@ -0,0 +1,513 @@
+#Copyright ReportLab Europe Ltd. 2000-2004
+#see license.txt for license details
+#history http://www.reportlab.co.uk/cgi-bin/viewcvs.cgi/public/reportlab/trunk/reportlab/docs/userguide/ch2a_fonts.py
+from reportlab.tools.docco.rl_doc_utils import *
+from reportlab.lib.codecharts import SingleByteEncodingChart
+from reportlab.platypus import Image
+import reportlab
+
+heading1("Fonts and encodings")
+
+disc("""
+This chapter covers fonts, encodings and Asian language capabilities.
+If you are purely concerned with generating PDFs for Western
+European languages, you can just read the "Unicode is the default" section
+below and skip the rest on a first reading.
+We expect this section to grow considerably over time. We
+hope that Open Source will enable us to give better support for
+more of the world's languages than other tools, and we welcome
+feedback and help in this area.
+""")
+
+heading2("Unicode and UTF8 are the default input encodings")
+
+disc("""
+Starting with reportlab Version 2.0 (May 2006), all text input you
+provide to our APIs should be in UTF8 or as Python Unicode objects.
+This applies to arguments to canvas.drawString and related APIs,
+table cell content, drawing object parameters, and paragraph source
+text.
+""")
+
+
+disc("""
+We considered making the input encoding configurable or even locale-dependent,
+but decided that "explicit is better than implicit".""")
+
+disc("""
+This simplifies many things we used to do previously regarding greek
+letters, symbols and so on. To display any character, find out its
+unicode code point, and make sure the font you are using is able
+to display it.""")
+
+disc("""
