SilverStream
Application Server 3.5

com.sssw.rt.form
Class AgfForm

java.lang.Object
 |
 +--java.awt.Component
       |
       +--java.awt.Container
             |
             +--javax.swing.JComponent
                   |
                   +--javax.swing.JPanel
                         |
                         +--com.sssw.rt.atlas.AtPanel
                               |
                               +--com.sssw.rt.form.PvBasePanel
                                     |
                                     +--com.sssw.rt.form.PvBaseContainer
                                           |
                                           +--com.sssw.rt.form.AgfForm
All Implemented Interfaces:
Accessible, ActionListener, AgiControl, AgiHelpInfo, AgiRTEditorListener, AgiTabstopHandler, EventListener, ImageObserver, ItemListener, MenuContainer, Serializable, WindowListener

public class AgfForm
extends PvBaseContainer
implements ActionListener, ItemListener, WindowListener, AgiRTEditorListener

The AgfForm control (Form) is the basic building block of a java-based interactive user interface.

Every form has these several instance variables built-in:
agBrowser - an instance of the PvHelperBrowser class that manages the user's Browser environment.
agData - an instance of the AgcDataPrimary class that binds the form to a primary dataset.
agDialog - an instance of the PvHelperDialog class that displays message dialogs or forms as dialog boxes.
agGeneral - an instance of the PvHelperGeneral class that invokes business objects.
agDataMgr - an instance of the AgoBindingManager class that manages data binding and enables searching the data.

Properties:
Background Color, Background Image, Background Image Mode, Distinct, Height, Help Page, Initial Data Mode, Limit Rows, Maximum Rows, Order By, Show Validation Errors, Transparent, Where Clause, Width
Events:
doLayout, formActivate, formCustomEvent, formLoaded, formPaint, globalValidationFailed, globalValidationTest, menuItemSelected, menuItemStateChanged, mouseClicked, mouseDragged, mouseEntered, mouseExited, mouseMoved, mousePressed, mouseReleased, preprocessKeyPressed, privateEvents, windowClosing
See Also:
Serialized Form

Inner classes inherited from class javax.swing.JPanel
JPanel.AccessibleJPanel
 
Inner classes inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Fields inherited from class com.sssw.rt.atlas.AtPanel
BGIMAGE_DRAW_CENTERED, BGIMAGE_DRAW_NORMAL, BGIMAGE_DRAW_STRETCH, BGIMAGE_DRAW_TILED
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Constructor Summary
AgfForm()
           
 
Method Summary
 CheckboxMenuItem addCheckboxMenuItem(Menu menu, String label)
          Creates a checkbox menu item, adds it to the specified menu, and adds this form as a Listener for the item.
protected  void addControls()
          Adds the child controls to the form (calling "this.add(Component)" for each control).
 MenuItem addMenuItem(Menu menu, String label, MenuShortcut shortcut)
          Creates a menu item, adds it to the specified menu, and adds this form as a Listener for the item.
protected  boolean adjustControlSizes()
          Return true if you want the sizes of the form and the controls on it to be adjusted for the fonts on the runtime platform.
 void closeDialog(Object returnValue)
          Closes a form that has been opened as a dialog box.
protected  void debugPrint(String msg)
          Prints a String to the console when the form is run in debug mode.
 void fireCustomEvent(AgfForm target, Object identifier, Object argument)
          Fires the formCustomEvent event, which allows a modeless dialog to communicate with its parent form and vice versa.
 void fireEvent(int eventId, Object arg)
          Fires a specified user-defined event to the form's containing form (parent).
 Frame getFrame()
          Returns the frame containing this form.
 Image getImage(String imageSpec)
          Gets an image from a database or URL.
 int getIntParameter(String name)
          Returns a parameter as an integer value.
 Object getParameter(String name)
          Returns the value of a parameter.
 Hashtable getParameters()
          Returns a Hashtable that contains all of the parameters associated with the form.
 AgfForm getParentForm()
          Returns a form object that is the parent (container) of the current form.
 String getStringParameter(String name)
          Returns a parameter as a String value.
 String getUser()
          Returns the user name of the current user.
 void setParameter(String name, int value)
          Assigns a value to a parameter.
 void setParameter(String name, Object value)
          Assigns a value to a parameter.
 void setPassword(String newPassword)
          Changes the current user's password.
 boolean userInGroup(String group)
          Returns a boolean indicating whether the current user is in the specified group.
 
Methods inherited from class com.sssw.rt.form.PvBaseContainer
acceptValues, addControl, addControlAt, getControl, getControlCount, getUserDefinedTabOrder, removeControl, setTabOrder, setUserDefinedTabOrder
 
Methods inherited from class com.sssw.rt.form.PvBasePanel
getBackgroundColor, getFontIdentifier, setBackgroundColor, setFontIdentifier
 
Methods inherited from class com.sssw.rt.atlas.AtPanel
addImpl, addNotify, clientPaint, clientPaint, deliverMouseEvent, deliverMouseMoveEvent, doAtCommand, drawTiledImage, enableAtCommands, getBackgroundImage, getBackgroundImageMode, getHelper, getTransparent, hide, hideToolTip, imageUpdate, isFocusTraversable, isOptimizedDrawingEnabled, ownedImage, paintBorder, paintComponent, paintImmediately, paintImmediately, paintNow, preprocessKeyEvent, processEvent, reshape, setBackgroundImage, setBackgroundImageMode, setTransparent, show, showToolTip
 
Methods inherited from class javax.swing.JPanel
getAccessibleContext, getUIClassID, paramString, updateUI
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addPropertyChangeListener, addPropertyChangeListener, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getActionForKeyStroke, getAlignmentX, getAlignmentY, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getConditionForKeyStroke, getDebugGraphicsOptions, getGraphics, getHeight, getInsets, getInsets, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getVisibleRect, getWidth, getX, getY, grabFocus, hasFocus, isDoubleBuffered, isFocusCycleRoot, isLightweightComponent, isManagingFocus, isOpaque, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintChildren, print, printAll, processComponentKeyEvent, processFocusEvent, processKeyEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removePropertyChangeListener, removePropertyChangeListener, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, resetKeyboardActions, revalidate, scrollRectToVisible, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setDebugGraphicsOptions, setDoubleBuffered, setEnabled, setFont, setForeground, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setUI, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getLayout, insets, invalidate, isAncestorOf, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, remove, remove, removeAll, removeContainerListener, setCursor, setLayout, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, disable, disableEvents, dispatchEvent, enable, enable, enableEvents, enableInputMethods, getBackground, getBounds, getColorModel, getComponentOrientation, getCursor, getDropTarget, getFont, getFontMetrics, getForeground, getInputContext, getInputMethodRequests, getLocale, getLocation, getLocationOnScreen, getName, getParent, getPeer, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, inside, isDisplayable, isEnabled, isLightweight, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processInputMethodEvent, processMouseEvent, remove, removeComponentListener, removeFocusListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setDropTarget, setLocale, setLocation, setLocation, setName, setSize, setSize, show, size, toString, transferFocus
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 
Methods implemented from interface java.awt.event.ActionListener
actionPerformed
 
Methods implemented from interface com.sssw.rt.form.AgiControl
getComponent, getHelpInfo, setHelpInfo
 
Methods implemented from interface com.sssw.rt.event.AgiRTEditorListener
editorImageButtonClicked, editorLinkButtonClicked, editorObjectButtonClicked, htmlAnchorDetected, htmlAnchorSelected
 
Methods implemented from interface com.sssw.rt.util.AgiTabstopHandler
getTabOrder
 
Methods implemented from interface java.awt.event.ItemListener
itemStateChanged
 
Methods implemented from interface java.awt.event.WindowListener
windowActivated, windowClosed, windowClosing, windowDeactivated, windowDeiconified, windowIconified, windowOpened
 

Constructor Detail

AgfForm

public AgfForm()
Method Detail

addControls

protected void addControls()
Adds the child controls to the form (calling "this.add(Component)" for each control). Override to perform the add yourself.

addMenuItem

public MenuItem addMenuItem(Menu menu,
                            String label,
                            MenuShortcut shortcut)
Creates a menu item, adds it to the specified menu, and adds this form as a Listener for the item. The form's menuItemSelected method will be invoked when the menu item is selected.

The 'label' parameter may be null to insert a separator item.
The 'shortcut' parameter may be null if no shortcut is desired for the item.
The 'shortcut' parameter is ignored if the 'label' parameter is null

Parameters:
menu - the menu to which the item is added
label - the text of the menu item
shortcut - a shortcut to the menu item
Example:
 	addMenuItem(myHelpMenu, "About...", null);
 

addCheckboxMenuItem

public CheckboxMenuItem addCheckboxMenuItem(Menu menu,
                                            String label)
Creates a checkbox menu item, adds it to the specified menu, and adds this form as a Listener for the item.

The form's menuItemStateChanged method is invoked when the menu item is selected.

Parameters:
menu - The menu to which the item is added
label - The text of the menu item
Example:
 	addCheckboxMenuItem(myOptionsMenu, "Show Grid");
 

getParentForm

public AgfForm getParentForm()
Returns a form object that is the parent (container) of the current form.
Usage:

The current form might be a subform or a form launched as a dialog box (agDialog.showFormDialog()).

Example:

The following example illustrates how to obtain the current form's parent form.

  AgfForm parent;
  parent = getParentForm();
 

setParameter

public void setParameter(String name,
                         Object value)
Assigns a value to a parameter.
Parameters:
name - the parameter's name.
value - the value to set for the parameter.
Usage:

This parameter is a user-defined parameter.

Example:
  setParameter("Exchange Rate", new Double(1.53));
 

setParameter

public void setParameter(String name,
                         int value)
Assigns a value to a parameter.
Parameters:
name - the parameter's name.
value - the value to set for the parameter.
Usage:

This parameter is a user-defined parameter.

Example:
  setParameter("Repeat Count", 6);
 

getParameter

public Object getParameter(String name)
Returns the value of a parameter.
Parameters:
name - the name of the parameter
Usage:

The parameters are user-defined parameters passed in as a Hashtable or set using the setParameter() method.

Example:
 	Object value = getParameter("Exchange Rate");
 
See Also:
AgfForm.setParameter(String, int)

getStringParameter

public String getStringParameter(String name)
Returns a parameter as a String value.
Parameters:
name - the name of the parameter.
Usage:

The parameters are user-defined parameters passed in as a Hashtable or set using the setParameter() method.

Example:

This example illustrates how to use the getStringParameter() method.

  String param;
  param = getStringParameter("name");
 
See Also:
AgfForm.getParameters(), AgfForm.getIntParameter(String), AgfForm.getParameter(String), Events Produced property, Parameters property

getIntParameter

public int getIntParameter(String name)
Returns a parameter as an integer value.
Parameters:
name - The name of the parameter.
Usage:

The parameters are user-defined parameters passed in as a Hashtable or set using the setParameter() method.

Example:

This example illustrates how to get the integer value of the salary parameter.

  int param;
  param = getIntParameter("salary");
 
See Also:
AgfForm.getParameters(), AgfForm.getStringParameter(String), AgfForm.getParameter(String), Events Produced property, Parameters property

getParameters

public Hashtable getParameters()
Returns a Hashtable that contains all of the parameters associated with the form.
Usage:

The parameters are user-defined parameters passed in as a Hashtable or set using the setParameter() method.

Example:

This example illustrates how to use the getParameters() method.

  Hashtable params;
  params = getParameters();
 
See Also:
AgfForm.getStringParameter(String), AgfForm.getIntParameter(String), AgfForm.getParameter(String), Events Produced property, Parameters property

fireEvent

public void fireEvent(int eventId,
                      Object arg)
Fires a specified user-defined event to the form's containing form (parent).
Parameters:
eventID - specifies the event to fire.
argument - specified data to include with the event.
Usage:

User-defined events can be created by adding an event name through the form's property sheet (Events Produced property). Typically user-defined events are created for subforms to enable the subform to inform the parent form of conditions or user actions on the subform.

Example:

This example shows how the fireEvent() method is called for example from a button on a subform:

  fireEvent(this.TRIGGER, arg);
 

The keyword "this" is not required. It refers to the form and not the button. The example could also read

  fireEvent(TRIGGER, arg);
 

In the parent form, the TRIGGER event is listed in the programming editor under the subform name in the event list.


fireCustomEvent

public void fireCustomEvent(AgfForm target,
                            Object identifier,
                            Object argument)
Fires the formCustomEvent event, which allows a modeless dialog to communicate with its parent form and vice versa.
Parameters:
target - specifies form to receive the formCustomEvent
identifier - can contain any value that identifies the event and/or form that fired it. It can be any value agreed upon by both forms (e.g. "UPDATE_NOW").
argument - specifies additional data to pass with the event
Usage:

As an example, a button could be used on the modeless dialog to tell the parent dialog to update its display. On the dialog form, code like this would be added to the button:

      fireCustomEvent(getParentForm(), "update display", null)
 

Then on the parent, code would be added to formCustomEvent to check the identifier, and update the display, if the String is "update display". This mechanism works just as well when showing a form in a frame(FORM_FRAME) as it does for showing a form in a modeless dialog.


getFrame

public Frame getFrame()
Returns the frame containing this form.
Example:
 	Frame myFrame = getFrame();
 

closeDialog

public void closeDialog(Object returnValue)
Closes a form that has been opened as a dialog box.
Parameters:
returnValue - specifies the object to return to the caller of showFormDialog().
Usage:

This method is typically called from the actionPerformed event of the form's OK or Cancel button. Note that closeDialog() does not validate the form before closing it. The windowClosing event is used to force the dialog to validate the form before closing it.

However, this event only occurs on the topmost form in the window that the user closes by clicking the windows close box, for example. It is not called on any subforms, or any frames that have been popped up in frames or modeless dialogs. It is up to you to notify these other forms, if this behavior is desired.

Hashtables are often used to pass information from a parent form to dialog boxes or subforms launched from it.

A form can be displayed as a dialog box by calling the agDialog.showFormDialog() method.

Example:
 	closeDialog(Boolean.TRUE);
 
See Also:
PvHelperDialog.showFormDialog(String, String), windowClosing event

getImage

public Image getImage(String imageSpec)
Gets an image from a database or URL.
Parameters:
imageSpec - The name of the image, if the image is contained in the same database as the form, a full URL to the image, or databaseName:imageName
Example:
 	Image img = getImage("Utility:UnderConstruction.gif");
 

debugPrint

protected void debugPrint(String msg)
Prints a String to the console when the form is run in debug mode.
Parameters:
msg - specifies the debug message to display.
Usage:

The message prints in the console window.

To specify debug mode:

  • Choose the Edit menu from the Main Designer window.
  • Choose the Preferences menu option.
  • Choose the compiler tab.
  • Make sure that the Include debugging information radio button is on.
Example:
 	debugPrint("The value of the field is " + field1.getText());
 

adjustControlSizes

protected boolean adjustControlSizes()
Return true if you want the sizes of the form and the controls on it to be adjusted for the fonts on the runtime platform. If the fonts on the runtime platform are larger than the fonts on the design-time platform, then the form and the controls will be made larger, and vice versa.

Default is false - don't adjust the control sizes. (Default was true before Release 3.0.)


getUser

public String getUser()
Returns the user name of the current user.
Usage:

If the user has not logged in, the getUser() method returns "Anonymous".

Example:

This example illustrates how to obtain the current user.

  String user;
  user = getUser();
 
See Also:
AgfForm.userInGroup(String)

setPassword

public void setPassword(String newPassword)
                 throws AgoException,
                        IOException
Changes the current user's password.
Parameters:
newPassword - specifies the password to set
Example:
 	setPassword(field1.getText());
 

userInGroup

public boolean userInGroup(String group)
Returns a boolean indicating whether the current user is in the specified group.
Parameters:
group - specifies the group name If the user is part of the group, the method returns true.
Example:
 	if (userInGroup("Administrators"))
 	{
 		// Allow administration tasks...
 	}
 
See Also:
AgfForm.getUser()

SilverStream
Application Server 3.5