#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/platypus/doctemplate.py

__version__=''' $Id$ '''

__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

class LayoutError(Exception):

    pass

def _doNothing(canvas, doc):

    "Dummy callback for onPage"

    pass

class IndexingFlowable(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 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, unused = sys.exc_info()

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

    def __call__(self):

        return self

    def identity(self, maxLen=None):

        return "ActionFlowable: %s" % str(self.action)

class LCActionFlowable(ActionFlowable):

    locChanger = 1                  #we cause a frame or page change

class NextFrameFlowable(ActionFlowable):

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

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

class CurrentFrameFlowable(LCActionFlowable):

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

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

class _FrameBreak(LCActionFlowable):

    '''

    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 = LCActionFlowable('pageBegin')

def _evalMeasurement(n):

    if type(n) is type(''):

        from paraparser import _num

        n = _num(n)

        if type(n) is type(()): n = n[1]

    return n

class Indenter(ActionFlowable):

    """Increases or decreases left and right margins of frame.

    This allows one to have a 'context-sensitive' indentation

    and makes nested lists way easier.

    """

    def __init__(self, left=0, right=0):

        self.left = _evalMeasurement(left)

        self.right = _evalMeasurement(right)

    def apply(self, doc):

        doc.frame._leftExtraIndent = doc.frame._leftExtraIndent + self.left

        doc.frame._rightExtraIndent = doc.frame._rightExtraIndent + self.right

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=None):

        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 != template size then the canv size is set to

        the template size or if that's not available to the

        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.

    pageSize: a 2-tuple or a size constant from reportlab/lib/pagesizes.pu.

     Used by the SimpleDocTemplate subclass which does NOT accept a list of

     pageTemplates but makes one for you; ignored when using pageTemplates.

    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,

                    'invariant':None,

                    '_pageBreakQuick':1}

    _invalidInitArgs = ()

    _firstPageTemplateIndex = 0

    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 = []

        #callback facility for progress monitoring

        self._onPage = None

        self._onProgress = None

        self._flowableCount = 0  # so we know how far to go

        #infinite loop detection if we start doing lots of empty pages

        self._curPageFlowableCount = 0

        self._emptyPages = 0

        self._emptyPagesAllowed = 10

        #context sensitive margins - set by story, not from outside

        self._leftExtraIndent = 0.0

        self._rightExtraIndent = 0.0

        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 setPageCallBack(self, func):

        'Simple progress monitor - func(pageNo) called on each new page'

        self._onPage = func

    def setProgressCallBack(self, func):

        '''Cleverer progress monitor - func(typ, value) called regularly'''

        self._onProgress = func

    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[self._firstPageTemplateIndex]

        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()

        #keep a count of flowables added to this page.  zero indicates bad stuff

        self._curPageFlowableCount = 0

        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

        '''

        #detect infinite loops...

        if self._curPageFlowableCount == 0:

            self._emptyPages = self._emptyPages + 1

        else:

            self._emptyPages = 0

        if self._emptyPages >= self._emptyPagesAllowed:

            if 1:

                raise LayoutError("More than %d pages generated without content - halting layout.  Likely that a flowable is too large for any frame." % self._emptyPagesAllowed)

            else:

                pass    #attempt to restore to good state

        else:

            if self._onProgress:

                self._onProgress('PAGE', self.canv.getPageNumber())

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

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

            self.afterPage()

            self.canv.showPage()

            if hasattr(self,'_nextPageTemplateCycle'):

                #they are cycling through pages'; we keep the index

                cyc = self._nextPageTemplateCycle

                idx = self._nextPageTemplateIndex

                self.pageTemplate = cyc[idx]  #which is one of the ones in the list anyway

                #bump up by 1

                self._nextPageTemplateIndex = (idx + 1) % len(cyc)

            elif hasattr(self,'_nextPageTemplateIndex'):

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

                del self._nextPageTemplateIndex

            if self._emptyPages==0:

                pass    #store good state here

        self._hanging.append(PageBegin)

    def handle_pageBreak(self,slow=None):

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

        if self._pageBreakQuick and not slow:

            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)

        f._leftExtraIndent = self._leftExtraIndent

        f._rightExtraIndent = self._rightExtraIndent

    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.

        '''

        self._leftExtraIndent = self.frame._leftExtraIndent

        self._rightExtraIndent = self.frame._rightExtraIndent

        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 change to the page template with name or index pt'''

        if type(pt) is StringType:

            if hasattr(self, '_nextPageTemplateCycle'): del self._nextPageTemplateCycle

            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:

            if hasattr(self, '_nextPageTemplateCycle'): del self._nextPageTemplateCycle

            self._nextPageTemplateIndex = pt

        elif type(pt) in (ListType, TupleType):

            #used for alternating left/right pages

            #collect the refs to the template objects, complain if any are bad

            cycle = []

            for templateName in pt:

                found = 0

                for t in self.pageTemplates:

                    if t.id == templateName:

                        cycle.append(t)