#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

__doc__="""

This module contains the core structure of platypus.

Platypus constructs documents.	Document styles are determined by DocumentTemplates.

Each DocumentTemplate contains one or more PageTemplates which defines the look of the

pages of the document.

Each PageTemplate has a procedure for drawing the "non-flowing" part of the page

(for example the header, footer, page number, fixed logo graphic, watermark, etcetera) and

a set of Frames which enclose the flowing part of the page (for example the paragraphs,

tables, or non-fixed diagrams of the text).

A document is built when a DocumentTemplate is fed a sequence of Flowables.

The action of the build consumes the flowables in order and places them onto

frames on pages as space allows.  When a frame runs out of space the next frame

of the page is used.  If no frame remains a new page is created.  A new page

can also be created if a page break is forced.

The special invisible flowable NextPageTemplate can be used to specify

the page template for the next page (which by default is the one being used

for the current frame).

"""

from reportlab.platypus.flowables import *

from reportlab.platypus.paragraph import Paragraph

from reportlab.platypus.frames import Frame

from reportlab.rl_config import defaultPageSize, _verbose

import reportlab.lib.sequencer

from types import *

import sys

def _doNothing(canvas, doc):

	"Dummy callback for onPage"

	pass

class IndexingFlowable0(Flowable):

	"""Abstract interface definition for flowables which might

	hold references to other pages or themselves be targets

	of cross-references.  XRefStart, XRefDest, Table of Contents,

	Indexes etc."""

	def isIndexing(self):

		return 1

	def isSatisfied(self):

		return 1

	def notify(self, kind, stuff):

		"""This will be called by the framework wherever 'stuff' happens.

		'kind' will be a value that can be used to decide whether to

		pay attention or not."""

		pass

	def beforeBuild(self):

		"""Called by multiBuild before it starts; use this to clear

		old contents"""

		pass

	def afterBuild(self):

		"""Called after build ends but before isSatisfied"""

		pass

class ActionFlowable(Flowable):

	'''This Flowable is never drawn, it can be used for data driven controls

	   For example to change a page template (from one column to two, for example)

	   use NextPageTemplate which creates an ActionFlowable.

	'''

	def __init__(self,action=()):

		if type(action) not in (ListType, TupleType):

			action = (action,)

		self.action = tuple(action)

	def wrap(self, availWidth, availHeight):

		'''Should never be called.'''

		raise NotImplementedError

	def draw(self):

		'''Should never be called.'''

		raise NotImplementedError

	def apply(self,doc):

		'''

		This is called by the doc.build processing to allow the instance to

		implement its behaviour

		'''

		action = self.action[0]

		args = tuple(self.action[1:])

		arn = 'handle_'+action

		try:

			apply(getattr(doc,arn), args)

		except AttributeError, aerr:

			if aerr.args[0]==arn:

				raise NotImplementedError, "Can't handle ActionFlowable(%s)" % action

			else:

				raise

		except "bogus":

			t, v, None = sys.exc_info()

			raise t, "%s\n	 handle_%s args=%s"%(v,action,args)

	def __call__(self):

		return self

class NextFrameFlowable(ActionFlowable):

	def __init__(self,ix,resume=0):

		ActionFlowable.__init__(self,('nextFrame',ix,resume))

class CurrentFrameFlowable(ActionFlowable):

	def __init__(self,ix,resume=0):

		ActionFlowable.__init__(self,('currentFrame',ix,resume))

class _FrameBreak(ActionFlowable):

	'''

	A special ActionFlowable that allows setting doc._nextFrameIndex

	eg story.append(FrameBreak('mySpecialFrame'))

	'''

	def __call__(self,ix=None,resume=0):

		r = self.__class__(self.action+(resume,))

		r._ix = ix

		return r

	def apply(self,doc):

		if getattr(self,'_ix',None): doc._nextFrameIndex = self._ix

		ActionFlowable.apply(self,doc)

FrameBreak = _FrameBreak('frameEnd')

PageBegin = ActionFlowable('pageBegin')

class NextPageTemplate(ActionFlowable):

	"""When you get to the next page, use the template specified (change to two column, for example)  """

	def __init__(self,pt):

		ActionFlowable.__init__(self,('nextPageTemplate',pt))

class PageTemplate:

	"""

	essentially a list of Frames and an onPage routine to call at the start

	of a page when this is selected. onPageEnd gets called at the end.

	derived classes can also implement beforeDrawPage and afterDrawPage if they want

	"""

	def __init__(self,id=None,frames=[],onPage=_doNothing, onPageEnd=_doNothing,

				 pagesize=defaultPageSize):

		if type(frames) not in (ListType,TupleType): frames = [frames]

		assert filter(lambda x: not isinstance(x,Frame), frames)==[], "frames argument error"

		self.id = id

		self.frames = frames

		self.onPage = onPage

		self.onPageEnd = onPageEnd

		self.pagesize = pagesize

	def beforeDrawPage(self,canv,doc):

		"""Override this if you want additional functionality or prefer

		a class based page routine.  Called before any flowables for

		this page are processed."""

		pass

	def checkPageSize(self,canv,doc):

		'''This gets called by the template framework

		If canv size != doc size then the canv size is set to

		doc size.

		'''

		#### NEVER EVER EVER COMPARE FLOATS FOR EQUALITY

		#RGB converting pagesizes to ints means we are accurate to one point

		#RGB I suggest we should be aiming a little better

		cp = None

		dp = None

		sp = None

		if canv._pagesize: cp = map(int, canv._pagesize)

		if self.pagesize: sp = map(int, self.pagesize)

		if doc.pagesize: dp = map(int, doc.pagesize)

		if cp!=sp:

			if sp:

				canv.setPageSize(self.pagesize)

			elif cp!=dp:

				canv.setPageSize(doc.pagesize)

	def afterDrawPage(self, canv, doc):

		"""This is called after the last flowable for the page has

		been processed.  You might use this if the page header or

		footer needed knowledge of what flowables were drawn on

		this page."""

		pass

class BaseDocTemplate:

	"""

	First attempt at defining a document template class.

	The basic idea is simple.

	0)	The document has a list of data associated with it

		this data should derive from flowables. We'll have

		special classes like PageBreak, FrameBreak to do things

		like forcing a page end etc.

	1)	The document has one or more page templates.

	2)	Each page template has one or more frames.

	3)	The document class provides base methods for handling the

		story events and some reasonable methods for getting the

		story flowables into the frames.

	4)	The document instances can override the base handler routines.

	Most of the methods for this class are not called directly by the user,

	but in some advanced usages they may need to be overridden via subclassing.

	EXCEPTION: doctemplate.build(...) must be called for most reasonable uses

	since it builds a document using the page template.

	Each document template builds exactly one document into a file specified

	by the filename argument on initialization.

	Possible keyword arguments for the initialization:

	pageTemplates: A list of templates.  Must be nonempty.	Names

	  assigned to the templates are used for referring to them so no two used

	  templates should have the same name.	For example you might want one template

	  for a title page, one for a section first page, one for a first page of

	  a chapter and two more for the interior of a chapter on odd and even pages.

	  If this argument is omitted then at least one pageTemplate should be provided

	  using the addPageTemplates method before the document is built.

	showBoundary: if set draw a box around the frame boundaries.

	leftMargin:

	rightMargin:

	topMargin:

	bottomMargin:  Margin sizes in points (default 1 inch)

	  These margins may be overridden by the pageTemplates.  They are primarily of interest

	  for the SimpleDocumentTemplate subclass.

	allowSplitting:  If set flowables (eg, paragraphs) may be split across frames or pages

	  (default: 1)

	title: Internal title for document (does not automatically display on any page)

	author: Internal author for document (does not automatically display on any page)

	"""

	_initArgs = {	'pagesize':defaultPageSize,

					'pageTemplates':[],

					'showBoundary':0,

					'leftMargin':inch,

					'rightMargin':inch,

					'topMargin':inch,

					'bottomMargin':inch,

					'allowSplitting':1,

					'title':None,

					'author':None,

					'_pageBreakQuick':1}

	_invalidInitArgs = ()

	def __init__(self, filename, **kw):

		"""create a document template bound to a filename (see class documentation for keyword arguments)"""

		self.filename = filename

		for k in self._initArgs.keys():

			if not kw.has_key(k):

				v = self._initArgs[k]

			else:

				if k in self._invalidInitArgs:

					raise ValueError, "Invalid argument %s" % k

				v = kw[k]

			setattr(self,k,v)

		#print "pagesize is", self.pagesize

		p = self.pageTemplates

		self.pageTemplates = []

		self.addPageTemplates(p)

		# facility to assist multi-build and cross-referencing.

		# various hooks can put things into here - key is what

		# you want, value is a page number.  This can then be

		# passed to indexing flowables.

		self._pageRefs = {}

		self._indexingFlowables = []

		self._calc()

		self.afterInit()

	def _calc(self):

		self._rightMargin = self.pagesize[0] - self.rightMargin

		self._topMargin = self.pagesize[1] - self.topMargin

		self.width = self._rightMargin - self.leftMargin

		self.height = self._topMargin - self.bottomMargin

	def clean_hanging(self):

		'handle internal postponed actions'

		while len(self._hanging):

			self.handle_flowable(self._hanging)

	def addPageTemplates(self,pageTemplates):

		'add one or a sequence of pageTemplates'

		if type(pageTemplates) not in (ListType,TupleType):

			pageTemplates = [pageTemplates]

		#this test below fails due to inconsistent imports!

		#assert filter(lambda x: not isinstance(x,PageTemplate), pageTemplates)==[], "pageTemplates argument error"

		for t in pageTemplates:

			self.pageTemplates.append(t)

	def handle_documentBegin(self):

		'''implement actions at beginning of document'''

		self._hanging = [PageBegin]

		self.pageTemplate = self.pageTemplates[0]

		self.page = 0

		self.beforeDocument()

	def handle_pageBegin(self):

		'''Perform actions required at beginning of page.

		shouldn't normally be called directly'''

		self.page = self.page + 1

		self.pageTemplate.beforeDrawPage(self.canv,self)

		self.pageTemplate.checkPageSize(self.canv,self)

		self.pageTemplate.onPage(self.canv,self)

		for f in self.pageTemplate.frames: f._reset()

		self.beforePage()

		if hasattr(self,'_nextFrameIndex'):

			del self._nextFrameIndex

		self.frame = self.pageTemplate.frames[0]

		self.handle_frameBegin()

	def handle_pageEnd(self):

		''' show the current page

			check the next page template

			hang a page begin

		'''

		self.pageTemplate.afterDrawPage(self.canv, self)

		self.pageTemplate.onPageEnd(self.canv, self)

		self.afterPage()

		self.canv.showPage()

		if hasattr(self,'_nextPageTemplateIndex'):

			self.pageTemplate = self.pageTemplates[self._nextPageTemplateIndex]

			del self._nextPageTemplateIndex

		self._hanging.append(PageBegin)

	def handle_pageBreak(self):

		'''some might choose not to end all the frames'''

		if self._pageBreakQuick:

			self.handle_pageEnd()

		else:

			n = len(self._hanging)

			while len(self._hanging)==n:

				self.handle_frameEnd()

	def handle_frameBegin(self,resume=0):

		'''What to do at the beginning of a frame'''

		f = self.frame

		if f._atTop:

			if self.showBoundary or self.frame.showBoundary:

				self.frame.drawBoundary(self.canv)

	def handle_frameEnd(self,resume=0):

		''' Handles the semantics of the end of a frame. This includes the selection of

			the next frame or if this is the last frame then invoke pageEnd.

		'''

		if hasattr(self,'_nextFrameIndex'):

			frame = self.pageTemplate.frames[self._nextFrameIndex]

			del self._nextFrameIndex

			self.handle_frameBegin(resume)

		elif hasattr(self.frame,'lastFrame') or self.frame is self.pageTemplate.frames[-1]:

			self.handle_pageEnd()

			self.frame = None

		else:

			f = self.frame

			self.frame = self.pageTemplate.frames[self.pageTemplate.frames.index(f) + 1]

			self.handle_frameBegin()

	def handle_nextPageTemplate(self,pt):

		'''On endPage chenge to the page template with name or index pt'''

		if type(pt) is StringType:

			for t in self.pageTemplates:

				if t.id == pt:

					self._nextPageTemplateIndex = self.pageTemplates.index(t)

					return

			raise ValueError, "can't find template('%s')"%pt

		elif type(pt) is IntType:

			self._nextPageTemplateIndex = pt

		else:

			raise TypeError, "argument pt should be string or integer"

	def handle_nextFrame(self,fx):

		'''On endFrame chenge to the frame with name or index fx'''

		if type(fx) is StringType:

			for f in self.pageTemplate.frames:

				if f.id == fx:

					self._nextFrameIndex = self.pageTemplate.frames.index(f)

					return

			raise ValueError, "can't find frame('%s')"%fx

		elif type(fx) is IntType:

			self._nextFrameIndex = fx

		else:

			raise TypeError, "argument fx should be string or integer"

	def handle_currentFrame(self,fx):

		'''chenge to the frame with name or index fx'''

		if type(fx) is StringType:

			for f in self.pageTemplate.frames:

				if f.id == fx:

					self._nextFrameIndex = self.pageTemplate.frames.index(f)

					return

			raise ValueError, "can't find frame('%s')"%fx

		elif type(fx) is IntType:

			self._nextFrameIndex = fx

		else:

			raise TypeError, "argument fx should be string or integer"

	def handle_breakBefore(self, flowables):

		'''preprocessing step to allow pageBreakBefore and frameBreakBefore attributes'''

		first = flowables[0]

		# if we insert a page break before, we'll process that, see it again,

		# and go in an infinite loop.  So we need to set a flag on the object

		# saying 'skip me'.  This should be unset on the next pass

		if hasattr(first, '_skipMeNextTime'):

			delattr(first, '_skipMeNextTime')

			return

		# this could all be made much quicker by putting the attributes

		# in to the flowables with a defult value of 0

		if hasattr(first,'pageBreakBefore') and first.pageBreakBefore == 1:

			first._skipMeNextTime = 1

			first.insert(0, PageBreak())

			return

		if hasattr(first,'style') and hasattr(first.style, 'pageBreakBefore') and first.style.pageBreakBefore == 1:

			first._skipMeNextTime = 1

			flowables.insert(0, PageBreak())

			return

		if hasattr(first,'frameBreakBefore') and first.frameBreakBefore == 1:

			first._skipMeNextTime = 1

			flowables.insert(0, FrameBreak())

			return

		if hasattr(first,'style') and hasattr(first.style, 'frameBreakBefore') and first.style.frameBreakBefore == 1:

			first._skipMeNextTime = 1

			flowables.insert(0, FrameBreak())

			return

	def handle_keepWithNext(self, flowables):

		"implements keepWithNext"

	def handle_flowable(self,flowables):

		'''try to handle one flowable from the front of list flowables.'''

		#allow document a chance to look at, modify or ignore

		#the object(s) about to be processed

		self.filterFlowables(flowables)

		self.handle_breakBefore(flowables)

		self.handle_keepWithNext(flowables)

		f = flowables[0]

		del flowables[0]

		if f is None:

			return

		if isinstance(f,PageBreak):

			self.handle_pageBreak()

			self.afterFlowable(f)

		elif isinstance(f,ActionFlowable):

			f.apply(self)

			self.afterFlowable(f)

		else:

			#try to fit it then draw it

			if self.frame.add(f, self.canv, trySplit=self.allowSplitting):

				self.afterFlowable(f)

			else:

				#if isinstance(f, KeepTogether): print 'could not add it to frame'

				if self.allowSplitting:

					# see if this is a splittable thing

					S = self.frame.split(f,self.canv)

					n = len(S)