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

Nested Classes
`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
`BreakingAlgorithm.KnuthNode` `bestNodeForLastPage`

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

Constructors
Constructor and Description
`BalancingColumnBreakingAlgorithm(LayoutManager topLevelLM, PageProvider pageProvider, PageBreakingAlgorithm.PageBreakingLayoutListener layoutListener, int alignment, int alignmentLast, MinOptMax footnoteSeparatorLength, boolean partOverflowRecovery, int columnCount)`

### Method Summary

All Methods Instance Methods Concrete Methods
`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 void` `createForcedNodes(BreakingAlgorithm.KnuthNode node, int line, int elementIdx, int difference, double r, double demerits, int fitnessClass, int availableShrink, int availableStretch, int newWidth, int newStretch, int newShrink)`
`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 void` `deactivateNode(BreakingAlgorithm.KnuthNode node, int line)` Deactivate the given node
`protected void` `disableFloatHandling()`
`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)`
`protected BreakingAlgorithm.KnuthNode` `getBestFloatEdgeNode()`
`protected int` `getFloatHeight()`
`protected AbstractBreaker.FloatPosition` `getFloatPosition()`
`FObj` `getFObj()`
`protected 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.
`LinkedList<AbstractBreaker.PageBreakPosition>` `getPageBreaks()`
`protected void` `handleBox(KnuthBox box)` Page-breaking specific handling of the given box.
`protected int` `handleFloat()`
`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 boolean` `handlingEndOfFloat()`
`protected boolean` `handlingFloat()`
`protected boolean` `handlingStartOfFloat()`
`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
`void` `loadFootnotes(List fl, List<Integer> ll, int tfl, int ifl, boolean fp, boolean nf, int fnfi, int fli, int fei, MinOptMax fsl, int pfli, int pfei)`
`protected BreakingAlgorithm.KnuthNode` `recoverFromOverflow()` Recover from an overflow condition.
`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` `relayFootnotes(PageSequenceLayoutManager pslm)`
`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, findBreakingPoints, findBreakingPoints, forceNode, getAlignment, getAlignmentLast, getElement, getLastTooLong, getLastTooShort, getLineWidth, getMaxRecoveryAttempts, getNode, handleElementAt, handleGlueAt, isPartOverflowRecoveryActivated, removeNode, replaceLastDeactivated, setConstantLineWidth, toString`

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

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

### Field Detail

#### bestNodeForLastPage

    public BreakingAlgorithm.KnuthNode bestNodeForLastPage

### Constructor Detail

#### BalancingColumnBreakingAlgorithm

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

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

#### recoverFromOverflow

    protected BreakingAlgorithm.KnuthNode recoverFromOverflow()

Description copied from class: `BreakingAlgorithm`
Recover from an overflow condition.

Overrides:
  `recoverFromOverflow` in class `BreakingAlgorithm`
Returns:
  the new `lastForced` node

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

#### handlingFloat

    protected boolean handlingFloat()

Overrides:
  `handlingFloat` in class `BreakingAlgorithm`

#### createForcedNodes

    protected void createForcedNodes(BreakingAlgorithm.KnuthNode node,
                                     int line,
                                     int elementIdx,
                                     int difference,
                                     double r,
                                     double demerits,
                                     int fitnessClass,
                                     int availableShrink,
                                     int availableStretch,
                                     int newWidth,
                                     int newStretch,
                                     int newShrink)

Overrides:
  `createForcedNodes` in class `BreakingAlgorithm`

#### handleFloat

    protected int handleFloat()

Overrides:
  `handleFloat` in class `BreakingAlgorithm`

#### getBestFloatEdgeNode

    protected BreakingAlgorithm.KnuthNode getBestFloatEdgeNode()

#### getFloatPosition

    protected AbstractBreaker.FloatPosition getFloatPosition()

#### getFloatHeight

    protected int getFloatHeight()

#### handlingStartOfFloat

    protected boolean handlingStartOfFloat()

#### handlingEndOfFloat

    protected boolean handlingEndOfFloat()

#### deactivateNode

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

Deactivate the given node

Overrides:
  `deactivateNode` in class `BreakingAlgorithm`
Parameters:
  `node` - the node
  `line` - the line number

#### disableFloatHandling

    protected void disableFloatHandling()

Overrides:
  `disableFloatHandling` in class `BreakingAlgorithm`

#### loadFootnotes

    public void loadFootnotes(List fl,
                              List<Integer> ll,
                              int tfl,
                              int ifl,
                              boolean fp,
                              boolean nf,
                              int fnfi,
                              int fli,
                              int fei,
                              MinOptMax fsl,
                              int pfli,
                              int pfei)

#### relayFootnotes

    public void relayFootnotes(PageSequenceLayoutManager pslm)