fop 1.1

## org.apache.fop.layoutmgr
Class BalancingColumnBreakingAlgorithm

    java.lang.Object
      org.apache.fop.layoutmgr.BreakingAlgorithm
          org.apache.fop.layoutmgr.BalancingColumnBreakingAlgorithm

    public class BalancingColumnBreakingAlgorithm

extends BreakingAlgorithm

This is a the breaking algorithm that is responsible for balancing columns in multi-column layout.

Nested Class Summary
`static interface` `PageBreakingAlgorithm.PageBreakingLayoutListener` Interface to notify about layout events during page breaking.

Nested classes/interfaces inherited from class org.apache.fop.layoutmgr.BreakingAlgorithm
`BreakingAlgorithm.BestRecords, BreakingAlgorithm.KnuthNode`

Field Summary

Fields inherited from class org.apache.fop.layoutmgr.BreakingAlgorithm
`activeLines, activeNodeCount, alignment, alignmentLast, ALL_BREAKS, best, considerTooShort, endLine, incompatibleFitnessDemerit, indentFirstPart, INFINITE_RATIO, lineWidth, maxFlaggedPenaltiesCount, NO_FLAGGED_PENALTIES, ONLY_FORCED_BREAKS, par, repeatedFlaggedDemerit, startLine, totalShrink, totalStretch, totalWidth`

Constructor Summary
`BalancingColumnBreakingAlgorithm(LayoutManager topLevelLM, PageProvider pageProvider, PageBreakingAlgorithm.PageBreakingLayoutListener layoutListener, int alignment, int alignmentLast, MinOptMax footnoteSeparatorLength, boolean partOverflowRecovery, int columnCount)` Construct a balancing column breaking algorithm.

Method Summary
`protected void` `addNode(int line, BreakingAlgorithm.KnuthNode node)` Add a node at the end of the given line's existing active nodes.
`protected BreakingAlgorithm.KnuthNode` `compareNodes(BreakingAlgorithm.KnuthNode node1, BreakingAlgorithm.KnuthNode node2)` Compare two KnuthNodes and return the node with the least demerit.
`protected double` `computeAdjustmentRatio(BreakingAlgorithm.KnuthNode activeNode, int difference)` Return the adjustment ratio needed to make up for the difference.
`protected double` `computeDemerits(BreakingAlgorithm.KnuthNode activeNode, KnuthElement element, int fitnessClass, double r)` Computes the demerits of the current breaking (that is, up to the given element), if the next-to-last chosen breakpoint is the given active node.
`protected int` `computeDifference(BreakingAlgorithm.KnuthNode activeNode, KnuthElement element, int elementIndex)` Return the difference between the natural width of a line that would be made between the given active node and the given element, and the available width of the real line.
`protected void` `considerLegalBreak(KnuthElement element, int elementIdx)` Determines if the given breakpoint is a feasible breakpoint.
`protected BreakingAlgorithm.KnuthNode` `createNode(int position, int line, int fitness, int totalWidth, int totalStretch, int totalShrink)` Creates a new active node for a break from the best active node of the given fitness class to the element at the given position.
`protected BreakingAlgorithm.KnuthNode` `createNode(int position, int line, int fitness, int totalWidth, int totalStretch, int totalShrink, double adjustRatio, int availableShrink, int availableStretch, int difference, double totalDemerits, BreakingAlgorithm.KnuthNode previous)` Creates a new active node for a feasible breakpoint at the given position.
`protected boolean` `elementCanEndLine(KnuthElement element, int line, int difference)` Check if the given `KnuthElement` can end the line with the given number.
`protected int` `filterActiveNodes()` Filter active nodes.
`protected void` `finish()` Hook for subclasses to trigger special behavior after ending the main loop in `BreakingAlgorithm.findBreakingPoints(KnuthSequence,int,double,boolean,int)`
`FObj` `getFObj()`
`protected java.util.List<KnuthElement>` `getFootnoteList(int index)` Obtain the element-list corresponding to the footnote at the given index.
`protected int` `getIPDdifference()` obtain ipd difference
`protected int` `getLineWidth(int line)` Returns the line/part width of a given line/part.
`java.util.LinkedList<AbstractBreaker.PageBreakPosition>` `getPageBreaks()`
`protected void` `handleBox(KnuthBox box)` Page-breaking specific handling of the given box.
`protected int` `handleIpdChange()` handle ipd change
`protected void` `handlePenaltyAt(KnuthPenalty penalty, int position, int allowedBreaks)` Overridden to consider penalties with value `KnuthElement.INFINITE` as legal break-points, if the current keep-context allows this (a keep-*.within-page="always" constraint still permits column-breaks) Handle a `KnuthPenalty` at the given position, taking into account the type of breaks allowed.
`protected void` `initialize()` Initializes the algorithm's variables.
`void` `insertPageBreakAsFirst(AbstractBreaker.PageBreakPosition pageBreak)` Insert the given `AbstractBreaker.PageBreakPosition` as the first element in the list of page-breaks
`protected BreakingAlgorithm.KnuthNode` `recoverFromTooLong(BreakingAlgorithm.KnuthNode lastTooLong)` Overridden to defer a part to the next page, if it must be kept within one page, but is too large to fit in the last column.
`void` `removeAllPageBreaks()` Removes all page breaks from the result list.
`protected int` `restartFrom(BreakingAlgorithm.KnuthNode restartingNode, int currentIndex)` Restart from the given node at the given index.
`void` `updateData1(int total, double demerits)` Empty method, hook for subclasses.
`void` `updateData2(BreakingAlgorithm.KnuthNode bestActiveNode, KnuthSequence sequence, int total)` Empty method, hook for subclasses.

Methods inherited from class org.apache.fop.layoutmgr.BreakingAlgorithm
`activateNode, calculateBreakPoints, deactivateNode, findBreakingPoints, findBreakingPoints, forceNode, getAlignment, getAlignmentLast, getElement, getLastTooShort, getLineWidth, getMaxRecoveryAttempts, getNode, handleElementAt, handleGlueAt, isPartOverflowRecoveryActivated, recoverFromOverflow, removeNode, replaceLastDeactivated, setConstantLineWidth, toString`

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### BalancingColumnBreakingAlgorithm

    public BalancingColumnBreakingAlgorithm(LayoutManager topLevelLM,
                                            PageProvider pageProvider,
                                            PageBreakingAlgorithm.PageBreakingLayoutListener layoutListener,
                                            int alignment,
                                            int alignmentLast,
                                            MinOptMax footnoteSeparatorLength,
                                            boolean partOverflowRecovery,
                                            int columnCount)

  Construct a balancing column breaking algorithm.

  Parameters:
    `topLevelLM` - the top level layout manager
    `pageProvider` - the page provider
    `layoutListener` - the layout listener
    `alignment` - alignment of the paragraph/page. One of `Constants.EN_START`, `Constants.EN_JUSTIFY`, `Constants.EN_CENTER`, `Constants.EN_END`. For pages, `Constants.EN_BEFORE` and `Constants.EN_AFTER` are mapped to the corresponding inline properties, `Constants.EN_START` and `Constants.EN_END`.
    `alignmentLast` - alignment of the paragraph's last line
    `footnoteSeparatorLength` - length of footnote separator
    `partOverflowRecovery` - `true` if too long elements should be moved to the next line/part
    `columnCount` - number of columns
  See Also:
    `PageBreakingAlgorithm`

Method Detail

### computeDemerits

    protected double computeDemerits(BreakingAlgorithm.KnuthNode activeNode,
                                     KnuthElement element,
                                     int fitnessClass,
                                     double r)

  Computes the demerits of the current breaking (that is, up to the given element), if the next-to-last chosen breakpoint is the given active node. This adds to the total demerits of the given active node, the demerits of a line starting at this node and ending at the given element.

  Parameters:
    `activeNode` - considered preceding line break
    `element` - considered current line break
    `fitnessClass` - fitness of the current line
    `r` - adjustment ratio for the current line
  Returns:
    the demerit of the current line

### initialize

    protected void initialize()

  Initializes the algorithm's variables.

  Overrides:
    `initialize` in class `BreakingAlgorithm`

### recoverFromTooLong

    protected BreakingAlgorithm.KnuthNode recoverFromTooLong(BreakingAlgorithm.KnuthNode lastTooLong)

  Overridden to defer a part to the next page, if it must be kept within one page, but is too large to fit in the last column. Recover from a `BreakingAlgorithm.KnuthNode` leading to a line that is too long. The default implementation creates a new node corresponding to a break point after the previous node that led to a line that was too short.

  Overrides:
    `recoverFromTooLong` in class `BreakingAlgorithm`
  Parameters:
    `lastTooLong` - the node that leads to a "too long" line
  Returns:
    node corresponding to a breakpoint after the previous "too short" line

### compareNodes

    protected BreakingAlgorithm.KnuthNode compareNodes(BreakingAlgorithm.KnuthNode node1,
                                                       BreakingAlgorithm.KnuthNode node2)

  Compare two KnuthNodes and return the node with the least demerit.

  Overrides:
    `compareNodes` in class `BreakingAlgorithm`
  Parameters:
    `node1` - The first knuth node.
    `node2` - The other knuth node.
  Returns:
    the node with the least demerit.

### createNode

    protected BreakingAlgorithm.KnuthNode createNode(int position,
                                                     int line,
                                                     int fitness,
                                                     int totalWidth,
                                                     int totalStretch,
                                                     int totalShrink,
                                                     double adjustRatio,
                                                     int availableShrink,
                                                     int availableStretch,
                                                     int difference,
                                                     double totalDemerits,
                                                     BreakingAlgorithm.KnuthNode previous)

  Creates a new active node for a feasible breakpoint at the given position. Only called in forced mode.

  Overrides:
    `createNode` in class `BreakingAlgorithm`
  Parameters:
    `position` - index of the element in the Knuth sequence
    `line` - number of the line ending at the breakpoint
    `fitness` - fitness class of the line ending at the breakpoint. One of 0, 1, 2, 3.
    `totalWidth` - accumulated width of the KnuthElements up to after the breakpoint
    `totalStretch` - accumulated stretchability of the KnuthElements up to after the breakpoint
    `totalShrink` - accumulated shrinkability of the KnuthElements up to after the breakpoint
    `adjustRatio` - adjustment ratio if the line ends at this breakpoint
    `availableShrink` - available stretch of the line ending at this breakpoint
    `availableStretch` - available shrink of the line ending at this breakpoint
    `difference` - difference between target and actual line width
    `totalDemerits` - minimum total demerits up to the breakpoint
    `previous` - active node for the preceding breakpoint
  Returns:
    a new node

### createNode

    protected BreakingAlgorithm.KnuthNode createNode(int position,
                                                     int line,
                                                     int fitness,
                                                     int totalWidth,
                                                     int totalStretch,
                                                     int totalShrink)

  Creates a new active node for a break from the best active node of the given fitness class to the element at the given position.

  Overrides:
    `createNode` in class `BreakingAlgorithm`
  Parameters:
    `position` - index of the element in the Knuth sequence
    `line` - number of the line ending at the breakpoint
    `fitness` - fitness class of the line ending at the breakpoint. One of 0, 1, 2, 3.
    `totalWidth` - accumulated width of the KnuthElements up to after the breakpoint
    `totalStretch` - accumulated stretchability of the KnuthElements up to after the breakpoint
    `totalShrink` - accumulated shrinkability of the KnuthElements up to after the breakpoint
  Returns:
    a new node
  See Also:
    `BreakingAlgorithm.createNode(int, int, int, int, int, int, double, int, int, int, double, org.apache.fop.layoutmgr.BreakingAlgorithm.KnuthNode)`, `BreakingAlgorithm.BestRecords`

### handleBox

    protected void handleBox(KnuthBox box)

  Page-breaking specific handling of the given box. Currently it adds the footnotes cited in the given box to the list of to-be-handled footnotes. Handle a `KnuthBox`.
  Note: default implementation just adds the box's width to the total content width. Subclasses that do not keep track of this themselves, but override this method, should remember to call `super.handleBox(box)` to avoid unwanted side-effects.

  Overrides:
    `handleBox` in class `BreakingAlgorithm`
  Parameters:
    `box` - the `KnuthBox` to handle

### handlePenaltyAt

    protected void handlePenaltyAt(KnuthPenalty penalty,
                                   int position,
                                   int allowedBreaks)

  Overridden to consider penalties with value `KnuthElement.INFINITE` as legal break-points, if the current keep-context allows this (a keep-*.within-page="always" constraint still permits column-breaks) Handle a `KnuthPenalty` at the given position, taking into account the type of breaks allowed.

  Overrides:
    `handlePenaltyAt` in class `BreakingAlgorithm`
  Parameters:
    `penalty` - the `KnuthPenalty` to handle
    `position` - the position of the penalty in the list
    `allowedBreaks` - the type of breaks that are allowed

### restartFrom

    protected int restartFrom(BreakingAlgorithm.KnuthNode restartingNode,
                              int currentIndex)

  Restart from the given node at the given index.

  Overrides:
    `restartFrom` in class `BreakingAlgorithm`
  Parameters:
    `restartingNode` - the `BreakingAlgorithm.KnuthNode` to restart from
    `currentIndex` - the current position index
  Returns:
    the index of the restart point

### considerLegalBreak

    protected void considerLegalBreak(KnuthElement element,
                                      int elementIdx)

  Determines if the given breakpoint is a feasible breakpoint. That is, if a decent line may be built between one of the currently active nodes and this breakpoint.

  Overrides:
    `considerLegalBreak` in class `BreakingAlgorithm`
  Parameters:
    `element` - the paragraph's element to consider
    `elementIdx` - the element's index inside the paragraph

### elementCanEndLine

    protected boolean elementCanEndLine(KnuthElement element,
                                        int line,
                                        int difference)

  Check if the given `KnuthElement` can end the line with the given number.

  Overrides:
    `elementCanEndLine` in class `BreakingAlgorithm`
  Parameters:
    `element` - the element
    `line` - the line number
    `difference` - an integer
  Returns:
    `true` if the element can end the line

### computeDifference

    protected int computeDifference(BreakingAlgorithm.KnuthNode activeNode,
                                    KnuthElement element,
                                    int elementIndex)

  Return the difference between the natural width of a line that would be made between the given active node and the given element, and the available width of the real line.

  Overrides:
    `computeDifference` in class `BreakingAlgorithm`
  Parameters:
    `activeNode` - node for the previous breakpoint
    `element` - currently considered breakpoint
    `elementIndex` - index of the element that is considered as a breakpoint
  Returns:
    The difference in width. Positive numbers mean extra space in the line, negative number that the line overflows.

### computeAdjustmentRatio

    protected double computeAdjustmentRatio(BreakingAlgorithm.KnuthNode activeNode,
                                            int difference)

  Return the adjustment ratio needed to make up for the difference. A ratio of
  - 0 means that the break has the exact right width
  - >= -1 && < 0 means that the break is wider than the line, but within the minimim values of the glues.
  - >0 && < 1 means that the break is smaller than the line width, but within the maximum values of the glues.
  - > 1 means that the break is too small to make up for the glues.

  Overrides:
    `computeAdjustmentRatio` in class `BreakingAlgorithm`
  Parameters:
    `activeNode` - the currently active node
    `difference` - the difference between content-length and available width
  Returns:
    The adjustment ratio.

### finish

    protected void finish()

  Hook for subclasses to trigger special behavior after ending the main loop in `BreakingAlgorithm.findBreakingPoints(KnuthSequence,int,double,boolean,int)`

  Overrides:
    `finish` in class `BreakingAlgorithm`

### getPageBreaks

    public java.util.LinkedList<AbstractBreaker.PageBreakPosition> getPageBreaks()

  Returns:
    a list of `AbstractBreaker.PageBreakPosition` elements corresponding to the computed page- and column-breaks

### insertPageBreakAsFirst

    public void insertPageBreakAsFirst(AbstractBreaker.PageBreakPosition pageBreak)

  Insert the given `AbstractBreaker.PageBreakPosition` as the first element in the list of page-breaks

  Parameters:
    `pageBreak` - the position to insert

### removeAllPageBreaks

    public void removeAllPageBreaks()

  Removes all page breaks from the result list. This is used by block-containers and static-content when it is only desired to know where there is an overflow but later the whole content should be painted as one part.

### updateData1

    public void updateData1(int total,
                            double demerits)

  Empty method, hook for subclasses. Called before determining the optimal breakpoints corresponding to a given active node.

  Specified by:
    `updateData1` in class `BreakingAlgorithm`
  Parameters:
    `total` - number of lines for the active node
    `demerits` - total demerits of the paragraph for the active node

### updateData2

    public void updateData2(BreakingAlgorithm.KnuthNode bestActiveNode,
                            KnuthSequence sequence,
                            int total)

  Empty method, hook for subclasses. Called when determining the optimal breakpoints for a given active node.

  Specified by:
    `updateData2` in class `BreakingAlgorithm`
  Parameters:
    `bestActiveNode` - a node in the chain of best active nodes, corresponding to one of the optimal breakpoints
    `sequence` - the corresponding paragraph
    `total` - the number of lines into which the paragraph will be broken

### filterActiveNodes

    protected int filterActiveNodes()

  Filter active nodes.

  Specified by:
    `filterActiveNodes` in class `BreakingAlgorithm`
  Returns:
    an integer

### getFootnoteList

    protected final java.util.List<KnuthElement> getFootnoteList(int index)

  Obtain the element-list corresponding to the footnote at the given index.

  Parameters:
    `index` - the index in the list of footnotes
  Returns:
    the element-list

### getFObj

    public FObj getFObj()

  Returns:
    the associated top-level formatting object.

### getLineWidth

    protected int getLineWidth(int line)

  Returns the line/part width of a given line/part.

  Overrides:
    `getLineWidth` in class `BreakingAlgorithm`
  Parameters:
    `line` - the line/part number
  Returns:
    the width/length in millipoints

### getIPDdifference

    protected int getIPDdifference()

  obtain ipd difference

  Overrides:
    `getIPDdifference` in class `BreakingAlgorithm`
  Returns:
    an integer

### handleIpdChange

    protected int handleIpdChange()

  handle ipd change

  Overrides:
    `handleIpdChange` in class `BreakingAlgorithm`
  Returns:
    an integer

### addNode

    protected void addNode(int line,
                           BreakingAlgorithm.KnuthNode node)

  Add a node at the end of the given line's existing active nodes. If this is the first node in the line, adjust endLine accordingly.

  Overrides:
    `addNode` in class `BreakingAlgorithm`
  Parameters:
    `line` - number of the line ending at the node's corresponding breakpoint
    `node` - the active node to add

fop 1.1

Copyright 1999-2012 The Apache Software Foundation. All Rights Reserved.