8.4. Defining a Widget Set

The client-side components, or in GWT terminology, widgets, must be made usable in the client-side GWT application by defining a widget set factory that can create the widgets by their UIDL tag name. (Actually, such a widget set factory is the client-side application.)

A widget set factory needs to inherit the default factory DefaultWidgetSet and implement the createWidget() and resolveWidgetType() methods. The methods must call their default implementation to allow creation of the standard widgets.

The following example shows how to define a widget set factory class for the Color Picker example. The tag name of the widget was defined in the server-side implementation of the widget (see Section 8.3.3, “Example: Integrating the Color Picker Widget”) as colorpicker. The resolveWidgetType() must resolve this name to the class object of the IColorPicker integration class, which is later passed to the createWidget() method for creating an instance of the IColorPicker class.

import com.itmill.toolkit.demo.colorpicker.gwt.client.ui.IColorPicker;
import com.itmill.toolkit.terminal.gwt.client.DefaultWidgetSet;
import com.itmill.toolkit.terminal.gwt.client.Paintable;
import com.itmill.toolkit.terminal.gwt.client.UIDL;

public class ColorPickerWidgetSet extends DefaultWidgetSet {
    /** Resolves UIDL tag name to widget class. */
    protected Class resolveWidgetType(UIDL uidl) {
        final String tag = uidl.getTag();
        if ("colorpicker".equals(tag))
            return IColorPicker.class;

        // Let the DefaultWidgetSet handle resolution of default widgets
        return super.resolveWidgetType(uidl);
    }

    /** Creates a widget instance according to its class object. */
    public Paintable createWidget(UIDL uidl) {
        final Class type = resolveWidgetType(uidl);
        if (IColorPicker.class == type)
            return new IColorPicker();

        // Let the DefaultWidgetSet handle creation of default widgets
        return super.createWidget(uidl);
    }
}

The default widgets in IT Mill Toolkit actually use more than just the tag name to resolve the actual widget class. For example, the Button server-side component, which has tag name button, can be resolved to either an IButton or ICheckBox widget, depending on the switch (switchMode) attribute. IT Mill Toolkit Client-Side Engine can actually replace the client-side object of the parameters change.

8.4.1. GWT Module Descriptor

A widget set is actually a GWT application and needs to be defined in the GWT module descriptor as the entry point of the application. A GWT module descriptor is an XML file with extension .gwt.xml.

The following example shows the GWT module descriptor of the Color Picker application. The client-side entry point will be the WidgetSet class. We also define the default stylesheet for the color picker widget, as described above in Section 8.2.3, “Styling GWT Widgets”.

<module>
    <!-- Inherit the NoEntry version to avoid multiple entrypoints -->
    <inherits name="com.itmill.toolkit.terminal.gwt.DefaultWidgetSetNoEntry" /> 
    
    <!-- WidgetSet default theme -->    
    <stylesheet src="colorpicker/styles.css"/>

    <!-- Entry point -->
    <entry-point class="com.itmill.toolkit.demo.colorpicker.gwt.client.WidgetSet"/>
  
</module>

For more information about the GWT Module XML Format, please see Google Web Toolkit Developer Guide.