Save This Page
Home » openjdk-7 » javax » swing » [javadoc | source]
javax.swing
public class: GroupLayout [javadoc | source]
java.lang.Object
   javax.swing.GroupLayout

All Implemented Interfaces:
    LayoutManager2

{@code GroupLayout} is a {@code LayoutManager} that hierarchically groups components in order to position them in a {@code Container}. {@code GroupLayout} is intended for use by builders, but may be hand-coded as well. Grouping is done by instances of the Group class. {@code GroupLayout} supports two types of groups. A sequential group positions its child elements sequentially, one after another. A parallel group aligns its child elements in one of four ways.

Each group may contain any number of elements, where an element is a {@code Group}, {@code Component}, or gap. A gap can be thought of as an invisible component with a minimum, preferred and maximum size. In addition {@code GroupLayout} supports a preferred gap, whose value comes from {@code LayoutStyle}.

Elements are similar to a spring. Each element has a range as specified by a minimum, preferred and maximum. Gaps have either a developer-specified range, or a range determined by {@code LayoutStyle}. The range for {@code Component}s is determined from the {@code Component}'s {@code getMinimumSize}, {@code getPreferredSize} and {@code getMaximumSize} methods. In addition, when adding {@code Component}s you may specify a particular range to use instead of that from the component. The range for a {@code Group} is determined by the type of group. A {@code ParallelGroup}'s range is the maximum of the ranges of its elements. A {@code SequentialGroup}'s range is the sum of the ranges of its elements.

{@code GroupLayout} treats each axis independently. That is, there is a group representing the horizontal axis, and a group representing the vertical axis. The horizontal group is responsible for determining the minimum, preferred and maximum size along the horizontal axis as well as setting the x and width of the components contained in it. The vertical group is responsible for determining the minimum, preferred and maximum size along the vertical axis as well as setting the y and height of the components contained in it. Each {@code Component} must exist in both a horizontal and vertical group, otherwise an {@code IllegalStateException} is thrown during layout, or when the minimum, preferred or maximum size is requested.

The following diagram shows a sequential group along the horizontal axis. The sequential group contains three components. A parallel group was used along the vertical axis.

To reinforce that each axis is treated independently the diagram shows the range of each group and element along each axis. The range of each component has been projected onto the axes, and the groups are rendered in blue (horizontal) and red (vertical). For readability there is a gap between each of the elements in the sequential group.

The sequential group along the horizontal axis is rendered as a solid blue line. Notice the sequential group is the sum of the children elements it contains.

Along the vertical axis the parallel group is the maximum of the height of each of the components. As all three components have the same height, the parallel group has the same height.

The following diagram shows the same three components, but with the parallel group along the horizontal axis and the sequential group along the vertical axis.

As {@code c1} is the largest of the three components, the parallel group is sized to {@code c1}. As {@code c2} and {@code c3} are smaller than {@code c1} they are aligned based on the alignment specified for the component (if specified) or the default alignment of the parallel group. In the diagram {@code c2} and {@code c3} were created with an alignment of {@code LEADING}. If the component orientation were right-to-left then {@code c2} and {@code c3} would be positioned on the opposite side.

The following diagram shows a sequential group along both the horizontal and vertical axis.

{@code GroupLayout} provides the ability to insert gaps between {@code Component}s. The size of the gap is determined by an instance of {@code LayoutStyle}. This may be turned on using the {@code setAutoCreateGaps} method. Similarly, you may use the {@code setAutoCreateContainerGaps} method to insert gaps between components that touch the edge of the parent container and the container.

The following builds a panel consisting of two labels in one column, followed by two textfields in the next column:

  JComponent panel = ...;
  GroupLayout layout = new GroupLayout(panel);
  panel.setLayout(layout);

  // Turn on automatically adding gaps between components
  layout.setAutoCreateGaps(true);

  // Turn on automatically creating gaps between components that touch
  // the edge of the container and the container.
  layout.setAutoCreateContainerGaps(true);

  // Create a sequential group for the horizontal axis.

  GroupLayout.SequentialGroup hGroup = layout.createSequentialGroup();

  // The sequential group in turn contains two parallel groups.
  // One parallel group contains the labels, the other the text fields.
  // Putting the labels in a parallel group along the horizontal axis
  // positions them at the same x location.
  //
  // Variable indentation is used to reinforce the level of grouping.
  hGroup.addGroup(layout.createParallelGroup().
           addComponent(label1).addComponent(label2));
  hGroup.addGroup(layout.createParallelGroup().
           addComponent(tf1).addComponent(tf2));
  layout.setHorizontalGroup(hGroup);

  // Create a sequential group for the vertical axis.
  GroupLayout.SequentialGroup vGroup = layout.createSequentialGroup();

  // The sequential group contains two parallel groups that align
  // the contents along the baseline. The first parallel group contains
  // the first label and text field, and the second parallel group contains
  // the second label and text field. By using a sequential group
  // the labels and text fields are positioned vertically after one another.
  vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE).
           addComponent(label1).addComponent(tf1));
  vGroup.addGroup(layout.createParallelGroup(Alignment.BASELINE).
           addComponent(label2).addComponent(tf2));
  layout.setVerticalGroup(vGroup);

When run the following is produced.

This layout consists of the following.

There are a couple of things to notice in this code:
Nested Class Summary:
public enum class  GroupLayout.Alignment  Enumeration of the possible ways {@code ParallelGroup} can align its children. 
abstract public class  GroupLayout.Group  {@code Group} provides the basis for the two types of operations supported by {@code GroupLayout}: laying out components one after another ({@link SequentialGroup SequentialGroup}) or aligned ({@link ParallelGroup ParallelGroup}). {@code Group} and its subclasses have no public constructor; to create one use one of {@code createSequentialGroup} or {@code createParallelGroup}. Additionally, taking a {@code Group} created from one {@code GroupLayout} and using it with another will produce undefined results.

Various methods in {@code Group} and its subclasses allow you to explicitly specify the range. The arguments to these methods can take two forms, either a value greater than or equal to 0, or one of {@code DEFAULT_SIZE} or {@code PREFERRED_SIZE}. A value greater than or equal to {@code 0} indicates a specific size. {@code DEFAULT_SIZE} indicates the corresponding size from the component should be used. For example, if {@code DEFAULT_SIZE} is passed as the minimum size argument, the minimum size is obtained from invoking {@code getMinimumSize} on the component. Likewise, {@code PREFERRED_SIZE} indicates the value from {@code getPreferredSize} should be used. The following example adds {@code myComponent} to {@code group} with specific values for the range. That is, the minimum is explicitly specified as 100, preferred as 200, and maximum as 300.

  group.addComponent(myComponent, 100, 200, 300);
The following example adds {@code myComponent} to {@code group} using a combination of the forms. The minimum size is forced to be the same as the preferred size, the preferred size is determined by using {@code myComponent.getPreferredSize} and the maximum is determined by invoking {@code getMaximumSize} on the component.
  group.addComponent(myComponent, GroupLayout.PREFERRED_SIZE,
            GroupLayout.PREFERRED_SIZE, GroupLayout.DEFAULT_SIZE);

Unless otherwise specified all the methods of {@code Group} and its subclasses that allow you to specify a range throw an {@code IllegalArgumentException} if passed an invalid range. An invalid range is one in which any of the values are < 0 and not one of {@code PREFERRED_SIZE} or {@code DEFAULT_SIZE}, or the following is not met (for specific values): {@code min} <= {@code pref} <= {@code max}.

Similarly any methods that take a {@code Component} throw a {@code IllegalArgumentException} if passed {@code null} and any methods that take a {@code Group} throw an {@code NullPointerException} if passed {@code null}. 

public class  GroupLayout.SequentialGroup  A {@code Group} that positions and sizes its elements sequentially, one after another. This class has no public constructor, use the {@code createSequentialGroup} method to create one.

In order to align a {@code SequentialGroup} along the baseline of a baseline aligned {@code ParallelGroup} you need to specify which of the elements of the {@code SequentialGroup} is used to determine the baseline. The element used to calculate the baseline is specified using one of the {@code add} methods that take a {@code boolean}. The last element added with a value of {@code true} for {@code useAsBaseline} is used to calculate the baseline. 

public class  GroupLayout.ParallelGroup  A {@code Group} that aligns and sizes it's children. {@code ParallelGroup} aligns it's children in four possible ways: along the baseline, centered, anchored to the leading edge, or anchored to the trailing edge.

Baseline

A {@code ParallelGroup} that aligns it's children along the baseline must first decide where the baseline is anchored. The baseline can either be anchored to the top, or anchored to the bottom of the group. That is, the distance between the baseline and the beginning of the group can be a constant distance, or the distance between the end of the group and the baseline can be a constant distance. The possible choices correspond to the {@code BaselineResizeBehavior} constants {@link java.awt.Component.BaselineResizeBehavior#CONSTANT_ASCENT CONSTANT_ASCENT} and {@link java.awt.Component.BaselineResizeBehavior#CONSTANT_DESCENT CONSTANT_DESCENT}.

The baseline anchor may be explicitly specified by the {@code createBaselineGroup} method, or determined based on the elements. If not explicitly specified, the baseline will be anchored to the bottom if all the elements with a baseline, and that are aligned to the baseline, have a baseline resize behavior of {@code CONSTANT_DESCENT}; otherwise the baseline is anchored to the top of the group.

Elements aligned to the baseline are resizable if they have have a baseline resize behavior of {@code CONSTANT_ASCENT} or {@code CONSTANT_DESCENT}. Elements with a baseline resize behavior of {@code OTHER} or {@code CENTER_OFFSET} are not resizable.

The baseline is calculated based on the preferred height of each of the elements that have a baseline. The baseline is calculated using the following algorithm: {@code max(maxNonBaselineHeight, maxAscent + maxDescent)}, where the {@code maxNonBaselineHeight} is the maximum height of all elements that do not have a baseline, or are not aligned along the baseline. {@code maxAscent} is the maximum ascent (baseline) of all elements that have a baseline and are aligned along the baseline. {@code maxDescent} is the maximum descent (preferred height - baseline) of all elements that have a baseline and are aligned along the baseline.

A {@code ParallelGroup} that aligns it's elements along the baseline is only useful along the vertical axis. If you create a baseline group and use it along the horizontal axis an {@code IllegalStateException} is thrown when you ask {@code GroupLayout} for the minimum, preferred or maximum size or attempt to layout the components.

Elements that are not aligned to the baseline and smaller than the size of the {@code ParallelGroup} are positioned in one of three ways: centered, anchored to the leading edge, or anchored to the trailing edge.

Non-baseline {@code ParallelGroup}

{@code ParallelGroup}s created with an alignment other than {@code BASELINE} align elements that are smaller than the size of the group in one of three ways: centered, anchored to the leading edge, or anchored to the trailing edge.

The leading edge is based on the axis and {@code ComponentOrientation}. For the vertical axis the top edge is always the leading edge, and the bottom edge is always the trailing edge. When the {@code ComponentOrientation} is {@code LEFT_TO_RIGHT}, the leading edge is the left edge and the trailing edge the right edge. A {@code ComponentOrientation} of {@code RIGHT_TO_LEFT} flips the left and right edges. Child elements are aligned based on the specified alignment the element was added with. If you do not specify an alignment, the alignment specified for the {@code ParallelGroup} is used.

To align elements along the baseline you {@code createBaselineGroup}, or {@code createParallelGroup} with an alignment of {@code BASELINE}. If the group was not created with a baseline alignment, and you attempt to add an element specifying a baseline alignment, an {@code IllegalArgumentException} is thrown. 

Field Summary
public static final  int DEFAULT_SIZE    Indicates the size from the component or gap should be used for a particular range value. 
public static final  int PREFERRED_SIZE    Indicates the preferred size from the component or gap should be used for a particular range value. 
Constructor:
 public GroupLayout(Container host) 
    Creates a {@code GroupLayout} for the specified {@code Container}.
    Parameters:
    host - the {@code Container} the {@code GroupLayout} is the {@code LayoutManager} for
    Throws:
    IllegalArgumentException - if host is {@code null}
Method from javax.swing.GroupLayout Summary:
addLayoutComponent,   addLayoutComponent,   createBaselineGroup,   createParallelGroup,   createParallelGroup,   createParallelGroup,   createSequentialGroup,   getAutoCreateContainerGaps,   getAutoCreateGaps,   getHonorsVisibility,   getLayoutAlignmentX,   getLayoutAlignmentY,   getLayoutStyle,   invalidateLayout,   layoutContainer,   linkSize,   linkSize,   maximumLayoutSize,   minimumLayoutSize,   preferredLayoutSize,   removeLayoutComponent,   replace,   setAutoCreateContainerGaps,   setAutoCreateGaps,   setHonorsVisibility,   setHonorsVisibility,   setHorizontalGroup,   setLayoutStyle,   setVerticalGroup,   toString
Methods from java.lang.Object:
clone,   equals,   finalize,   getClass,   hashCode,   notify,   notifyAll,   toString,   wait,   wait,   wait
Method from javax.swing.GroupLayout Detail:
 public  void addLayoutComponent(String name,
    Component component) 
    Notification that a {@code Component} has been added to the parent container. You should not invoke this method directly, instead you should use one of the {@code Group} methods to add a {@code Component}.
 public  void addLayoutComponent(Component component,
    Object constraints) 
    Notification that a {@code Component} has been added to the parent container. You should not invoke this method directly, instead you should use one of the {@code Group} methods to add a {@code Component}.
 public ParallelGroup createBaselineGroup(boolean resizable,
    boolean anchorBaselineToTop) 
    Creates and returns a {@code ParallelGroup} that aligns it's elements along the baseline.
 public ParallelGroup createParallelGroup() 
    Creates and returns a {@code ParallelGroup} with an alignment of {@code Alignment.LEADING}. This is a cover method for the more general {@code createParallelGroup(Alignment)} method.
 public ParallelGroup createParallelGroup(Alignment alignment) 
    Creates and returns a {@code ParallelGroup} with the specified alignment. This is a cover method for the more general {@code createParallelGroup(Alignment,boolean)} method with {@code true} supplied for the second argument.
 public ParallelGroup createParallelGroup(Alignment alignment,
    boolean resizable) 
    Creates and returns a {@code ParallelGroup} with the specified alignment and resize behavior. The {@code alignment} argument specifies how children elements are positioned that do not fill the group. For example, if a {@code ParallelGroup} with an alignment of {@code TRAILING} is given 100 and a child only needs 50, the child is positioned at the position 50 (with a component orientation of left-to-right).

    Baseline alignment is only useful when used along the vertical axis. A {@code ParallelGroup} created with a baseline alignment along the horizontal axis is treated as {@code LEADING}.

    Refer to ParallelGroup for details on the behavior of baseline groups.

 public SequentialGroup createSequentialGroup() 
    Creates and returns a {@code SequentialGroup}.
 public boolean getAutoCreateContainerGaps() 
    Returns {@code true} if gaps between the container and components that border the container are automatically created.
 public boolean getAutoCreateGaps() 
    Returns {@code true} if gaps between components are automatically created.
 public boolean getHonorsVisibility() 
    Returns whether component visiblity is considered when sizing and positioning components.
 public float getLayoutAlignmentX(Container parent) 
    Returns the alignment along the x axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.
 public float getLayoutAlignmentY(Container parent) 
    Returns the alignment along the y axis. This specifies how the component would like to be aligned relative to other components. The value should be a number between 0 and 1 where 0 represents alignment along the origin, 1 is aligned the furthest away from the origin, 0.5 is centered, etc.
 public LayoutStyle getLayoutStyle() 
    Returns the {@code LayoutStyle} used for calculating the preferred gap between components. This returns the value specified to {@code setLayoutStyle}, which may be {@code null}.
 public  void invalidateLayout(Container parent) 
    Invalidates the layout, indicating that if the layout manager has cached information it should be discarded.
 public  void layoutContainer(Container parent) 
    Lays out the specified container.
 public  void linkSize(Component components) 
    Forces the specified components to have the same size regardless of their preferred, minimum or maximum sizes. Components that are linked are given the maximum of the preferred size of each of the linked components. For example, if you link two components with a preferred width of 10 and 20, both components are given a width of 20.

    This can be used multiple times to force any number of components to share the same size.

    Linked Components are not be resizable.

 public  void linkSize(int axis,
    Component components) 
    Forces the specified components to have the same size along the specified axis regardless of their preferred, minimum or maximum sizes. Components that are linked are given the maximum of the preferred size of each of the linked components. For example, if you link two components along the horizontal axis and the preferred width is 10 and 20, both components are given a width of 20.

    This can be used multiple times to force any number of components to share the same size.

    Linked {@code Component}s are not be resizable.

 public Dimension maximumLayoutSize(Container parent) 
    Returns the maximum size for the specified container.
 public Dimension minimumLayoutSize(Container parent) 
    Returns the minimum size for the specified container.
 public Dimension preferredLayoutSize(Container parent) 
    Returns the preferred size for the specified container.
 public  void removeLayoutComponent(Component component) 
    Notification that a {@code Component} has been removed from the parent container. You should not invoke this method directly, instead invoke {@code remove} on the parent {@code Container}.
 public  void replace(Component existingComponent,
    Component newComponent) 
    Replaces an existing component with a new one.
 public  void setAutoCreateContainerGaps(boolean autoCreateContainerPadding) 
    Sets whether a gap between the container and components that touch the border of the container should automatically be created. The default is {@code false}.
 public  void setAutoCreateGaps(boolean autoCreatePadding) 
    Sets whether a gap between components should automatically be created. For example, if this is {@code true} and you add two components to a {@code SequentialGroup} a gap between the two components is automatically be created. The default is {@code false}.
 public  void setHonorsVisibility(boolean honorsVisibility) 
    Sets whether component visiblity is considered when sizing and positioning components. A value of {@code true} indicates that non-visible components should not be treated as part of the layout. A value of {@code false} indicates that components should be positioned and sized regardless of visibility.

    A value of {@code false} is useful when the visibility of components is dynamically adjusted and you don't want surrounding components and the sizing to change.

    The specified value is used for components that do not have an explicit visibility specified.

    The default is {@code true}.

 public  void setHonorsVisibility(Component component,
    Boolean honorsVisibility) 
    Sets whether the component's visiblity is considered for sizing and positioning. A value of {@code Boolean.TRUE} indicates that if {@code component} is not visible it should not be treated as part of the layout. A value of {@code false} indicates that {@code component} is positioned and sized regardless of it's visibility. A value of {@code null} indicates the value specified by the single argument method {@code setHonorsVisibility} should be used.

    If {@code component} is not a child of the {@code Container} this {@code GroupLayout} is managine, it will be added to the {@code Container}.

 public  void setHorizontalGroup(Group group) 
    Sets the {@code Group} that positions and sizes components along the horizontal axis.
 public  void setLayoutStyle(LayoutStyle layoutStyle) 
    Sets the {@code LayoutStyle} used to calculate the preferred gaps between components. A value of {@code null} indicates the shared instance of {@code LayoutStyle} should be used.
 public  void setVerticalGroup(Group group) 
    Sets the {@code Group} that positions and sizes components along the vertical axis.
 public String toString() 
    Returns a string representation of this {@code GroupLayout}. This method is intended to be used for debugging purposes, and the content and format of the returned string may vary between implementations.