--- a/reportlab/platypus/doctemplate.py	Sun Jul 07 22:29:02 2002 +0000
+++ b/reportlab/platypus/doctemplate.py	Tue Jul 09 16:47:43 2002 +0000
@@ -1,9 +1,9 @@
 #copyright ReportLab Inc. 2000
 #see license.txt for license details
 #history http://cvs.sourceforge.net/cgi-bin/cvsweb.cgi/reportlab/platypus/doctemplate.py?cvsroot=reportlab
-#$Header: /tmp/reportlab/reportlab/platypus/doctemplate.py,v 1.53 2002/07/07 22:29:02 andy_robinson Exp $
+#$Header: /tmp/reportlab/reportlab/platypus/doctemplate.py,v 1.54 2002/07/09 16:47:43 rgbecker Exp $
 
-__version__=''' $Id: doctemplate.py,v 1.53 2002/07/07 22:29:02 andy_robinson Exp $ '''
+__version__=''' $Id: doctemplate.py,v 1.54 2002/07/09 16:47:43 rgbecker Exp $ '''
 
 __doc__="""
 This module contains the core structure of platypus.
@@ -734,6 +734,43 @@
 		BaseDocTemplate.build(self,flowables)
 
 
+def progressCB(typ, value):
+	"""Example prototype for progress monitoring.
+
+	This aims to provide info about what is going on
+	during a big job.  It should enable, for example, a reasonably
+	smooth progress bar to be drawn.  We design the argument
+	signature to be predictable and conducive to programming in
+	other (type safe) languages.  If set, this will be called
+	repeatedly with pairs of values.  The first is a string
+	indicating the type of call; the second is a numeric value.
+
+	typ 'STARTING', value = 0
+	typ 'SIZE_EST', value = numeric estimate of job size
+	typ 'PASS', value = number of this rendering pass
+	typ 'PROGRESS', value = number between 0 and SIZE_EST
+	typ 'PAGE', value = page number of page
+	type 'FINISHED', value = 0
+
+	The sequence is
+		STARTING - always called once
+		SIZE_EST - always called once
+		PROGRESS - called often
+		PAGE - called often when page is emitted
+		FINISHED - called when really, really finished
+	
+	some juggling is needed to accurately estimate numbers of
+	pages in pageDrawing mode.
+
+	NOTE: the SIZE_EST is a guess.  It is possible that the
+	PROGRESS value may slightly exceed it, or may even step
+	back a little on rare occasions.  The only way to be
+	really accurate would be to do two passes, and I don't
+	want to take that performance hit.
+	"""
+	print 'PROGRESS MONITOR:  %-10s   %d' % (typ, value)
+
+
 	##########################################################
 	##
 	##	 testing