Extending a SilverStream Control

How to extend a SilverStream control and use it on a form.

About this technique	Details
Category	Java Client Techniques> General techniques for controls
Description	You'll learn about: Creating a subclassed control Adding the constructor Building the JAR file Adding the control to a form Responding to mouse events
Related reading	See the chapters on advanced form techniques and using JAR files in the Programmer's Guide and the JAR Designer in the Tools Guide

In SilverStream, you can subclass SilverStream and AWT-based form controls to add to or change their functionality. These extendable classes have names that begin with Agc, without a "J".

NOTE   You cannot extend Swing-based controls because they are not serializable in JDK 1.2.These non-extendable classes have names that begin with AgcJ.

This example creates the BlueLabel control, which extends the com.sssw.rt.form.AgcLabel control. It is always blue with white text.

The basic steps are:

1. In the Business Object Designer, create a package and the class. The new class must be in a package so that you can put it in a JAR file.

2. Write a constructor and, optionally, other methods for the class.

3. Use the Jar Designer to put the newly created class in a JAR file.

4. In the Form Designer, associate the JAR file with your form and write code to instantiate the control.

Creating a subclassed control   

To create a new package and a class that extends AgcLabel:

1. In the Main Designer, select Objects on the left and create a package by selecting New package from the New action menu. In this example, the package is called controls.

2. In the Main Designer, with Objects selected on the left and the controls package selected on the right, create a business object by selecting New Object from the New action menu. In the Wizard:
   • Do not specify a trigger for the object.

   • Name the class BlueLabel and specify that it extends com.sssw.rt.form.AgcLabel.

     When you're finished with the Wizard, SilverStream displays the Business Object Designer so that you can write the Java code for the class. A package statement is already included in the code.

3. For this specific class, import the following classes:

     import java.awt.Color; 
     import com.sssw.rt.gui.AgoFontIdentifier; 
     import com.sssw.rt.form.AgcLabel; 
   

4. Add a constructor, described next. You can add as many custom methods as necessary for your class.

Adding the constructor   

To write the constructor for the BlueLabel control:

1. From the Business Object Programming Editor, choose Tools>Add New Method.

2. Specify these attributes for the constructor when prompted by the New Method Wizard:

   Name: BlueLabel

   Visibility: public

   Return Type: empty (the field must be blank; constructors have no return value)

   Parameters: 2

3. Add these parameters when prompted by the Wizard:

   Name: labelName

   Type: String

   Name: labelText

   Type: String

4. Add the following code for the BlueLabel constructor method. It creates a label control with these attributes: a blue background, white text, grooved border, font size 14, and font name TimesRoman.

     AgoFontIdentifier font; 
     super.setName(labelName); 
     super.setText(labelText); 
      
     //grooved border 
     super.setBorderStyle(AgcLabel.BORDER_GROOVED); 
     super.setTransparent(false); 
      
     // set text style normal. 
     super.setTextStyle(AgcLabel.STYLE_NORMAL); 
      
     // white text 
     super.setTextColor(Color.white); 
      
     super.setBackgroundColor(Color.blue); 
     super.setJustification(AgcLabel.JUSTIFY_LEFT); 
     super.setWordWrap(false); 
     font = new AgoFontIdentifier("TimesRoman", 0, 14); 
     super.setFontIdentifier(font); 
   

Building the JAR file    

To create a JAR file that contains the control:

1. Click the EJB Jars and Media icon in the left pane.

2. Click the New button in the right pane and select Create JAR from the popup menu. The JAR Designer appears.

3. From the JAR Contents tab, double-click the BlueLabel object to add it to the JAR file list.

4. Save the JAR file.

Adding the control to a form   

Add the control to a form by:

1. In the Form Designer, create a new form or open an existing form.

2. To associate the JAR file that contains the BlueLabel class with the form, in the Form Designer select File>Jar Files and select the JAR file you created.

3. Open the Programming Editor for the form and in the General/Imports section, add the following import statement:

     import controls.BlueLabel; 
   

4. In the General/Declarations section, declare an instance variable for the control.

     public BlueLabel testBlueLabel; 
   

5. In the FormActivate event (or some other event where you want to instantiate the control), add the following code.

     // Create the label, set its size, location, and tool tip 
     testBlueLabel = new BlueLabel("testBlueLabel", "Blue Label"); 
     testBlueLabel.setLocation(5,45); 
     testBlueLabel.setSize(100,25); 
     testBlueLabel.setToolTipText("Example Blue Label"); 
   

6. Add the control to the form using the AgfForm.add() method. The following example uses the this object reference to specify the current form.

     this.add(testBlueLabel); 
   

Responding to mouse events   

For the control to respond to events, you must add the appropriate event listener interfaces. This example adds a mouse listener so that you can respond to events involving the label. SilverStream can generate stubs for interface methods when you use this procedure:

1. In the Programming Editor, select File>Java Interfaces and add the interface java.awt.event.mouseListener. Select the check box Create stubs for interface methods.

2. In the formActivate event, add the form as a listener for this control's mouse events.

     testBlueLabel.addMouseListener(this); 
   

3. Find the generated stubs for the events you want to respond to and write appropriate code.

For example, this code for mouseEntered finds out the component for which the event occurred. This is the same sort of code SilverStream generates to dispatch event handling to methods for individual controls. The only response in this simple example is to display a message in the lblRpt control. You can write similar code for mouseClicked, mouseExited, mouseReleased, and mousePressed.

  public void mouseEntered(java.awt.event.MouseEvent mouseEvent1) 
  { 
     Object src = mouseEvent1.getSource(); 
     if (src == testBlueLabel) 
     { 
        lblRpt.setText( 
           "mouseEntered " + ((Component) src).getName(); 
     } 
  } 

NOTE   If other controls on the form must also respond to mouse events, write code for all controls using these event handling methods that you add yourself, rather than write code in the SilverStream-generated event handlers. For information, see the section on handling events for controls instantiated at runtime in the Advanced Form Topics chapter of the Programmer's Guide.