OpenJDK 27 · javax.swing.text.View · APIdia, the JavaDoc alternative

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:

Participate in layout.

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 above text describes this graphic.

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:

Sample calling sequence between parent view and child view:
setSize, getMinimum, getPreferred, getMaximum, getAlignment, setSize

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.

Render a portion of the model.

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:

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.
The coordinate system is the same as the hosting 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.
The default is to not clip the children. It is more efficient to allow a view to clip only if it really feels it needs clipping.
The Graphics object given is not initialized in any way. A view should set any settings needed.
A 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 order of views relative to the model is up to the implementation. Although child views will typically be arranged in the same order that they occur in the model, they may be visually arranged in an entirely different order. View implementations may have Z-Order associated with them if the children are overlapping.

The methods for rendering are:

paint

Translate between the model and view coordinate systems.

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.

Respond to changes from the model.

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 DocumentListeners. 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 and Description
public static final int	BadBreakWeight The weight to indicate a view is a bad break opportunity for the purpose of formatting.
private Element	elem
public static final int	ExcellentBreakWeight The weight to indicate a view supports breaking, and this represents a very attractive place to break.
pack-priv int	firstUpdateIndex The index of the first child view to be notified.
public 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.
public static final int	GoodBreakWeight The weight to indicate a view supports breaking, but better opportunities probably exist.
pack-priv int	lastUpdateIndex The index of the last child view to be notified.
private View	parent
pack-priv static final Position.Bias[]	sharedBiasReturn
public static final int	X_AXIS Axis for format/break operations.
public static final int	Y_AXIS Axis for format/break operations.

Access	Constructor and Description
public	View(Element the `Element` to represent elem) Creates a new `View` object.

Method Summary

Modifier and Type	Method and Description
public void	append(View the view v) Appends a single child view.
public View	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. breakView(int may be either `View.X_AXIS` or `View.Y_AXIS` axis, int the location in the document model that a broken fragment would occupy >= 0. This would be the starting offset of the fragment returned offset, float the position along the axis that the broken view would occupy >= 0. This may be useful for things like tab calculations pos, float specifies the distance along the axis where a potential break is desired >= 0 len) Tries to break this view on the given axis.
pack-priv void	calculateUpdateIndexes(DocumentEvent the change information from the associated document e) Calculates the first and the last indexes of the child views that need to be notified of the change to the model.
public void	changedUpdate(DocumentEvent the change information from the associated document e, Shape the current allocation of the view a, ViewFactory the factory to use to rebuild if the view has children f) Gives notification from the document that attributes were changed in a location that this view is responsible for.
public View	Returns: the view fragment, or itself if the view doesn't support breaking into fragments createFragment(int the starting offset >= 0. This should be a value greater or equal to the element starting offset and less than the element ending offset. p0, int 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. p1) Creates a view that represents a portion of the element.
protected void	forwardUpdate(DocumentEvent.ElementChange changes to the element this view is responsible for (may be `null` if there were no changes). ec, DocumentEvent the change information from the associated document e, Shape the current allocation of the view a, ViewFactory the factory to use to rebuild if the view has children f) Forwards the given `DocumentEvent` to the child views that need to be notified of the change to the model.
protected void	forwardUpdateToView(View the child view to forward the event to v, DocumentEvent the change information from the associated document e, Shape the current allocation of the view a, ViewFactory the factory to use to rebuild if the view has children f) Forwards the `DocumentEvent` to the give child view.
public float	Returns: the value 0.5 getAlignment(int may be either `View.X_AXIS` or `View.Y_AXIS` axis) Determines the desired alignment for this view along an axis.
public AttributeSet	Returns: the attributes to use when rendering getAttributes() Fetches the attributes to use when rendering.
public int	Returns: the weight, which should be a value between ForcedBreakWeight and BadBreakWeight getBreakWeight(int may be either `View.X_AXIS` or `View.Y_AXIS` axis, float the potential location of the start of the broken view >= 0. This may be useful for calculating tab positions pos, float specifies the relative length from pos where a potential break is desired >= 0 len) Determines how attractive a break opportunity in this view is.
public Shape	Returns: the allocation to the child getChildAllocation(int the index of the child, >= 0 && < `getViewCount()` index, Shape the allocation to this view a) Fetches the allocation for the given child view.
public Container	Returns: the container, `null` if none getContainer() Fetches the container hosting the view.
public Document	Returns: the view model, `null` if none getDocument() Fetches the model associated with the view.
public Element	Returns: the subject getElement() Fetches the structural portion of the subject that this view is mapped to.
public int	Returns: the ending offset into the model >= 0 getEndOffset() Fetches the portion of the model for which this view is responsible.
public Graphics	Returns: a `Graphics` object for rendering getGraphics() Fetch a `Graphics` for rendering.
public float	Returns: the maximum span the view can be rendered into getMaximumSpan(int may be either `View.X_AXIS` or `View.Y_AXIS` axis) Determines the maximum span for this view along an axis.
public float	Returns: the minimum span the view can be rendered into getMinimumSpan(int may be either `View.X_AXIS` or `View.Y_AXIS` axis) Determines the minimum span for this view along an axis.
public int	Returns: the location within the model that best represents the next location visual position getNextVisualPositionFrom(int the position to convert pos, Position.Bias the bias b, Shape the allocated region in which to render a, int 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 direction, Position.Bias[] the returned bias biasRet) Provides a way to determine the next visually represented model location at which one might place a caret.
public View	Returns: the parent, or `null` if none exists getParent() Returns the parent of the view.
public abstract float	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 getPreferredSpan(int may be either `View.X_AXIS` or `View.Y_AXIS` axis) Determines the preferred span for this view along an axis.
public int	Returns: the weight getResizeWeight(int may be either `View.X_AXIS` or `View.Y_AXIS` axis) Determines the resizability of the view along the given axis.
public int	Returns: the starting offset into the model >= 0 getStartOffset() Fetches the portion of the model for which this view is responsible.
public String	Returns: the tooltip text at the specified location getToolTipText(float the x coordinate x, float the y coordinate y, Shape current allocation of the View. allocation) Returns the tooltip text at the specified location.
public View	Returns: the view getView(int the number of the view to get, >= 0 && < getViewCount() n) Gets the nth child view.
public int	Returns: the number of views >= 0 getViewCount() Returns the number of views in this view.
public ViewFactory	Returns: the factory, `null` if none getViewFactory() Fetches the `ViewFactory` implementation that is feeding the view hierarchy.
public int	Returns: index of the view representing the given position, or -1 if no view represents that position getViewIndex(int the position >= 0 pos, Position.Bias the bias b) Returns the child view index representing the given position in the model.
public int	Returns: index of the view representing the given location, or -1 if no view represents that position getViewIndex(float the x coordinate x, float the y coordinate y, Shape current allocation of the View. allocation) Returns the child view index representing the given position in the view.
public void	insert(int the offset of the view to insert before >= 0 offs, View the view v) Inserts a single child view.
public void	insertUpdate(DocumentEvent the change information from the associated document e, Shape the current allocation of the view a, ViewFactory the factory to use to rebuild if the view has children f) Gives notification that something was inserted into the document in a location that this view is responsible for.
public boolean	Returns: always returns true isVisible() Returns a boolean that indicates whether the view is visible or not.
public abstract Shape	Returns: the bounding box, in view coordinate space, of the character at the specified position modelToView(int the position of the desired character (>=0) pos, Shape the area of the view, which encompasses the requested character a, Position.Bias 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` b) Provides a mapping, for a given character, from the document model coordinate space to the view coordinate space.
public Shape	Returns: the bounding box which is a union of the region specified by the first and last character positions modelToView(int the position of the first character (>=0) p0, Position.Bias 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` b0, int the position of the last character (>=0) p1, Position.Bias the bias for the second character position, defined one of the legal values shown above b1, Shape the area of the view, which encompasses the requested region a) Provides a mapping, for a given region, from the document model coordinate space to the view coordinate space.
public Shape	Returns: the bounding box of the given position is returned modelToView(int the position to convert >= 0 pos, Shape the allocated region in which to render a) Deprecated Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it.
public abstract void	paint(Graphics the rendering surface to use g, Shape the allocated region to render into allocation) Renders using the given rendering surface and area on that surface.
public void	preferenceChanged(View the child view child, boolean true if the width preference has changed width, boolean true if the height preference has changed height) Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout.
public void	remove(int the position i) Removes one of the children at the given position.
public void	removeAll() Removes all of the children.
public void	removeUpdate(DocumentEvent the change information from the associated document e, Shape the current allocation of the view a, ViewFactory the factory to use to rebuild if the view has children f) Gives notification that something was removed from the document in a location that this view is responsible for.
public void	replace(int the starting index into the child views to insert the new views. This should be a value >= 0 and <= getViewCount offset, int the number of existing child views to remove This should be a value >= 0 and <= (getViewCount() - offset). length, View[] the child views to add. This value can be `null` to indicate no children are being added (useful to remove). views) Replaces child views.
public void	setParent(View the new parent, or `null` if the view is being removed from a parent parent) Establishes the parent view for this view.
public void	setSize(float the width >= 0 width, float the height >= 0 height) Sets the size of the view.
pack-priv void	updateAfterChange() Updates the view to reflect the changes.
protected boolean	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 updateChildren(DocumentEvent.ElementChange the change information for the element this view is responsible for. This should not be `null` if this method gets called ec, DocumentEvent the change information from the associated document e, ViewFactory the factory to use to build child views 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.
protected void	updateLayout(DocumentEvent.ElementChange changes to the element this view is responsible for (may be `null` if there were no changes) ec, DocumentEvent the change information from the associated document e, Shape the current allocation of the view a) Updates the layout in response to receiving notification of change from the model.
public abstract int	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. viewToModel(float the X coordinate >= 0 x, float the Y coordinate >= 0 y, Shape the allocated region in which to render a, Position.Bias[] the returned bias biasReturn) Provides a mapping from the view coordinate space to the logical coordinate space of the model.
public int	Returns: the location within the model that best represents the given point in the view >= 0 viewToModel(float the X coordinate >= 0 x, float the Y coordinate >= 0 y, Shape the allocated region in which to render a) Deprecated Provides a mapping from the view coordinate space to the logical coordinate space of the model.

Inherited from java.lang.Object:: clone equals finalize getClass hashCode notify notifyAll toString wait wait wait

public abstract Class View

Field Summary

Constructor Summary

Method Summary