Java example source code file (AsyncBoxView.java)
The AsyncBoxView.java Java example source code/*
* Copyright (c) 1999, 2013, 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.
*/
package javax.swing.text;
import java.util.*;
import java.util.List;
import java.awt.*;
import javax.swing.SwingUtilities;
import javax.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
*/
public class AsyncBoxView extends View {
/**
* 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.
*/
public AsyncBoxView(Element elem, int axis) {
super(elem);
stats = new ArrayList<ChildState>();
this.axis = axis;
locator = new ChildLocator();
flushTask = new FlushTask();
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.
*/
public int getMajorAxis() {
return axis;
}
/**
* Fetch the minor axis (the axis orthogonal
* to the tiled axis). This will have a value of
* either X_AXIS or Y_AXIS.
*/
public int getMinorAxis() {
return (axis == X_AXIS) ? Y_AXIS : X_AXIS;
}
/**
* Get the top part of the margin around the view.
*/
public float getTopInset() {
return topInset;
}
/**
* Set the top part of the margin around the view.
*
* @param i the value of the inset
*/
public void setTopInset(float i) {
topInset = i;
}
/**
* Get the bottom part of the margin around the view.
*/
public float getBottomInset() {
return bottomInset;
}
/**
* Set the bottom part of the margin around the view.
*
* @param i the value of the inset
*/
public void setBottomInset(float i) {
bottomInset = i;
}
/**
* Get the left part of the margin around the view.
*/
public float getLeftInset() {
return leftInset;
}
/**
* Set the left part of the margin around the view.
*
* @param i the value of the inset
*/
public void setLeftInset(float i) {
leftInset = i;
}
/**
* Get the right part of the margin around the view.
*/
public float getRightInset() {
return rightInset;
}
/**
* Set the right part of the margin around the view.
*
* @param i the value of the inset
*/
public void setRightInset(float i) {
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.
* @since 1.4
*/
protected float getInsetSpan(int axis) {
float margin = (axis == X_AXIS) ?
getLeftInset() + getRightInset() : getTopInset() + getBottomInset();
return margin;
}
/**
* 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.
*
* @since 1.4
*/
protected void setEstimatedMajorSpan(boolean isEstimated) {
estimatedMajorSpan = isEstimated;
}
/**
* Is the major span currently estimated?
*
* @since 1.4
*/
protected boolean getEstimatedMajorSpan() {
return estimatedMajorSpan;
}
/**
* 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 >= 0 and < getViewCount().
*/
protected ChildState getChildState(int index) {
synchronized(stats) {
if ((index >= 0) && (index < stats.size())) {
return stats.get(index);
}
return null;
}
}
/**
* Fetch the queue to use for layout.
*/
protected LayoutQueue getLayoutQueue() {
return LayoutQueue.getDefaultQueue();
}
/**
* New ChildState records are created through
* this method to allow subclasses the extend
* the ChildState records to do/hold more
*/
protected ChildState createChildState(View v) {
return new ChildState(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.
*/
protected synchronized void majorRequirementChange(ChildState cs, float delta) {
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).
*/
protected synchronized void minorRequirementChange(ChildState cs) {
minorChanged = true;
}
/**
* Publish the changes in preferences upward to the parent
* view. This is normally called by the layout thread.
*/
protected void flushRequirementChanges() {
AbstractDocument doc = (AbstractDocument) getDocument();
try {
doc.readLock();
View parent = null;
boolean horizontal = false;
boolean vertical = false;
synchronized(this) {
// perform tasks that iterate over the children while
// preventing the collection from changing.
synchronized(stats) {
int n = getViewCount();
if ((n > 0) && (minorChanged || estimatedMajorSpan)) {
LayoutQueue q = getLayoutQueue();
ChildState min = getChildState(0);
ChildState pref = getChildState(0);
float span = 0f;
for (int i = 1; i < n; i++) {
ChildState cs = 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.
Component c = 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 >= 0
* @param length the number of existing views to replace >= 0
* @param views the child views to insert
*/
public void replace(int offset, int length, View[] views) {
synchronized(stats) {
// remove the replaced state records
for (int i = 0; i < length; i++) {
ChildState cs = stats.remove(offset);
float csSpan = cs.getMajorSpan();
cs.getChildView().setParent(null);
if (csSpan != 0) {
majorRequirementChange(cs, -csSpan);
}
}
// insert the state records for the new children
LayoutQueue q = getLayoutQueue();
if (views != null) {
for (int i = 0; i < views.length; i++) {
ChildState s = 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
*/
protected void loadChildren(ViewFactory f) {
Element e = getElement();
int n = e.getElementCount();
if (n > 0) {
View[] added = new View[n];
for (int i = 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 >= 0
* @return index of the view representing the given position, or
* -1 if no view represents that position
*/
protected synchronized int getViewIndexAtPosition(int pos, Position.Bias b) {
boolean isBackward = (b == Position.Bias.Backward);
pos = (isBackward) ? Math.max(0, pos - 1) : pos;
Element elem = getElement();
return elem.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
*/
protected void updateLayout(DocumentEvent.ElementChange ec,
DocumentEvent e, Shape a) {
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.
int index = Math.max(ec.getIndex() - 1, 0);
ChildState cs = 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
* 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 method will not be called.
*
* @param parent the parent of the view, null if none
*/
public void setParent(View parent) {
super.setParent(parent);
if ((parent != null) && (getViewCount() == 0)) {
ViewFactory f = 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
*/
public synchronized void preferenceChanged(View child, boolean width, boolean height) {
if (child == null) {
getParent().preferenceChanged(this, width, height);
} else {
if (changing != null) {
View cv = changing.getChildView();
if (cv == child) {
// size was being changed on the child, no need to
// queue work for it.
changing.preferenceChanged(width, height);
return;
}
}
int index = getViewIndex(child.getStartOffset(),
Position.Bias.Forward);
ChildState cs = getChildState(index);
cs.preferenceChanged(width, height);
LayoutQueue q = 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 >= 0
* @param height the height >= 0
*/
public void setSize(float width, float height) {
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 or
* <code>View.Y_AXIS
* @return the current span of the view along the given axis, >= 0
*/
float getSpanOnAxis(int axis) {
if (axis == getMajorAxis()) {
return majorSpan;
}
return minorSpan;
}
/**
* 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 or
* <code>View.Y_AXIS
* @param span the span to layout to >= 0
*/
void setSpanOnAxis(int axis, float span) {
float margin = getInsetSpan(axis);
if (axis == getMinorAxis()) {
float targetSpan = 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.
int n = getViewCount();
if (n != 0) {
LayoutQueue q = getLayoutQueue();
for (int i = 0; i < n; i++) {
ChildState cs = 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
*/
public void paint(Graphics g, Shape alloc) {
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 >= 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.
* @exception IllegalArgumentException for an invalid axis type
*/
public float getPreferredSpan(int axis) {
float margin = getInsetSpan(axis);
if (axis == this.axis) {
return majorSpan + margin;
}
if (prefRequest != null) {
View child = prefRequest.getChildView();
return child.getPreferredSpan(axis) + margin;
}
// nothing is known about the children yet
return margin + 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 >= 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.
* @exception IllegalArgumentException for an invalid axis type
*/
public float getMinimumSpan(int axis) {
if (axis == this.axis) {
return getPreferredSpan(axis);
}
if (minRequest != null) {
View child = minRequest.getChildView();
return child.getMinimumSpan(axis);
}
// nothing is known about the children yet
if (axis == X_AXIS) {
return getLeftInset() + getRightInset() + 5;
} else {
return getTopInset() + 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 >= 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.
* @exception IllegalArgumentException for an invalid axis type
*/
public float getMaximumSpan(int axis) {
if (axis == this.axis) {
return getPreferredSpan(axis);
}
return Integer.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 >= 0
* @see View#getViewCount
*/
public int getViewCount() {
synchronized(stats) {
return stats.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, >= 0 && < getViewCount()
* @return the view
*/
public View getView(int n) {
ChildState cs = getChildState(n);
if (cs != null) {
return cs.getChildView();
}
return null;
}
/**
* 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, >= 0 && < getViewCount()
* @param a the allocation to this view.
* @return the allocation to the child
*/
public Shape getChildAllocation(int index, Shape a) {
Shape ca = locator.getChildAllocation(index, a);
return ca;
}
/**
* 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 >= 0
* @return index of the view representing the given position, or
* -1 if no view represents that position
* @since 1.3
*/
public int getViewIndex(int pos, Position.Bias b) {
return getViewIndexAtPosition(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 >= 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
* @exception BadLocationException if the given position does
* not represent a valid location in the associated document
* @exception IllegalArgumentException for an invalid bias argument
* @see View#viewToModel
*/
public Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException {
int index = getViewIndex(pos, b);
Shape 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.
ChildState cs = getChildState(index);
synchronized (cs) {
View cv = cs.getChildView();
Shape v = cv.modelToView(pos, ca, b);
return v;
}
}
/**
* 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 >= 0
* @param y the Y coordinate >= 0
* @param a the allocated region to render into
* @return the location within the model that best represents the
* given point in the view >= 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.
*/
public int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn) {
int pos; // return position
int index; // child index to forward to
Shape ca; // 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.
ChildState cs = getChildState(index);
synchronized (cs) {
View v = cs.getChildView();
pos = v.viewToModel(x, y, ca, biasReturn);
}
return pos;
}
/**
* 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 >=0. If the value is -1, a position
* will be calculated automatically. If the value < -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>
Other Java examples (source code examples)Here is a short list of links related to this Java AsyncBoxView.java source code file: |
The search page
Other Java source code examples at this package level
Click here to learn more about this project
