Templates

Like a rich client transformation, a rich client template is a Java™ class. It extends from the com.ibm.hats.rcp.ui.templates.RcpTemplate class, which extends from org.eclipse.swt.widgets.Composite. A template can contain SWT widgets, macro controls, and host and application keys. Because a template is an SWT composite, non-HATS widgets can be added to the template.

A template cannot contain host components (ComponentRendering composites), default rendering composites, or global variable controls, while a transformation can contain them.

You can create a template by extending one of the predefined templates that HATS provides. A template defines the basic layout and style of an application, such as:

Table 9 lists the methods that can be overridden by the RcpTemplate class.

Table 9. RcpTemplate methods
Method Description
getDefaultFont() Returns the default font to be used by widgets.
getDefaultMonospacedFont() Allows you to override the default monospaced font at the template level.
getDefaultBackgroundColor() Returns the default background color for the template.
getDefaultForegroundColor() Returns the default foreground color for the template.
getColorMapper() Returns an IColorMapper object that controls how host colors are mapped to colors on the view.
getTableColorProvider() Returns an ITableColorProvider object that controls what colors are used for table controls.
getContentContainer() Returns the composite that will be the parent of transformations or other composites displayed on the template.

Refer to the HATS Rich Client Platform API reference for more information on these methods.

The HATS runtime is responsible for constructing and disposing of templates. HATS runtime performs the following steps:

  1. Constructs a new instance of the specified template class. This class must be a descendent of RcpTemplate, meaning that it must extend from RcpTemplate or from a class that extends from RcpTemplate.
  2. Constructs a new instance of the transformation class.
  3. Calls the setContent() method of the template instance, passing it the transformation instance. This method calls the applyStyleToComposite() method of the transformation instance
  4. Calls the setContent() method of the transformation view instance, passing it the template instance.

Editing templates

Templates are found in the HATS Projects view under Rich Client Content > Templates.

Assuming the Java client application editor (VE) feature, also known as the Visual Editor, is installed with Rational® SDP, you can use it to edit your transformations. In addition to the information in this section, see Editing templates for rich client projects in the HATS User's and Administrator's Guide.

By default, the templates shipped by HATS return the background color, foreground color, and font of the template class for the methods of RcpTemplate. It is recommended that you use the Properties view in the Visual Editor to update the background color, foreground color, and font of the template if you implement the IRcpTemplate interface.

Note:
As documented in the Eclipse API reference, you must dispose of Image, Color, and Font objects that you create. You should not dispose of a color retrieved using the Display.getSystemColor() method, since you did not create it. For non-standard colors, it is recommended that you use the ColorManager class provided by HATS. This class manages the creation, caching, and disposing of colors. You should not dispose of colors created by the ColorManager. A FontManager class is also provided, which works similarly to the ColorManager class, except that it manages fonts.

The Visual Editor has a known problem in cleaning up Image, Color, and Font objects. You must add the cleanup logic manually using the Java Editor, if you add them to your templates or transformations using the Properties Editor provided by the Visual Editor. For example, if you add a new Color object using the Visual Editor, the following code is generated:

sideBarArea.setBackground(new Color(Display.getCurrent(), 221, 228, 255));

Next you should add the following lines of code for cleaning up the Color object when you dispose of the widget:

sideBarArea.addDisposeListener(new DisposeListener(){    
    public void widgetDisposed(DisposeEvent e){        
       Color background = sideBarArea.getBackground();        
       if (background != null && !background.isDisposed()) {            
           background.dispose();        
       }                    
    }
});

Similar logic for cleaning up is required for Image and Font objects. The following lines of code are an example for cleaning up an Image object.

label = new Label(bannerArea, SWT.RIGHT);
gridData = new GridData(SWT.END, SWT.CENTER, true, true);
label.setImage(new Image(Display.getCurrent(), getClass().
                                getResourceAsStream("/images/sportsmast.gif")));
label.setLayoutData(gridData);
label.addDisposeListener(new DisposeListener() {    
    public void widgetDisposed(DisposeEvent e){        
        Image image = label.getImage();        
              if (image != null && !image.isDisposed()) {            
                  image.dispose();
              }
        } 
});

As explained, you do not have to clean up Color and Font objects if you use the ColorManager or FontManager classes that HATS provides, Note that you need to write the cleanup code using Java Editor instead of the Properties Editor that the Visual Editor provides. The following code is a sample of how to use ColorManager:

sideBarArea.setBackground(com.ibm.hats.rcp.ui.misc.ColorManager.
                    getInstance(Display.getCurrent()).getColor(221, 228, 255));

Samples

Customizing host color mappings

The mapping of host colors to colors on the view are controlled by the IColorMapper object returned by the getColorMapper() method of the template class. The default implementation of this method returns an object of type DefaultColorMapper. The following color mapper classes are provided by HATS:

DefaultColorMapper should be used by templates that have a non-white background color since it maps the color of white host fields to white. WhiteBackgroundColorMapper should be used by templates that have a white or light background color since it maps the color of white host fields to black and uses darker colors (compared to the default color mapper).

The mapColor() method of the IColorMapper object is responsible for mapping a host color to an SWT RGB value. This method is typically called from the HATS field widget when the Enable foreground colors setting is enabled. Table 10 lists the possible host color values that can be supplied to this method.

Table 10. Colors supplied to the mapColor method
Host Color Description
0 Blank
1 Blue
2 Green
3 Cyan
4 Red
5 Magenta
6 Brown (3270), Yellow (5250)
7 White (normal intensity)
8 Gray
9 Light blue
10 Light green
11 Light cyan
12 Light red
13 Light magenta
14 Yellow
15 White (high intensity)

There are two approaches for altering how colors are mapped by your template:

  1. Create a class that implements the IColorMapper interface, implement the mapColor() method, and update your template to return a new instance of this class
  2. Create a class that extends from one of the provided color mapper classes, override the mapColor() method, and update your template to return a new instance of this class.

If you choose to extend one of the classes provided by HATS, you will need to override the mapColor() method. The following code sample shows how to change the color for blue (host color 1) and magenta (host color 5) host fields:

public class MyCustomColorMapper extends DefaultColorMapper {

	public RGB mapColor(int hostColor) {
		RGB rgb = null;
		
		if (hostColor == 1) {
			rgb = new RGB(100, 100, 100);
		} else if (hostColor == 5) { 
			rgb = new RGB(255, 0, 0); 	
		} else {
			rgb = super.mapColor(hostColor);
		}
		
		return rgb;
	}

}

The following code sample shows how to implement the getColorMapper() method of your template class to return your custom color mapper.

Notes:
  1. This method might already exist in your template. If so, replace the current method with the following:
    public IColorMapper getColorMapper() {
            return new MyCustomColorMapper();
        }
  2. Color mappings are controlled at the template level. If you need to alter how colors are mapped at the transformation level, you need to create a new template, which can extend your existing template, and configure your screen customizations to use this template.

Removing borders from input fields

To remove borders from input fields rendered by HATS widgets, you can override the getControlStyleClass(Class) method of your template and return 0 when the specific class is the SWT Text widget class (org.eclipse.swt.widgets.Text).

To override the getControlClassStyle() method, do the following:

  1. Click in the Source editor pane.
  2. Click Select Source > Override/Implement Methods.
  3. Under RcpTemplate, select the getControlClassStyle checkbox.
  4. Click Ok.

Add the following code to the getControlClassStyle() method:

if (controlClass.equals(org.eclipse.swt.widgets.Text.class)) {
		return 0;
	} else {
		return super.getControlClassStyle(controlClass);
	}