A view that arranges its children into a box shape by tiling
its children along an axis. The box is somewhat like that
found in TeX where there is alignment of the
children, flexibility of the children is considered, etc.
This is a building block that might be useful to represent
things like a collection of lines, paragraphs,
lists, columns, pages, etc. The axis along which the children are tiled is
considered the major axis. The orthogonal axis is the minor axis.

Layout for each axis is handled separately by the methods
layoutMajorAxis and layoutMinorAxis.
Subclasses can change the layout algorithm by
reimplementing these methods. These methods will be called
as necessary depending upon whether or not there is cached
layout information and the cache is considered
valid. These methods are typically called if the given size
along the axis changes, or if layoutChanged is
called to force an updated layout. The layoutChanged
method invalidates cached layout information, if there is any.
The requirements published to the parent view are calculated by
the methods calculateMajorAxisRequirements
and calculateMinorAxisRequirements.
If the layout algorithm is changed, these methods will
likely need to be reimplemented.

BoxView

Method Detail

getAxis

Fetches the tile axis property. This is the axis along which
the child views are tiled.

Returns:

the major axis of the box, either
View.X_AXIS or View.Y_AXIS

Since:

1.3

setAxis

public void setAxis(int axis)

Sets the tile axis property. This is the axis along which
the child views are tiled.

Parameters:

axis - either View.X_AXIS or View.Y_AXIS

Since:

1.3

layoutChanged

public void layoutChanged(int axis)

Invalidates the layout along an axis. This happens
automatically if the preferences have changed for
any of the child views. In some cases the layout
may need to be recalculated when the preferences
have not changed. The layout can be marked as
invalid by calling this method. The layout will
be updated the next time the setSize method
is called on this view (typically in paint).

forwardUpdate

Forwards the given DocumentEvent to the child views
that need to be notified of the change to the model.
If a child changed its requirements and the allocation
was valid prior to forwarding the portion of the box
from the starting child to the end of the box will
be repainted.

preferenceChanged

This is called by a child to indicate its
preferred span has changed. This is implemented to
throw away cached layout information so that new
calculations will be done the next time the children
need an allocation.

getChildAllocation

Fetches the allocation for the given child view.
This enables finding out where various views
are located. This is implemented to return
null if the layout is invalid,
otherwise the superclass behavior is executed.

getAlignment

public float getAlignment(int axis)

Determines the desired alignment for this view along an
axis. This is implemented to give the total alignment
needed to position the children with the alignment points
lined up along the axis orthogonal to the axis that is
being tiled. The axis being tiled will request to be
centered (i.e. 0.5f).

the desired alignment >= 0.0f && <= 1.0f; this should
be a value between 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

the span the view would like to be rendered into >= 0;
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

getMinimumSpan

the span the view would like to be rendered into >= 0;
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

getMaximumSpan

the span the view would like to be rendered into >= 0;
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

layoutMajorAxis

Performs layout for the major axis of the box (i.e. the
axis that it represents). The results of the layout (the
offset and span for each children) are placed in the given
arrays which represent the allocations to the children
along the major axis.

Parameters:

targetSpan - the total span given to the view, which
would be used to layout the children

axis - the axis being layed out

offsets - the offsets from the origin of the view for
each of the child views; this is a return value and is
filled in by the implementation of this method

spans - the span of each child view; this is a return
value and is filled in by the implementation of this method

layoutMinorAxis

Performs layout for the minor axis of the box (i.e. the
axis orthogonal to the axis that it represents). The results
of the layout (the offset and span for each children) are
placed in the given arrays which represent the allocations to
the children along the minor axis.

Parameters:

targetSpan - the total span given to the view, which
would be used to layout the children

axis - the axis being layed out

offsets - the offsets from the origin of the view for
each of the child views; this is a return value and is
filled in by the implementation of this method

spans - the span of each child view; this is a return
value and is filled in by the implementation of this method

flipEastAndWestAtEnds

Determines in which direction the next view lays.
Consider the View at index n. Typically the Views
are layed out from left to right, so that the View
to the EAST will be at index n + 1, and the View
to the WEST will be at index n - 1. In certain situations,
such as with bidirectional text, it is possible
that the View to EAST is not at index n + 1,
but rather at index n - 1, or that the View
to the WEST is not at index n - 1, but index n + 1.
In this case this method would return true,
indicating the Views are layed out in
descending order. Otherwise the method would return false
indicating the Views are layed out in ascending order.

If the receiver is laying its Views along the
Y_AXIS, this will will return the value from
invoking the same method on the View
responsible for rendering position and
bias. Otherwise this will return false.