BalancingColumnBreakingAlgorithm (Apache FOP 2.7 API)
Date: 2022-01-12

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
    Modifier and Type | Class and Description
    --- | ---
    `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
    Modifier and Type | Field and Description
    --- | ---
    `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
    Modifier and Type | Method and Description
    --- | ---
    `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 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` | `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(java.util.List fl, java.util.List 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 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

    - #### 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(java.util.List fl,
                                    java.util.List 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)

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