lfurini 2004/12/06 03:55:19
Modified: src/java/org/apache/fop/layoutmgr KnuthElement.java
KnuthBox.java KnuthGlue.java KnuthPenalty.java
Log:
Comments added
Revision Changes Path
1.3 +43 -2
xml-fop/src/java/org/apache/fop/layoutmgr/KnuthElement.java
Index: KnuthElement.java
===================================================================
RCS file:
/home/cvs/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthElement.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- KnuthElement.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthElement.java 6 Dec 2004 11:55:18 -0000 1.3
@@ -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 @@
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 @@
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 @@
return null;
}
}
-}
\ No newline at end of file
+}
1.3 +34 -2 xml-fop/src/java/org/apache/fop/layoutmgr/KnuthBox.java
Index: KnuthBox.java
===================================================================
RCS file: /home/cvs/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthBox.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- KnuthBox.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthBox.java 6 Dec 2004 11:55:18 -0000 1.3
@@ -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 @@
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
+}
1.3 +43 -2 xml-fop/src/java/org/apache/fop/layoutmgr/KnuthGlue.java
Index: KnuthGlue.java
===================================================================
RCS file: /home/cvs/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthGlue.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- KnuthGlue.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthGlue.java 6 Dec 2004 11:55:18 -0000 1.3
@@ -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
+}
1.3 +35 -2
xml-fop/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java
Index: KnuthPenalty.java
===================================================================
RCS file:
/home/cvs/xml-fop/src/java/org/apache/fop/layoutmgr/KnuthPenalty.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- KnuthPenalty.java 6 Sep 2004 19:07:12 -0000 1.2
+++ KnuthPenalty.java 6 Dec 2004 11:55:18 -0000 1.3
@@ -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
+}
---------------------------------------------------------------------
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
