From 5ee3037ec76310a8a8280eed1440d5b620919d05 Mon Sep 17 00:00:00 2001 From: Luca Furini Date: Mon, 6 Dec 2004 11:55:18 +0000 Subject: [PATCH] Comments added git-svn-id: https://svn.apache.org/repos/asf/xmlgraphics/fop/trunk@198188 13f79535-47bb-0310-9956-ffa450edef68 --- .../org/apache/fop/layoutmgr/KnuthBox.java | 34 ++++++++++++++- .../apache/fop/layoutmgr/KnuthElement.java | 43 ++++++++++++++++++- .../org/apache/fop/layoutmgr/KnuthGlue.java | 43 ++++++++++++++++++- .../apache/fop/layoutmgr/KnuthPenalty.java | 35 ++++++++++++++- 4 files changed, 151 insertions(+), 4 deletions(-) diff --git a/src/java/org/apache/fop/layoutmgr/KnuthBox.java b/src/java/org/apache/fop/layoutmgr/KnuthBox.java index 7f5e5e8a6..76f56eb4e 100644 --- a/src/java/org/apache/fop/layoutmgr/KnuthBox.java +++ b/src/java/org/apache/fop/layoutmgr/KnuthBox.java @@ -18,11 +18,34 @@ package org.apache.fop.layoutmgr; +/** + * An instance of this class represents an unbreakable piece of content with + * fixed width: for example an image, a syllable (but only if letter spacing + * is constant), ... + * + * A KnuthBox is never a feasible breaking point. + * + * The represented piece of content is never suppressed. + * + * Besides the inherited methods and attributes, this class has some more + * attributes to store information about the content height and its vertical + * positioning, and the methods used to get them. + */ public class KnuthBox extends KnuthElement { private int lead; private int total; private int middle; + /** + * Create a new KnuthBox. + * + * @param w the width of this box + * @param l the height of this box above the main baseline + * @param t the total height of this box + * @param m the height of this box above and below the middle baseline + * @param pos the Position stored in this box + * @param bAux is this box auxiliary? + */ public KnuthBox(int w, int l, int t, int m, Position pos, boolean bAux) { super(KNUTH_BOX, w, pos, bAux); lead = l; @@ -30,15 +53,24 @@ public class KnuthBox extends KnuthElement { middle = m; } + /** + * Return the height of this box above the main baseline. + */ public int getLead() { return lead; } + /** + * Return the total height of this box. + */ public int getTotal() { return total; } + /** + * Return the height of this box above and below the middle baseline. + */ public int getMiddle() { return middle; } -} \ No newline at end of file +} diff --git a/src/java/org/apache/fop/layoutmgr/KnuthElement.java b/src/java/org/apache/fop/layoutmgr/KnuthElement.java index 0b88e2c81..77d85555e 100644 --- a/src/java/org/apache/fop/layoutmgr/KnuthElement.java +++ b/src/java/org/apache/fop/layoutmgr/KnuthElement.java @@ -18,6 +18,14 @@ package org.apache.fop.layoutmgr; +/** + * This is the super class for KnuthBox, KnuthGlue and KnuthPenalty. + * + * It stores information common to all sub classes, and the methods to get it: + * the width, a Position and a boolean marking KnuthElements used for some + * special feature (for example, the additional elements used to represent + * a space when text alignment is right, left or center). + */ public abstract class KnuthElement { public static final int KNUTH_BOX = 0; @@ -31,6 +39,15 @@ public abstract class KnuthElement { private Position position; private boolean bIsAuxiliary; + /** + * Create a new KnuthElement. + * This class being abstract, this can be called only by subclasses. + * + * @param t the type of this element (one of the KNUTH_* constants) + * @param w the width of this element + * @param pos the Position stored in this element + * @param bAux is this an auxiliary element? + */ protected KnuthElement(int t, int w, Position pos, boolean bAux) { type = t; width = w; @@ -38,34 +55,58 @@ public abstract class KnuthElement { bIsAuxiliary = bAux; } + /** + * Return true if this element is a KnuthBox. + */ public boolean isBox() { return (type == KNUTH_BOX); } + /** + * Return true if this element is a KnuthGlue. + */ public boolean isGlue() { return (type == KNUTH_GLUE); } + /** + * Return true if this element is a KnuthPenalty. + */ public boolean isPenalty() { return (type == KNUTH_PENALTY); } + /** + * Return true if this element is an auxiliary one. + */ public boolean isAuxiliary() { return bIsAuxiliary; } + /** + * Return the width of this element. + */ public int getW() { return width; } + /** + * Return the Position stored in this element. + */ public Position getPosition() { return position; } + /** + * Change the Position stored in this element. + */ public void setPosition(Position pos) { position = pos; } + /** + * Return the LayoutManager responsible for this element. + */ public LayoutManager getLayoutManager() { if (position != null) { return position.getLM(); @@ -73,4 +114,4 @@ public abstract class KnuthElement { return null; } } -} \ No newline at end of file +} diff --git a/src/java/org/apache/fop/layoutmgr/KnuthGlue.java b/src/java/org/apache/fop/layoutmgr/KnuthGlue.java index b18648d98..f26b540ce 100644 --- a/src/java/org/apache/fop/layoutmgr/KnuthGlue.java +++ b/src/java/org/apache/fop/layoutmgr/KnuthGlue.java @@ -18,21 +18,62 @@ package org.apache.fop.layoutmgr; +/** + * An instance of this class represents a piece of content with adjustable + * width: for example a space between words of justified text. + * + * A KnuthGlue is a feasible breaking point only if it immediately follows + * a KnuthBox. + * + * The represented piece of content is suppressed if either the KnuthGlue + * is a chosen breaking point or there isn't any KnuthBox between the + * previous breaking point and the KnuthGlue itself. + * + * So, an unsuppressible piece of content with adjustable width, for example + * a leader or a word with adjustable letter space, cannot be represented + * by a single KnuthGlue; it can be represented using the sequence: + * KnuthBox(width = 0) + * KnuthPenalty(width = 0, penalty = infinity) + * KnuthGlue(...) + * KnuthBox(width = 0) + * where the infinity penalty avoids choosing the KnuthGlue as a breaking point + * and the 0-width KnuthBoxes prevent suppression. + * + * Besides the inherited methods and attributes, this class has two attributes + * used to store the stretchability (difference between max and opt width) and + * the shrinkability (difference between opt and min width), and the methods + * to get these values. + */ public class KnuthGlue extends KnuthElement { private int stretchability; private int shrinkability; + /** + * Create a new KnuthGlue. + * + * @param w the width of this glue + * @param y the stretchability of this glue + * @param z the shrinkability of this glue + * @param pos the Position stored in this glue + * @param bAux is this glue auxiliary? + */ public KnuthGlue(int w, int y, int z, Position pos, boolean bAux) { super(KNUTH_GLUE, w, pos, bAux); stretchability = y; shrinkability = z; } + /** + * Return the stretchability of this glue. + */ public int getY() { return stretchability; } + /** + * Return the shrinkability of this glue. + */ public int getZ() { return shrinkability; } -} \ No newline at end of file +} diff --git a/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java b/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java index a2a045c06..0af1f3210 100644 --- a/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java +++ b/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java @@ -18,21 +18,54 @@ package org.apache.fop.layoutmgr; +/** + * An instance of this class represents information about a feasible + * breaking point; it does not represent any piece of content. + * + * A KnuthPenalty is a feasible breaking point unless its value is infinity; + * a KnuthPenalty whose value is -infinity represents a forced break. + * + * A KnuthPenalty is suppressed, and its width is ignored, if it is not a + * chosen breaking point; for example, a KnuthPenalty representing a + * hyphenation point has a width (the "-" width), which must be ignored if + * that point is not chosen as a breaking point. + * + * Besides the inherited methods and attributes, this class has two more + * attributes and the methods used to get them: the penalty value, which is + * a kind of "aesthetic cost" (the higher the value, the more unsightly the + * breaking point), and a boolean that marks KnuthPenalties which should not + * be chosen as breaking points for consecutive lines. + */ public class KnuthPenalty extends KnuthElement { private int penalty; private boolean bFlagged; + /** + * Create a new KnuthPenalty. + * + * @param w the width of this penalty + * @param p the penalty value of this penalty + * @param f is this penalty flagged? + * @param pos the Position stored in this penalty + * @param bAux is this penalty auxiliary? + */ public KnuthPenalty(int w, int p, boolean f, Position pos, boolean bAux) { super(KNUTH_PENALTY, w, pos, bAux); penalty = p; bFlagged = f; } + /** + * Return the penalty value of this penalty. + */ public int getP() { return penalty; } + /** + * Return true is this penalty is a flagged one. + */ public boolean isFlagged() { return bFlagged; } -} \ No newline at end of file +} -- 2.39.5