ZIETrans Toolkit support for custom component and widget settings

You can provide GUI support for modifying the settings of your custom component and widget. This is useful if other developers will be using your custom component or widget or you want to easily test different combinations of settings using the preview features available in the ZIETrans Toolkit. The base component and widget classes implement the ICustomPropertySupplier interface. This interface allows a component or widget to contribute setting information to the ZIETrans Toolkit. This information is used to render a panel by which the settings of the component or widget can be modified. Not all settings need to be exposed in the GUI.

The getCustomProperties() method returns a vector of HCustomProperty customizable property objects. Each HCustomProperty object represents a setting of the component or widget. The ZIETrans Toolkit renders each HCustomProperty objects based on its type. For example, an object of type HCustomProperty.TYPE_BOOLEAN is rendered as a GUI checkbox.

The following sample code demonstrates how a widget can provide GUI support for three of its settings (mySetting1, mySetting2, and mySetting3):

// Returns the number of settings panels (property pages) to be contributed 
//by this widget.  The returned value must be greater than or equal to 1 if 
//custom properties will be supplied via the getCustomProperties() method.  
public int getPropertyPageCount() {
         return 1;     
}

// Returns a Vector (list) of custom properties to be displayed in the GUI 
//panel for this component or widget.     
public Vector getCustomProperties(int iPageNumber, Properties properties, 
         ResourceBundle bundle) {
         Vector props = new Vector();          

// Constructs a boolean property that will be rendered as a checkbox         
HCustomProperty prop1 = HCustomProperty.new_Boolean("mySetting1", 
                "Enable some boolean setting", false, null, null);         
props.add(prop1); 

// Constructs a string property that will be rendered as a text field         
HCustomProperty prop2 = HCustomProperty.new_String("mySetting2", 
                "Some string value setting", false, null,
                 null, null, null);         
props.add(prop2);          

// Constructs an enumeration property that will be rendered as a drop-down         
HCustomProperty prop3 = HCustomProperty.new_Enumeration("mySetting3", 
                 "Some enumerated value setting", false,
                 new String[] { "A", "B", "C" }, new String[] 
                 { "Option A", "Option B", "Option C" }, null, null, null);
props.add(prop3);          

return props;     }

The values supplied by the user of the custom component or widget will be available in the componentSettings Properties object passed into the recognize() method of the component or the widgetSettingsProperties object passed into the constructor of the widget. The getCustomProperties() method may be called during runtime to collect default values for settings.

For a description of the arguments and usage of these methods, refer to the ZIETrans API References (Javadoc) for the HCustomProperty class. See Using the API documentation (Javadoc).