Opening Subforms

How to open a subform from a parent form and then communicate between them.

About this technique	Details
Category	Java Client Techniques> Dialogs and subforms
Description	You'll learn about: Opening various kinds of subforms from a parent form Firing a custom event back to the parent form Directly manipulating controls on the parent form
	You can run this technique code from: Database: Examples3_Java Form: frmShowForm NOTE   First make sure that database is running on your localhost SilverStream Server
Related reading	See the chapter on programming forms in the Programmer's Guide

The example uses frmShowForm as the parent form and subfrmShowForm as the subform.

Opening various kinds of subforms from a parent form   

On a parent form, you can set a button to open a single kind of subform or you can offer ways for users to choose the kind of subform to open.

Using the showFormDialog method

The following example shows how to open a single kind of subform.

  private void handle_btnShowFormDialog_actionPerformed(ActionEvent evt)  
  {  
       fldReturnValue.setText("");  
       try  
           {  
            agDialog.showFormDialog("Modal Dialog", SUBFORM_NAME);  
           }  
       catch (Exception e)  
       {  
        agDialog.displayError(e);  
       } 
  } 

Notes about the code

• This code runs in the parent form (frmShowForm).

• showFormDialog() opens a modal dialog. (Its title is "Modal Dialog".) To open other types of dialogs or windows, use the showForm() method.

• The constant SUBFORM_NAME names the subform to open.

Using the showForm method

The following example shows how code on a parent form takes user input to set up the location and type of subform.

  private void handle_btnShowForm_actionPerformed(ActionEvent evt) 
     { 
      fldReturnValue.setText("");     
      int iIndex =  comboWindowType.getSelectedIndex(); 
     } 
      if (iIndex < 0) 
        iIndex = 0; 
      String sWindowType = (String) 
         comboWindowType.getItemValue(iIndex); 
      String sX = fldXCoordinate.getText(); 
      String sY = fldYCoordinate.getText();     
      } 
      int iWindowType = Integer.parseInt(sWindowType); 
      int x = Integer.parseInt (fldXCoordinate.getText()); 
      int y = Integer.parseInt (fldYCoordinate.getText()); 
     
      String sTitle = GS_MODAL; 
      switch (iWindowType) 
      { 
        case GI_MODAL: 
          sTitle = GS_MODAL; 
          break; 
        case GI_MODELESS: 
          sTitle = GS_MODELESS; 
          break; 
        case GI_FRAME: 
          sTitle = GS_FRAME; 
          break; 
        case GI_DIALOG: 
          sTitle = GS_DIALOG; 
          break; 
      }      
      try 
      { 
        agDialog.showForm(sTitle,  
                  agDialog.getForm(SUBFORM_NAME),  
                  iWindowType,  
                  chkResize.getState(), 
                  x, 
                  y); 
      } 
      catch (Exception e) 
      { 
        agDialog.displayError(e); 
      } 
    } 

Notes about the code

• This code runs in the parent form (frmShowForm).

• The top left coordinate of the subform uses parameters from the calling form but these can be modified by the user.

• agDialog.getForm() instantiates the form named in the constant SUBFORM_NAME.

• iWindowType holds the value the user selected in the tcbWindowType field specifying the type of subform to open.

• chkResize.getState() determines whether the subform can be resized.

Firing a custom event back to the parent form   

This example shows how a subform (subfrmShowForm) can communicate back to the parent form (frmShowForm) by firing a custom event to the parent form, where code for formCustomEvent responds to fireCustomEvent().

  public void setFireCustomEventValue(String psCustomEventName) 
  { 
    // Get parent form 
    AgfForm frmParent = getParentForm (); 
   
    // Fire the Custom event in the parent form, passing a string 
    // Custom event will set value in TextField on parent 
    fireCustomEvent (frmParent, psCustomEventName, null); 
  } 

Notes about the code

• This code runs in the subform (subfrmShowForm).

• frmParent holds a reference to the parent form. AgfForm is the ancestor class of all SilverStream forms.

• fireCustomEvent() fires the custom event in the parent form passing a string containing the text from the pushed button on the subform.

Directly manipulating controls on the parent form   

This example shows how to call a method on the parent form. The parent form implements the interface InterfaceShowForm. The interface defines the setReturnValue() method and the parent form implements it. The interface is not essential to the technique; you can call methods on the parent form directly. However, an interface enforces consistency especially when more than one form needs to implement the method.

The interface is in the Objects section of the Main Designer, on the com.examples.formInterfaces branch. This is its definition:

  package com.examples.formInterfaces; 
   
  public interface InterfaceShowForm 
  { 
     public void setReturnValue(String psValue); 
  } 

This is code in the subform that calls the method.

  public void setControlReturnValue(String psControlName) 
  { 
   
     InterfaceShowForm frmParent =  
        (InterfaceShowForm) getParentForm(); 
   
     frmParent.setReturnValue(psControlName); 
  } 

Notes about the code

• This code runs in the subform (subfrmShowForm).

• The reference to the parent form returned by getParentForm() is cast to the interface, not AgfForm. Otherwise, the code wouldn't compile because the setReturnValue() method is not defined in AgfForm.