Baggie Layout Readme

What is "Baggie Layout"?

Baggie Layout is a Swing LayoutManager (created in May 2006). It replaces GridBagLayout by offering all the same functionality (except for x,y coordinate positioning). It allows you to lay out your container in two ways, XML (preferred), or constraint objects.

The preferred way is to write xml, with an "id" attribute on each "td" element to place components. The syntax is almost the same as strict xhtml. Some attribute names are different, such as align which is divided into horizontal and vertical. Compatibility is maintained for user friendliness, so "align" is assumed to be horizontal align, or you can specify both horizontal and vertical in the same attribute separated by a space or comma.

The second way to lay out your container is to use the BaggieConstraint bean. It is alot like the GridBagConstraints object, having similar properties, but it follows the JavaBean design pattern, and uses enums instead of primitive int fields. Instead of fields to set how the constraint works, you call setter methods. You can also call a single method that parses all your properties from one string if that is more convenient.

It will always remain free and open source.

BaggieLayout on SourceForge
Download
JavaDoc API
Change Log
LGPL License

Goals

1. flexibility
   • Using colspan and rowspan, much like in html/xhtml, you can do whatever you want with your layout. Before BaggieLayout, only GridBagLayout and SpringLayout could ever do complex things (but not without extra empty hidden panels, etc.)
   • You can externalize your layout, in an external xml file, which can be loaded in different ways, a simple String, or an InputSource which can be created from anything (String, File, InputStream, etc.)
2. ease of programming
   • Instead of having pages of complicated calculations, constraints, and hack solutions like extra panels, invisible fields, etc. BaggieLayout allows you to specify where you want things, and they actually do what you tell them to!
   • Layout is specified either with a bean, or with simple xml. It's easier than using a gui to do it, and then you're not stuck relying on the gui later on.
3. expected results when dealing with component minimum/maximum/preferred size
   • Unlike most layouts, in BaggieLayout, components are never allowed to be larger than their maximum or smaller than their minimum size.
   • Preferred size is never ignored. The rendered size is as close to the preferred as possible, and the amount removed/added is relative to weights you specify.

Since a good LayoutManager is something should already be included in the JRE but is not, I hope to one day make BaggieLayout part of the standard JRE. I always wanted a LayoutManager like this, but never knew how to make one, or never tried until recently. If you can help me do this, please email me.

How to use it

1. During development, enable warnings.

   Warnings are quite helpful, but are disabled by default to prevent spamming stdout. An application will still run with problems, except xml parsing problems, but the layout might not be exactly what you expected.

   BaggieLayout.setPrintingWarnings(true);
   BaggieLayout.setPrintingWarningTraces(true);
   		

2. If you want minimum/maximum sizes to be used properly, allow swing to render the window instead of your OS. (optional)

   JFrame.setDefaultLookAndFeelDecorated(true);
   		

3. If you want the window to calculate its minimum/maximum size based on its components, try the SizeControlledJFrame (optional)

   JFrame f = new SizeControlledJFrame("Example");
   		

   It uses some unorthodox methods to control the window size, and so far was only tested thorougly on WindowsXP.

4. Using XML (preferred)

   1. XML: Create the BaggieLayout Object, passing in the JContainer as the first parameter, and xml String, or InputSource as the second.

      Your xml can come from a file, or from a String, generated with a StringBuilder in a loop, or however you want.

      BaggieLayout layout = new BaggieLayout( 
      	this, //this is the JPanel
      	"<table width='1,2' height='1,1,0'>" +
      	"	<tr alignAll='left'>" +
      	"		<td colSpan='2' id='menuBar' />" +
      	"	</tr>" +
      	"	<tr fillAll='both' borderAll='EtchedBorder'>" +
      	"		<td id='fileTree' />" +
      	"		<td id='editor' />" +
      	"	</tr>" +
      	"	<tr>" +
      	"		<td align='left' margin='0 5 0 5' fill='horizontal' colSpan='2' id='statusBar' />" +
      	"	</tr>" +
      	"</table>"
      );
      				

   2. Add the components to the container, specifying the id

      this.add( menuBar, "menuBar" );
      this.add( treeScroll, "fileTree" );
      this.add( editorScroll, "editor" );
      this.add( statusBar, "statusBar" );
      				

5. Using Constraints

   1. Create the BaggieLayout Object, passing in the JContainer as the first parameter, and the width weights for the second, and the height weights for the third.

      Weights are set across the whole table, not just cells, so we specify 2 width weights, since the total colspan for any row is 2, and we specify 3 height widths, since the total rowspan for any column is 3. The syntax not very strict; commas are optional, and extra spaces are removed.

      BaggieLayout layout = new BaggieLayout( this, "1,1", "1  1 1" );
      				

   2. Add the components to the container, using a BaggieConstraint object

      Properties can be set through setters, the setProperties(String) method, or the BaggieConstraint(String) constructor which calls setProperties(String). To move to the next line, and to finish the last line, call endRow() which will return a cloned BaggieConstraint without changing the old one, so it can still be reused.

      BaggieConstraint cst = new BaggieConstraint();
      cst.setAlign( BaggieConstraint.Align.LEFT );
      cst.setColSpan(2);
      this.add( menuBar, cst.endRow() );
      
      cst.setColSpan(1);
      cst.setFill( BaggieConstraint.Fill.BOTH );
      this.add( treeScroll, cst );
      
      this.add( editorScroll, cst.endRow() );
      
      cst.setMargin(0,5,0,5);
      cst.setColSpan(2);
      cst.setFill(BaggieConstraint.Fill.HORIZONTAL);
      this.add( statusBar, cst.endRow() );
      				

Dependencies

Java 6.0

Contributors

Original author and only coder:
	Peter Maloney <circumlocuter@yahoo.com>

Additional contributiors:
	(Ideas, misc. help)
	Stephen Maloney
	Sam Maloney <sam.maloney@gmail.com>

Testing and bug reports:
	Stephen Maloney
	Sam Maloney <sam.maloney@gmail.com>