---

javax.swing.text
Class View

java.lang.Object
 |
 +--javax.swing.text.View

All Implemented Interfaces:

SwingConstants

Direct Known Subclasses:

AsyncBoxView, ComponentView, CompositeView, GlyphView, IconView, PlainView, javax.swing.text.WrappedPlainView.WrappedLine

---

public abstract class View

extends Object

implements SwingConstants

Safe:

---

BadBreakWeight

public static final int BadBreakWeight

Enabled: The weight to indicate a view is a bad break opportunity for the purpose of formatting. This value indicates that no attempt should be made to break the view into fragments as the view has not been written to support fragmenting.

See Also:

getBreakWeight(int, float, float), GoodBreakWeight, ExcellentBreakWeight, ForcedBreakWeight

---

GoodBreakWeight

public static final int GoodBreakWeight

Enabled: The weight to indicate a view supports breaking, but better opportunities probably exist.

See Also:

getBreakWeight(int, float, float), BadBreakWeight, ExcellentBreakWeight, ForcedBreakWeight

---

ExcellentBreakWeight

public static final int ExcellentBreakWeight

Enabled: The weight to indicate a view supports breaking, and this represents a very attractive place to break.

See Also:

getBreakWeight(int, float, float), BadBreakWeight, GoodBreakWeight, ForcedBreakWeight

---

ForcedBreakWeight

public static final int ForcedBreakWeight

Enabled: The weight to indicate a view supports breaking, and must be broken to be represented properly when placed in a view that formats its children by breaking them.

See Also:

getBreakWeight(int, float, float), BadBreakWeight, GoodBreakWeight, ExcellentBreakWeight

---

X_AXIS

public static final int X_AXIS

Enabled: Axis for format/break operations.

---

Y_AXIS

public static final int Y_AXIS

Enabled: Axis for format/break operations.

---

sharedBiasReturn

static final javax.swing.text.Position.Bias[] sharedBiasReturn

---

parent

private View parent

---

elem

private Element elem

View

public View(Element elem)

Enabled: Creates a new View object.

Parameters:

elem - the Element to represent

getParent

public View getParent()

Suppressed: Returns the parent of the view.

Returns:

the parent, or null if none exists

---

isVisible

public boolean isVisible()

Enabled: Returns a boolean that indicates whether the view is visible or not. By default all views are visible.

Returns:

always returns true

---

getPreferredSpan

public abstract float getPreferredSpan(int axis)

Enabled: Determines the preferred span for this view along an axis.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

Returns:

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 Also:

getPreferredSpan(int)

---

getMinimumSpan

public float getMinimumSpan(int axis)

Enabled: Determines the minimum span for this view along an axis.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

Returns:

the minimum span the view can be rendered into

See Also:

getPreferredSpan(int)

---

getMaximumSpan

public float getMaximumSpan(int axis)

Enabled: Determines the maximum span for this view along an axis.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

Returns:

the maximum span the view can be rendered into

See Also:

getPreferredSpan(int)

---

preferenceChanged

public void preferenceChanged(View child,
 boolean width,
 boolean height)

Enabled: 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 revalidate on the associated text component.

Parameters:

child - the child view

width - true if the width preference has changed

height - true if the height preference has changed

See Also:

javax.swing.JComponent#revalidate

---

getAlignment

public float getAlignment(int axis)

Enabled: Determines the desired alignment for this view along an axis. The desired alignment is returned. This should be 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.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

Returns:

the value 0.5

---

paint

public abstract void paint(Graphics g,
 Shape allocation)

Suppressed: Renders using the given rendering surface and area on that surface. The view may need to do layout and create child views to enable itself to render into the given allocation.

Parameters:

g - the rendering surface to use

allocation - the allocated region to render into

See Also:

paint(java.awt.Graphics, java.awt.Shape)

---

setParent

public void setParent(View parent)

Suppressed: Establishes the parent view for this view. This is guaranteed to be called before any other methods if the parent view is functioning properly. This is also the last method called, since it is called to indicate 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, propogating the notification that they have been disconnected from the view tree. If this is reimplemented, super.setParent() should be called.

Parameters:

parent - the new parent, or null if the view is being removed from a parent

---

getViewCount

public int getViewCount()

Enabled: Returns the number of views in this view. Since the default is to not be a composite view this returns 0.

Returns:

the number of views>= 0

See Also:

getViewCount()

---

getView

public View getView(int n)

Enabled: Gets the nth child view. Since there are no children by default, this returns null.

Parameters:

n - the number of the view to get,>= 0 && < getViewCount()

Returns:

the view

---

removeAll

public void removeAll()

Enabled: Removes all of the children. This is a convenience call to replace.

Since:

1.3

---

remove

public void remove(int i)

Enabled: Removes one of the children at the given position. This is a convenience call to replace.

Since:

1.3

---

insert

public void insert(int offs,
 View v)

Enabled: Inserts a single child view. This is a convenience call to replace.

Parameters:

offs - the offset of the view to insert before>= 0

v - the view

Since:

1.3

See Also:

replace(int, int, javax.swing.text.View[])

---

append

public void append(View v)

Enabled: Appends a single child view. This is a convenience call to replace.

Parameters:

v - the view

Since:

1.3

See Also:

replace(int, int, javax.swing.text.View[])

---

replace

public void replace(int offset,
 int length,
 View[] views)

Enabled: 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 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.

Parameters:

length - the number of existing child views to remove This should be a value>= 0 and <= (getViewCount() - offset).

views - the child views to add. This value can be null to indicate no children are being added (useful to remove).

Since:

1.3

---

getViewIndex

public int getViewIndex(int pos,
 javax.swing.text.Position.Bias b)

Suppressed: 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.

Parameters:

pos - the position>= 0

Returns:

index of the view representing the given position, or -1 if no view represents that position

Since:

1.3

---

getChildAllocation

public Shape getChildAllocation(int index,
 Shape a)

Enabled: 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 null since the default is to not have any child views.

Parameters:

index - the index of the child,>= 0 && < getViewCount()

a - the allocation to this view

Returns:

the allocation to the child

---

getNextVisualPositionFrom

public int getNextVisualPositionFrom(int pos,
 javax.swing.text.Position.Bias b,
 Shape a,
 int direction,
 javax.swing.text.Position.Bias[] biasRet)
 throws BadLocationException

Suppressed: Provides a way to determine the next visually represented model location at which 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.

Parameters:

pos - the position to convert>= 0

a - the allocated region in which to render

direction - the direction from the current position that can be thought of as the arrow keys typically found on a keyboard. This will be one of the following values:

• SwingConstants.WEST
• SwingConstants.EAST
• SwingConstants.NORTH
• SwingConstants.SOUTH

Returns:

the location within the model that best represents the next location visual position

BadLocationException

---

modelToView

public abstract Shape modelToView(int pos,
 Shape a,
 javax.swing.text.Position.Bias b)
 throws BadLocationException

Suppressed: Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.

Parameters:

pos - the position of the desired character (>=0)

a - the area of the view, which encompasses the requested character

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; b will have one of these values:

• Position.Bias.Forward
• Position.Bias.Backward

Returns:

the bounding box, in view coordinate space, of the character at the specified position

BadLocationException

See Also:

viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

---

modelToView

public Shape modelToView(int p0,
 javax.swing.text.Position.Bias b0,
 int p1,
 javax.swing.text.Position.Bias b1,
 Shape a)
 throws BadLocationException

Suppressed: Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space. The specified region is created as a union of the first and last character positions.

Parameters:

p0 - the position of the first character (>=0)

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; b0 will have one of these values:

• Position.Bias.Forward
• Position.Bias.Backward

p1 - the position of the last character (>=0)

b1 - the bias for the second character position, defined one of the legal values shown above

a - the area of the view, which encompasses the requested region

Returns:

the bounding box which is a union of the region specified by the first and last character positions

BadLocationException

See Also:

viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

---

viewToModel

public abstract int viewToModel(float x,
 float y,
 Shape a,
 javax.swing.text.Position.Bias[] biasReturn)

Suppressed: 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.

Parameters:

x - the X coordinate>= 0

y - the Y coordinate>= 0

a - the allocated region in which to render

Returns:

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.

---

insertUpdate

public void insertUpdate(DocumentEvent e,
 Shape a,
 ViewFactory f)

Enabled: Gives notification that something was inserted into the document in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:

1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:

e - the change information from the associated document

a - the current allocation of the view

f - the factory to use to rebuild if the view has children

See Also:

insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

removeUpdate

public void removeUpdate(DocumentEvent e,
 Shape a,
 ViewFactory f)

Enabled: Gives notification that something was removed from the document in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:

1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:

e - the change information from the associated document

a - the current allocation of the view

f - the factory to use to rebuild if the view has children

See Also:

removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

changedUpdate

public void changedUpdate(DocumentEvent e,
 Shape a,
 ViewFactory f)

Enabled: Gives notification from the document that attributes were changed in a location that this view is responsible for. To reduce the burden to subclasses, this functionality is spread out into the following calls that subclasses can reimplement:

1. updateChildren is called if there were any changes to the element this view is responsible for. If this view has child views that are represent the child elements, then this method should do whatever is necessary to make sure the child views correctly represent the model.
2. forwardUpdate is called to forward the DocumentEvent to the appropriate child views.
3. updateLayout is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing.

Parameters:

e - the change information from the associated document

a - the current allocation of the view

f - the factory to use to rebuild if the view has children

See Also:

changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

getDocument

public Document getDocument()

Enabled: Fetches the model associated with the view.

Returns:

the view model, null if none

See Also:

getDocument()

---

getStartOffset

public int getStartOffset()

Enabled: Fetches the portion of the model for which this view is responsible.

Returns:

the starting offset into the model>= 0

See Also:

getStartOffset()

---

getEndOffset

public int getEndOffset()

Enabled: Fetches the portion of the model for which this view is responsible.

Returns:

the ending offset into the model>= 0

See Also:

getEndOffset()

---

getElement

public Element getElement()

Enabled: Fetches the structural portion of the subject that this view is mapped to. The view may not be responsible for the entire portion of the element.

Returns:

the subject

See Also:

getElement()

---

getGraphics

public Graphics getGraphics()

Enabled: Fetch a Graphics for rendering. This can be used to determine font characteristics, and will be different for a print view than a component view.

Returns:

a Graphics object for rendering

Since:

1.3

---

getAttributes

public AttributeSet getAttributes()

Enabled: Fetches the attributes to use when rendering. By default this simply returns the attributes of the associated element. This method should be used rather than using the element directly to obtain access to the attributes to allow 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 AttributeSet returned by this method.

---

breakView

public View breakView(int axis,
 int offset,
 float pos,
 float len)

Enabled: Tries to break this view on the given axis. This is called by views that try to do formatting of their children. For example, a view of a paragraph will typically try to place its children into row and views representing chunks of text can sometimes be broken down into smaller pieces.

This is implemented to return the view itself, which represents the default behavior on not being 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.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

offset - the location in the document model that a broken fragment would occupy>= 0. This would be the starting offset of the fragment returned

pos - the position along the axis that the broken view would occupy>= 0. This may be useful for things like tab calculations

len - specifies the distance along the axis where a potential break is desired>= 0

Returns:

the fragment of the view that represents the given span, if the view can be broken. If the view doesn't support breaking behavior, the view itself is returned.

See Also:

ParagraphView

---

createFragment

public View createFragment(int p0,
 int p1)

Enabled: Creates a view that represents a portion of the element. This is potentially useful during formatting operations for taking measurements of fragments of the view. If the view doesn't support fragmenting (the default), it should return itself.

Parameters:

p0 - the starting offset>= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset.

p1 - the ending offset> p0. This should be a value less than or equal to the elements end offset and greater than the elements starting offset.

Returns:

the view fragment, or itself if the view doesn't support breaking into fragments

See Also:

LabelView

---

getBreakWeight

public int getBreakWeight(int axis,
 float pos,
 float len)

Enabled: Determines how attractive a break opportunity in this view is. This can be used for determining which view is the most attractive to call 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 BadBreakWeight should not be considered for a break. A value greater than or equal to ForcedBreakWeight should be broken.

This is implemented to provide the default behavior of returning 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 LabelView. An example of a view that uses break weight is ParagraphView.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

pos - the potential location of the start of the broken view>= 0. This may be useful for calculating tab positions

len - specifies the relative length from pos where a potential break is desired>= 0

Returns:

the weight, which should be a value between ForcedBreakWeight and BadBreakWeight

See Also:

LabelView, ParagraphView, BadBreakWeight, GoodBreakWeight, ExcellentBreakWeight, ForcedBreakWeight

---

getResizeWeight

public int getResizeWeight(int axis)

Enabled: Determines the resizability of the view along the given axis. A value of 0 or less is not resizable.

Parameters:

axis - may be either View.X_AXIS or View.Y_AXIS

Returns:

the weight

---

setSize

public void setSize(float width,
 float height)

Enabled: Sets the size of the view. This should cause layout of the view along the given axis, if it has any layout duties.

Parameters:

width - the width>= 0

height - the height>= 0

---

getContainer

public Container getContainer()

Suppressed: 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.

Returns:

the container, null if none

---

getViewFactory

public ViewFactory getViewFactory()

Enabled: Fetches the 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.

Returns:

the factory, null if none

---

getToolTipText

public String getToolTipText(float x,
 float y,
 Shape allocation)

Enabled: Returns the tooltip text at the specified location. The default implementation returns the value from the child View identified by the passed in location.

Since:

1.4

See Also:

JTextComponent.getToolTipText(java.awt.event.MouseEvent)

---

getViewIndex

public int getViewIndex(float x,
 float y,
 Shape allocation)

Enabled: 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 x, y.

Parameters:

x - the x coordinate

y - the y coordinate

allocation - current allocation of the View.

Returns:

index of the view representing the given location, or -1 if no view represents that position

Since:

1.4

---

updateChildren

protected boolean updateChildren(javax.swing.event.DocumentEvent.ElementChange ec,
 DocumentEvent e,
 ViewFactory f)

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 ViewFactory is used to create child views for each element specified as added in the ElementChange, starting at the index specified in the given ElementChange. The number of child views representing the removed elements specified are removed.

Parameters:

ec - the change information for the element this view is responsible for. This should not be null if this method gets called

e - the change information from the associated document

f - the factory to use to build child views

Returns:

whether or not the child views represent the child elements of the element this view is responsible for. Some views create children that represent a portion of the element they are responsible for, and should return false. This information is used to determine if views in the range of the added elements should be forwarded to or not

Since:

1.3

See Also:

insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

forwardUpdate

protected void forwardUpdate(javax.swing.event.DocumentEvent.ElementChange ec,
 DocumentEvent e,
 Shape a,
 ViewFactory f)

Forwards the given 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).

Parameters:

ec - changes to the element this view is responsible for (may be null if there were no changes).

e - the change information from the associated document

a - the current allocation of the view

f - the factory to use to rebuild if the view has children

Since:

1.3

See Also:

insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

forwardUpdateToView

protected void forwardUpdateToView(View v,
 DocumentEvent e,
 Shape a,
 ViewFactory f)

Forwards the DocumentEvent to the give child view. This simply messages the view with a call to insertUpdate, removeUpdate, or changedUpdate depending upon the type of the event. This is called by forwardUpdate to forward the event to children that need it.

Parameters:

v - the child view to forward the event to

e - the change information from the associated document

a - the current allocation of the view

f - the factory to use to rebuild if the view has children

Since:

1.3

See Also:

forwardUpdate(javax.swing.event.DocumentEvent.ElementChange, javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

updateLayout

protected void updateLayout(javax.swing.event.DocumentEvent.ElementChange ec,
 DocumentEvent e,
 Shape a)

Updates the layout in response to receiving notification of change from the model. This is implemented to call preferenceChanged to reschedule a new layout if the ElementChange record is not null.

Parameters:

ec - changes to the element this view is responsible for (may be null if there were no changes)

e - the change information from the associated document

a - the current allocation of the view

Since:

1.3

See Also:

insertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), removeUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory), changedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)

---

modelToView

public Shape modelToView(int pos,
 Shape a)
 throws BadLocationException

Deprecated.

Enabled: 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 Position.Bias.Forward which was previously implied.

Parameters:

pos - the position to convert>= 0

a - the allocated region in which to render

Returns:

the bounding box of the given position is returned

BadLocationException

See Also:

modelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)

---

viewToModel

public int viewToModel(float x,
 float y,
 Shape a)

Deprecated.

Enabled: Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Parameters:

x - the X coordinate>= 0

y - the Y coordinate>= 0

a - the allocated region in which to render

Returns:

the location within the model that best represents the given point in the view>= 0

See Also:

viewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])

---

---