|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
java.lang.Object | +--javax.swing.text.View
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. In fact, the original View implementation was a lightweight component. There were several reasons why the Component implementation was abandoned in favor of an alternative.
There was barely had time to get the lightweight component support in the 1.1 version of the JDK. There simply wasn't time to lighten up the component further to where it would need to be to be used for text purposes. The additions made to JComponent increased the memory consumption, and as it currently stands it's much too heavy for representing text.
The layout semantics aren't quite right for text, and changing the current layout semantics of component might break existing applications.
The component api uses integers, but in 1.2 one can use floating point device independent coordinates. An api that works in both 1.1 and 1.2 would be convenient for minimizing transition difficulties. The View class uses the Shape interface and float arguments to enable View implementations for the Java 2 platform v1.2 and later while still functioning in the older 1.1 JDK.
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 it's 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 independantly 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 views 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:
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 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 it's 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:
Field Summary | |
static int |
BadBreakWeight
The weight to indicate a view is a bad break opportunity for the purpose of formatting. |
static int |
ExcellentBreakWeight
The weight to indicate a view supports breaking, and this represents a very attractive place to break. |
static 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 it's children by breaking them. |
static int |
GoodBreakWeight
The weight to indicate a view supports breaking, but better opportunities probably exist. |
static int |
X_AXIS
Axis for format/break operations. |
static int |
Y_AXIS
Axis for format/break operations. |
Fields inherited from interface javax.swing.SwingConstants |
BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NORTH, NORTH_EAST, NORTH_WEST, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST |
Constructor Summary | |
View(Element elem)
Creates a new View object. |
Method Summary | |
void |
append(View v)
Appends a single child view. |
View |
breakView(int axis,
int offset,
float pos,
float len)
Tries to break this view on the given axis. |
void |
changedUpdate(DocumentEvent e,
Shape a,
ViewFactory f)
Gives notification from the document that attributes were changed in a location that this view is responsible for. |
View |
createFragment(int p0,
int p1)
Create a view that represents a portion of the element. |
protected void |
forwardUpdate(DocumentEvent.ElementChange ec,
DocumentEvent e,
Shape a,
ViewFactory f)
Forward the given DocumentEvent to the child views that need to be notified of the change to the model. |
protected void |
forwardUpdateToView(View v,
DocumentEvent e,
Shape a,
ViewFactory f)
Forward the DocumentEvent to the give child view. |
float |
getAlignment(int axis)
Determines the desired alignment for this view along an axis. |
AttributeSet |
getAttributes()
Fetches the attributes to use when rendering. |
int |
getBreakWeight(int axis,
float pos,
float len)
Determines how attractive a break opportunity in this view is. |
Shape |
getChildAllocation(int index,
Shape a)
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 that this view is responsible for. |
Graphics |
getGraphics()
Fetch a Graphics for rendering. |
float |
getMaximumSpan(int axis)
Determines the maximum span for this view along an axis. |
float |
getMinimumSpan(int axis)
Determines the minimum span for this view along an axis. |
int |
getNextVisualPositionFrom(int pos,
Position.Bias b,
Shape a,
int direction,
Position.Bias[] biasRet)
Provides a way to determine the next visually represented model location that one might place a caret. |
View |
getParent()
Returns the parent of the view. |
abstract float |
getPreferredSpan(int axis)
Determines the preferred span for this view along an axis. |
int |
getResizeWeight(int axis)
Determines the resizability of the view along the given axis. |
int |
getStartOffset()
Fetches the portion of the model that this view is responsible for. |
View |
getView(int n)
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(int pos,
Position.Bias b)
Returns the child view index representing the given position in the model. |
void |
insert(int offs,
View v)
Inserts a single child view. |
void |
insertUpdate(DocumentEvent e,
Shape a,
ViewFactory f)
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(int p0,
Position.Bias b0,
int p1,
Position.Bias b1,
Shape a)
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. |
Shape |
modelToView(int pos,
Shape a)
Deprecated. |
abstract Shape |
modelToView(int pos,
Shape a,
Position.Bias b)
Provides a mapping from the document model coordinate space to the coordinate space of the view mapped to it. |
abstract void |
paint(Graphics g,
Shape allocation)
Renders using the given rendering surface and area on that surface. |
void |
preferenceChanged(View child,
boolean width,
boolean height)
Child views can call this on the parent to indicate that the preference has changed and should be reconsidered for layout. |
void |
remove(int i)
Removes one of the children at the given position. |
void |
removeAll()
Removes all of the children. |
void |
removeUpdate(DocumentEvent e,
Shape a,
ViewFactory f)
Gives notification that something was removed from the document in a location that this view is responsible for. |
void |
replace(int offset,
int length,
View[] views)
Replace child views. |
void |
setParent(View parent)
Establishes the parent view for this view. |
void |
setSize(float width,
float height)
Sets the size of the view. |
protected boolean |
updateChildren(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. |
protected void |
updateLayout(DocumentEvent.ElementChange ec,
DocumentEvent e,
Shape a)
Update the layout in response to receiving notification of change from the model. |
int |
viewToModel(float x,
float y,
Shape a)
Deprecated. |
abstract int |
viewToModel(float x,
float y,
Shape a,
Position.Bias[] biasReturn)
Provides a mapping from the view coordinate space to the logical coordinate space of the model. |
Methods inherited from class java.lang.Object |
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait |
Field Detail |
public static final int BadBreakWeight
getBreakWeight(int, float, float)
,
GoodBreakWeight
,
ExcellentBreakWeight
,
ForcedBreakWeight
public static final int GoodBreakWeight
getBreakWeight(int, float, float)
,
BadBreakWeight
,
ExcellentBreakWeight
,
ForcedBreakWeight
public static final int ExcellentBreakWeight
getBreakWeight(int, float, float)
,
BadBreakWeight
,
GoodBreakWeight
,
ForcedBreakWeight
public static final int ForcedBreakWeight
getBreakWeight(int, float, float)
,
BadBreakWeight
,
GoodBreakWeight
,
ExcellentBreakWeight
public static final int X_AXIS
public static final int Y_AXIS
Constructor Detail |
public View(Element elem)
elem
- the element to representMethod Detail |
public View getParent()
public boolean isVisible()
public abstract float getPreferredSpan(int axis)
axis
- may be either View.X_AXIS or View.Y_AXISgetPreferredSpan(int)
public float getMinimumSpan(int axis)
axis
- may be either View.X_AXIS or View.Y_AXISgetPreferredSpan(int)
public float getMaximumSpan(int axis)
axis
- may be either View.X_AXIS or View.Y_AXISgetPreferredSpan(int)
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 changedJComponent.revalidate()
public float getAlignment(int axis)
axis
- may be either View.X_AXIS or View.Y_AXISpublic abstract void paint(Graphics g, Shape allocation)
g
- the rendering surface to useallocation
- the allocated region to render intopaint(java.awt.Graphics, java.awt.Shape)
public void setParent(View parent)
super.setParent()
should be called.parent
- the new parent, or null if the view is
being removed from a parent it was previously added
topublic int getViewCount()
getViewCount()
public View getView(int n)
n
- the number of the view to get, >= 0 && < getViewCount()public void removeAll()
public void remove(int i)
public void insert(int offs, View v)
offs
- the offset of the view to insert before >= 0v
- the viewreplace(int, int, javax.swing.text.View[])
public void append(View v)
v
- the viewreplace(int, int, javax.swing.text.View[])
public void replace(int offset, int length, View[] views)
index
- the starting index into the child views to insert
the new views. This should be a value >= 0 and <= getViewCount.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).public int getViewIndex(int pos, Position.Bias b)
pos
- the position >= 0public Shape getChildAllocation(int index, Shape a)
index
- the index of the child, >= 0 && < getViewCount()a
- the allocation to this view.public int getNextVisualPositionFrom(int pos, Position.Bias b, Shape a, int direction, Position.Bias[] biasRet) throws BadLocationException
pos
- the position to convert >= 0a
- the allocated region to render intodirection
- the direction from the current position that can
be thought of as the arrow keys typically found on a keyboard.
This may be SwingConstants.WEST, SwingConstants.EAST,
SwingConstants.NORTH, or SwingConstants.SOUTH.BadLocationException
- IllegalArgumentException
- for an invalid directionpublic abstract Shape modelToView(int pos, Shape a, Position.Bias b) throws BadLocationException
pos
- the position to convert >= 0a
- the allocated region to render intob
- the bias toward the previous character or the
next character represented by the offset, in case the
position is a boundary of two views.BadLocationException
- if the given position does
not represent a valid location in the associated documentIllegalArgumentException
- for an invalid bias argumentviewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
public Shape modelToView(int p0, Position.Bias b0, int p1, Position.Bias b1, Shape a) throws BadLocationException
p0
- the position to convert >= 0b0
- the bias toward the previous character or the
next character represented by p0, in case the
position is a boundary of two views.p1
- the position to convert >= 0b1
- the bias toward the previous character or the
next character represented by p1, in case the
position is a boundary of two views.a
- the allocated region to render intoBadLocationException
- if the given position does
not represent a valid location in the associated documentIllegalArgumentException
- for an invalid bias argumentviewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
public abstract int viewToModel(float x, float y, Shape a, Position.Bias[] biasReturn)
x
- the X coordinate >= 0y
- the Y coordinate >= 0a
- the allocated region to render intopublic void insertUpdate(DocumentEvent e, Shape a, ViewFactory f)
e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childreninsertUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
public void removeUpdate(DocumentEvent e, Shape a, ViewFactory f)
e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenremoveUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
public void changedUpdate(DocumentEvent e, Shape a, ViewFactory f)
e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenchangedUpdate(javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
public Document getDocument()
getDocument()
public int getStartOffset()
getStartOffset()
public int getEndOffset()
getEndOffset()
public Element getElement()
getElement()
public Graphics getGraphics()
public AttributeSet getAttributes()
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_AXISoffset
- 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.ParagraphView
public 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.LabelView
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_AXISpos
- 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.LabelView
,
ParagraphView
,
BadBreakWeight
,
GoodBreakWeight
,
ExcellentBreakWeight
,
ForcedBreakWeight
public int getResizeWeight(int axis)
axis
- View.X_AXIS or View.Y_AXISpublic void setSize(float width, float height)
width
- the width >= 0height
- the height >= 0public Container getContainer()
public ViewFactory getViewFactory()
protected boolean updateChildren(DocumentEvent.ElementChange ec, DocumentEvent e, ViewFactory f)
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 documentf
- the factory to use to build child viewsinsertUpdate(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)
protected void forwardUpdate(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a, ViewFactory f)
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 childreninsertUpdate(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)
protected void forwardUpdateToView(View v, DocumentEvent e, Shape a, ViewFactory f)
v
- the child view to forward the event to.e
- the change information from the associated documenta
- the current allocation of the viewf
- the factory to use to rebuild if the view has childrenforwardUpdate(javax.swing.event.DocumentEvent.ElementChange, javax.swing.event.DocumentEvent, java.awt.Shape, javax.swing.text.ViewFactory)
protected void updateLayout(DocumentEvent.ElementChange ec, DocumentEvent e, Shape a)
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 childreninsertUpdate(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)
public Shape modelToView(int pos, Shape a) throws BadLocationException
pos
- the position to convert >= 0a
- the allocated region to render intoBadLocationException
- if the given position does
not represent a valid location in the associated documentmodelToView(int, java.awt.Shape, javax.swing.text.Position.Bias)
public int viewToModel(float x, float y, Shape a)
x
- the X coordinate >= 0y
- the Y coordinate >= 0a
- the allocated region to render intoviewToModel(float, float, java.awt.Shape, javax.swing.text.Position.Bias[])
|
JavaTM 2 Platform Std. Ed. v1.3 |
|||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: INNER | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
Java, Java 2D, and JDBC are trademarks or registered trademarks of Sun Microsystems, Inc. in the US and other countries.
Copyright 1993-2000 Sun Microsystems, Inc. 901 San Antonio Road
Palo Alto, California, 94303, U.S.A. All Rights Reserved.