All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class com.ibm.as400.ui.framework.java.PanelManager

java.lang.Object
   |
   +----com.ibm.as400.ui.framework.java.PanelManager

public class PanelManager
extends Object
implements PaneManager, WindowManager
Creates a graphical panel defined using the Panel Definition Markup Language (PDML). The panel may be either a standalone window or a modal dialog.

PanelManager performs the following processing on behalf of the application:

To locate a panel definition, PanelManager needs three pieces of information:

The framework first searches the specified location for a file with a name matching the panel name, and an extension of .pdml.ser. If the serialized panel definition is not found, an attempt will be made to load a ResourceBundle and a PDML file which correspond to the specified resource name. If the resources cannot be located a DisplayManagerException will be thrown.

Examples

Assume that the panel MyPanel is defined in the file TestPanels.pdml, and that a properties file TestPanels.properties is associated with the panel definition. Both files reside in the directory com/ourCompany/ourPackage, which is accessible from a directory defined in the classpath, or from a ZIP or JAR file defined in the classpath. The following code creates the panel and displays it:

 import com.ibm.as400.ui.framework.java.*;
  
 // Create the panel manager. Parameters:
 // 1. Resource name of the panel definition
 // 2. Name of panel
 // 3. List of DataBeans omitted
  
 try {
 PanelManager pm = new PanelManager("com.ourCompany.ourPackage.TestPanels",
                                    "MyPanel",
                                    null);
 }
 catch (DisplayManagerException e) {
 e.displayUserMessage(null);
 System.exit(-1);
 }
  
 // Display the panel
 pm.setVisible(true);
 
Once the DataBeans that supply data to the panel have been implemented and the attributes have been identified in the PDML, the following code may be used to construct a fully-functioning dialog:

 import com.ibm.as400.ui.framework.java.*;
 import java.awt.Frame;
  
 // Instantiate the objects which supply data to the panel
 TestDataBean1 db1 = new TestDataBean1();
 TestDataBean2 db2 = new TestDataBean2();
  
 // Initialize the objects
 db1.load();
 db2.load();
  
 // Set up to pass the objects to the UI framework
 DataBean[] dataBeans = { db1, db2 };
  
 // Create the panel manager. Parameters:
 // 1. Resource name of the panel definition
 // 2. Name of panel
 // 3. List of DataBeans
 // 4. Owner frame window
  
 Frame owner;
 ...
 try {
 PanelManager pm = new PanelManager("com.ourCompany.ourPackage.TestPanels",
                                    "MyPanel",
                                    dataBeans,
                                    owner);
 }
 catch (DisplayManagerException e) {
 e.displayUserMessage(null);
 System.exit(-1);
 }
  
 // Display the panel
 pm.setVisible(true);
 

Command Line Interface

The command line interface may be used to display newly-defined panels, or to serialize PDML panel definitions.
 java com.ibm.as400.ui.framework.java.PanelManager
     [-serialize]
     [-locale <language code>_<country code>_<variant>]
     <resource name>
     <panel name>
 
Options:
-serialize
Parses the PDML panel definition and creates a serialized version of the panel. The name of the serialized file will match the panel name, and the file extension will be .pdml.ser. If this option is specified the panel will not be displayed on the screen.

-locale <language code>_<country code>_<variant>
Identifies the locale which should be used to locate the panel definition. The locale string should consist of a two-letter lowercase ISO Language Code, a two-letter uppercase ISO country code, and an optional variant string, each delimited by an underscore ("_") character. If this parameter is omitted the default locale will be used. If resources for the default locale cannot be found, an attempt will be made to use the base resources for the panel.

<resource name>
The fully-qualified resource name of the PDML document/resource bundle combination which defines the panel specification.

<panel name>
The name of the panel, as specified on the PANEL tag in the PDML document.

Examples:

Test a base sample panel:

java com.ibm.as400.ui.framework.java.PanelManager com.ourCompany.ourPackage.TestPanels MyPanel

Serialize the base panel:

java com.ibm.as400.ui.framework.java.PanelManager -serialize com.ourCompany.ourPackage.TestPanels MyPanel

Test the UK version:

java com.ibm.as400.ui.framework.java.PanelManager -locale en_UK com.ourCompany.ourPackage.TestPanels MyPanel

Serialize the UK version:

java com.ibm.as400.ui.framework.java.PanelManager -serialize -locale en_UK com.ourCompany.ourPackage.TestPanels MyPanel

See Also:
DisplayManagerException

Constructor Index

 o PanelManager(String, Locale, String)
Constructs a PanelManager for the specified panel, and then serializes the panel definition.
 o PanelManager(String, Locale, String, DataBean[])
Constructs a PanelManager for the specified panel.
 o PanelManager(String, Locale, String, DataBean[], Container)
Constructs a PanelManager for the specified panel, using the specified container.
 o PanelManager(String, Locale, String, DataBean[], Frame)
Constructs a PanelManager for the specified panel.
 o PanelManager(String, String, DataBean[])
Constructs a PanelManager for the specified panel.
 o PanelManager(String, String, DataBean[], Container)
Constructs a PanelManager for the specified panel, using the specified container.
 o PanelManager(String, String, DataBean[], Frame)
Constructs a PanelManager for the specified panel.

Method Index

 o activatePanel()
Runs the activation handlers for this panel.
 o addCancelListener(ActionListener)
Adds an ActionListener which is notified when the user cancels out of a window.
 o addCommitListener(ActionListener)
Adds an ActionListener which is notified when commit processing is complete.
 o applyChanges()
Transmits changes to user data to the DataBeans which manage the data.
 o commit(Vector)
Commits the changes to data displayed on the panel.
 o getComponent(String)
Returns the panel component identified by name.
 o getComponentDescriptor(String)
Returns the JavaComponentDescriptor for the specified panel component.
 o getContainer()
Returns the container which holds the user interface components for the panel.
 o getDataBeans()
Returns the list of DataBeans that was specified on this object's constructor.
 o getDelegateManager(String)
Returns the PaneManager to which the receiver is delegating management of the specified subpane.
 o getExitOnClose()
Determines whether the application exits when this panel is closed.
 o getFormatter(String)
Returns any specialized formatter to be used for a component.
 o getPreferredSize()
Returns the preferred size of this panel.
 o getTitle()
Returns the panel's title.
 o getWindow()
Returns the main panel window.
 o isVisible()
Determines whether this panel is visible.
 o loadData()
Called during initialization to load data into the panel.
 o main(String[])
Provides a command line interface to PanelManager.
 o prepareToCommit(Vector)
Request the DataBeans which manage data for the panel to verify that their data is in a consistent state.
 o refreshComponent(String)
Reloads a UI component with updated data from the component's DataBean.
 o serialize()
Serializes the panel definition.
 o setAggregateManager(PaneManager)
Sets the owning PaneManager for the receiver.
 o setExitOnClose(boolean)
Controls whether the application exits when the panel is closed, based on the value of parameter exit.
 o setFormatter(String, DataFormatter, boolean)
Sets a pre-created formatter to be used for a component.
 o setHelpPath(String)
 o setModalRelativeTo(WindowManager)
Sets the location of the panel being managed relative to a panel managed by the specified WindowManager.
 o setTitle(String)
Overrides the panel title defined in the panel definition.
 o setVisible(boolean)
Shows or hides the panel, depending on the value of parameter show.
 o setWaitCursor(boolean)
Sets or clears the wait cursor for the entire panel, based on the value of parameter wait.
 o setWaitPending(boolean)
Enables or disables the entire panel, based on the value of parameter wait.
 o showPane(String)
Displays the specified pane.
 o toString()
Returns a string representation of this object.

Constructors

 o PanelManager
 public PanelManager(String baseName,
                     String panelName,
                     DataBean dataBeans[]) throws DisplayManagerException
Constructs a PanelManager for the specified panel. The panel will be modeless.

The default locale will be used to load the panel definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
panelName - the name of the panel, as specified on the PANEL tag in the PDML document
dataBeans - a list of DataBeans which supply data to the panel (may be null)
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException
 o PanelManager
 public PanelManager(String baseName,
                     Locale locale,
                     String panelName,
                     DataBean dataBeans[]) throws DisplayManagerException
Constructs a PanelManager for the specified panel. The panel will be modeless.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
locale - the desired locale to be used to load the panel definition
panelName - the name of the panel, as specified on the PANEL tag in the PDML document
dataBeans - a list of DataBeans which supply data to the panel (may be null)
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException
 o PanelManager
 public PanelManager(String baseName,
                     String panelName,
                     DataBean dataBeans[],
                     Frame owner) throws DisplayManagerException
Constructs a PanelManager for the specified panel. The panel will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the panel has closed.

The default locale will be used to load the panel definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
panelName - the name of the panel, as specified on the PANEL tag in the PDML document
dataBeans - a list of DataBeans which supply data to the panel (may be null)
owner - the owning frame
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException, setVisible
 o PanelManager
 public PanelManager(String baseName,
                     Locale locale,
                     String panelName,
                     DataBean dataBeans[],
                     Frame owner) throws DisplayManagerException
Constructs a PanelManager for the specified panel. The panel will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the panel has closed.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
locale - the desired locale to be used to load the panel definition
panelName - the name of the panel, as specified on the PANEL tag in the PDML
dataBeans - a list of DataBeans which supply data to the panel (may be null)
owner - the owning frame
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException, setVisible
 o PanelManager
 public PanelManager(String baseName,
                     String panelName,
                     DataBean dataBeans[],
                     Container container) throws DisplayManagerException
Constructs a PanelManager for the specified panel, using the specified container. This constructor allows the application to supply its own container, rather than relying on this object to create a container of the appropriate type.

The default locale will be used to load the panel definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
panelName - the name of the panel, as specified on the PANEL tag in the PDML
dataBeans - a list of DataBeans which supply data to the panel (may be null)
container - the application's container
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException
 o PanelManager
 public PanelManager(String baseName,
                     Locale locale,
                     String panelName,
                     DataBean dataBeans[],
                     Container container) throws DisplayManagerException
Constructs a PanelManager for the specified panel, using the specified container. This constructor allows the application to supply its own container, rather than relying on this object to create a container of the appropriate type.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
locale - the desired locale to be used to load the panel definition
panelName - the name of the panel, as specified on the PANEL tag in the PDML
dataBeans - a list of DataBeans which supply data to the panel (may be null)
container - the application's container
Throws: DisplayManagerException
if an error was encountered accessing the panel definition
See Also:
DisplayManagerException
 o PanelManager
 public PanelManager(String baseName,
                     Locale locale,
                     String panelName) throws DisplayManagerException
Constructs a PanelManager for the specified panel, and then serializes the panel definition. This constructor cannot be used to display the panel.

If a null locale is specified, the default locale will be used to load the panel definition. If resources for the default locale cannot be found, an attempt will be made to use the base resources for the panel.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the panel specification
locale - the desired locale to be used to load the panel definition (may be null)
panelName - the name of the panel, as specified on the PANEL tag in the PDML
Throws: DisplayManagerException
if an error was encountered accessing or serializing the panel definition
See Also:
serialize

Methods

 o main
 public static void main(String args[])
Provides a command line interface to PanelManager. See the class description.

 o serialize
 public void serialize() throws IOException
Serializes the panel definition. The filename of the serialized file will be of the form
 <panel name>_<locale string>.pdml.ser
 
where <panel name> is the name of the panel as specified on the PANEL tag in the PDML, and <locale string> consists of the ISO Language Code, ISO Country Code, and optional variant codes, each delimited by an underscore ("_") character.

Throws: IOException
if serialized file cannot be written
 o setExitOnClose
 public void setExitOnClose(boolean exit)
Controls whether the application exits when the panel is closed, based on the value of parameter exit. The default value is false.

This method has no effect if it is called after this panel is made visible, or if the application supplied the container to be managed.

Parameters:
exit - If true, exit the application; otherwise, just hide the panel.
See Also:
getExitOnClose
 o getExitOnClose
 public boolean getExitOnClose()
Determines whether the application exits when this panel is closed.

Returns:
true if the application will be exited; false otherwise.
See Also:
setExitOnClose
 o setTitle
 public void setTitle(String title)
Overrides the panel title defined in the panel definition.

This method has no effect if the application supplied the ???? ????????

Parameters:
title - The title which should appear in the panel's title bar.
See Also:
getTitle
 o setHelpPath
 public void setHelpPath(String path)
 o setVisible
 public void setVisible(boolean show)
Shows or hides the panel, depending on the value of parameter show. If an owner frame was specified on the constructor indicating that the panel is modal, the application will block on the call to setVisible until the panel has closed.

This method has no effect if the application supplied the container to be managed.

Parameters:
show - If true, shows the panel; otherwise, hides the panel.
See Also:
isVisible
 o isVisible
 public boolean isVisible()
Determines whether this panel is visible. The panel is initially invisible.

Returns:
true if the panel is visible; false otherwise.
See Also:
setVisible
 o getDataBeans
 public DataBean[] getDataBeans()
Returns the list of DataBeans that was specified on this object's constructor.

Returns:
a Vector of DataBeans
 o getContainer
 public Container getContainer()
Returns the container which holds the user interface components for the panel. The Container object supplied on this object's constructor will be returned, if one was specified. Otherwise, this method will return the content pane of a JDialog or JFrame object, depending on whether the panel is modal or modeless.

Returns:
the panel's container
 o getPreferredSize
 public Dimension getPreferredSize()
Returns the preferred size of this panel.

Returns:
A dimension object indicating this panel's preferred size.
 o refreshComponent
 public void refreshComponent(String componentName)
Reloads a UI component with updated data from the component's DataBean.

Parameters:
componentName - the name of the component whose data is to be refreshed, as specified in the PDML definition for the panel
 o setWaitCursor
 public void setWaitCursor(boolean wait)
Sets or clears the wait cursor for the entire panel, based on the value of parameter wait. If wait is true, the hourglass cursor will appear over the panel and all its components. Calling setWaitCursor with a value of false will restore the normal "default" cursor.

Parameters:
wait - If true, sets the wait cursor; otherwise, restores the default cursor.
See Also:
setWaitPending
 o setWaitPending
 public void setWaitPending(boolean wait)
Enables or disables the entire panel, based on the value of parameter wait. If wait is true, the panel and all its user-modifiable components will be grayed out and disabled for user input, and the hourglass cursor will be displayed. Calling setWaitPending with a value of false will restore the panel components to their normal "enabled" state, and restore the normal cursor.

Parameters:
enable - If true, enables the panel; otherwise, disables the panel.
See Also:
setWaitCursor
 o toString
 public String toString()
Returns a string representation of this object.

Returns:
the class name and panel title as a string
Overrides:
toString in class Object
 o setFormatter
 public void setFormatter(String componentName,
                          DataFormatter formatter,
                          boolean required)
Sets a pre-created formatter to be used for a component.

This facility is provided formatters which require specialized parameters or initialization beyond the standard inititialization offered during run time. The panel manager uses the formatter provided instead of creating a formatter at run time.

Parameters:
componentName - the name of the component as specified in the panel definition
formatter - a DataFormatter subclassed object
required - a value is required for this component
See Also:
DataFormatter
 o getFormatter
 public DataFormatter getFormatter(String componentName)
Returns any specialized formatter to be used for a component.

Parameters:
componentName - the name of the component as specified in the panel definition
Returns:
a DataFormatter or null if not set or not found true if the formatter was successfully set
See Also:
DataFormatter
 o getTitle
 public String getTitle()
Returns the panel's title.

Returns null if the application supplied the container to be managed.

Returns:
The title which appears in the panel's title bar.
See Also:
PaneManager, setTitle
 o loadData
 public void loadData()
Called during initialization to load data into the panel.

See Also:
PaneManager
 o activatePanel
 public void activatePanel()
Runs the activation handlers for this panel. Applications should call this method before calling setVisible if they supplied their own container on the constructor.

See Also:
setVisible, PaneManager
 o showPane
 public void showPane(String paneName)
Displays the specified pane. This method has no implementation, since PanelManager's single pane is always visible.

See Also:
PaneManager
 o getComponent
 public Component getComponent(String name)
Returns the panel component identified by name.

Parameters:
name - the name of the component as specified in the panel definition
Returns:
a Component having the name specified
See Also:
PaneManager
 o getComponentDescriptor
 public JavaComponentDescriptor getComponentDescriptor(String name)
Returns the JavaComponentDescriptor for the specified panel component.

Parameters:
name - the name of the component as specified in the panel definition
Returns:
a JavaComponentDescriptor for the component
See Also:
PaneManager
 o getDelegateManager
 public PaneManager getDelegateManager(String paneName)
Returns the PaneManager to which the receiver is delegating management of the specified subpane.

Parameters:
paneName - the name of the pane as specified in the PDML definition
Returns:
the desired PaneManager, or null if the object cannot be found
See Also:
PaneManager
 o setAggregateManager
 public void setAggregateManager(PaneManager mgr)
Sets the owning PaneManager for the receiver. The specified object identifies the PaneManager to which certain requests should be delegated when this PanelManager is participating in an aggregate user interface.

Parameters:
mgr - the PaneManager with which the receiver is to be associated
See Also:
PaneManager
 o applyChanges
 public void applyChanges() throws IllegalUserDataException
Transmits changes to user data to the DataBeans which manage the data. Calls the settor methods for all UI components that have accessor methods associated with them.

This method is called when the panel is about to be closed.

See Also:
PaneManager
 o prepareToCommit
 public void prepareToCommit(Vector preparedDataBeans)
Request the DataBeans which manage data for the panel to verify that their data is in a consistent state. Calls the verifyChanges method for all DataBeans associated with the panel.

This method is called when the panel is about to be closed.

Parameters:
preparedDataBeans - a list of DataBeans which have already been prepared on the current commit operation
See Also:
PaneManager
 o commit
 public void commit(Vector committedDataBeans)
Commits the changes to data displayed on the panel. Calls the commit method on all DataBeans which manage data for the panel.

This method is called when the user indicates a desire to permanently save changes to the data, by clicking an OK button for example.

Parameters:
committedDataBeans - a list of DataBeans which have already been saved on the current commit operation
See Also:
PaneManager
 o getWindow
 public Window getWindow()
Returns the main panel window. The window may be either an instance of JDialog or JFrame, depending on whether the panel is modal or modeless.

Returns:
the main window for this panel
See Also:
WindowManager
 o setModalRelativeTo
 public void setModalRelativeTo(WindowManager mgr)
Sets the location of the panel being managed relative to a panel managed by the specified WindowManager. If the panel is not currently showing, the panel for this PanelManager is centered on the screen.

This method has no effect if it is called after this panel is made visible.

Parameters:
mgr - the WindowManager managing the panel in relation to which this object's panel location is determined
See Also:
WindowManager
 o addCommitListener
 public void addCommitListener(ActionListener listener)
Adds an ActionListener which is notified when commit processing is complete.

This facility is provided for modeless windows, so that the application may learn when the window has closed. The listener's actionPerformed method will be called following successful completion of commit processing on the panel. The ActionEvent passed to the listener object will have its action command string set to "COMMIT".

This method is not recommended for modal windows, since the application will be blocked on the setVisible call until the window is closed.

Parameters:
listener - the ActionListener to be notified
See Also:
WindowManager
 o addCancelListener
 public void addCancelListener(ActionListener listener)
Adds an ActionListener which is notified when the user cancels out of a window.

This facility is provided for modeless windows, so that the application may learn when the window has closed. The listener's actionPerformed method will be called when the user cancels out of the panel without committing any changes. The ActionEvent passed to the listener object will have its action command string set to "CANCEL".

This method is not recommended for modal windows, since the application will be blocked on the setVisible call until the window is closed.

Parameters:
listener - the ActionListener to be notified
See Also:
WindowManager

All Packages  Class Hierarchy  This Package  Previous  Next  Index