ViewLayoutState (Editor Library) - NetBeans API Javadoc (Current Development Version)

Overview

Package

Class

Use

Tree

Deprecated

Index

Help

org.netbeans.modules.editor.lib/1 1.14.0 3

PREV CLASS NEXT CLASS

FRAMES NO FRAMES

SUMMARY: NESTED | FIELD | CONSTR | METHOD

DETAIL: FIELD | CONSTR | METHOD

org.netbeans.editor.view.spi
Interface ViewLayoutState

All Known Implementing Classes:: DefaultViewLayoutState, DrawEngineFakeDocView, GapBoxView, GapDocumentView, GapLineView, GapMultiLineView, SimpleViewLayoutState

public interface ViewLayoutState

Wrapper around a view that caches computed layout information about preferred, minimum and maximum span along minor axis and the preferred span along the major axis.
It's primarily intended to be used for views being children of GapBoxView based implementations.
After a change occurs in the wrapped view it calls getParent().preferenceChanged(this, width, height) the parent view will notify the layout state by calling #viewPreferenceChanged(width, height) to mark that the cached values need to be updated.
At some point later the parent view calls updateLayout() to update the layout of the child and synchronize the caching variables.

The layout state keeps one of the axes (either View.X_AXIS or View.Y_AXIS as the major one i.e. the children are laid out along that axis. The other axis is called minor.
The layout along the major axis dedicates the span equal to preferred span of the given view (wrapped by a layout state).
Span along minor axis is more complex and it's specific to particular implementations of ViewLayoutState.Parent.

It's encouraged that all the view implementations wishing to be used as children of GapBoxView based implementations in this framework implement this interface.
The benefit for the view implementing this interface is that no default wrapper object implementing this interface needs to be created which saves memory.
Moreover unlike the default wrapper the view can better decide which values really need to be cached and which (e.g. maximum or minimum span being equal to preferred span) do not need to be cached which can furhter eliminate certain caching variables and save additional memory.
Another reason is faster finding of the index value of the child view in its parent view (e.g. in preferenceChanged()) which is constant time compared to logartihmic time (binary search used).

Nested Class Summary

static interface ViewLayoutState.Parent
          Interface that the parent view of the view wrapped by ViewLayoutState is expected to implement.

Method Summary

double getLayoutMajorAxisPreferredSpan()
          Get the preferred span along major axis.

double getLayoutMajorAxisRawOffset()
          Get the raw visual offset of the view along the parent view's major axis.

float getLayoutMinorAxisAlignment()
          Get alignment along the minor axis.

float getLayoutMinorAxisMaximumSpan()
          Get the maximum span of the view along minor axis.

float getLayoutMinorAxisMinimumSpan()
          Get the minimum span of the view along minor axis.

float getLayoutMinorAxisPreferredSpan()
          Get the preferred span of the view along minor axis.

View getView()
          Get the view that this layout state is wrapping.

int getViewRawIndex()
          Get the raw index of the view (wrapped by this layout state) in its parent view.

boolean isFlyweight()
          Check whether this layout state and its associated view is flyweight (there is just one immutable shared instance of it).

boolean isLayoutValid()
          Check whether there are any layout duties present.

void markViewSizeInvalid()
          Parent calls this method to mark the current size of the view as invalid so that the next layout update of this layout state will call View.setSize() using getLayoutMajorAxisPreferredSpan() for major axis span and ViewLayoutState.Parent.getMinorAxisSpan(ViewLayoutState) for minor axis span.

ViewLayoutState selectLayoutMajorAxis(int majorAxis)
          Select which axis will be used as major axis by this layout state.

void setLayoutMajorAxisRawOffset(double layoutMajorAxisRawOffset)
          Parent can set the view's raw offset along the parent view's major axis using this method.

void setViewRawIndex(int viewRawIndex)
          Parent can set the index of the view (wrapped by this layout state) in itself.

void updateLayout()
          Do actual layout updating.

void viewPreferenceChanged(boolean width, boolean height)
          Notify this layout state that the preferences has changed for the view that it wraps.

Nested Class Summary
`static interface`	`ViewLayoutState.Parent` Interface that the parent view of the view wrapped by `ViewLayoutState` is expected to implement.

Method Summary
`double`	`getLayoutMajorAxisPreferredSpan()` Get the preferred span along major axis.
`double`	`getLayoutMajorAxisRawOffset()` Get the raw visual offset of the view along the parent view's major axis.
`float`	`getLayoutMinorAxisAlignment()` Get alignment along the minor axis.
`float`	`getLayoutMinorAxisMaximumSpan()` Get the maximum span of the view along minor axis.
`float`	`getLayoutMinorAxisMinimumSpan()` Get the minimum span of the view along minor axis.
`float`	`getLayoutMinorAxisPreferredSpan()` Get the preferred span of the view along minor axis.
`View`	`getView()` Get the view that this layout state is wrapping.
`int`	`getViewRawIndex()` Get the raw index of the view (wrapped by this layout state) in its parent view.
`boolean`	`isFlyweight()` Check whether this layout state and its associated view is flyweight (there is just one immutable shared instance of it).
`boolean`	`isLayoutValid()` Check whether there are any layout duties present.
`void`	`markViewSizeInvalid()` Parent calls this method to mark the current size of the view as invalid so that the next layout update of this layout state will call `View.setSize()` using `getLayoutMajorAxisPreferredSpan()` for major axis span and `ViewLayoutState.Parent.getMinorAxisSpan(ViewLayoutState)` for minor axis span.
`ViewLayoutState`	`selectLayoutMajorAxis(int majorAxis)` Select which axis will be used as major axis by this layout state.
`void`	`setLayoutMajorAxisRawOffset(double layoutMajorAxisRawOffset)` Parent can set the view's raw offset along the parent view's major axis using this method.
`void`	`setViewRawIndex(int viewRawIndex)` Parent can set the index of the view (wrapped by this layout state) in itself.
`void`	`updateLayout()` Do actual layout updating.
`void`	`viewPreferenceChanged(boolean width, boolean height)` Notify this layout state that the preferences has changed for the view that it wraps.

Method Detail

getView

View getView()

Get the view that this layout state is wrapping.

Returns:: view that this layout state is wrapping.

isFlyweight

boolean isFlyweight()

Check whether this layout state and its associated view is flyweight (there is just one immutable shared instance of it).

Returns:: true if this layout state and its associated view are flyweight or false if not.

getViewRawIndex

int getViewRawIndex()

Get the raw index of the view (wrapped by this layout state) in its parent view.
Storing of the index is useful for the parent which can then find the child's index in a constant time.

Returns:: raw integer index that must be post-processed by parent (if it uses gap-based storage) to become a real index.
Returned valud is undefined for flyweight layout states.

setViewRawIndex

void setViewRawIndex(int viewRawIndex)

Parent can set the index of the view (wrapped by this layout state) in itself.
This method must not be called on flyweight layout states.

Parameters:: viewRawIndex - raw index value. It can differ from the real index because parent could preprocess it because of possible use of a gap translation.

selectLayoutMajorAxis

ViewLayoutState selectLayoutMajorAxis(int majorAxis)

Select which axis will be used as major axis by this layout state.

Parameters:: majorAxis - major axis either View.X_AXIS or View.Y_AXIS.
Returns:: either this layout state if this state is able to work with the given major axis or another layout state if this state is only able to work over the other major axis.
A view (e.g. a flyweight view) that implements this interface can decide to only allow one axis as the major one.
That should mostly be fine because usually the view is tiled only along one axis.
The view may throw IllegalStateException in such case.

getLayoutMajorAxisPreferredSpan

double getLayoutMajorAxisPreferredSpan()

Get the preferred span along major axis.
The value is expected to be cached for fast access.

If the preferred span of the wrapped view changes then the value of the major axis span must change as well typically once the next layout state update takes place.
The wrapped view should call View.preferenceChanged in its parent once its preferred span changes. The parent view will later call i.e. updateLayout() to update the variable holding the preferred span along major axis.
Parent.majorAxisPreferenceChanged() must be called immediately after that change to notify the parent.

Although the value is returned as double (see #getLayoutMajorAxisOffset()) it can be maintained as float if the resolution of the float is sufficient to create proper deltas in Parent#majorAxisPreferenceChanged().
For example if a document has millions of lines it's necessary to maintain line offsets in document view as doubles but assuming that each line is only up to several tenths of pixels high it's enough to hold line height as float in line view layout state.

getLayoutMajorAxisRawOffset

double getLayoutMajorAxisRawOffset()

Get the raw visual offset of the view along the parent view's major axis.

Double is chosen instead of float because for y as major axis the truncation could occur when computing the offset for large files with many lines or for very long lines.
The resolution of mantissa of floats is 23 bits so assuming the line height is e.g. 17 pixels and we have more than 250.000 lines in the docuemnt (which is a lot to write but not so much for e.g. generated xml files) the last bit would be lost resulting in every odd line being shifted one pixel above incorrectly.
The views can still decide to use floats for internal storage of this value if the precision is sufficient.

Returns:: raw double visual offset along major axis. It must be post-processed by parent (if it uses gap-based storage) to become a real index.
Returned valud is undefined for flyweight layout states.

setLayoutMajorAxisRawOffset

void setLayoutMajorAxisRawOffset(double layoutMajorAxisRawOffset)

Parent can set the view's raw offset along the parent view's major axis using this method.
This method must not be called on flyweight layout states.

Parameters:: layoutMajorAxisRawOffset - raw offset value along the major axis. It is not particularly useful without postprocessing by the parent.

getLayoutMinorAxisPreferredSpan

float getLayoutMinorAxisPreferredSpan()

Get the preferred span of the view along minor axis.
The value is expected to be cached for fast access.

If there is a dedicated variable for this value then that variable should be updated during updateLayout() which usually happens some time after the view has called View.preferenceChanged() in the parent.
After the value gets updated the layout state must immediately call Parent.minorAxisPreferenceChanged() to notify the parent about the change of minor span.

getLayoutMinorAxisMinimumSpan

float getLayoutMinorAxisMinimumSpan()

Get the minimum span of the view along minor axis.
The value is expected to be cached for fast access.
By default GapBoxView implementations do not use the minimum span of their children so the particular layout state may decide not to cache the minimum span value and return preferred span instead to save memory that would otherwise be used for caching variables.

If there is a dedicated variable for this value then that variable should be updated during updateLayout() which usually happens once the view has called View.preferenceChanged() in the parent.
After the value gets updated the layout state must immediately call Parent.minorAxisPreferenceChanged() to notify the parent about the change of minor span.

getLayoutMinorAxisMaximumSpan

float getLayoutMinorAxisMaximumSpan()

Get the maximum span of the view along minor axis.
The value is expected to be cached for fast access.
As the default GapBoxView implementations do not use the maximum span of their children the particular layout state may decide not to cache the maximum span value and return preferred span instead to save memory that would otherwise be used for caching variables.

If there is a dedicated variable for this value then that variable gets updated by updateLayout() which usually happens once the view has called View.preferenceChanged() in the parent.
After the value gets updated the layout state must immediately call Parent.minorAxisPreferenceChanged() to notify the parent about the change of minor span.

getLayoutMinorAxisAlignment

float getLayoutMinorAxisAlignment()

Get alignment along the minor axis.
The value is expected to be cached for fast access.

If there is a dedicated variable for this value then that variable gets updated by updateLayout() which usually happens once the view has called View.preferenceChanged() in its parent view which in turn calls #viewPreferenceChanged().
After the value gets updated the layout state must call Parent.minorAxisPreferenceChanged() to notify the parent about the change of minor span.

updateLayout

void updateLayout()

Do actual layout updating.
The first thing to do is to see if any work actually needs to be done.
Certain views such as line-wrapping views may react to View.setSize() being called on them by changing its preferred span along an axis. For such views the actual internal updating must be done twice (because of another call to parent.preferenceChanged()).
Anyway upon exit of this method the isLayoutValid() must return true.
This method must be no-op for flyweight layout states because they should have their values up-to-date since their construction without ever calling this method.
The view is responsible for repainting itself if that's necessary. Prior to asking the component to repaint the appropriate region

viewPreferenceChanged

void viewPreferenceChanged(boolean width,
                           boolean height)

Notify this layout state that the preferences has changed for the view that it wraps.
This gets called in response to the wrapped view calling View.preferenceChanged() in its parent.
Usually this method only makes sense when the layout state is a generic wrapper around a black-box view. If layout state and the view are one object then this method is usually no-op.
The layout state should just mark its internal state as changed but wait for layout update (that will be called by parent) to update the layout variables.
This method must be no-op for flyweight layout states.

Parameters:: width - true if the width preference has changed; height - true if the height preference has changed

markViewSizeInvalid

void markViewSizeInvalid()

Parent calls this method to mark the current size of the view as invalid so that the next layout update of this layout state will call View.setSize() using getLayoutMajorAxisPreferredSpan() for major axis span and ViewLayoutState.Parent.getMinorAxisSpan(ViewLayoutState) for minor axis span.
Parent is responsible for scheduling of layout update for the child after calling this method.
This method must be no-op for flyweight layout states.

isLayoutValid

boolean isLayoutValid()

Check whether there are any layout duties present.

Returns:: true if there are no layout duties or false if the layout needs to be udpated.
Flyweight layout states must always return true here.