CalloutEmitter
Date: 2016-07-03

com.nwalsh.saxon

## Class CalloutEmitter

- java.lang.Object
- - com.icl.saxon.output.Emitter
  - - com.nwalsh.saxon.CopyEmitter
    - - com.nwalsh.saxon.CalloutEmitter

- All Implemented Interfaces:
    javax.xml.transform.Result

      public class CalloutEmitter
      extends CopyEmitter

  Saxon extension to decorate a result tree fragment with callouts.

  $Id: CalloutEmitter.java 5907 2006-04-27 08:26:47Z xmldoc $

  Copyright (C) 2000 Norman Walsh.

  This class provides the guts of a Saxon 6.* implementation of callouts for verbatim environments. (It is used by the Verbatim class.)

  The general design is this: the stylesheets construct a result tree fragment for some verbatim environment. The Verbatim class initializes a CalloutEmitter with information about the callouts that should be applied to the verbatim environment in question. Then the result tree fragment is "replayed" through the CalloutEmitter; the CalloutEmitter builds a new result tree fragment from this event stream, decorated with callouts, and that is returned.

  Change Log:

  1.0

    Initial release.

  See Also:
    `Verbatim`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected int` | `defaultColumn` The default column for callouts that specify only a line.
    `protected java.util.Stack` | `elementStack` A stack for the preserving information about open elements.
    `protected boolean` | `firstElement` Is the next element absolutely the first element in the fragment?
    `protected boolean` | `foStylesheet` Is the stylesheet currently running an FO stylesheet?
    `protected static java.lang.String` | `foURI` The FO namespace name.
    `protected java.util.Stack` | `tempStack` A stack for holding information about temporarily closed elements.
    `protected static java.lang.String` | `xhURI` The XHTML namespace name.

    - ### Fields inherited from class com.nwalsh.saxon.CopyEmitter

      `namePool, rtf, rtfEmitter`

    - ### Fields inherited from class com.icl.saxon.output.Emitter

      `locator, outputProperties, outputStream, systemId, writer`

    - ### Fields inherited from interface javax.xml.transform.Result

      `PI_DISABLE_OUTPUT_ESCAPING, PI_ENABLE_OUTPUT_ESCAPING`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `CalloutEmitter(com.icl.saxon.Controller controller, com.icl.saxon.om.NamePool namePool, int defaultColumn, boolean foStylesheet, FormatCallout fCallout)` Constructor for the CalloutEmitter.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `addCallout(int coNum, org.w3c.dom.Node node, int defaultColumn)` Add a callout to the global callout array
    `void` | `characters(char[] chars, int start, int len)` Process characters.
    `void` | `endElement(int nameCode)` Process end element events.
    `protected void` | `formatPad(int numBlanks)` Add blanks to the result tree fragment.
    `void` | `setupCallouts(org.w3c.dom.NodeList areaspecNodeList)` Examine the areaspec and determine the number and position of callouts.
    `protected boolean` | `skipThisElement(int nameCode)` Protect the outer-most block wrapper.
    `void` | `startElement(int nameCode, org.xml.sax.Attributes attributes, int[] namespaces, int nscount)` Process start element events.

    - ### Methods inherited from class com.nwalsh.saxon.CopyEmitter

      `comment, endDocument, getResultTreeFragment, processingInstruction, setDocumentLocator, setEscaping, setNamePool, setUnparsedEntity, setWriter, startDocument`

    - ### Methods inherited from class com.icl.saxon.output.Emitter

      `getNamePool, getOutputProperties, getOutputStream, getSystemId, getWriter, makeEmitter, setOutputProperties, setOutputStream, setSystemId, usesWriter`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### elementStack

          protected java.util.Stack elementStack

      A stack for the preserving information about open elements.

    - #### tempStack

          protected java.util.Stack tempStack

      A stack for holding information about temporarily closed elements.

    - #### firstElement

          protected boolean firstElement

      Is the next element absolutely the first element in the fragment?

    - #### foURI

          protected static java.lang.String foURI

      The FO namespace name.

    - #### xhURI

          protected static java.lang.String xhURI

      The XHTML namespace name.

    - #### defaultColumn

          protected int defaultColumn

      The default column for callouts that specify only a line.

    - #### foStylesheet

          protected boolean foStylesheet

      Is the stylesheet currently running an FO stylesheet?

  - ### Constructor Detail

    - #### CalloutEmitter

          public CalloutEmitter(com.icl.saxon.Controller controller,
                        com.icl.saxon.om.NamePool namePool,
                        int defaultColumn,
                        boolean foStylesheet,
                        FormatCallout fCallout)

      Constructor for the CalloutEmitter.

      Parameters:
        `controller` -
        `namePool` - The name pool to use for constructing elements and attributes.
        `defaultColumn` - The default column for callouts.
        `foStylesheet` - Is this an FO stylesheet?
        `fCallout` -

  - ### Method Detail

    - #### setupCallouts

          public void setupCallouts(org.w3c.dom.NodeList areaspecNodeList)

      Examine the areaspec and determine the number and position of callouts.

      The `areaspecNodeSet` is examined and a sorted list of the callouts is constructed.

      This data structure is used to augment the result tree fragment with callout bullets.

      Parameters:
        `areaspecNodeList` - The source document <areaspec> element.

    - #### characters

          public void characters(char[] chars,
                        int start,
                        int len)
                          throws javax.xml.transform.TransformerException

      Process characters.
      Overrides:
        `characters` in class `CopyEmitter`
      Throws:
        `javax.xml.transform.TransformerException`

    - #### formatPad

          protected void formatPad(int numBlanks)

      Add blanks to the result tree fragment.

      This method adds `numBlanks` to the result tree fragment. It's used to pad lines when callouts occur after the last existing characater in a line.

      Parameters:
        `numBlanks` - The number of blanks to add.

    - #### addCallout

          protected void addCallout(int coNum,
                        org.w3c.dom.Node node,
                        int defaultColumn)

      Add a callout to the global callout array

      This method examines a callout `area` and adds it to the global callout array if it can be interpreted.

      Only the `linecolumn` and `linerange` units are supported. If no unit is specifed, `linecolumn` is assumed. If only a line is specified, the callout decoration appears in the `defaultColumn`.

      Parameters:
        `coNum` - The callout number.
        `node` - The `area`.
        `defaultColumn` - The default column for callouts.

    - #### endElement

          public void endElement(int nameCode)
                          throws javax.xml.transform.TransformerException

      Process end element events.
      Overrides:
        `endElement` in class `CopyEmitter`
      Throws:
        `javax.xml.transform.TransformerException`

    - #### startElement

          public void startElement(int nameCode,
                          org.xml.sax.Attributes attributes,
                          int[] namespaces,
                          int nscount)
                            throws javax.xml.transform.TransformerException

      Process start element events.
      Overrides:
        `startElement` in class `CopyEmitter`
      Throws:
        `javax.xml.transform.TransformerException`

    - #### skipThisElement

          protected boolean skipThisElement(int nameCode)

      Protect the outer-most block wrapper.

      Open elements in the result tree fragment are closed and reopened around callouts (so that callouts don't appear inside links or other environments). But if the result tree fragment is a single block (a div or pre in HTML, an fo:block in FO), that outer-most block is treated specially.

      This method returns true if the element in question is that outermost block.

      Parameters:
        `nameCode` - The name code for the element
      Returns:
        True if the element is the outer-most block, false otherwise.