3 Reasons to love MigLayout

By meverett | January 30, 2009

One of my favorite new libraries we added to LimeWire 5 is MigLayout. I had never used MigLayout but it was always one of those libraries I was interested in trying and it always seems to popup in blog posts and articles. I added the MigLayout jar to my local repository and fell in love with it instantly. Within a few weeks of adding it to CVS, all the developers were using it almost exclusively.

Why MigLayout?

There are dozens of layout managers so why is this one so special? There are three main reasons:

1) it’s extremely powerful. You can easily mimic everything from Gridbag Layout to BorderLayout to FlowLayout to Absolute Layout.

2) it’s extremely simple. There’s a handful of keywords and concepts to learn and most of the API can be committed to memory very quickly.

3) you don’t need any special plugins to layout or modify the code and you can use it virtually everywhere you need a layout manager.

Quick Overview

There are essentially three different ways to arrange components in MigLayout:

1) The default and most common usage is to treat the space as a grid with columns and rows. Components can be added to rows and columns and can span multiple rows and columns.

2) You can also mimic BorderLayout with docking components to the north, south, center, etc.

3) You can use absolute positioning. This allows you to place components in relation to the parent container or in relation to other components in the container.

The best part is you can combine all of these arrangements in a single component. You could, for instance, dock a component to the top, then use the grid to layout the remaining components below that. For a much more detailed overview, check out the tutorials at http://www.miglayout.com/.

Docking with MigLayout

This code mimics BorderLayout. The main difference is MigLayout allows you to add multiple components to the same area. In this case there are two components added using “dock north”. This is extremely useful since it allows you to perform complex layouts without wrapping components inside of a JPanel for the sake of laying out components. Notice that the order in which components are added effects how they are displayed, the first “North” panel fills the entire X-axis while the “North 2″ panel is bookmarked between “West” and “East” since it was added after those components.

//it’s important to note the order in which the components are added
//effects their width and height in relation to other components
setLayout(new MigLayout(”fill”));
add(createPanel(”North”), “dock north”);
add(createPanel(”East”), “dock east”);
add(createPanel(”West”), “dock west”);
add(createPanel(”North 2″), “dock north”);
add(createPanel(”Center”), “dock center”);

Flow Layout

This code mimics Flow Layout in both the horizontal and vertical direction. The only difference between vertical and horizontal is we add the keyword “wrap”. The “wrap” keyword tells the next component added to begin on a new row in the layout grid.

setLayout(new MigLayout(”fill”));
//grow tells the component to fill its entire grid space
add(createPanel(”Item 1″), “grow”);
add(createPanel(”Item 2″), “grow”);
add(createPanel(”Item 3″));
add(createPanel(”Item 4″), “grow”);
add(createPanel(”Item 5″), “grow”);

//wrap set on the constructor will put each
//component added on its own row in the grid
setLayout(new MigLayout(”fill, wrap”));
add(createPanel(”Item 1″), “grow”);
add(createPanel(”Item 2″), “grow”);
add(createPanel(”Item 3″));
add(createPanel(”Item 4″), “grow”);
add(createPanel(”Item 5″), “grow”);

More Complicated Layouts

These are rather trivial uses of MigLayout. The real power comes when you want to layout something a bit more complex. Typically you’d find Gridbag Layout being used for this or nested Border Layouts. The result usually ends up being very verbose and hard to maintain. If you notice, I add 7 components to the container and have only 7 lines of code. MigLayout provides a very clean, readable, and easily modified code base while laying out a rather complex component.

// fill entire space provided, 2 pixel gap between components and
// 10 pixel insets from all edges
setLayout(new MigLayout(” fill, insets 10, gap 2″));
// first line
// span all the columns, wrap: put next component on the next row
add(createLabel(”Login”), “span, wrap”);
// second line
// textfield should fill the remaining horizontal space
add(createLabel(”User Name”));
add(createTextField(), “growx, wrap”);
// third line
// passfield should fill the remaining horizontal space
add(createLabel(”Password”));
add(createPasswordField(), “growx, wrap”);
// fourth line
// ok skips first column, split puts ok/cancel button in same cell
// using tag: ok/cancel allows miglayout to swap their order based on the OS preference
add(createButton(”Ok”), “skip 1, split, alignx right, tag ok”);
add(createButton(”Cancel”), “tag cancel”);

Finally, adding the keyword “debug” to the constructor, allows you to visually see what’s going on internally. The red lines outline each cell in the grid, while the blue lines outline how that particular component fills its cell. Here you can see there are four rows and two columns. Comparing it to the code, you can see the login label spans two columns, the ok/cancel are put into the same cell and skip the first column, you can also see the 2 pixel gap between rows/columns and the 10 pixel inset. This is such an amazing feature and has saved me countless hours while trying to figure out complex layouts.

Hopefully it gave you a feel for how powerful MigLayout is while also having very clean and readable code. Here’s the source code for the demos: miglayout-demo-src.zip