SwingConstants
AsyncBoxView
, ComponentView
, CompositeView
, GlyphView
, IconView
, ImageView
, PlainView
public abstract class View extends Object implements SwingConstants
A very important part of the text package is the 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.
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 (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 views have been broken down into pieces. The convenience of a substantial relationship to the element makes it easier to build factories to produce the views, and makes it easier to keep track of the view pieces as the model is changed and the view must be changed to reflect the model. Simple views therefore represent an Element directly and complex views do not.
A view has the following responsibilities:
The view has a setSize
method which is like doLayout
and setSize
in Component
combined. The view has a preferenceChanged
method which is like invalidate
in Component
except that one can invalidate just one axis and the child requesting the change is identified.
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 implementation, the minimum span will be <= the preferred span which in turn will be <= the maximum span.
The minimum set of methods for layout are:
The 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 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 always be set to a value within the minimum and maximum span specified by that view. Additionally, the view must always call the 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 preferenceChanged
has been sent. This allows parent View implementations to cache the child requirements if desired. The calling sequence looks something like the following:
The exact calling sequence is up to the layout functionality of the parent view (if the view has any children). The view may collect the preferences of the children prior to determining what it will give each child, or it might iteratively update the children one at a time.
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 View
has the following semantics for rendering:
Component
(i.e. the Component
returned by the 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 Component
. Graphics
object given is not initialized in any way. A view should set any settings needed. 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 View
implementations. Each 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. The methods for rendering are:
Because the view objects are produced from a factory and therefore cannot necessarily be counted upon to be in a particular pattern, one must be able to perform translation to properly locate spatial representation of the model. The methods for doing this are:
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 DocumentEvent
.
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 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. At any level in the view hierarchy, that view knows enough about its children to best distribute the change information further. Changes are therefore broadcasted starting from the root of the view hierarchy. The methods for doing this are:
Modifier and Type | Field | Description |
---|---|---|
static final int |
BadBreakWeight |
The weight to indicate a view is a bad break opportunity for the purpose of formatting. |
static final int |
ExcellentBreakWeight |
The weight to indicate a view supports breaking, and this represents a very attractive place to break. |
static final int |
ForcedBreakWeight |
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. |
static final int |
GoodBreakWeight |
The weight to indicate a view supports breaking, but better opportunities probably exist. |
static final int |
X_AXIS |
Axis for format/break operations. |
static final int |
Y_AXIS |
Axis for format/break operations. |
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST
Constructor | Description |
---|---|
View |
Creates a new View object. |
Modifier and Type | Method | Description |
---|---|---|
void |
append |
Appends a single child view. |
View |
breakView |
Tries to break this view on the given axis. |
void |
changedUpdate |
Gives notification from the document that attributes were changed in a location that this view is responsible for. |
View |
createFragment |
Creates a view that represents a portion of the element. |
protected void |
forwardUpdate |
Forwards the given DocumentEvent to the child views that need to be notified of the change to the model. |
protected void |
forwardUpdateToView |
Forwards the DocumentEvent to the give child view. |
float |
getAlignment |
Determines the desired alignment for this view along an axis. |
AttributeSet |
getAttributes() |
Fetches the attributes to use when rendering. |
int |
getBreakWeight |
Determines how attractive a break opportunity in this view is. |
Shape |
getChildAllocation |
Fetches the allocation for the given child view. |
Container |
getContainer() |
Fetches the container hosting the view. |
Document |
getDocument() |
Fetches the model associated with the view. |
Element |
getElement() |
Fetches the structural portion of the subject that this view is mapped to. |
int |
getEndOffset() |
Fetches the portion of the model for which this view is responsible. |
Graphics |
getGraphics() |
Fetch a Graphics for rendering. |
float |
getMaximumSpan |
Determines the maximum span for this view along an axis. |
float |
getMinimumSpan |
Determines the minimum span for this view along an axis. |
int |
getNextVisualPositionFrom |
Provides a way to determine the next visually represented model location at which one might place a caret. |
View |
getParent() |
Returns the parent of the view. |
abstract float |
getPreferredSpan |
Determines the preferred span for this view along an axis. |
int |
getResizeWeight |
Determines the resizability of the view along the given axis. |
int |
getStartOffset() |
Fetches the portion of the model for which this view is responsible. |
String |
getToolTipText |
Returns the tooltip text at the specified location. |
View |
getView |
Gets the nth child view. |
int |
getViewCount() |
Returns the number of views in this view. |
ViewFactory |
getViewFactory() |
Fetches the ViewFactory implementation that is feeding the view hierarchy. |
int |
getViewIndex |
Returns the child view index representing the given position in the view. |
int |
getViewIndex |
Returns the child view index representing the given position in the model. |
void |
insert |
Inserts a single child view. |
void |
insertUpdate |
Gives notification that something was inserted into the document in a location that this view is responsible for. |
boolean |
isVisible() |
Returns a boolean that indicates whether the view is visible or not. |
Shape |
modelToView |
Deprecated. |
abstract Shape |
modelToView |
Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space. |
Shape |
modelToView |
Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space. |
abstract void |
paint |
Renders using the given rendering surface and area on that surface. |
void |
preferenceChanged |
Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout. |
void |
remove |
Removes one of the children at the given position. |
void |
removeAll() |
Removes all of the children. |
void |
removeUpdate |
Gives notification that something was removed from the document in a location that this view is responsible for. |
void |
replace |
Replaces child views. |
void |
setParent |
Establishes the parent view for this view. |
void |
setSize |
Sets the size of the view. |
protected boolean |
updateChildren |
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. |
protected void |
updateLayout |
Updates the layout in response to receiving notification of change from the model. |
int |
viewToModel |
Deprecated. |
abstract int |
viewToModel |
Provides a mapping from the view coordinate space to the logical coordinate space of the model. |
public static final int BadBreakWeight
public static final int GoodBreakWeight
public static final int ExcellentBreakWeight
public static final int ForcedBreakWeight
public static final int X_AXIS
public static final int Y_AXIS
public View(Element elem)
View
object.elem
- the Element
to representpublic View getParent()
null
if none existspublic boolean isVisible()
public abstract float getPreferredSpan(int axis)
axis
- may be either View.X_AXIS
or View.Y_AXIS
public float getMinimumSpan(int axis)
axis
- may be either View.X_AXIS
or View.Y_AXIS
public float getMaximumSpan(int axis)
axis
- may be either View.X_AXIS
or View.Y_AXIS
public void preferenceChanged(View child, boolean width, boolean height)
revalidate
on the associated text component.child
- the child viewwidth
- true if the width preference has changedheight
- true if the height preference has changedpublic float getAlignment(int axis)
axis
- may be either View.X_AXIS
or View.Y_AXIS
public abstract void paint(Graphics g, Shape allocation)
g
- the rendering surface to useallocation
- the allocated region to render intopublic void setParent(View parent)
super.setParent()
should be called.parent
- the new parent, or null
if the view is being removed from a parentpublic int getViewCount()
public View getView(int n)
null
.n
- the number of the view to get, >= 0 && < getViewCount()public void removeAll()
replace
.public void remove(int i)
replace
.i
- the positionpublic void insert(int offs, View v)
replace
.offs
- the offset of the view to insert before >= 0v
- the viewpublic void append(View v)
replace
.v
- the viewpublic void replace(int offset, int length, View[] views)
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.offset
- the starting index into the child views to insert the new views. This should be a value >= 0 and <= getViewCountlength
- 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).public int getViewIndex(int pos, Position.Bias b)
pos
- the position >= 0b
- the biaspublic Shape getChildAllocation(int index, Shape a)
null
since the default is to not have any child views.index
- the index of the child, >= 0 && < getViewCount()
a
- the allocation to this viewpublic int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) throws BadLocationException
BadLocationException
will be thrown.pos
- the position to convertb
- the biasa
- the allocated region in which to renderdirection
- 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: biasRet
- the returned biasBadLocationException
- the given position is not a valid position within the documentIllegalArgumentException
- if direction
doesn't have one of the legal values abovepublic abstract Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException
pos
- the position of the desired character (>=0)a
- the area of the view, which encompasses the requested characterb
- 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
BadLocationException
- if the specified position does not represent a valid location in the associated documentIllegalArgumentException
- if b
is not one of the legal Position.Bias
values listed abovepublic Shape modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) throws BadLocationException
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 abovea
- the area of the view, which encompasses the requested regionBadLocationException
- if the given position does not represent a valid location in the associated documentIllegalArgumentException
- if b0
or b1
are not one of the legal Position.Bias
values listed abovepublic abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn)
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.x
- the X coordinate >= 0y
- the Y coordinate >= 0a
- the allocated region in which to renderbiasReturn
- the returned biasbiasReturn
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 void insertUpdate(DocumentEvent e, Shape a, ViewFactory f)
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. forwardUpdate
is called to forward the DocumentEvent to the appropriate child views. updateLayout
is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing. e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenpublic void removeUpdate(DocumentEvent e, Shape a, ViewFactory f)
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. forwardUpdate
is called to forward the DocumentEvent to the appropriate child views. updateLayout
is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing. e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenpublic void changedUpdate(DocumentEvent e, Shape a, ViewFactory f)
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. forwardUpdate
is called to forward the DocumentEvent to the appropriate child views. updateLayout
is called to give the view a chance to either repair its layout, to reschedule layout, or do nothing. e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenpublic Document getDocument()
null
if nonepublic int getStartOffset()
public int getEndOffset()
public Element getElement()
public Graphics getGraphics()
Graphics
for rendering. This can be used to determine font characteristics, and will be different for a print view than a component view.Graphics
object for renderingpublic AttributeSet getAttributes()
AttributeSet
returned by this method.public View breakView(int axis, int offset, float pos, float len)
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.
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 returnedpos
- the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculationslen
- specifies the distance along the axis where a potential break is desired >= 0public View createFragment(int p0, int p1)
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.public int getBreakWeight(int axis, float pos, float len)
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
.
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 positionslen
- specifies the relative length from pos where a potential break is desired >= 0public int getResizeWeight(int axis)
axis
- may be either View.X_AXIS
or View.Y_AXIS
public void setSize(float width, float height)
width
- the width >= 0height
- the height >= 0public Container getContainer()
null
if nonepublic ViewFactory getViewFactory()
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.null
if nonepublic String getToolTipText(float x, float y, Shape allocation)
x
- the x coordinatey
- the y coordinateallocation
- current allocation of the View.public int getViewIndex(float x, float y, Shape allocation)
x
, y
.x
- the x coordinatey
- the y coordinateallocation
- current allocation of the View.protected boolean updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f)
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.ec
- the change information for the element this view is responsible for. This should not be null
if this method gets callede
- the change information from the associated documentf
- the factory to use to build child viewsprotected void forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f)
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).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 documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenprotected void forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f)
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.v
- the child view to forward the event toe
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenprotected void updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a)
preferenceChanged
to reschedule a new layout if the ElementChange
record is not null
.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 documenta
- the current allocation of the view@Deprecated public Shape modelToView(int pos, Shape a) throws BadLocationException
Position.Bias.Forward
which was previously implied.pos
- the position to convert >= 0a
- the allocated region in which to renderBadLocationException
- if the given position does not represent a valid location in the associated document@Deprecated public int viewToModel(float x, float y, Shape a)
x
- the X coordinate >= 0y
- the Y coordinate >= 0a
- the allocated region in which to render
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.desktop/javax/swing/text/View.html