#Copyright ReportLab Europe Ltd. 2000-2012

#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.

rlatypus 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.lib.units import inch

from reportlab.platypus.paragraph import Paragraph

from reportlab.platypus.frames import Frame

from reportlab.rl_config import defaultPageSize, verbose

import reportlab.lib.sequencer

from reportlab.pdfgen import canvas

from reportlab.lib.utils import isSeq, encode_label, decode_label, annotateException, strTypes

try:

    set

except NameError:

    from sets import Set as set

import sys

import logging

logger = logging.getLogger("reportlab.platypus")

class LayoutError(Exception):

    pass

def _fSizeString(f):

    #used to get size during error messages

    w=getattr(f,'width',None)

    if w is None:

        w=getattr(f,'_width',None)

    h=getattr(f,'height',None)

    if h is None:

        h=getattr(f,'_height',None)

    #tables in particular may have some nasty large culprit

    if hasattr(f, '_culprit'):

        c = ', %s, ' % f._culprit()

    else:

        c = ''

    if w is not None or h is not None:

        if w is None: w='???'

        if h is None: h='???'

        return '(%s x %s)%s' % (w,h,c)

    return ''

def _doNothing(canvas, doc):

    "Dummy callback for onPage"

    pass

class PTCycle(list):

    def __init__(self):

        self._restart = 0

        self._idx = 0

        list.__init__(self)

    def cyclicIterator(self):

        while 1:

            yield self[self._idx]

            self._idx += 1

            if self._idx>=len(self):

                self._idx = self._restart

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

        #must call super init to ensure it has a width and height (of zero),

        #as in some cases the packer might get called on it...

        Flowable.__init__(self)

        if not isSeq(action):

            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

        if arn=="handle_nextPageTemplate" and args[0]=='main':

            pass

        try:

            getattr(doc,arn)(*args)

        except AttributeError as aerr:

            if aerr.args[0]==arn:

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

            else:

                raise

        except:

            annotateException("\nhandle_%s args=%s"%(action,ascii(args)))

    def __call__(self):

        return self

    def identity(self, maxLen=None):

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

class LCActionFlowable(ActionFlowable):

    locChanger = 1                  #we cause a frame or page change

    def wrap(self, availWidth, availHeight):

        '''Should never be called.'''

        raise NotImplementedError

    def draw(self):

        '''Should never be called.'''

        raise NotImplementedError

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 NullActionFlowable(ActionFlowable):

    def apply(self,doc):

        pass

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.handle_nextFrame(self._ix)

        ActionFlowable.apply(self,doc)

FrameBreak = _FrameBreak('frameEnd')

PageBegin = LCActionFlowable('pageBegin')

def _evalMeasurement(n):

    if isinstance(n,str):

        from reportlab.platypus.paraparser import _num

        n = _num(n)

        if isSeq(n): n = n[1]

    return n

class FrameActionFlowable(Flowable):

    _fixedWidth = _fixedHeight = 1

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

        raise NotImplementedError('Abstract Class')

    def frameAction(self,frame):

        raise NotImplementedError('Abstract Class')

class Indenter(FrameActionFlowable):

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

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

    and makes nested lists way easier.

    """

    _ZEROSIZE=True

    width=0

    height=0

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

        self.left = _evalMeasurement(left)

        self.right = _evalMeasurement(right)

    def frameAction(self, frame):

        frame._leftExtraIndent += self.left

        frame._rightExtraIndent += self.right

class NotAtTopPageBreak(FrameActionFlowable):

    def __init__(self):

        pass

    def frameAction(self,frame):

        if not frame._atTop:

            frame.add_generated_content(PageBreak())

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

        frames = frames or []

        if not isSeq(frames): frames = [frames]

        assert [x for x in frames if not isinstance(x,Frame)]==[], "frames argument error"

        self.id = id

        self.frames = frames

        self.onPage = onPage

        self.onPageEnd = onPageEnd

        self.pagesize = pagesize

        self.autoNextPageTemplate = autoNextPageTemplate

    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 = list(map(int, canv._pagesize))

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

        if doc.pagesize: dp = list(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

def _addGeneratedContent(flowables,frame):

    S = getattr(frame,'_generated_content',None)

    if S: 

        flowables[0:0] = S

        del frame._generated_content

class onDrawStr(str):

    def __new__(cls,value,onDraw,label,kind=None):

        self = str.__new__(cls,value)

        self.onDraw = onDraw

        self.kind = kind

        self.label = label

        return self

class PageAccumulator:

    '''gadget to accumulate information in a page

    and then allow it to be interrogated at the end

    of the page'''

    _count = 0

    def __init__(self,name=None):

        if name is None:

            name = self.__class__.__name__+str(self.__class__._count)

            self.__class__._count += 1

        self.name = name

        self.data = []

    def reset(self):

        self.data[:] = []

    def add(self,*args):

        self.data.append(args)

    def onDrawText(self,*args):

        return '<onDraw name="%s" label="%s" />' % (self.name,encode_label(args))

    def __call__(self,canv,kind,label):

        self.add(*decode_label(label))

    def attachToPageTemplate(self,pt):

        if pt.onPage:

            def onPage(canv,doc,oop=pt.onPage):

                self.onPage(canv,doc)

                oop(canv,doc)

        else:

            def onPage(canv,doc):

                self.onPage(canv,doc)

        pt.onPage = onPage

        if pt.onPageEnd:

            def onPageEnd(canv,doc,oop=pt.onPageEnd):

                self.onPageEnd(canv,doc)

                oop(canv,doc)

        else:

            def onPageEnd(canv,doc):

                self.onPageEnd(canv,doc)

        pt.onPageEnd = onPageEnd

    def onPage(self,canv,doc):

        '''this will be called at the start of the page'''

        setattr(canv,self.name,self)    #push ourselves onto the canvas

        self.reset()

    def onPageEnd(self,canv,doc):

        '''this will be called at the end of a page'''

        self.pageEndAction(canv,doc)

        try:

            delattr(canv,self.name)

        except:

            pass

        self.reset()

    def pageEndAction(self,canv,doc):

        '''this should be overridden to do something useful'''

        pass

    def onDrawStr(self,value,*args):

        return onDrawStr(value,self,encode_label(args))

class BaseDocTemplate:

    """

    First attempt at defining a document template class.

    The basic idea is simple.

    1)  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.

    2)  The document has one or more page templates.

    3)  Each page template has one or more frames.

    4)  The document class provides base methods for handling the

        story events and some reasonable methods for getting the

        story flowables into the frames.

    5)  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,

                    'subject':None,

                    'creator':None,

                    'keywords':[],

                    'invariant':None,

                    'pageCompression':None,

                    '_pageBreakQuick':1,

                    'rotation':0,

                    '_debug':0,

                    'encrypt': None,

                    'cropMarks': None,

                    'enforceColorSpace': None,

                    }

    _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

        self._nameSpace = dict(doc=self)

        self._lifetimes = {}

        for k in self._initArgs.keys():

            if k not in kw:

                v = self._initArgs[k]

            else:

                if k in self._invalidInitArgs:

                    raise ValueError("Invalid argument %s" % k)

                v = kw[k]

            setattr(self,k,v)

        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