AsyncBoxView.java

/*
 * Copyright (c) 1999, 2015, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation. Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */
packagejavax.swing.text;

importjava.util.*;
importjava.util.List;
importjava.awt.*;
importjavax.swing.SwingUtilities;
importjavax.swing.event.DocumentEvent;

/**
 * A box that does layout asynchronously. This
 * is useful to keep the GUI event thread moving by
 * not doing any layout on it. The layout is done
 * on a granularity of operations on the child views.
 * After each child view is accessed for some part
 * of layout (a potentially time consuming operation)
 * the remaining tasks can be abandoned or a new higher
 * priority task (i.e. to service a synchronous request
 * or a visible area) can be taken on.
 * <p>
 * While the child view is being accessed
 * a read lock is acquired on the associated document
 * so that the model is stable while being accessed.
 *
 * @author Timothy Prinzing
 * @since 1.3
 */
publicclassAsyncBoxViewextendsView {

/**
 * Construct a box view that does asynchronous layout.
 *
 * @param elem the element of the model to represent
 * @param axis the axis to tile along. This can be
 * either X_AXIS or Y_AXIS.
 */
publicAsyncBoxView(Elementelem, intaxis) {
super(elem);
stats = newArrayList<ChildState>();
this.axis = axis;
locator = newChildLocator();
flushTask = newFlushTask();
minorSpan = Short.MAX_VALUE;
estimatedMajorSpan = false;
 }

/**
 * Fetch the major axis (the axis the children
 * are tiled along). This will have a value of
 * either X_AXIS or Y_AXIS.
 * @return the major axis
 */
publicintgetMajorAxis() {
returnaxis;
 }

/**
 * Fetch the minor axis (the axis orthogonal
 * to the tiled axis). This will have a value of
 * either X_AXIS or Y_AXIS.
 * @return the minor axis
 */
publicintgetMinorAxis() {
return (axis == X_AXIS) ? Y_AXIS : X_AXIS;
 }

/**
 * Get the top part of the margin around the view.
 * @return the top part of the margin around the view
 */
publicfloatgetTopInset() {
returntopInset;
 }

/**
 * Set the top part of the margin around the view.
 *
 * @param i the value of the inset
 */
publicvoidsetTopInset(floati) {
topInset = i;
 }

/**
 * Get the bottom part of the margin around the view.
 * @return the bottom part of the margin around the view
 */
publicfloatgetBottomInset() {
returnbottomInset;
 }

/**
 * Set the bottom part of the margin around the view.
 *
 * @param i the value of the inset
 */
publicvoidsetBottomInset(floati) {
bottomInset = i;
 }

/**
 * Get the left part of the margin around the view.
 * @return the left part of the margin around the view
 */
publicfloatgetLeftInset() {
returnleftInset;
 }

/**
 * Set the left part of the margin around the view.
 *
 * @param i the value of the inset
 */
publicvoidsetLeftInset(floati) {
leftInset = i;
 }

/**
 * Get the right part of the margin around the view.
 * @return the right part of the margin around the view
 */
publicfloatgetRightInset() {
returnrightInset;
 }

/**
 * Set the right part of the margin around the view.
 *
 * @param i the value of the inset
 */
publicvoidsetRightInset(floati) {
rightInset = i;
 }

/**
 * Fetch the span along an axis that is taken up by the insets.
 *
 * @param axis the axis to determine the total insets along,
 * either X_AXIS or Y_AXIS.
 * @return the span along an axis that is taken up by the insets
 * @since 1.4
 */
protectedfloatgetInsetSpan(intaxis) {
floatmargin = (axis == X_AXIS) ?
getLeftInset() + getRightInset() : getTopInset() + getBottomInset();
returnmargin;
 }

/**
 * Set the estimatedMajorSpan property that determines if the
 * major span should be treated as being estimated. If this
 * property is true, the value of setSize along the major axis
 * will change the requirements along the major axis and incremental
 * changes will be ignored until all of the children have been updated
 * (which will cause the property to automatically be set to false).
 * If the property is false the value of the majorSpan will be
 * considered to be accurate and incremental changes will be
 * added into the total as they are calculated.
 *
 * @param isEstimated new value for the estimatedMajorSpan property
 * @since 1.4
 */
protectedvoidsetEstimatedMajorSpan(booleanisEstimated) {
estimatedMajorSpan = isEstimated;
 }

/**
 * Is the major span currently estimated?
 * @return whether or not the major span currently estimated
 *
 * @since 1.4
 */
protectedbooleangetEstimatedMajorSpan() {
returnestimatedMajorSpan;
 }

/**
 * Fetch the object representing the layout state of
 * of the child at the given index.
 *
 * @param index the child index. This should be a
 * value &gt;= 0 and &lt; getViewCount().
 * @return the object representing the layout state of
 * of the child at the given index
 */
protectedChildStategetChildState(intindex) {
synchronized(stats) {
if ((index >= 0) && (index < stats.size())) {
returnstats.get(index);
 }
returnnull;
 }
 }

/**
 * Fetch the queue to use for layout.
 * @return the queue to use for layout
 */
protectedLayoutQueuegetLayoutQueue() {
returnLayoutQueue.getDefaultQueue();
 }

/**
 * New ChildState records are created through
 * this method to allow subclasses the extend
 * the ChildState records to do/hold more.
 * @param v the view
 * @return new child state
 */
protectedChildStatecreateChildState(Viewv) {
returnnewChildState(v);
 }

/**
 * Requirements changed along the major axis.
 * This is called by the thread doing layout for
 * the given ChildState object when it has completed
 * fetching the child views new preferences.
 * Typically this would be the layout thread, but
 * might be the event thread if it is trying to update
 * something immediately (such as to perform a
 * model/view translation).
 * <p>
 * This is implemented to mark the major axis as having
 * changed so that a future check to see if the requirements
 * need to be published to the parent view will consider
 * the major axis. If the span along the major axis is
 * not estimated, it is updated by the given delta to reflect
 * the incremental change. The delta is ignored if the
 * major span is estimated.
 * @param cs the child state
 * @param delta the delta
 */
protectedsynchronizedvoidmajorRequirementChange(ChildStatecs, floatdelta) {
if (estimatedMajorSpan == false) {
majorSpan += delta;
 }
majorChanged = true;
 }

/**
 * Requirements changed along the minor axis.
 * This is called by the thread doing layout for
 * the given ChildState object when it has completed
 * fetching the child views new preferences.
 * Typically this would be the layout thread, but
 * might be the GUI thread if it is trying to update
 * something immediately (such as to perform a
 * model/view translation).
 * @param cs the child state
 */
protectedsynchronizedvoidminorRequirementChange(ChildStatecs) {
minorChanged = true;
 }

/**
 * Publish the changes in preferences upward to the parent
 * view. This is normally called by the layout thread.
 */
protectedvoidflushRequirementChanges() {
AbstractDocumentdoc = (AbstractDocument) getDocument();
try {
doc.readLock();

Viewparent = null;
booleanhorizontal = false;
booleanvertical = false;

synchronized(this) {
// perform tasks that iterate over the children while
// preventing the collection from changing.
synchronized(stats) {
intn = getViewCount();
if ((n > 0) && (minorChanged || estimatedMajorSpan)) {
LayoutQueueq = getLayoutQueue();
ChildStatemin = getChildState(0);
ChildStatepref = getChildState(0);
floatspan = 0f;
for (inti = 1; i < n; i++) {
ChildStatecs = getChildState(i);
if (minorChanged) {
if (cs.min > min.min) {
min = cs;
 }
if (cs.pref > pref.pref) {
pref = cs;
 }
 }
if (estimatedMajorSpan) {
span += cs.getMajorSpan();
 }
 }

if (minorChanged) {
minRequest = min;
prefRequest = pref;
 }
if (estimatedMajorSpan) {
majorSpan = span;
estimatedMajorSpan = false;
majorChanged = true;
 }
 }
 }

// message preferenceChanged
if (majorChanged || minorChanged) {
parent = getParent();
if (parent != null) {
if (axis == X_AXIS) {
horizontal = majorChanged;
vertical = minorChanged;
 } else {
vertical = majorChanged;
horizontal = minorChanged;
 }
 }
majorChanged = false;
minorChanged = false;
 }
 }

// propagate a preferenceChanged, using the
// layout thread.
if (parent != null) {
parent.preferenceChanged(this, horizontal, vertical);

// probably want to change this to be more exact.
Componentc = getContainer();
if (c != null) {
c.repaint();
 }
 }
 } finally {
doc.readUnlock();
 }
 }

/**
 * Calls the superclass to update the child views, and
 * updates the status records for the children. This
 * is expected to be called while a write lock is held
 * on the model so that interaction with the layout
 * thread will not happen (i.e. the layout thread
 * acquires a read lock before doing anything).
 *
 * @param offset the starting offset into the child views &gt;= 0
 * @param length the number of existing views to replace &gt;= 0
 * @param views the child views to insert
 */
publicvoidreplace(intoffset, intlength, View[] views) {
synchronized(stats) {
// remove the replaced state records
for (inti = 0; i < length; i++) {
ChildStatecs = stats.remove(offset);
floatcsSpan = cs.getMajorSpan();

cs.getChildView().setParent(null);
if (csSpan != 0) {
majorRequirementChange(cs, -csSpan);
 }
 }

// insert the state records for the new children
LayoutQueueq = getLayoutQueue();
if (views != null) {
for (inti = 0; i < views.length; i++) {
ChildStates = createChildState(views[i]);
stats.add(offset + i, s);
q.addTask(s);
 }
 }

// notify that the size changed
q.addTask(flushTask);
 }
 }

/**
 * Loads all of the children to initialize the view.
 * This is called by the {@link #setParent setParent}
 * method. Subclasses can reimplement this to initialize
 * their child views in a different manner. The default
 * implementation creates a child view for each
 * child element.
 * <p>
 * Normally a write-lock is held on the Document while
 * the children are being changed, which keeps the rendering
 * and layout threads safe. The exception to this is when
 * the view is initialized to represent an existing element
 * (via this method), so it is synchronized to exclude
 * preferenceChanged while we are initializing.
 *
 * @param f the view factory
 * @see #setParent
 */
protectedvoidloadChildren(ViewFactoryf) {
Elemente = getElement();
intn = e.getElementCount();
if (n > 0) {
View[] added = newView[n];
for (inti = 0; i < n; i++) {
added[i] = f.create(e.getElement(i));
 }
replace(0, 0, added);
 }
 }

/**
 * Fetches the child view index representing the given position in
 * the model. This is implemented to fetch the view in the case
 * where there is a child view for each child element.
 *
 * @param pos the position &gt;= 0
 * @param b the position bias
 * @return index of the view representing the given position, or
 * -1 if no view represents that position
 */
protectedsynchronizedintgetViewIndexAtPosition(intpos, Position.Biasb) {
booleanisBackward = (b == Position.Bias.Backward);
pos = (isBackward) ? Math.max(0, pos - 1) : pos;
Elementelem = getElement();
returnelem.getElementIndex(pos);
 }

/**
 * Update the layout in response to receiving notification of
 * change from the model. This is implemented to note the
 * change on the ChildLocator so that offsets of the children
 * will be correctly computed.
 *
 * @param ec changes to the element this view is responsible
 * for (may be null if there were no changes).
 * @param e the change information from the associated document
 * @param a the current allocation of the view
 * @see #insertUpdate
 * @see #removeUpdate
 * @see #changedUpdate
 */
protectedvoidupdateLayout(DocumentEvent.ElementChangeec,
DocumentEvente, Shapea) {
if (ec != null) {
// the newly inserted children don't have a valid
// offset so the child locator needs to be messaged
// that the child prior to the new children has
// changed size.
intindex = Math.max(ec.getIndex() - 1, 0);
ChildStatecs = getChildState(index);
locator.childChanged(cs);
 }
 }

// --- View methods ------------------------------------

/**
 * Sets the parent of the view.
 * This is reimplemented to provide the superclass
 * behavior as well as calling the <code>loadChildren</code>
 * method if this view does not already have children.
 * The children should not be loaded in the
 * constructor because the act of setting the parent
 * may cause them to try to search up the hierarchy
 * (to get the hosting Container for example).
 * If this view has children (the view is being moved
 * from one place in the view hierarchy to another),
 * the <code>loadChildren</code> method will not be called.
 *
 * @param parent the parent of the view, null if none
 */
publicvoidsetParent(Viewparent) {
super.setParent(parent);
if ((parent != null) && (getViewCount() == 0)) {
ViewFactoryf = getViewFactory();
loadChildren(f);
 }
 }

/**
 * Child views can call this on the parent to indicate that
 * the preference has changed and should be reconsidered
 * for layout. This is reimplemented to queue new work
 * on the layout thread. This method gets messaged from
 * multiple threads via the children.
 *
 * @param child the child view
 * @param width true if the width preference has changed
 * @param height true if the height preference has changed
 * @see javax.swing.JComponent#revalidate
 */
publicsynchronizedvoidpreferenceChanged(Viewchild, booleanwidth, booleanheight) {
if (child == null) {
getParent().preferenceChanged(this, width, height);
 } else {
if (changing != null) {
Viewcv = changing.getChildView();
if (cv == child) {
// size was being changed on the child, no need to
// queue work for it.
changing.preferenceChanged(width, height);
return;
 }
 }
intindex = getViewIndex(child.getStartOffset(),
Position.Bias.Forward);
ChildStatecs = getChildState(index);
cs.preferenceChanged(width, height);
LayoutQueueq = getLayoutQueue();
q.addTask(cs);
q.addTask(flushTask);
 }
 }

/**
 * Sets the size of the view. This should cause
 * layout of the view if the view caches any layout
 * information.
 * <p>
 * Since the major axis is updated asynchronously and should be
 * the sum of the tiled children the call is ignored for the major
 * axis. Since the minor axis is flexible, work is queued to resize
 * the children if the minor span changes.
 *
 * @param width the width &gt;= 0
 * @param height the height &gt;= 0
 */
publicvoidsetSize(floatwidth, floatheight) {
setSpanOnAxis(X_AXIS, width);
setSpanOnAxis(Y_AXIS, height);
 }

/**
 * Retrieves the size of the view along an axis.
 *
 * @param axis may be either <code>View.X_AXIS</code> or
 * <code>View.Y_AXIS</code>
 * @return the current span of the view along the given axis, >= 0
 */
floatgetSpanOnAxis(intaxis) {
if (axis == getMajorAxis()) {
returnmajorSpan;
 }
returnminorSpan;
 }

/**
 * Sets the size of the view along an axis. Since the major
 * axis is updated asynchronously and should be the sum of the
 * tiled children the call is ignored for the major axis. Since
 * the minor axis is flexible, work is queued to resize the
 * children if the minor span changes.
 *
 * @param axis may be either <code>View.X_AXIS</code> or
 * <code>View.Y_AXIS</code>
 * @param span the span to layout to >= 0
 */
voidsetSpanOnAxis(intaxis, floatspan) {
floatmargin = getInsetSpan(axis);
if (axis == getMinorAxis()) {
floattargetSpan = span - margin;
if (targetSpan != minorSpan) {
minorSpan = targetSpan;

// mark all of the ChildState instances as needing to
// resize the child, and queue up work to fix them.
intn = getViewCount();
if (n != 0) {
LayoutQueueq = getLayoutQueue();
for (inti = 0; i < n; i++) {
ChildStatecs = getChildState(i);
cs.childSizeValid = false;
q.addTask(cs);
 }
q.addTask(flushTask);
 }
 }
 } else {
// along the major axis the value is ignored
// unless the estimatedMajorSpan property is
// true.
if (estimatedMajorSpan) {
majorSpan = span - margin;
 }
 }
 }

/**
 * Render the view using the given allocation and
 * rendering surface.
 * <p>
 * This is implemented to determine whether or not the
 * desired region to be rendered (i.e. the unclipped
 * area) is up to date or not. If up-to-date the children
 * are rendered. If not up-to-date, a task to build
 * the desired area is placed on the layout queue as
 * a high priority task. This keeps by event thread
 * moving by rendering if ready, and postponing until
 * a later time if not ready (since paint requests
 * can be rescheduled).
 *
 * @param g the rendering surface to use
 * @param alloc the allocated region to render into
 * @see View#paint
 */
publicvoidpaint(Graphicsg, Shapealloc) {
synchronized (locator) {
locator.setAllocation(alloc);
locator.paintChildren(g);
 }
 }

/**
 * Determines the preferred span for this view along an
 * axis.
 *
 * @param axis may be either View.X_AXIS or View.Y_AXIS
 * @return the span the view would like to be rendered into &gt;= 0.
 * Typically the view is told to render into the span
 * that is returned, although there is no guarantee.
 * The parent may choose to resize or break the view.
 * @throws IllegalArgumentException for an invalid axis type
 */
publicfloatgetPreferredSpan(intaxis) {
floatmargin = getInsetSpan(axis);
if (axis == this.axis) {
returnmajorSpan + margin;
 }
if (prefRequest != null) {
Viewchild = prefRequest.getChildView();
returnchild.getPreferredSpan(axis) + margin;
 }

// nothing is known about the children yet
returnmargin + 30;
 }

/**
 * Determines the minimum span for this view along an
 * axis.
 *
 * @param axis may be either View.X_AXIS or View.Y_AXIS
 * @return the span the view would like to be rendered into &gt;= 0.
 * Typically the view is told to render into the span
 * that is returned, although there is no guarantee.
 * The parent may choose to resize or break the view.
 * @throws IllegalArgumentException for an invalid axis type
 */
publicfloatgetMinimumSpan(intaxis) {
if (axis == this.axis) {
returngetPreferredSpan(axis);
 }
if (minRequest != null) {
Viewchild = minRequest.getChildView();
returnchild.getMinimumSpan(axis);
 }

// nothing is known about the children yet
if (axis == X_AXIS) {
returngetLeftInset() + getRightInset() + 5;
 } else {
returngetTopInset() + getBottomInset() + 5;
 }
 }

/**
 * Determines the maximum span for this view along an
 * axis.
 *
 * @param axis may be either View.X_AXIS or View.Y_AXIS
 * @return the span the view would like to be rendered into &gt;= 0.
 * Typically the view is told to render into the span
 * that is returned, although there is no guarantee.
 * The parent may choose to resize or break the view.
 * @throws IllegalArgumentException for an invalid axis type
 */
publicfloatgetMaximumSpan(intaxis) {
if (axis == this.axis) {
returngetPreferredSpan(axis);
 }
returnInteger.MAX_VALUE;
 }


/**
 * Returns the number of views in this view. Since
 * the default is to not be a composite view this
 * returns 0.
 *
 * @return the number of views &gt;= 0
 * @see View#getViewCount
 */
publicintgetViewCount() {
synchronized(stats) {
returnstats.size();
 }
 }

/**
 * Gets the nth child view. Since there are no
 * children by default, this returns null.
 *
 * @param n the number of the view to get, &gt;= 0 &amp;&amp; &lt; getViewCount()
 * @return the view
 */
publicViewgetView(intn) {
ChildStatecs = getChildState(n);
if (cs != null) {
returncs.getChildView();
 }
returnnull;
 }

/**
 * Fetches the allocation for the given child view.
 * This enables finding out where various views
 * are located, without assuming the views store
 * their location. This returns null since the
 * default is to not have any child views.
 *
 * @param index the index of the child, &gt;= 0 &amp;&amp; &lt; getViewCount()
 * @param a the allocation to this view.
 * @return the allocation to the child
 */
publicShapegetChildAllocation(intindex, Shapea) {
Shapeca = locator.getChildAllocation(index, a);
returnca;
 }

/**
 * Returns the child view index representing the given position in
 * the model. By default a view has no children so this is implemented
 * to return -1 to indicate there is no valid child index for any
 * position.
 *
 * @param pos the position &gt;= 0
 * @return index of the view representing the given position, or
 * -1 if no view represents that position
 * @since 1.3
 */
publicintgetViewIndex(intpos, Position.Biasb) {
returngetViewIndexAtPosition(pos, b);
 }

/**
 * Provides a mapping from the document model coordinate space
 * to the coordinate space of the view mapped to it.
 *
 * @param pos the position to convert &gt;= 0
 * @param a the allocated region to render into
 * @param b the bias toward the previous character or the
 * next character represented by the offset, in case the
 * position is a boundary of two views.
 * @return the bounding box of the given position is returned
 * @throws BadLocationException if the given position does
 * not represent a valid location in the associated document
 * @throws IllegalArgumentException for an invalid bias argument
 * @see View#viewToModel
 */
publicShapemodelToView(intpos, Shapea, Position.Biasb) throwsBadLocationException {
intindex = getViewIndex(pos, b);
Shapeca = locator.getChildAllocation(index, a);

// forward to the child view, and make sure we don't
// interact with the layout thread by synchronizing
// on the child state.
ChildStatecs = getChildState(index);
synchronized (cs) {
Viewcv = cs.getChildView();
Shapev = cv.modelToView(pos, ca, b);
returnv;
 }
 }

/**
 * Provides a mapping from the view coordinate space to the logical
 * coordinate space of the model. The biasReturn argument will be
 * filled in to indicate that the point given is closer to the next
 * character in the model or the previous character in the model.
 * <p>
 * This is expected to be called by the GUI thread, holding a
 * read-lock on the associated model. It is implemented to
 * locate the child view and determine it's allocation with a
 * lock on the ChildLocator object, and to call viewToModel
 * on the child view with a lock on the ChildState object
 * to avoid interaction with the layout thread.
 *
 * @param x the X coordinate &gt;= 0
 * @param y the Y coordinate &gt;= 0
 * @param a the allocated region to render into
 * @return the location within the model that best represents the
 * given point in the view &gt;= 0. The biasReturn argument will be
 * filled in to indicate that the point given is closer to the next
 * character in the model or the previous character in the model.
 */
publicintviewToModel(floatx, floaty, Shapea, Position.Bias[] biasReturn) {
intpos; // return position
intindex; // child index to forward to
Shapeca; // child allocation

// locate the child view and it's allocation so that
// we can forward to it. Make sure the layout thread
// doesn't change anything by trying to flush changes
// to the parent while the GUI thread is trying to
// find the child and it's allocation.
synchronized (locator) {
index = locator.getViewIndexAtPoint(x, y, a);
ca = locator.getChildAllocation(index, a);
 }

// forward to the child view, and make sure we don't
// interact with the layout thread by synchronizing
// on the child state.
ChildStatecs = getChildState(index);
synchronized (cs) {
Viewv = cs.getChildView();
pos = v.viewToModel(x, y, ca, biasReturn);
 }
returnpos;
 }

/**
 * Provides a way to determine the next visually represented model
 * location that one might place a caret. Some views may not be visible,
 * they might not be in the same order found in the model, or they just
 * might not allow access to some of the locations in the model.
 * This method enables specifying a position to convert
 * within the range of &gt;=0. If the value is -1, a position
 * will be calculated automatically. If the value &lt; -1,
 * the {@code BadLocationException} will be thrown.
 *
 * @param pos the position to convert
 * @param a the allocated region to render into
 * @param direction the direction from the current position that can
 * be thought of as the arrow keys typically found on a keyboard;
 * this may be one of the following:
 * <ul style="list-style-type:none">
 * <li><code>SwingConstants.WEST</code></li>
 * <li><code>SwingConstants.EAST</code></li>
 * <li><code>SwingConstants.NORTH</code></li>
 * <li><code>SwingConstants.SOUTH</code></li>
 * </ul>
 * @param biasRet an array contain the bias that was checked
 * @return the location within the model that best represents the next
 * location visual position
 * @throws BadLocationException the given position is not a valid
 * position within the document
 * @throws IllegalArgumentException if <code>direction</code> is invalid
 */
publicintgetNextVisualPositionFrom(intpos, Position.Biasb, Shapea,
intdirection,
Position.Bias[] biasRet)
throwsBadLocationException {
if (pos < -1 || pos > getDocument().getLength()) {
thrownewBadLocationException("invalid position", pos);
 }
returnUtilities.getNextVisualPositionFrom(
this, pos, b, a, direction, biasRet);
 }

// --- variables -----------------------------------------

/**
 * The major axis against which the children are
 * tiled.
 */
intaxis;

/**
 * The children and their layout statistics.
 */
List<ChildState> stats;

/**
 * Current span along the major axis. This
 * is also the value returned by getMinimumSize,
 * getPreferredSize, and getMaximumSize along
 * the major axis.
 */
floatmajorSpan;

/**
 * Is the span along the major axis estimated?
 */
booleanestimatedMajorSpan;

/**
 * Current span along the minor axis. This
 * is what layout was done against (i.e. things
 * are flexible in this direction).
 */
floatminorSpan;

/**
 * Object that manages the offsets of the
 * children. All locking for management of
 * child locations is on this object.
 */
protectedChildLocatorlocator;

floattopInset;
floatbottomInset;
floatleftInset;
floatrightInset;

ChildStateminRequest;
ChildStateprefRequest;
booleanmajorChanged;
booleanminorChanged;
RunnableflushTask;

/**
 * Child that is actively changing size. This often
 * causes a preferenceChanged, so this is a cache to
 * possibly speed up the marking the state. It also
 * helps flag an opportunity to avoid adding to flush
 * task to the layout queue.
 */
ChildStatechanging;

/**
 * A class to manage the effective position of the
 * child views in a localized area while changes are
 * being made around the localized area. The AsyncBoxView
 * may be continuously changing, but the visible area
 * needs to remain fairly stable until the layout thread
 * decides to publish an update to the parent.
 * @since 1.3
 */
publicclassChildLocator {

/**
 * construct a child locator.
 */
publicChildLocator() {
lastAlloc = newRectangle();
childAlloc = newRectangle();
 }

/**
 * Notification that a child changed. This can effect
 * whether or not new offset calculations are needed.
 * This is called by a ChildState object that has
 * changed it's major span. This can therefore be
 * called by multiple threads.
 * @param cs the child state
 */
publicsynchronizedvoidchildChanged(ChildStatecs) {
if (lastValidOffset == null) {
lastValidOffset = cs;
 } elseif (cs.getChildView().getStartOffset() <
lastValidOffset.getChildView().getStartOffset()) {
lastValidOffset = cs;
 }
 }

/**
 * Paint the children that intersect the clip area.
 * @param g the rendering surface to use
 */
publicsynchronizedvoidpaintChildren(Graphicsg) {
Rectangleclip = g.getClipBounds();
floattargetOffset = (axis == X_AXIS) ?
clip.x - lastAlloc.x : clip.y - lastAlloc.y;
intindex = getViewIndexAtVisualOffset(targetOffset);
intn = getViewCount();
floatoffs = getChildState(index).getMajorOffset();
for (inti = index; i < n; i++) {
ChildStatecs = getChildState(i);
cs.setMajorOffset(offs);
Shapeca = getChildAllocation(i);
if (intersectsClip(ca, clip)) {
synchronized (cs) {
Viewv = cs.getChildView();
v.paint(g, ca);
 }
 } else {
// done painting intersection
break;