Using Subforms to Share Globals among Forms

How to use subforms to share global methods, constants, and variables among forms.

About this technique	Details
Category	Java Client Techniques> Dialogs and subforms
Description	You'll learn about: Creating a subform to contain globals Getting a reference to a single subfrmCircle instance Accessing a single subfrmCircle instance from any subfrmGlobals instance Launching subfrmGlobals forms
	You can run this technique code from: Database: Examples3_Java Form: frmGlobalsLauncher 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 three forms to illustrate the technique:

• Circle subform (subfrmCircle) contains the variables and methods that are to be used globally. It includes the method initfrmCircle() that returns a reference to its first instance. This method replaces each subfrmCircle instance that calls it (except the first) with the first subfrmCircle instance.

• Globals subform (subfrmGlobals) accesses the variables of a particular Circle. With each Globals instantiation, a Circle is created. Then for each Circle that a Globals creates, its formLoaded() method calls the Circle's initfrmCircle() method to reference the first instance. This ensures that all Globals instances access the constants and variables of the same Circle instance (the first).

• Globals Launcher form (frmGlobalsLauncher) creates instances of the Globals subform.

Creating a subform to contain globals   

The following code declares a global counter variable, a global constant, and a reference to itself (subfrmCircle).

  //Declarations from subfrmCircle 
   
  // A reference to this subFrom, but only the first instance 
  private static subfrmCircle theOnlyfrmCircle; 
   
  // A Global counter variable (modifiable) 
  int counter = 0; 
   
  // A Global constant 
  static final double PI = 3.14159; 

Notes about the code

• Declare a reference to this subfrmCircle. This reference is used in the initfrmCircle() method.

• Initialize the counter variable to 0. The user can update this variable from various instances of subfrmGlobals because all instances access the same subfrmCircle instance.

• Set the global constant PI. This is a constant that cannot be changed.

Getting a reference to a single subfrmCircle instance   

The following code shows the method in subfrmCircle that returns a reference to the first instance. The first time it is called, initfrmCircle() sets the OnlyfrmCircle global variable to itself and returns it. In subsequent executions of this method, it returns OnlyfrmCircle.

  public subfrmCircle initfrmCircle() 
  { 
  // Sets the variable to reference the very first instance of  
  // this class. In this way, any other Globals form that calls  
  // this method will be refer to the same (the first)  
  // Circle instance. This permits only one instance of  
  // subfrmCircle to be shared across forms, like a global variable. 
  if(theOnlyfrmCircle==null) 
     theOnlyfrmCircle = this; 
  return theOnlyfrmCircle; 
  } 

Notes about the code

• The first time that this method is called, theOnlyfrmCircle is null. This code sets it to this (first) theOnlyfrmCircle instance and returns it.

• Future calls to this method by other subfrmCircle instances will bypass the if statement and therefore return the same (first) instance.

• The formloaded() method in subfrmGlobals uses initfrmCircle() to get the first subfrmCircle instance, then assigns it to the calling subfrmCircle instance.

Accessing a single subfrmCircle instance from any subfrmGlobals instance   

The following code shows how to set a new instance of a subfrmCircle object to the first instance of the subfrmCircle object. Other methods in subfrmGlobals show how to get the PI constant and increment the counter. These global variables are accessed by all subfrmGlobals instances.

  //formLoaded code in subfrmGlobals 
   
  protected void formLoaded() 
  { 
     nfmtFormat.setMaximumFractionDigits (5); 
     fldRadius.setText("2"); 
   
     // Get the reference to the single, "global" instance  
     // of the subForm 
     subfrmCircle = subfrmCircle.initfrmCircle(); 
  } 

This is code from the Show PI button in subfrmGlobals:

  private void handle_btnShowPI_actionPerformed(ActionEvent evt) 
  { 
     // Get the value of the constant PI from frmCircle 
     fldPi.setText(nfmtFormat.format (subfrmCircle.PI)); 
  } 
   
  private void handle_btnCounter_actionPerformed(ActionEvent evt) 
  { 
     // Increment the variable counter in the one and only frmCircle 
     subfrmCircle.m_counter++; 
     fldCounter.setText(String.valueOf(subfrmCircle.m_counter)); 
  } 

Notes about the code

• When a subfrmGlobals instance is created, it creates a subfrmCircle instance. The code sets this subfrmCircle instance to the first instance by calling initfrmCircle() and setting it to the returned value.

• Get the global variable PI. Since formLoaded() is called when the form is loaded, the new subfrmCircle instance is already reassigned to the first instance. Therefore the PI variable is the "global" constant that all subfrmGlobals instances access.

• Similarly, every subfrmGlobals instance increments the same "global" counter variable. Each time the user clicks the Increment Counter button, regardless of the instance in which the button is located, the counter value increases by 1 from its last displayed value.

Launching subfrmGlobals forms   

The following code launches a Globals subform with each button click. These forms are subfrmGlobals instances. Each instance is represented by an integer that is displayed in the title bar of the form's window.

  //General declarations in frmGlobalsLauncher 
  final static String SUBFORM_NAME = "subfrmGlobals"; 
  int m_instance = 1; 

The following shows the code for the launch subfrom button in frmGlobalsLauncher:l

  private void handle_btnLaunch_actionPerformed(ActionEvent evt) 
  { 
     try 
     { 
      // Show the form, noting its instance number in the title 
      agDialog.showForm( 
        "Instance "+ String.valueOf(m_instance), //title 
           agDialog.getForm(SUBFORM_NAME),      // form name 
           2,      // window type 
           false,  // resizable 
           -1,     // x position 
           -1);    // y position   
      // increment our instance counter 
      m_instance++; 
     } 
     catch (Exception e) 
     { 
      agDialog.displayError(e); 
     } 
  } 

Notes about the code

• Create a subfrmGlobals form by calling getForm() and supplying subfrmGlobals as a parameter.

• Display the created form in a window by calling showForm(). Note that the subfrmGlobals instance is displayed with the m_instance variable.

• m_instance increments by 1 after each subfrmGlobals instantiation.