< prev index next >
src/java.desktop/share/classes/javax/swing/text/View.java
Print this page
*** 28,47 ****
import javax.swing.SwingConstants;
import javax.swing.event.*;
/**
* <p>
! * A very important part of the text package is the <code>View</code> class.
* As the name suggests it represents a view of the text model,
* or a piece of the text model.
* It is this class that is responsible for the look of the text component.
* The view is not intended to be some completely new thing that one must
* learn, but rather is much like a lightweight component.
* <p>
By default, a view is very light. It contains a reference to the parent
view from which it can fetch many things without holding state, and it
! contains a reference to a portion of the model (<code>Element</code>).
A view does not
have to exactly represent an element in the model, that is simply a typical
and therefore convenient mapping. A view can alternatively maintain a couple
of Position objects to maintain its location in the model (i.e. represent
a fragment of an element). This is typically the result of formatting where
--- 28,47 ----
import javax.swing.SwingConstants;
import javax.swing.event.*;
/**
* <p>
! * A very important part of the text package is the {@code View} class.
* As the name suggests it represents a view of the text model,
* or a piece of the text model.
* It is this class that is responsible for the look of the text component.
* The view is not intended to be some completely new thing that one must
* learn, but rather is much like a lightweight component.
* <p>
By default, a view is very light. It contains a reference to the parent
view from which it can fetch many things without holding state, and it
! contains a reference to a portion of the model ({@code Element}).
A view does not
have to exactly represent an element in the model, that is simply a typical
and therefore convenient mapping. A view can alternatively maintain a couple
of Position objects to maintain its location in the model (i.e. represent
a fragment of an element). This is typically the result of formatting where
*** 54,67 ****
A view has the following responsibilities:
<dl>
<dt><b>Participate in layout.</b>
<dd>
! <p>The view has a <code>setSize</code> method which is like
! <code>doLayout</code> and <code>setSize</code> in <code>Component</code> combined.
! The view has a <code>preferenceChanged</code> method which is
! like <code>invalidate</code> in <code>Component</code> except that one can
invalidate just one axis
and the child requesting the change is identified.
<p>A View expresses the size that it would like to be in terms of three
values, a minimum, a preferred, and a maximum span. Layout in a view is
can be done independently upon each axis. For a properly functioning View
--- 54,67 ----
A view has the following responsibilities:
<dl>
<dt><b>Participate in layout.</b>
<dd>
! <p>The view has a {@code setSize} method which is like
! {@code doLayout} and {@code setSize} in {@code Component} combined.
! The view has a {@code preferenceChanged} method which is
! like {@code invalidate} in {@code Component} except that one can
invalidate just one axis
and the child requesting the change is identified.
<p>A View expresses the size that it would like to be in terms of three
values, a minimum, a preferred, and a maximum span. Layout in a view is
can be done independently upon each axis. For a properly functioning View
*** 78,98 ****
<li>{@link #getAlignment(int) getAlignment}
<li>{@link #preferenceChanged(javax.swing.text.View, boolean, boolean) preferenceChanged}
<li>{@link #setSize(float, float) setSize}
</ul>
! <p>The <code>setSize</code> method should be prepared to be called a number of times
(i.e. It may be called even if the size didn't change).
! The <code>setSize</code> method
is generally called to make sure the View layout is complete prior to trying
to perform an operation on it that requires an up-to-date layout. A view's
size should <em>always</em> be set to a value within the minimum and maximum
span specified by that view. Additionally, the view must always call the
! <code>preferenceChanged</code> method on the parent if it has changed the
values for the
layout it would like, and expects the parent to honor. The parent View is
! not required to recognize a change until the <code>preferenceChanged</code>
has been sent.
This allows parent View implementations to cache the child requirements if
desired. The calling sequence looks something like the following:
</p>
<p style="text-align:center">
--- 78,98 ----
<li>{@link #getAlignment(int) getAlignment}
<li>{@link #preferenceChanged(javax.swing.text.View, boolean, boolean) preferenceChanged}
<li>{@link #setSize(float, float) setSize}
</ul>
! <p>The {@code setSize} method should be prepared to be called a number of times
(i.e. It may be called even if the size didn't change).
! The {@code setSize} method
is generally called to make sure the View layout is complete prior to trying
to perform an operation on it that requires an up-to-date layout. A view's
size should <em>always</em> be set to a value within the minimum and maximum
span specified by that view. Additionally, the view must always call the
! {@code preferenceChanged} method on the parent if it has changed the
values for the
layout it would like, and expects the parent to honor. The parent View is
! not required to recognize a change until the {@code preferenceChanged}
has been sent.
This allows parent View implementations to cache the child requirements if
desired. The calling sequence looks something like the following:
</p>
<p style="text-align:center">
*** 107,137 ****
<dt><b>Render a portion of the model.</b>
<dd>
<p>This is done in the paint method, which is pretty much like a component
paint method. Views are expected to potentially populate a fairly large
! tree. A <code>View</code> has the following semantics for rendering:
</p>
<ul>
<li>The view gets its allocation from the parent at paint time, so it
must be prepared to redo layout if the allocated area is different from
what it is prepared to deal with.
! <li>The coordinate system is the same as the hosting <code>Component</code>
! (i.e. the <code>Component</code> returned by the
{@link #getContainer getContainer} method).
This means a child view lives in the same coordinate system as the parent
view unless the parent has explicitly changed the coordinate system.
To schedule itself to be repainted a view can call repaint on the hosting
! <code>Component</code>.
<li>The default is to <em>not clip</em> the children. It is more efficient
to allow a view to clip only if it really feels it needs clipping.
! <li>The <code>Graphics</code> object given is not initialized in any way.
A view should set any settings needed.
! <li>A <code>View</code> is inherently transparent. While a view may render into its
entire allocation, typically a view does not. Rendering is performed by
! traversing down the tree of <code>View</code> implementations.
! Each <code>View</code> is responsible
for rendering its children. This behavior is depended upon for thread
safety. While view implementations do not necessarily have to be implemented
with thread safety in mind, other view implementations that do make use of
concurrency can depend upon a tree traversal to guarantee thread safety.
<li>The order of views relative to the model is up to the implementation.
--- 107,137 ----
<dt><b>Render a portion of the model.</b>
<dd>
<p>This is done in the paint method, which is pretty much like a component
paint method. Views are expected to potentially populate a fairly large
! tree. A {@code View} has the following semantics for rendering:
</p>
<ul>
<li>The view gets its allocation from the parent at paint time, so it
must be prepared to redo layout if the allocated area is different from
what it is prepared to deal with.
! <li>The coordinate system is the same as the hosting {@code Component}
! (i.e. the {@code Component} returned by the
{@link #getContainer getContainer} method).
This means a child view lives in the same coordinate system as the parent
view unless the parent has explicitly changed the coordinate system.
To schedule itself to be repainted a view can call repaint on the hosting
! {@code Component}.
<li>The default is to <em>not clip</em> the children. It is more efficient
to allow a view to clip only if it really feels it needs clipping.
! <li>The {@code Graphics} object given is not initialized in any way.
A view should set any settings needed.
! <li>A {@code View} is inherently transparent. While a view may render into its
entire allocation, typically a view does not. Rendering is performed by
! traversing down the tree of {@code View} implementations.
! Each {@code View} is responsible
for rendering its children. This behavior is depended upon for thread
safety. While view implementations do not necessarily have to be implemented
with thread safety in mind, other view implementations that do make use of
concurrency can depend upon a tree traversal to guarantee thread safety.
<li>The order of views relative to the model is up to the implementation.
*** 159,176 ****
<li>{@link #getStartOffset() getStartOffset}
<li>{@link #getEndOffset() getEndOffset}
</ul>
<p>The layout must be valid prior to attempting to make the translation.
The translation is not valid, and must not be attempted while changes
! are being broadcasted from the model via a <code>DocumentEvent</code>.
</p>
<dt><b>Respond to changes from the model.</b>
<dd>
<p>If the overall view is represented by many pieces (which is the best situation
if one want to be able to change the view and write the least amount of new code),
! it would be impractical to have a huge number of <code>DocumentListener</code>s.
If each
view listened to the model, only a few would actually be interested in the
changes broadcasted at any given time. Since the model has no knowledge of
views, it has no way to filter the broadcast of change information. The view
hierarchy itself is instead responsible for propagating the change information.
--- 159,176 ----
<li>{@link #getStartOffset() getStartOffset}
<li>{@link #getEndOffset() getEndOffset}
</ul>
<p>The layout must be valid prior to attempting to make the translation.
The translation is not valid, and must not be attempted while changes
! are being broadcasted from the model via a {@code DocumentEvent}.
</p>
<dt><b>Respond to changes from the model.</b>
<dd>
<p>If the overall view is represented by many pieces (which is the best situation
if one want to be able to change the view and write the least amount of new code),
! it would be impractical to have a huge number of {@code DocumentListener}s.
If each
view listened to the model, only a few would actually be interested in the
changes broadcasted at any given time. Since the model has no knowledge of
views, it has no way to filter the broadcast of change information. The view
hierarchy itself is instead responsible for propagating the change information.
*** 188,209 ****
* @author Timothy Prinzing
*/
public abstract class View implements SwingConstants {
/**
! * Creates a new <code>View</code> object.
*
! * @param elem the <code>Element</code> to represent
*/
public View(Element elem) {
this.elem = elem;
}
/**
* Returns the parent of the view.
*
! * @return the parent, or <code>null</code> if none exists
*/
public View getParent() {
return parent;
}
--- 188,209 ----
* @author Timothy Prinzing
*/
public abstract class View implements SwingConstants {
/**
! * Creates a new {@code View} object.
*
! * @param elem the {@code Element} to represent
*/
public View(Element elem) {
this.elem = elem;
}
/**
* Returns the parent of the view.
*
! * @return the parent, or {@code null} if none exists
*/
public View getParent() {
return parent;
}
*** 221,232 ****
/**
* Determines the preferred span for this view along an
* axis.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @return the span the view would like to be rendered into.
* 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
* @see View#getPreferredSpan
--- 221,232 ----
/**
* Determines the preferred span for this view along an
* axis.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @return the span the view would like to be rendered into.
* 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
* @see View#getPreferredSpan
*** 235,246 ****
/**
* Determines the minimum span for this view along an
* axis.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @return the minimum span the view can be rendered into
* @see View#getPreferredSpan
*/
public float getMinimumSpan(int axis) {
int w = getResizeWeight(axis);
--- 235,246 ----
/**
* Determines the minimum span for this view along an
* axis.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @return the minimum span the view can be rendered into
* @see View#getPreferredSpan
*/
public float getMinimumSpan(int axis) {
int w = getResizeWeight(axis);
*** 253,264 ****
/**
* Determines the maximum span for this view along an
* axis.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @return the maximum span the view can be rendered into
* @see View#getPreferredSpan
*/
public float getMaximumSpan(int axis) {
int w = getResizeWeight(axis);
--- 253,264 ----
/**
* Determines the maximum span for this view along an
* axis.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @return the maximum span the view can be rendered into
* @see View#getPreferredSpan
*/
public float getMaximumSpan(int axis) {
int w = getResizeWeight(axis);
*** 272,282 ****
/**
* Child views can call this on the parent to indicate that
* the preference has changed and should be reconsidered
* for layout. By default this just propagates upward to
* the next parent. The root view will call
! * <code>revalidate</code> on the associated text component.
*
* @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
--- 272,282 ----
/**
* Child views can call this on the parent to indicate that
* the preference has changed and should be reconsidered
* for layout. By default this just propagates upward to
* the next parent. The root view will call
! * {@code revalidate} on the associated text component.
*
* @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
*** 294,305 ****
* a value >= 0.0 and <= 1.0, where 0 indicates alignment at
* the origin and 1.0 indicates alignment to the full span
* away from the origin. An alignment of 0.5 would be the
* center of the view.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @return the value 0.5
*/
public float getAlignment(int axis) {
return 0.5f;
}
--- 294,305 ----
* a value >= 0.0 and <= 1.0, where 0 indicates alignment at
* the origin and 1.0 indicates alignment to the full span
* away from the origin. An alignment of 0.5 would be the
* center of the view.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @return the value 0.5
*/
public float getAlignment(int axis) {
return 0.5f;
}
*** 322,335 ****
* the view has been removed from the hierarchy as
* well. When this method is called to set the parent to
* null, this method does the same for each of its children,
* propagating the notification that they have been
* disconnected from the view tree. If this is
! * reimplemented, <code>super.setParent()</code> should
* be called.
*
! * @param parent the new parent, or <code>null</code> if the view is
* being removed from a parent
*/
public void setParent(View parent) {
// if the parent is null then propogate down the view tree
if (parent == null) {
--- 322,335 ----
* the view has been removed from the hierarchy as
* well. When this method is called to set the parent to
* null, this method does the same for each of its children,
* propagating the notification that they have been
* disconnected from the view tree. If this is
! * reimplemented, {@code super.setParent()} should
* be called.
*
! * @param parent the new parent, or {@code null} if the view is
* being removed from a parent
*/
public void setParent(View parent) {
// if the parent is null then propogate down the view tree
if (parent == null) {
*** 356,366 ****
return 0;
}
/**
* Gets the <i>n</i>th child view. Since there are no
! * children by default, this returns <code>null</code>.
*
* @param n the number of the view to get, >= 0 && < getViewCount()
* @return the view
*/
public View getView(int n) {
--- 356,366 ----
return 0;
}
/**
* Gets the <i>n</i>th child view. Since there are no
! * children by default, this returns {@code null}.
*
* @param n the number of the view to get, >= 0 && < getViewCount()
* @return the view
*/
public View getView(int n) {
*** 368,398 ****
}
/**
* Removes all of the children. This is a convenience
! * call to <code>replace</code>.
*
* @since 1.3
*/
public void removeAll() {
replace(0, getViewCount(), null);
}
/**
* Removes one of the children at the given position.
! * This is a convenience call to <code>replace</code>.
* @param i the position
* @since 1.3
*/
public void remove(int i) {
replace(i, 1, null);
}
/**
* Inserts a single child view. This is a convenience
! * call to <code>replace</code>.
*
* @param offs the offset of the view to insert before >= 0
* @param v the view
* @see #replace
* @since 1.3
--- 368,398 ----
}
/**
* Removes all of the children. This is a convenience
! * call to {@code replace}.
*
* @since 1.3
*/
public void removeAll() {
replace(0, getViewCount(), null);
}
/**
* Removes one of the children at the given position.
! * This is a convenience call to {@code replace}.
* @param i the position
* @since 1.3
*/
public void remove(int i) {
replace(i, 1, null);
}
/**
* Inserts a single child view. This is a convenience
! * call to {@code replace}.
*
* @param offs the offset of the view to insert before >= 0
* @param v the view
* @see #replace
* @since 1.3
*** 403,413 ****
replace(offs, 0, one);
}
/**
* Appends a single child view. This is a convenience
! * call to <code>replace</code>.
*
* @param v the view
* @see #replace
* @since 1.3
*/
--- 403,413 ----
replace(offs, 0, one);
}
/**
* Appends a single child view. This is a convenience
! * call to {@code replace}.
*
* @param v the view
* @see #replace
* @since 1.3
*/
*** 419,439 ****
/**
* Replaces child views. If there are no views to remove
* this acts as an insert. If there are no views to
* add this acts as a remove. Views being removed will
! * have the parent set to <code>null</code>, and the internal reference
* to them removed so that they can be garbage collected.
* This is implemented to do nothing, because by default
* a view has no children.
*
* @param offset the starting index into the child views to insert
* the new views. This should be a value >= 0 and <= getViewCount
* @param length the number of existing child views to remove
* This should be a value >= 0 and <= (getViewCount() - offset).
* @param views the child views to add. This value can be
! * <code>null</code> to indicate no children are being added
* (useful to remove).
* @since 1.3
*/
public void replace(int offset, int length, View[] views) {
}
--- 419,439 ----
/**
* Replaces child views. If there are no views to remove
* this acts as an insert. If there are no views to
* add this acts as a remove. Views being removed will
! * have the parent set to {@code null}, and the internal reference
* to them removed so that they can be garbage collected.
* This is implemented to do nothing, because by default
* a view has no children.
*
* @param offset the starting index into the child views to insert
* the new views. This should be a value >= 0 and <= getViewCount
* @param length the number of existing child views to remove
* This should be a value >= 0 and <= (getViewCount() - offset).
* @param views the child views to add. This value can be
! * {@code null} to indicate no children are being added
* (useful to remove).
* @since 1.3
*/
public void replace(int offset, int length, View[] views) {
}
*** 456,470 ****
/**
* Fetches the allocation for the given child view.
* This enables finding out where various views
* are located, without assuming how the views store
! * their location. This returns <code>null</code> since the
* default is to not have any child views.
*
* @param index the index of the child, >= 0 && <
! * <code>getViewCount()</code>
* @param a the allocation to this view
* @return the allocation to the child
*/
public Shape getChildAllocation(int index, Shape a) {
return null;
--- 456,470 ----
/**
* Fetches the allocation for the given child view.
* This enables finding out where various views
* are located, without assuming how the views store
! * their location. This returns {@code null} since the
* default is to not have any child views.
*
* @param index the index of the child, >= 0 && <
! * {@code getViewCount()}
* @param a the allocation to this view
* @return the allocation to the child
*/
public Shape getChildAllocation(int index, Shape a) {
return null;
*** 496,506 ****
* @param biasRet the returned bias
* @return the location within the model that best represents the next
* location visual position
* @exception BadLocationException the given position is not a valid
* position within the document
! * @exception IllegalArgumentException if <code>direction</code>
* doesn't have one of the legal values above
*/
public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,
int direction, Position.Bias[] biasRet)
throws BadLocationException {
--- 496,506 ----
* @param biasRet the returned bias
* @return the location within the model that best represents the next
* location visual position
* @exception BadLocationException the given position is not a valid
* position within the document
! * @exception IllegalArgumentException if {@code direction}
* doesn't have one of the legal values above
*/
public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a,
int direction, Position.Bias[] biasRet)
throws BadLocationException {
*** 575,596 ****
*
* @param pos the position of the desired character (>=0)
* @param a the area of the view, which encompasses the requested character
* @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; <code>b</code> will have one
* of these values:
* <ul>
! * <li> <code>Position.Bias.Forward</code>
! * <li> <code>Position.Bias.Backward</code>
* </ul>
* @return the bounding box, in view coordinate space,
* of the character at the specified position
* @exception BadLocationException if the specified position does
* not represent a valid location in the associated document
! * @exception IllegalArgumentException if <code>b</code> is not one of the
! * legal <code>Position.Bias</code> values listed above
* @see View#viewToModel
*/
public abstract Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException;
/**
--- 575,596 ----
*
* @param pos the position of the desired character (>=0)
* @param a the area of the view, which encompasses the requested character
* @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; {@code b} will have one
* of these values:
* <ul>
! * <li> {@code Position.Bias.Forward}
! * <li> {@code Position.Bias.Backward}
* </ul>
* @return the bounding box, in view coordinate space,
* of the character at the specified position
* @exception BadLocationException if the specified position does
* not represent a valid location in the associated document
! * @exception IllegalArgumentException if {@code b} is not one of the
! * legal {@code Position.Bias} values listed above
* @see View#viewToModel
*/
public abstract Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException;
/**
*** 601,627 ****
*
* @param p0 the position of the first character (>=0)
* @param b0 the bias of the first character position,
* toward the previous character or the
* next character represented by the offset, in case the
! * position is a boundary of two views; <code>b0</code> will have one
* of these values:
* <ul style="list-style-type:none">
! * <li> <code>Position.Bias.Forward</code>
! * <li> <code>Position.Bias.Backward</code>
* </ul>
* @param p1 the position of the last character (>=0)
* @param b1 the bias for the second character position, defined
* one of the legal values shown above
* @param a the area of the view, which encompasses the requested region
* @return the bounding box which is a union of the region specified
* by the first and last character positions
* @exception BadLocationException if the given position does
* not represent a valid location in the associated document
! * @exception IllegalArgumentException if <code>b0</code> or
! * <code>b1</code> are not one of the
! * legal <code>Position.Bias</code> values listed above
* @see View#viewToModel
*/
public Shape modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) throws BadLocationException {
Shape s0 = modelToView(p0, a, b0);
Shape s1;
--- 601,627 ----
*
* @param p0 the position of the first character (>=0)
* @param b0 the bias of the first character position,
* toward the previous character or the
* next character represented by the offset, in case the
! * position is a boundary of two views; {@code b0} will have one
* of these values:
* <ul style="list-style-type:none">
! * <li> {@code Position.Bias.Forward}
! * <li> {@code Position.Bias.Backward}
* </ul>
* @param p1 the position of the last character (>=0)
* @param b1 the bias for the second character position, defined
* one of the legal values shown above
* @param a the area of the view, which encompasses the requested region
* @return the bounding box which is a union of the region specified
* by the first and last character positions
* @exception BadLocationException if the given position does
* not represent a valid location in the associated document
! * @exception IllegalArgumentException if {@code b0} or
! * {@code b1} are not one of the
! * legal {@code Position.Bias} values listed above
* @see View#viewToModel
*/
public Shape modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) throws BadLocationException {
Shape s0 = modelToView(p0, a, b0);
Shape s1;
*** 656,676 ****
return r0;
}
/**
* Provides a mapping from the view coordinate space to the logical
! * coordinate space of the model. The <code>biasReturn</code>
* 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.
*
* @param x the X coordinate >= 0
* @param y the Y coordinate >= 0
* @param a the allocated region in which to render
* @param biasReturn the returned bias
* @return the location within the model that best represents the
! * given point in the view >= 0. The <code>biasReturn</code>
* 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 abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn);
--- 656,676 ----
return r0;
}
/**
* Provides a mapping from the view coordinate space to the logical
! * coordinate space of the model. The {@code 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.
*
* @param x the X coordinate >= 0
* @param y the Y coordinate >= 0
* @param a the allocated region in which to render
* @param biasReturn the returned bias
* @return the location within the model that best represents the
! * given point in the view >= 0. The {@code 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 abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn);
*** 799,809 ****
}
/**
* Fetches the model associated with the view.
*
! * @return the view model, <code>null</code> if none
* @see View#getDocument
*/
public Document getDocument() {
return elem.getDocument();
}
--- 799,809 ----
}
/**
* Fetches the model associated with the view.
*
! * @return the view model, {@code null} if none
* @see View#getDocument
*/
public Document getDocument() {
return elem.getDocument();
}
*** 841,856 ****
public Element getElement() {
return elem;
}
/**
! * Fetch a <code>Graphics</code> for rendering.
* This can be used to determine
* font characteristics, and will be different for a print view
* than a component view.
*
! * @return a <code>Graphics</code> object for rendering
* @since 1.3
*/
public Graphics getGraphics() {
// PENDING(prinz) this is a temporary implementation
Component c = getContainer();
--- 841,856 ----
public Element getElement() {
return elem;
}
/**
! * Fetch a {@code Graphics} for rendering.
* This can be used to determine
* font characteristics, and will be different for a print view
* than a component view.
*
! * @return a {@code Graphics} object for rendering
* @since 1.3
*/
public Graphics getGraphics() {
// PENDING(prinz) this is a temporary implementation
Component c = getContainer();
*** 865,875 ****
* view-specific attributes to be mixed in or to allow the
* view to have view-specific conversion of attributes by
* subclasses.
* Each view should document what attributes it recognizes
* for the purpose of rendering or layout, and should always
! * access them through the <code>AttributeSet</code> returned
* by this method.
* @return the attributes to use when rendering
*/
public AttributeSet getAttributes() {
return elem.getAttributes();
--- 865,875 ----
* view-specific attributes to be mixed in or to allow the
* view to have view-specific conversion of attributes by
* subclasses.
* Each view should document what attributes it recognizes
* for the purpose of rendering or layout, and should always
! * access them through the {@code AttributeSet} returned
* by this method.
* @return the attributes to use when rendering
*/
public AttributeSet getAttributes() {
return elem.getAttributes();
*** 888,899 ****
* breakable. If the view does support breaking, the
* starting offset of the view returned should be the
* given offset, and the end offset should be less than
* or equal to the end offset of the view being broken.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @param offset the location in the document model
* that a broken fragment would occupy >= 0. This
* would be the starting offset of the fragment
* returned
* @param pos the position along the axis that the
--- 888,899 ----
* breakable. If the view does support breaking, the
* starting offset of the view returned should be the
* given offset, and the end offset should be less than
* or equal to the end offset of the view being broken.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @param offset the location in the document model
* that a broken fragment would occupy >= 0. This
* would be the starting offset of the fragment
* returned
* @param pos the position along the axis that the
*** 933,964 ****
}
/**
* Determines how attractive a break opportunity in
* this view is. This can be used for determining which
! * view is the most attractive to call <code>breakView</code>
* on in the process of formatting. A view that represents
* text that has whitespace in it might be more attractive
* than a view that has no whitespace, for example. The
* higher the weight, the more attractive the break. A
! * value equal to or lower than <code>BadBreakWeight</code>
* should not be considered for a break. A value greater
! * than or equal to <code>ForcedBreakWeight</code> should
* be broken.
* <p>
* This is implemented to provide the default behavior
! * of returning <code>BadBreakWeight</code> unless the length
* is greater than the length of the view in which case the
* entire view represents the fragment. Unless a view has
* been written to support breaking behavior, it is not
* attractive to try and break the view. An example of
! * a view that does support breaking is <code>LabelView</code>.
* An example of a view that uses break weight is
! * <code>ParagraphView</code>.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @param pos the potential location of the start of the
* broken view >= 0. This may be useful for calculating tab
* positions
* @param len specifies the relative length from <em>pos</em>
* where a potential break is desired >= 0
--- 933,964 ----
}
/**
* Determines how attractive a break opportunity in
* this view is. This can be used for determining which
! * view is the most attractive to call {@code breakView}
* on in the process of formatting. A view that represents
* text that has whitespace in it might be more attractive
* than a view that has no whitespace, for example. The
* higher the weight, the more attractive the break. A
! * value equal to or lower than {@code BadBreakWeight}
* should not be considered for a break. A value greater
! * than or equal to {@code ForcedBreakWeight} should
* be broken.
* <p>
* This is implemented to provide the default behavior
! * of returning {@code BadBreakWeight} unless the length
* is greater than the length of the view in which case the
* entire view represents the fragment. Unless a view has
* been written to support breaking behavior, it is not
* attractive to try and break the view. An example of
! * a view that does support breaking is {@code LabelView}.
* An example of a view that uses break weight is
! * {@code ParagraphView}.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @param pos the potential location of the start of the
* broken view >= 0. This may be useful for calculating tab
* positions
* @param len specifies the relative length from <em>pos</em>
* where a potential break is desired >= 0
*** 980,991 ****
/**
* Determines the resizability of the view along the
* given axis. A value of 0 or less is not resizable.
*
! * @param axis may be either <code>View.X_AXIS</code> or
! * <code>View.Y_AXIS</code>
* @return the weight
*/
public int getResizeWeight(int axis) {
return 0;
}
--- 980,991 ----
/**
* Determines the resizability of the view along the
* given axis. A value of 0 or less is not resizable.
*
! * @param axis may be either {@code View.X_AXIS} or
! * {@code View.Y_AXIS}
* @return the weight
*/
public int getResizeWeight(int axis) {
return 0;
}
*** 1005,1029 ****
* Fetches the container hosting the view. This is useful for
* things like scheduling a repaint, finding out the host
* components font, etc. The default implementation
* of this is to forward the query to the parent view.
*
! * @return the container, <code>null</code> if none
*/
public Container getContainer() {
View v = getParent();
return (v != null) ? v.getContainer() : null;
}
/**
! * Fetches the <code>ViewFactory</code> implementation that is feeding
* the view hierarchy. Normally the views are given this
* as an argument to updates from the model when they
* are most likely to need the factory, but this
* method serves to provide it at other times.
*
! * @return the factory, <code>null</code> if none
*/
public ViewFactory getViewFactory() {
View v = getParent();
return (v != null) ? v.getViewFactory() : null;
}
--- 1005,1029 ----
* Fetches the container hosting the view. This is useful for
* things like scheduling a repaint, finding out the host
* components font, etc. The default implementation
* of this is to forward the query to the parent view.
*
! * @return the container, {@code null} if none
*/
public Container getContainer() {
View v = getParent();
return (v != null) ? v.getContainer() : null;
}
/**
! * Fetches the {@code ViewFactory} implementation that is feeding
* the view hierarchy. Normally the views are given this
* as an argument to updates from the model when they
* are most likely to need the factory, but this
* method serves to provide it at other times.
*
! * @return the factory, {@code null} if none
*/
public ViewFactory getViewFactory() {
View v = getParent();
return (v != null) ? v.getViewFactory() : null;
}
*** 1054,1064 ****
}
/**
* Returns the child view index representing the given position in
* the view. This iterates over all the children returning the
! * first with a bounds that contains <code>x</code>, <code>y</code>.
*
* @param x the x coordinate
* @param y the y coordinate
* @param allocation current allocation of the View.
* @return index of the view representing the given location, or
--- 1054,1064 ----
}
/**
* Returns the child view index representing the given position in
* the view. This iterates over all the children returning the
! * first with a bounds that contains {@code x}, {@code y}.
*
* @param x the x coordinate
* @param y the y coordinate
* @param allocation current allocation of the View.
* @return index of the view representing the given location, or
*** 1085,1102 ****
* Updates the child views in response to receiving notification
* that the model changed, and there is change record for the
* element this view is responsible for. This is implemented
* to assume the child views are directly responsible for the
* child elements of the element this view represents. The
! * <code>ViewFactory</code> is used to create child views for each element
! * specified as added in the <code>ElementChange</code>, starting at the
! * index specified in the given <code>ElementChange</code>. The number of
* child views representing the removed elements specified are
* removed.
*
* @param ec the change information for the element this view
! * is responsible for. This should not be <code>null</code> if
* this method gets called
* @param e the change information from the associated document
* @param f the factory to use to build child views
* @return whether or not the child views represent the
* child elements of the element this view is responsible
--- 1085,1102 ----
* Updates the child views in response to receiving notification
* that the model changed, and there is change record for the
* element this view is responsible for. This is implemented
* to assume the child views are directly responsible for the
* child elements of the element this view represents. The
! * {@code ViewFactory} is used to create child views for each element
! * specified as added in the {@code ElementChange}, starting at the
! * index specified in the given {@code ElementChange}. The number of
* child views representing the removed elements specified are
* removed.
*
* @param ec the change information for the element this view
! * is responsible for. This should not be {@code null} if
* this method gets called
* @param e the change information from the associated document
* @param f the factory to use to build child views
* @return whether or not the child views represent the
* child elements of the element this view is responsible
*** 1129,1147 ****
replace(index, nremoved, added);
return true;
}
/**
! * Forwards the given <code>DocumentEvent</code> to the child views
* that need to be notified of the change to the model.
* If there were changes to the element this view is
* responsible for, that should be considered when
* forwarding (i.e. new child views should not get
* notified).
*
* @param ec changes to the element this view is responsible
! * for (may be <code>null</code> if there were no changes).
* @param e the change information from the associated document
* @param a the current allocation of the view
* @param f the factory to use to rebuild if the view has children
* @see #insertUpdate
* @see #removeUpdate
--- 1129,1147 ----
replace(index, nremoved, added);
return true;
}
/**
! * Forwards the given {@code DocumentEvent} to the child views
* that need to be notified of the change to the model.
* If there were changes to the element this view is
* responsible for, that should be considered when
* forwarding (i.e. new child views should not get
* notified).
*
* @param ec changes to the element this view is responsible
! * for (may be {@code null} if there were no changes).
* @param e the change information from the associated document
* @param a the current allocation of the view
* @param f the factory to use to rebuild if the view has children
* @see #insertUpdate
* @see #removeUpdate
*** 1213,1225 ****
void updateAfterChange() {
// Do nothing by default. Should be overridden in subclasses, if any.
}
/**
! * Forwards the <code>DocumentEvent</code> to the give child view. This
! * simply messages the view with a call to <code>insertUpdate</code>,
! * <code>removeUpdate</code>, or <code>changedUpdate</code> depending
* upon the type of the event. This is called by
* {@link #forwardUpdate forwardUpdate} to forward
* the event to children that need it.
*
* @param v the child view to forward the event to
--- 1213,1225 ----
void updateAfterChange() {
// Do nothing by default. Should be overridden in subclasses, if any.
}
/**
! * Forwards the {@code DocumentEvent} to the give child view. This
! * simply messages the view with a call to {@code insertUpdate},
! * {@code removeUpdate}, or {@code changedUpdate} depending
* upon the type of the event. This is called by
* {@link #forwardUpdate forwardUpdate} to forward
* the event to children that need it.
*
* @param v the child view to forward the event to
*** 1242,1256 ****
}
/**
* Updates the layout in response to receiving notification of
* change from the model. This is implemented to call
! * <code>preferenceChanged</code> to reschedule a new layout
! * if the <code>ElementChange</code> record is not <code>null</code>.
*
* @param ec changes to the element this view is responsible
! * for (may be <code>null</code> 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
--- 1242,1256 ----
}
/**
* Updates the layout in response to receiving notification of
* change from the model. This is implemented to call
! * {@code preferenceChanged} to reschedule a new layout
! * if the {@code ElementChange} record is not {@code null}.
*
* @param ec changes to the element this view is responsible
! * for (may be {@code 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
*** 1329,1339 ****
public static final int Y_AXIS = VERTICAL;
/**
* Provides a mapping from the document model coordinate space
* to the coordinate space of the view mapped to it. This is
! * implemented to default the bias to <code>Position.Bias.Forward</code>
* which was previously implied.
*
* @param pos the position to convert >= 0
* @param a the allocated region in which to render
* @return the bounding box of the given position is returned
--- 1329,1339 ----
public static final int Y_AXIS = VERTICAL;
/**
* Provides a mapping from the document model coordinate space
* to the coordinate space of the view mapped to it. This is
! * implemented to default the bias to {@code Position.Bias.Forward}
* which was previously implied.
*
* @param pos the position to convert >= 0
* @param a the allocated region in which to render
* @return the bounding box of the given position is returned
< prev index next >