How to use PileLayout

Table of contents

Introduction
Gaps and margins
Placement
Reissuing
License

Introduction

A PileLayout is a layout manager that piles components either vertically or horizontally. Components are laid out with their preferred with and height, aligned or resized according to the constraints used.

Gap and margins

Components are laid out in a pile, leaving space between components (gaps) and from the boundaries of the container and the components inside (margins).


PileLayout offers a combination of constructors to allow to specify any combination of gap and margins:

PileLayout(int direction)
a default value is used as gap and for all margins
PileLayout(int direction, int gap)
the specified value is used as gap and for all margins
PileLayout(int direction, Insets margins)
a default value is used as gap along with the specified margins
PileLayout(int direction, int gap, Insets margins)
the specified value is used as gap along with the specified margins

In most cases the default configuration can be used, without worrying about margins and gaps.

Alignment

Let's create a JFrame whose content pane layout is a PileLayout arranged horizontally:

    JFrame f = new JFrame("PileLayout Horizontal Test");
f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
Container c = f.getContentPane();
c.setLayout(new PileLayout(PileLayout.DIRECTION_HORIZONTAL));

Components will be disposed horizontally in the container one aside the other. Now let's add some components:

    JLabel label;
label = new JLabel("Top aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_TOP);
label = new JLabel("Middle aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_MIDDLE);
label = new JLabel("Bottom aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_BOTTOM);
label = new JLabel("Fitted");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_FIT);
label = new JLabel("Expanded");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_EXPAND);
f.pack();
f.setSize(f.getSize().width + 50, f.getSize().height + 50);
f.setVisible(true);

The above code creates the following frame:

A border has been added to the labels (through the setBorder method, you can see it in the code) to better see how the placement works. The five labels added to the container have different constraints, to show how the five different constraints constants work. The first label is top aligned (this is the default, if you don't specify a constraints object), the second is centered vertically, the third is bottom aligned. The fourth has the special constraint ALIGN_FIT: instead of being aligned some way, it will be resized to fill the whole container height. The last label has special constraint ALIGN_EXPAND: like ALIGN_FIT it will fit the height of the container, but unlike ALIGN_FIT it will also fit  its width.
Note that all this behaviors are visible only if the container is bigger than its preferred size, otherwise each component will be laid out with its preferred size. In this example the frame is expanded using the seSize method to be 50 pixels wider and 50 pixels taller.

Another example, this time arranged vertically:

    f = new JFrame("PileLayout Vertical Test");
f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
c = f.getContentPane();
c.setLayout(new PileLayout(PileLayout.DIRECTION_VERTICAL));
label = new JLabel("This component is left aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_LEFT);
label = new JLabel("This component is center aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_CENTER);
label = new JLabel("This component is right aligned");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_RIGHT);
label = new JLabel("This component is fitted");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_FIT);
label = new JLabel("This component is expanded");
label.setBorder(BorderFactory.createLineBorder(Color.black));
c.add(label, PileLayout.ALIGN_EXPAND);
f.pack();
f.setSize(f.getSize().width + 50, f.getSize().height + 50);
f.setVisible(true);

The above code creates the following frame:

This time the placement is vertical, so the ALIGN_FIT and the ALIGN_EXPAND constraints work in the opposite directions. With the vertical placement components are by default left aligned.

Let's see a final example:
    f = new JFrame("PileLayout Mixed Test");
f.setDefaultCloseOperation(JFrame.EXIT_ON_CLOSE);
c = f.getContentPane();
c.setLayout(new PileLayout(PileLayout.DIRECTION_VERTICAL));
label = new JLabel("Name:");
c.add(label);
JTextField text = new JTextField(24);
c.add(text, PileLayout.ALIGN_FIT);
label = new JLabel("Age:");
c.add(label);
text = new JTextField(3);
c.add(text);
label = new JLabel("City:");
c.add(label);
text = new JTextField(24);
c.add(text, PileLayout.ALIGN_FIT);
label = new JLabel("Social security number:");
c.add(label);
text = new JTextField(16);
c.add(text);
label = new JLabel("Notes:");
c.add(label);
JTextArea area = new JTextArea(4, 24);
c.add(new JScrollPane(area), PileLayout.ALIGN_EXPAND);
JPanel buttonsPanel = new JPanel(new PileLayout(PileLayout.DIRECTION_HORIZONTAL, new Insets(0, 0, 0, 0)));
buttonsPanel.add(new JLabel(), PileLayout.ALIGN_EXPAND);
buttonsPanel.add(new JButton("OK"));
buttonsPanel.add(new JButton("Cancel"));
c.add(buttonsPanel, PileLayout.ALIGN_FIT);
f.pack();
f.setVisible(true);

The above code creates the following frame:

The layout is created with vertical placement and default gap and margins. Most components are added without specifying a constraints, only the "Name" and "City" text fields are added with ALIGN_FIT and the "Notes" text area is added with ALIGN_EXPAND. As you can see from the figure all the text fields will expand horizontally when the frame is made wider. This can be useful for an user that wants to see more text than available at the default frame size: enlarging the frame she will get bigger text fields. And the "Notes" text area is added with ALIGN_EXPAND, so it will expand also vertically, letting the user decide how much rows of text to see at once.

Now let's look at the second part of the example:

    JPanel buttonsPanel = new JPanel(new PileLayout(PileLayout.DIRECTION_HORIZONTAL, new Insets(0, 0, 0, 0)));
buttonsPanel.add(new JLabel(), PileLayout.ALIGN_EXPAND);
buttonsPanel.add(new JButton("OK"));
buttonsPanel.add(new JButton("Cancel"));
c.add(buttonsPanel, PileLayout.ALIGN_FIT);

The last component of the first PileLayout contains the OK and Cancel buttons. They are put in a nested PileLayout. This second PileLayout has horizontal direction, with the first component being an empty label added with ALIGN_EXPAND. This trick permits to right-align the buttons, because the first empty label will grow to adapt to the width of the containing panel (that will expand only in with because it's added with ALIGN_FIT in the last line) . Note also that the margins are all set to 0, this is to avoid to add the default margins of the nested PileLayout to the enclosing PileLayout gap and margins.

License

All the software, either in binary or source form, and this accompanying documentation is subject to the following conditions:

  Copyright  2006, 2007 Roberto Mariottini. All rights reserved.

Permission is granted to anyone to use this software in source and binary forms
for any purpose, with or without modification, including commercial applications,
and to alter it and redistribute it freely, provided that the following conditions
are met:

o Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
o The origin of this software must not be misrepresented; you must not
claim that you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation would be
appreciated but is not required.
o Altered source versions must be plainly marked as such, and must not
be misrepresented as being the original software.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.

Copyright 2006, 2007 Roberto Mariottini. All Rights Reserved.