*
|
*
|
*
* Nesting multiple panels with different combinations of horizontal and * vertical gives an effect similar to GridBagLayout, without the * complexity. The diagram shows two panels arranged horizontally, each * of which contains 3 components arranged vertically. * *
The BoxLayout manager is constructed with an axis parameter that * specifies the type of layout that will be done. There are four choices: * *
X_AXIS - Components are laid out horizontally * from left to right.* *
Y_AXIS - Components are laid out vertically * from top to bottom.* *
LINE_AXIS - Components are laid out the way * words are laid out in a line, based on the container's * ComponentOrientation property. If the container's * ComponentOrientation is horizontal then components are laid out * horizontally, otherwise they are laid out vertically. For horizontal * orientations, if the container's ComponentOrientation is left to * right then components are laid out left to right, otherwise they are laid * out right to left. For vertical orientations components are always laid out * from top to bottom.* *
PAGE_AXIS - Components are laid out the way * text lines are laid out on a page, based on the container's * ComponentOrientation property. If the container's * ComponentOrientation is horizontal then components are laid out * vertically, otherwise they are laid out horizontally. For horizontal * orientations, if the container's ComponentOrientation is left to * right then components are laid out left to right, otherwise they are laid * out right to left. For vertical orientations components are always * laid out from top to bottom.*
* For all directions, components are arranged in the same order as they were * added to the container. *
* BoxLayout attempts to arrange components * at their preferred widths (for horizontal layout) * or heights (for vertical layout). * For a horizontal layout, * if not all the components are the same height, * BoxLayout attempts to make all the components * as high as the highest component. * If that's not possible for a particular component, * then BoxLayout aligns that component vertically, * according to the component's Y alignment. * By default, a component has a Y alignment of 0.5, * which means that the vertical center of the component * should have the same Y coordinate as * the vertical centers of other components with 0.5 Y alignment. *
* Similarly, for a vertical layout,
* BoxLayout attempts to make all components in the column
* as wide as the widest component.
* If that fails, it aligns them horizontally
* according to their X alignments. For PAGE_AXIS layout,
* horizontal alignment is done based on the leading edge of the component.
* In other words, an X alignment value of 0.0 means the left edge of a
* component if the container's ComponentOrientation is left to
* right and it means the right edge of the component otherwise.
*
* Instead of using BoxLayout directly, many programs use the Box class. * The Box class is a lightweight container that uses a BoxLayout. * It also provides handy methods to help you use BoxLayout well. * Adding components to multiple nested boxes is a powerful way to get * the arrangement you want. *
* For further information and examples see * How to Use BoxLayout, * a section in The Java Tutorial. *
* Warning:
* Serialized objects of this class will not be compatible with
* future Swing releases. The current serialization support is
* appropriate for short term storage or RMI between applications running
* the same version of Swing. As of 1.4, support for long term storage
* of all JavaBeansTM
* has been added to the java.beans package.
* Please see {@link java.beans.XMLEncoder}.
*
* @see Box
* @see java.awt.ComponentOrientation
* @see JComponent#getAlignmentX
* @see JComponent#getAlignmentY
*
* @author Timothy Prinzing
*/
@SuppressWarnings("serial")
public class BoxLayout implements LayoutManager2, Serializable {
/**
* Specifies that components should be laid out left to right.
*/
public static final int X_AXIS = 0;
/**
* Specifies that components should be laid out top to bottom.
*/
public static final int Y_AXIS = 1;
/**
* Specifies that components should be laid out in the direction of
* a line of text as determined by the target container's
* ComponentOrientation property.
*/
public static final int LINE_AXIS = 2;
/**
* Specifies that components should be laid out in the direction that
* lines flow across a page as determined by the target container's
* ComponentOrientation property.
*/
public static final int PAGE_AXIS = 3;
/**
* Creates a layout manager that will lay out components along the
* given axis.
*
* @param target the container that needs to be laid out
* @param axis the axis to lay out components along. Can be one of:
* BoxLayout.X_AXIS,
* BoxLayout.Y_AXIS,
* BoxLayout.LINE_AXIS or
* BoxLayout.PAGE_AXIS
*
* @exception AWTError if the value of axis is invalid
*/
@ConstructorProperties({"target", "axis"})
public BoxLayout(Container target, int axis) {
if (axis != X_AXIS && axis != Y_AXIS &&
axis != LINE_AXIS && axis != PAGE_AXIS) {
throw new AWTError("Invalid axis");
}
this.axis = axis;
this.target = target;
}
/**
* Constructs a BoxLayout that
* produces debugging messages.
*
* @param target the container that needs to be laid out
* @param axis the axis to lay out components along. Can be one of:
* BoxLayout.X_AXIS,
* BoxLayout.Y_AXIS,
* BoxLayout.LINE_AXIS or
* BoxLayout.PAGE_AXIS
*
* @param dbg the stream to which debugging messages should be sent,
* null if none
*/
BoxLayout(Container target, int axis, PrintStream dbg) {
this(target, axis);
this.dbg = dbg;
}
/**
* Returns the container that uses this layout manager.
*
* @return the container that uses this layout manager
*
* @since 1.6
*/
public final Container getTarget() {
return this.target;
}
/**
* Returns the axis that was used to lay out components.
* Returns one of:
* BoxLayout.X_AXIS,
* BoxLayout.Y_AXIS,
* BoxLayout.LINE_AXIS or
* BoxLayout.PAGE_AXIS
*
* @return the axis that was used to lay out components
*
* @since 1.6
*/
public final int getAxis() {
return this.axis;
}
/**
* Indicates that a child has changed its layout related information,
* and thus any cached calculations should be flushed.
*
* This method is called by AWT when the invalidate method is called * on the Container. Since the invalidate method may be called * asynchronously to the event thread, this method may be called * asynchronously. * * @param target the affected container * * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor */ public synchronized void invalidateLayout(Container target) { checkContainer(target); xChildren = null; yChildren = null; xTotal = null; yTotal = null; } /** * Not used by this class. * * @param name the name of the component * @param comp the component */ public void addLayoutComponent(String name, Component comp) { invalidateLayout(comp.getParent()); } /** * Not used by this class. * * @param comp the component */ public void removeLayoutComponent(Component comp) { invalidateLayout(comp.getParent()); } /** * Not used by this class. * * @param comp the component * @param constraints constraints */ public void addLayoutComponent(Component comp, Object constraints) { invalidateLayout(comp.getParent()); } /** * Returns the preferred dimensions for this layout, given the components * in the specified target container. * * @param target the container that needs to be laid out * @return the dimensions >= 0 && <= Integer.MAX_VALUE * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor * @see Container * @see #minimumLayoutSize * @see #maximumLayoutSize */ public Dimension preferredLayoutSize(Container target) { Dimension size; synchronized(this) { checkContainer(target); checkRequests(); size = new Dimension(xTotal.preferred, yTotal.preferred); } Insets insets = target.getInsets(); size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); return size; } /** * Returns the minimum dimensions needed to lay out the components * contained in the specified target container. * * @param target the container that needs to be laid out * @return the dimensions >= 0 && <= Integer.MAX_VALUE * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor * @see #preferredLayoutSize * @see #maximumLayoutSize */ public Dimension minimumLayoutSize(Container target) { Dimension size; synchronized(this) { checkContainer(target); checkRequests(); size = new Dimension(xTotal.minimum, yTotal.minimum); } Insets insets = target.getInsets(); size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); return size; } /** * Returns the maximum dimensions the target container can use * to lay out the components it contains. * * @param target the container that needs to be laid out * @return the dimenions >= 0 && <= Integer.MAX_VALUE * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor * @see #preferredLayoutSize * @see #minimumLayoutSize */ public Dimension maximumLayoutSize(Container target) { Dimension size; synchronized(this) { checkContainer(target); checkRequests(); size = new Dimension(xTotal.maximum, yTotal.maximum); } Insets insets = target.getInsets(); size.width = (int) Math.min((long) size.width + (long) insets.left + (long) insets.right, Integer.MAX_VALUE); size.height = (int) Math.min((long) size.height + (long) insets.top + (long) insets.bottom, Integer.MAX_VALUE); return size; } /** * Returns the alignment along the X axis for the container. * If the box is horizontal, the default * alignment will be returned. Otherwise, the alignment needed * to place the children along the X axis will be returned. * * @param target the container * @return the alignment >= 0.0f && <= 1.0f * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor */ public synchronized float getLayoutAlignmentX(Container target) { checkContainer(target); checkRequests(); return xTotal.alignment; } /** * Returns the alignment along the Y axis for the container. * If the box is vertical, the default * alignment will be returned. Otherwise, the alignment needed * to place the children along the Y axis will be returned. * * @param target the container * @return the alignment >= 0.0f && <= 1.0f * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor */ public synchronized float getLayoutAlignmentY(Container target) { checkContainer(target); checkRequests(); return yTotal.alignment; } /** * Called by the AWT when the specified container * needs to be laid out. * * @param target the container to lay out * * @exception AWTError if the target isn't the container specified to the * BoxLayout constructor */ public void layoutContainer(Container target) { checkContainer(target); int nChildren = target.getComponentCount(); int[] xOffsets = new int[nChildren]; int[] xSpans = new int[nChildren]; int[] yOffsets = new int[nChildren]; int[] ySpans = new int[nChildren]; Dimension alloc = target.getSize(); Insets in = target.getInsets(); alloc.width -= in.left + in.right; alloc.height -= in.top + in.bottom; // Resolve axis to an absolute value (either X_AXIS or Y_AXIS) ComponentOrientation o = target.getComponentOrientation(); int absoluteAxis = resolveAxis( axis, o ); boolean ltr = (absoluteAxis != axis) ? o.isLeftToRight() : true; // determine the child placements synchronized(this) { checkRequests(); if (absoluteAxis == X_AXIS) { SizeRequirements.calculateTiledPositions(alloc.width, xTotal, xChildren, xOffsets, xSpans, ltr); SizeRequirements.calculateAlignedPositions(alloc.height, yTotal, yChildren, yOffsets, ySpans); } else { SizeRequirements.calculateAlignedPositions(alloc.width, xTotal, xChildren, xOffsets, xSpans, ltr); SizeRequirements.calculateTiledPositions(alloc.height, yTotal, yChildren, yOffsets, ySpans); } } // flush changes to the container for (int i = 0; i < nChildren; i++) { Component c = target.getComponent(i); c.setBounds((int) Math.min((long) in.left + (long) xOffsets[i], Integer.MAX_VALUE), (int) Math.min((long) in.top + (long) yOffsets[i], Integer.MAX_VALUE), xSpans[i], ySpans[i]); } if (dbg != null) { for (int i = 0; i < nChildren; i++) { Component c = target.getComponent(i); dbg.println(c.toString()); dbg.println("X: " + xChildren[i]); dbg.println("Y: " + yChildren[i]); } } } void checkContainer(Container target) { if (this.target != target) { throw new AWTError("BoxLayout can't be shared"); } } void checkRequests() { if (xChildren == null || yChildren == null) { // The requests have been invalidated... recalculate // the request information. int n = target.getComponentCount(); xChildren = new SizeRequirements[n]; yChildren = new SizeRequirements[n]; for (int i = 0; i < n; i++) { Component c = target.getComponent(i); if (!c.isVisible()) { xChildren[i] = new SizeRequirements(0,0,0, c.getAlignmentX()); yChildren[i] = new SizeRequirements(0,0,0, c.getAlignmentY()); continue; } Dimension min = c.getMinimumSize(); Dimension typ = c.getPreferredSize(); Dimension max = c.getMaximumSize(); xChildren[i] = new SizeRequirements(min.width, typ.width, max.width, c.getAlignmentX()); yChildren[i] = new SizeRequirements(min.height, typ.height, max.height, c.getAlignmentY()); } // Resolve axis to an absolute value (either X_AXIS or Y_AXIS) int absoluteAxis = resolveAxis(axis,target.getComponentOrientation()); if (absoluteAxis == X_AXIS) { xTotal = SizeRequirements.getTiledSizeRequirements(xChildren); yTotal = SizeRequirements.getAlignedSizeRequirements(yChildren); } else { xTotal = SizeRequirements.getAlignedSizeRequirements(xChildren); yTotal = SizeRequirements.getTiledSizeRequirements(yChildren); } } } /** * Given one of the 4 axis values, resolve it to an absolute axis. * The relative axis values, PAGE_AXIS and LINE_AXIS are converted * to their absolute couterpart given the target's ComponentOrientation * value. The absolute axes, X_AXIS and Y_AXIS are returned unmodified. * * @param axis the axis to resolve * @param o the ComponentOrientation to resolve against * @return the resolved axis */ private int resolveAxis( int axis, ComponentOrientation o ) { int absoluteAxis; if( axis == LINE_AXIS ) { absoluteAxis = o.isHorizontal() ? X_AXIS : Y_AXIS; } else if( axis == PAGE_AXIS ) { absoluteAxis = o.isHorizontal() ? Y_AXIS : X_AXIS; } else { absoluteAxis = axis; } return absoluteAxis; } private int axis; private Container target; private transient SizeRequirements[] xChildren; private transient SizeRequirements[] yChildren; private transient SizeRequirements xTotal; private transient SizeRequirements yTotal; private transient PrintStream dbg; }