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

W processWidget( W widget, String elementName, Map<String, String> attributes, M metawidget );

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

processWidget is called for each widget built by the WidgetBuilders. WidgetProcessors can modify the given widget 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 help them if needed (e.g. to access a UI context with which to create validators).

The processWidget method must return the processed widget. This is typically the same as the given widget. The parent Metawidget then passes this to the next WidgetProcessor in the list as shown in Figure 2.6.

Figure 2.6. Typical WidgetProcessor list

In most cases the WidgetProcessor will simply be modifying the given widget (adding validators, changing styles and so on). However it can decide to swap the widget out by returning a different widget entirely. This new widget will then be passed down the list as shown in Figure 2.7. For an example use of this capability, see HiddenFieldProcessor.

Figure 2.7. WidgetProcessors can substitute widgets

Alternatively, the WidgetProcessor can decide to exclude the widget entirely by returning null. Subsequent WidgetProcessors will not be called, as shown in Figure 2.8, and no widget will be added to the Layout.

Figure 2.8. WidgetProcessors can exclude widgets

Some Metawidgets will instantiate default WidgetProcessors. This default behaviour can be overridden either in code:

metawidget.addWidgetProcessor( new MyWidgetProcessor() );

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

<swingMetawidget xmlns="java:org.metawidget.swing">
	<widgetProcessors>
		<array>
			<myWidgetProcessor xmlns="java:com.myapp"/>
		</array>
	</widgetProcessors>
</swingMetawidget>

This allows easy plugging in of alternate WidgetProcessors. Note that overriding the default means the default is no longer instantiated. In the example above, this would mean MyWidgetProcessor is used but the default WidgetProcessors are not.

The list of WidgetProcessors is maintained by the parent Metawidget, and is changeable (this is different to say, CompositeInspector or CompositeWidgetBuilder whose lists are immutable). This capability is designed to allow easy attaching of event handlers, and scenarios such as inner classes that have connections to their parent class:

final Object someObject = ...;
				
metawidget.addWidgetProcessor( new WidgetProcessor<JComponent, SwingMetawidget>() {
	JComponent processWidget( JComponent widget, String elementName, Map<String, String> attributes,
											SwingMetawidget metawidget ) {

		...decide whether to attach event handler...
		
		widget.add( new AbstractAction() {
			public void actionPerformed( ActionEvent e ) {
				someObject.doSomething();
			}
		}	
	}
}

The WidgetProcessor interface only has a single method. This allows it to take advantage of future Java language features such as:

final Object someObject = ...;

metawidget.addWidgetProcessor(
	#(JComponent w, String name, Map<String, String> attr, SwingMetawidget m)
	{ w.add( #(ActionEvent e) { someObject.doSomething() } ) } );

However for those needing more control over the WidgetProcessor lifecycle there is an extended interface AdvancedWidgetProcessor. This interface defines two additional methods:

void onStartBuild( M metawidget );
				
void onEndBuild( M metawidget );

Figure 2.9. onStartBuild and onEndBuild are called once, processWidget is called for each widget

The first method, onStartBuild, is called at the start of the widget building process, before the WidgetBuilder is called. WidgetProcessors may wish to act on this event to initialize themselves ready for processing. However 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. WidgetProcessors may wish to act on this event to clean themselves up following processing. However it is acceptable to do nothing.

Some Metawidgets have default WidgetProcessors. Overriding the default means the default is no longer instantiated. This may not be what you want, so you may want to instantiate the default along with your new WidgetProcessor. 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:

<array>
	<simpleBindingProcessor />
	<reflectionBindingProcessor />
	<disabledAttributeProcessor />
</array>

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.angular.widgetprocessor.AngularWidgetProcessor(...)
]

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.RequiredAttributeProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.widgetprocessor.SimpleBindingProcessor()
]

[
	new metawidget.widgetprocessor.IdProcessor(),
	new metawidget.widgetprocessor.RequiredAttributeProcessor(),
	new metawidget.widgetprocessor.PlaceholderAttributeProcessor(),
	new metawidget.widgetprocessor.DisabledAttributeProcessor(),
	new metawidget.jqueryui.widgetprocessor.JQueryUIBindingProcessor(),	
	new metawidget.widgetprocessor.SimpleBindingProcessor()
]

<array>
	<requiredAttributeProcessor />
	<immediateAttributeProcessor />
	<standardBindingProcessor />
	<readableIdProcessor />
	<labelProcessor />
	<standardValidatorProcessor />
	<standardConverterProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<pathProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<nameProcessor />
	<cssStyleProcessor />							
</array>

<array>
	<reflectionBindingProcessor />
</array>

<array>
	<reflectionBindingProcessor />
</array>

<array>
	<simpleBindingProcessor />
	<reflectionBindingProcessor />
	<captionProcessor />
	<requiredProcessor />
	<minimumMaximumValidatorProcessor />
</array>

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

Although individual WidgetProcessors are immutable, the List they are contained in can be changed. Methods such as addWidgetProcessor allows clients to dynamically add WidgetProcessors at runtime. This is useful for adding event handlers (see Section 2.5.1, “Interface”).

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

metawidget.addWidgetProcessor( new BeansBindingProcessor( new BeansBindingProcessorConfig()
			.setUpdateStrategy( UpdateStrategy.READ_WRITE )));

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

<beansBindingProcessor xmlns="java:org.metawidget.swing.widgetprocessor.binding.beansbinding"
	config="BeansBindingProcessorConfig">
	<updateStrategy>
		<enum>READ_WRITE</enum>
	</updateStrategy>
</beansBindingProcessor>

Here is an example of a custom WidgetProcessor to add tooltips to JComponents. It extends the code from the tutorial (see Section 1.1, “Part 1 (Java version) - The First Metawidget Application”).

package com.myapp;
	
import static org.metawidget.inspector.InspectionResultConstants.*;
import java.util.*;
import javax.swing.*;
import org.metawidget.swing.*;
import org.metawidget.widgetprocessor.iface.*;

public class Main {

	public static void main( String[] args ) {
		Person person = new Person();

		SwingMetawidget metawidget = new SwingMetawidget();
		metawidget.addWidgetProcessor( new TooltipProcessor() );
		metawidget.setToInspect( person );

		JFrame frame = new JFrame( "Metawidget Tutorial" );
		frame.setDefaultCloseOperation( JFrame.EXIT_ON_CLOSE );
		frame.getContentPane().add( metawidget );
		frame.setSize( 400, 250 );
		frame.setVisible( true );
	}

	static class TooltipProcessor
		implements WidgetProcessor<JComponent, SwingMetawidget> {
		
		public JComponent processWidget( JComponent widget, String elementName,
										 Map<String, String> attributes, SwingMetawidget metawidget ) {
			widget.setToolTipText( attributes.get( NAME ) );
			return widget;
		}
	}
}

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