All Layouts must implement the Layout interface. This is a simple interface that defines only one method:

void layoutWidget(W widget,String elementName,Map<String,String> attributes,C container,M metawidget);

Where W is a widget type (such as JComponent or UIComponent) and M is a Metawidget type (such as SwingMetawidget or UIMetawidget).

Where W is a widget type (i.e. Control, JComponent etc), C is widget container type (i.e. Composite, JComponent etc) and M is a Metawidget type (i.e. SwtMetawidget, SwingMetawidget etc). Don't be put off by having so many parameterized types! Metawidget needs them so that it can present a consistent API across many architectures. However this complication doesn't impact your own custom plugins because you're able to substitute concrete, platform-specific values for each parameter (i.e. Control, Composite, SwtMetawidget ).

layoutWidget is called for each widget. Layouts should add the given widget as a child of the given container, according to the given elementName (which is typically just 'property' or 'action' from the inspection-result) and the various attributes (as parsed from the inspection-result). They can use the given metawidget to access additional services if needed (such as state saving beween invocations, see Section 2.6.7, “Implementing Your Own Layout”).

layoutWidget is called 'in-place'

layoutWidget is called immediately after WidgetBuilder.buildWidget and WidgetProcessor.processWidget, and before the next widget is generated. An alternate design would be to 'collect' all widgets generated by buildWidget and processWidget, then iterate over them separately for the layout. If you prefer this approach, you can simulate it by having layoutWidget do nothing but 'remember' each widget, then iterate over them in endContainerLayout (see Section 2.6.2, “Advanced Interface”). However not all UI frameworks allow this approach, because they do not suport widgets being instantiated independent of a layout, nor moved between layouts (e.g. SWT).

The Layout interface only has a single method. However for those needing more control over the Layout lifecycle there is an extended interface AdvancedLayout. This interface defines four additional methods:

void onStartBuild(M metawidget);
				
void startContainerLayout(W container, M metawidget);
				
void endContainerLayout(W container, M metawidget);

void onEndBuild(M metawidget);

Figure 2.10. startContainerLayout and endContainerLayout are called for each container, layoutWidget is called for each widget

The first method, onStartBuild, is called at the start of the widget building process, before the WidgetBuilder is called. Layouts may wish to act on this event to initialize themselves ready for processing, or to perform 'outermost-container-only' processing, such as adding toolbar facets. However it is acceptable to do nothing.

The second method, startContainerLayout, is called to initialize the given container. It is acceptable to do nothing.

The third method, endContainerLayout, is called to finish the given container. It is acceptable to do nothing.

The last method, onEndBuild, is called at the end of the widget building process, after all widgets have been built and added to the Layout. Layouts may wish to act on this event to clean themselves up following processing, or to perform 'outermost-container-only' processing, such as adding status bar facets. However it is acceptable to do nothing.

LayoutDecorator allows you to combine multiple Layouts together in a heirarchy. Conceptually, this is similar to CompositeInspector or CompositeWidgetBuilder, but Layouts are fundamentally different in that most are 'end points' that cannot sensibly be composed into sequential lists (i.e. what should happen if you try to combine a GridBagLayout with a FlowLayout?).

Rather, Layouts must be combined heirarchically, with an 'outer' Layout delegating to a single 'inner' Layout. LayoutDecorator is an abstract class that can be extended in order to decorate other Layouts. For example, GridBagLayout can be decorated using TabbedPaneLayoutDecorator to add tabbed section functionality.

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<gridBagLayout />
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

A LayoutDecorator can also decorate another LayoutDecorator to provide fine-grained control over nested sections. For example, the domain object...

public class Person {
	@UiSection( { "Person", "Name" } )
	public String firstname;
	
	public String surname;
	
	@UiSection( { "Person", "Contact Detail" } )
	public String telephone;
}

...could be rendered using nested TabbedPaneLayoutDecorators...

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</tabbedPaneLayoutDecorator>			
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.11.

Figure 2.11. Nested TabbedPaneLayoutDecorators

Alternatively, it could use a TabbedPaneLayoutDecorator nested within a SeparatorLayoutDecorator...

<metawidgetLayout>
	<separatorLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="SeparatorLayoutDecoratorConfig">
		<layout>
			<tabbedPaneLayoutDecorator config="TabbedPaneLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</tabbedPaneLayoutDecorator>			
		</layout>
	</separatorLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.12.

Figure 2.12. TabbedPaneLayoutDecorator within a SeparatorLayoutDecorator

Or the opposite - a SeparatorLayoutDecorator nested within a TabbedPaneLayoutDecorator...

<metawidgetLayout>
	<tabbedPaneLayoutDecorator xmlns="java:org.metawidget.swing.layout"
		config="TabbedPaneLayoutDecoratorConfig">
		<layout>
			<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
				<layout>
					<gridBagLayout />
				</layout>
			</separatorLayoutDecorator>			
		</layout>
	</tabbedPaneLayoutDecorator>			
</metawidgetLayout>

...as shown in Figure 2.13.

Figure 2.13. SeparatorLayoutDecorator within a TabbedPaneLayoutDecorator

Unless explicitly specified, each Metawidget will instantiate a default Layout. This default behaviour can be overridden either in code:

metawidget.setLayout( new MyLayout() );

Or via metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<swingMetawidget xmlns="java:org.metawidget.swing">
	<layout>
		<myLayout xmlns="java:com.myapp"/>
	</layout>
</swingMetawidget>

This allows easy plugging in of alternate Layouts.

All Metawidgets have default Layouts. You can see the default by looking in the Metawidget JAR for the file metawidget-xxx-default.xml (where xxx is your target platform, such as swing or struts).

For reference, the defaults are:

<textViewLayoutDecorator config="TextViewLayoutDecoratorConfig">
	<layout>
		<tableLayout />
	</layout>
</textViewLayoutDecorator>

new metawidget.layout.HeadingTagLayoutDecorator(
	new metawidget.layout.TableLayout()
)

<outputTextLayoutDecorator config="OutputTextLayoutDecoratorConfig">
		<layout>
			<simpleLayout/>
		</layout>
	</outputTextLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<springTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<htmlTableLayout/>
	</layout>
</headingTagLayoutDecorator>

<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
	<layout>
		<gridBagLayout/>
	</layout>
</separatorLayoutDecorator>

<separatorLayoutDecorator config="SeparatorLayoutDecoratorConfig">
	<layout>
		<gridLayout/>
	</layout>
</separatorLayoutDecorator>

<headingTagLayoutDecorator config="HeadingTagLayoutDecoratorConfig">
	<layout>
		<formLayout/>
	</layout>
</separatorLayoutDecorator>

All Layouts are required to be immutable. This means you only need a single instance of a Layout for your entire application. If you are using metawidget.xml then ConfigReader takes care of this for you, but if you are instantiating Layouts in Java code you should reuse instances.

Note that immutable only means Layouts cannot be changed once instantiated - it does not mean they cannot be configured. Many Layouts have corresponding xxxConfig classes that allow them to be configured prior to instantation in a type-safe way. For example, an HtmlTableLayout can be configured in code:

metawidget.setLayout( new HtmlTableLayout( new HtmlTableLayoutConfig().setNumberOfColumns( 2 ));

Or in metawidget.xml (see Section 2.7, “metawidget.xml and ConfigReader”):

<htmlTableLayout xmlns="java:org.metawidget.jsp.tagext.html.layout"
	config="HtmlTableLayoutConfig">
	<numberOfColumns>
		<int>2</int>
	</numberOfColumns>
</htmlTableLayout>

Here is an example of a custom Layout that arranges components in a bulleted HTML list. It could be useful for, say, arranging action elements that were represented by HTML anchor tags:

package com.myapp;

import java.util.*;
import javax.servlet.jsp.*;
import javax.servlet.jsp.tagext.*;
import org.metawidget.jsp.*;
import org.metawidget.jsp.tagext.*;
import org.metawidget.layout.iface.*;

public class HtmlListLayout
	implements AdvancedLayout<Tag, MetawidgetTag> {
	
	public void onStartBuild( MetawidgetTag metawidgetTag ) {}

	public void startContainerLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void layoutChild( Tag tag, String elementName, Map<String, String> attributes,
		Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "<li>" );
			writer.write( JspUtils.writeTag( metawidgetTag.getPageContext(), tag, containerTag, null ) );
			writer.write( "</li>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}

	public void endContainerLayout( Tag containerTag, MetawidgetTag metawidgetTag ) {
		try {
			JspWriter writer = metawidgetTag.getPageContext().getOut();
			writer.write( "</ul>" );
		} catch ( Exception e ) {
			throw LayoutException.newException( e );
		}
	}
	
	public void onEndBuild( MetawidgetTag metawidgetTag ) {}	
}

Like Inspectors, InspectionResultProcessors, WidgetBuilders and WidgetProcessors, Layouts are required to be immutable. However they will generally need to store some internal state, such as tracking the current row in a table layout. This can be achieved in two ways: