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

java.lang.Object
  |
  +--com.ibm.as400.ui.framework.java.PanelManager
All Implemented Interfaces:
PaneManager, WindowManager
Direct Known Subclasses:
DynamicPanelManager

public class PanelManager
extends java.lang.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
  
 PanelManager pm = null;
 try {
 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;
 ...
 PanelManager pm = null;
 try {
 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

Since:
v4r2m0
See Also:
DisplayManagerException

Field Summary
protected  int m_windowMinHeight
           
protected  int m_windowMinWidth
           
 
Fields inherited from interface com.ibm.as400.ui.framework.java.WindowManager
OFFSET_FROM_OWNER
 
Constructor Summary
PanelManager(java.lang.String baseName, java.util.Locale locale, java.lang.String panelName)
          Constructs a PanelManager for the specified panel, and then serializes the panel definition.
PanelManager(java.lang.String baseName, java.util.Locale locale, java.lang.String panelName, DataBean[] dataBeans)
          Constructs a PanelManager for the specified panel.
PanelManager(java.lang.String baseName, java.util.Locale locale, java.lang.String panelName, DataBean[] dataBeans, java.awt.Container container)
          Constructs a PanelManager for the specified panel, using the specified container.
PanelManager(java.lang.String baseName, java.util.Locale locale, java.lang.String panelName, DataBean[] dataBeans, java.awt.Frame owner)
          Constructs a PanelManager for the specified panel.
PanelManager(java.lang.String baseName, java.lang.String panelName, DataBean[] dataBeans)
          Constructs a PanelManager for the specified panel.
PanelManager(java.lang.String baseName, java.lang.String panelName, DataBean[] dataBeans, java.awt.Container container)
          Constructs a PanelManager for the specified panel, using the specified container.
PanelManager(java.lang.String baseName, java.lang.String panelName, DataBean[] dataBeans, java.awt.Frame owner)
          Constructs a PanelManager for the specified panel.
 
Method Summary
 void activatePanel()
          Runs the activation handlers for this panel.
 void addActionListener(java.lang.String componentName, java.awt.event.ActionListener al)
          Adds an ActionListener to the component identified by componentName These listeners will not be notified when DataBean updating occurs through calls to loadData() or refreshComponent().
 void addActivationHandler(EventHandler eh)
          Adds an ActionListener which is notified when this panel is shown
 void addCancelListener(java.awt.event.ActionListener listener)
          Adds an ActionListener which is notified when the user cancels out of a window.
 void addCancelListener(java.lang.Object listener)
           
 void addCommitListener(java.awt.event.ActionListener listener)
          Adds an ActionListener which is notified when commit processing is complete.
 void addCommitListener(java.lang.Object listener)
           
 void addExpansionListener(java.lang.String treeTableName, java.lang.Object listener)
          Adds a TreeExpansionListener which is notified when the user expands a node in the specified tree table.
 void addHelpListener(HelpListener listener)
          Identifies an alternate help system.
 void applyChanges()
          Transmits changes to user data to the DataBeans which manage the data.
 void applyChanges(java.lang.String componentName)
          Transmits changes to user data to the DataBeans which manage the data.
 void commit(java.util.Vector committedDataBeans)
          Commits the changes to data displayed on the panel.
 void displayHelp()
          Displays the overview help for the panel.
 void dispose()
          Closes the panel and releases all resources used by the panel and its associated UI components.
 PaneManager getAggregateManager()
          Returns the owning PaneManager for the receiver.
 java.awt.Component getComponent(java.lang.String name)
          Returns the panel component identified by name.
 com.ibm.as400.ui.framework.java.JavaComponentDescriptor getComponentDescriptor(java.lang.String name)
          Returns the JavaComponentDescriptor for the specified panel component.
 java.lang.String getComponentText(java.lang.String componentName)
          Convenience method which gets the component's text
 java.awt.Container getContainer()
          Returns the container which holds the user interface components for the panel.
 DataBean[] getDataBeans()
          Returns the list of DataBeans that was specified on this object's constructor.
 PaneManager getDelegateManager(java.lang.String paneName)
          Returns the PaneManager to which the receiver is delegating management of the specified subpane.
 boolean getExitOnClose()
          Determines whether the application exits when this panel is closed.
 DataFormatter getFormatter(java.lang.String componentName)
          Returns any specialized formatter to be used for a component.
 java.lang.String getIconName()
          Returns the name of the icon used for this panel.
 javax.swing.JMenuBar getMenuBar()
          Returns the menu bar defined for this panel.
 MenuManager getMenuManager(java.lang.String name)
          Returns a MenuManager associated with this panel's menu bar.
 java.lang.String getName()
          Gets this PanelManager's name
 NodeDescriptor getNode(java.lang.String treeTableName, int row)
          Returns the tree node in the specified table row
 WindowManager getOwnerManager()
          Returns the WindowManager in relation to which the receiver has been set modal, or null if the receiver is not modal relative to another window.
 java.awt.Dimension getPreferredSize()
          Returns the preferred size of this panel.
 PaneManager getRootManager()
          Returns the root PaneManager for the receiver.
 boolean getSaveOnThread()
          Indicates whether calls to the save method on the application's DataBean objects will be called on a non-UI thread.
 int getTableRow(java.lang.String treeTableName, NodeDescriptor nd)
          Returns the table row number containing the specified tree node
 java.lang.String getTitle()
          Returns the panel's title.
 javax.swing.JToolBar getToolBar()
          Returns the toolbar defined for this panel.
 javax.swing.AbstractButton getToolBarButton(java.lang.String name)
          Returns a JComponent from the ToolBar
 java.awt.Window getWindow()
          Returns the main panel window.
 void handleDataException(IllegalUserDataException ex)
          Provides the default handling for an IllegalUserDataException.
static void handleDataException(IllegalUserDataException ex, java.awt.Container messageOwner)
          Provides the default handling for an IllegalUserDataException.
 boolean isEnabled(java.lang.String name)
          Determines whether the panel component identified by name is Enabled.
 boolean isRequiredField(java.lang.String componentName)
          Returns whether this entry-field requires a non-blank entry
 boolean isVisible()
          Determines whether this panel is visible.
 boolean isVisible(java.lang.String name)
          Determines whether the panel component identified by name is Enabled.
 void loadData()
          Called during initialization to load data into the panel.
static void main(java.lang.String[] args)
          Provides a command line interface to PanelManager.
 void prepareToCommit(java.util.Vector preparedDataBeans)
          Request the DataBeans which manage data for the panel to verify that their data is in a consistent state.
 void refreshComponent(java.lang.String componentName)
          Reloads a UI component with updated data from the component's DataBean.
 void refreshTree(java.lang.String treeName)
          Reloads a tree component with updated data from the tree's DataBean, while preserving the expansion state of all visible nodes Warning: NodeDescriptors in the tree must have unique names.
 void removeActionListener(java.lang.String componentName, java.awt.event.ActionListener al)
          Removes an ActionListener from the component identified by componentName
 void removeExpansionListener(java.lang.Object listener)
          Removes a TreeExpansionListener from the 'active list'
 void serialize()
          Serializes the panel definition.
 void setAggregateManager(PaneManager mgr)
          Sets the owning PaneManager for the receiver.
 void setButtonText(java.lang.String buttonName, java.lang.String text)
          Sets the button's text
 void setComponentText(java.lang.String componentName, java.lang.String text)
          Convenience method which sets the component's text
 void setEnabled(java.lang.String name, boolean b)
          Enables the panel component identified by name.
 void setExitOnClose(boolean exit)
          Controls whether the application exits when the panel is closed, based on the value of parameter exit.
 void setExpanded(java.lang.String treeTableName, NodeDescriptor nd, boolean bExpand)
          Programmatically expand or collapse a node in a tree component
 void setFormatter(java.lang.String componentName, DataFormatter formatter, boolean required)
          Sets a pre-created formatter to be used for a component.
 void setHelpPath(java.lang.String path)
          Base location for help files.
 void setIconName(java.lang.String fileName)
          Overrides the name of the icon to use for this panel.
 void setModalRelativeTo(WindowManager mgr)
          Sets the location of the panel being managed relative to a panel managed by the specified WindowManager.
 void setName(java.lang.String name)
          Sets the name of this PanelManager This method should only be used for PanelManagers that will be added to PropertySheets or Wizards and must be called before they are added
 void setRequiredField(java.lang.String componentName, boolean required)
          Sets whether this field should be required
 void setSaveOnThread(boolean saveOnThread)
          Controls whether calls to the save method on the application's DataBean objects will be called on a non-UI thread.
 void setTitle(java.lang.String title)
          Overrides the panel title defined in the panel definition.
 void setToolBarIcon(javax.swing.ImageIcon icon)
          Sets the Icon to be displayed right justified on the toolbar
 void setVisible(boolean show)
          Shows or hides the panel, depending on the value of parameter show.
 void setVisible(java.lang.String name, boolean b)
          Shows or hides the panel component identified by name.
 void setWaitCursor(boolean wait)
          Sets or clears the wait cursor for the entire panel, based on the value of parameter wait.
 void setWaitPending(boolean wait)
          Enables or disables the entire panel, based on the value of parameter wait.
 void showPane(java.lang.String paneName)
          Displays the specified pane.
 java.lang.String toString()
          Returns a string representation of this object.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

m_windowMinWidth

protected int m_windowMinWidth

m_windowMinHeight

protected int m_windowMinHeight
Constructor Detail

PanelManager

public PanelManager(java.lang.String baseName,
                    java.lang.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
Since:
v4r2m0
See Also:
DisplayManagerException

PanelManager

public PanelManager(java.lang.String baseName,
                    java.util.Locale locale,
                    java.lang.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
Since:
v4r2m0
See Also:
DisplayManagerException

PanelManager

public PanelManager(java.lang.String baseName,
                    java.lang.String panelName,
                    DataBean[] dataBeans,
                    java.awt.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
Since:
v4r2m0
See Also:
DisplayManagerException, setVisible(boolean)

PanelManager

public PanelManager(java.lang.String baseName,
                    java.util.Locale locale,
                    java.lang.String panelName,
                    DataBean[] dataBeans,
                    java.awt.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
Since:
v4r2m0
See Also:
DisplayManagerException, setVisible(boolean)

PanelManager

public PanelManager(java.lang.String baseName,
                    java.lang.String panelName,
                    DataBean[] dataBeans,
                    java.awt.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
Since:
v4r2m0
See Also:
DisplayManagerException

PanelManager

public PanelManager(java.lang.String baseName,
                    java.util.Locale locale,
                    java.lang.String panelName,
                    DataBean[] dataBeans,
                    java.awt.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
Since:
v4r2m0
See Also:
DisplayManagerException

PanelManager

public PanelManager(java.lang.String baseName,
                    java.util.Locale locale,
                    java.lang.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
Since:
v4r2m0
See Also:
serialize()
Method Detail

main

public static void main(java.lang.String[] args)
Provides a command line interface to PanelManager. See the class description.
Since:
v4r2m0

serialize

public void serialize()
               throws java.io.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:
java.io.IOException - if serialized file cannot be written
Since:
v4r2m0

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.
Since:
v4r2m0
See Also:
getExitOnClose()

getExitOnClose

public boolean getExitOnClose()
Determines whether the application exits when this panel is closed.
Returns:
true if the application will be exited; false otherwise.
Since:
v4r2m0
See Also:
setExitOnClose(boolean)

setTitle

public void setTitle(java.lang.String title)
Overrides the panel title defined in the panel definition.

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

Parameters:
title - The title which should appear in the panel's title bar.
Since:
v4r2m0
See Also:
getTitle()

setIconName

public void setIconName(java.lang.String fileName)
Overrides the name of the icon to use for this panel. Use the package structure and the the filename so the icon file is found in the classpath. This method must be called before setVisible(true) and only sets the icon for modeless windows.
Parameters:
fileName - The filename of the icon to search for in the classpath.
Since:
v5r1m0
See Also:
getIconName()

getIconName

public java.lang.String getIconName()
Returns the name of the icon used for this panel.
Returns:
The filename of the icon.
Since:
v5r1m0
See Also:
getIconName()

setHelpPath

public void setHelpPath(java.lang.String path)
Description copied from interface: PaneManager
Base location for help files. For use in the no-plugin applet case. For example for MyPanel, setHelpPath("http://www.ibm.com/help/") will cause the PanelManager to load http://www.ibm.com/help/MyPanel.html as the help file.
Specified by:
setHelpPath in interface PaneManager

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.

Specified by:
setVisible in interface WindowManager
Parameters:
show - If true, shows the panel; otherwise, hides the panel.
Since:
v4r2m0
See Also:
isVisible(), WindowManager

isVisible

public boolean isVisible()
Determines whether this panel is visible. The panel is initially invisible.
Specified by:
isVisible in interface WindowManager
Returns:
true if the panel is visible; false otherwise.
Since:
v4r2m0
See Also:
setVisible(boolean), WindowManager

getDataBeans

public DataBean[] getDataBeans()
Returns the list of DataBeans that was specified on this object's constructor.
Returns:
a Vector of DataBeans
Since:
v4r2m0

getContainer

public java.awt.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
Since:
v4r2m0

addActivationHandler

public void addActivationHandler(EventHandler eh)
Adds an ActionListener which is notified when this panel is shown

The ActionEvent passed to the listener object will have its action command string set to "Activated".

Parameters:
eh - the instance of java.awt.event.ActionListener to be notified
Since:
v5r1m0
See Also:
EventHandler

getPreferredSize

public java.awt.Dimension getPreferredSize()
Returns the preferred size of this panel.
Returns:
A dimension object indicating this panel's preferred size.
Since:
v4r2m0

refreshComponent

public void refreshComponent(java.lang.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
Since:
v4r2m0

refreshTree

public void refreshTree(java.lang.String treeName)
Reloads a tree component with updated data from the tree's DataBean, while preserving the expansion state of all visible nodes Warning: NodeDescriptors in the tree must have unique names.
Parameters:
treeName - the name of the tree whose data is to be refreshed, as specified in the PDML definition for the panel
Since:
v5r1m0

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.
Since:
v4r2m0
See Also:
setWaitPending(boolean)

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.
Since:
v4r2m0
See Also:
setWaitCursor(boolean)

toString

public java.lang.String toString()
Returns a string representation of this object.
Overrides:
toString in class java.lang.Object
Returns:
the class name and panel title as a string
Since:
v4r2m0m0

setFormatter

public void setFormatter(java.lang.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.

Specified by:
setFormatter in interface PaneManager
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
Since:
v4r2m0
See Also:
DataFormatter

getFormatter

public DataFormatter getFormatter(java.lang.String componentName)
Returns any specialized formatter to be used for a component.

Specified by:
getFormatter in interface PaneManager
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
Since:
v4r2m0
See Also:
DataFormatter

setRequiredField

public void setRequiredField(java.lang.String componentName,
                             boolean required)
Sets whether this field should be required

Parameters:
componentName - the name of the component as specified in the panel definition
required - whether this field should be required
Throws:
java.lang.IllegalArgumentException - if no formatter is specified for this field
Since:
v5r1m0
See Also:
DataFormatter

isRequiredField

public boolean isRequiredField(java.lang.String componentName)
Returns whether this entry-field requires a non-blank entry

Parameters:
componentName - the name of the component as specified in the panel definition
Returns:
true if a non-blank is entry is required; false otherwise
Throws:
java.lang.IllegalArgumentException - if no formatter is specified for this field
Since:
v5r1m0
See Also:
DataFormatter

setButtonText

public void setButtonText(java.lang.String buttonName,
                          java.lang.String text)
Sets the button's text

Parameters:
buttonName - the name of the button as specified in the panel definition
text - The text to display on the button
Throws:
java.lang.IllegalArgumentException - if there isn't a button named buttonName
Since:
v5r1m0
See Also:
DataFormatter

setComponentText

public void setComponentText(java.lang.String componentName,
                             java.lang.String text)
Convenience method which sets the component's text

Parameters:
componentName - the name of the component as specified in the panel definition
text - The text to display on the component
Throws:
java.lang.IllegalArgumentException - if there isn't a component named componentName
java.lang.IllegalArgumentException - if the component doesn't have a way to set text
Since:
v5r1m0

getComponentText

public java.lang.String getComponentText(java.lang.String componentName)
Convenience method which gets the component's text

Parameters:
componentName - the name of the component as specified in the panel definition
Returns:
the text from the component
Throws:
java.lang.IllegalArgumentException - if there isn't a component named componentName
java.lang.IllegalArgumentException - if the component doesn't have a way to get text
Since:
v5r1m0

getMenuManager

public MenuManager getMenuManager(java.lang.String name)
Returns a MenuManager associated with this panel's menu bar.

Parameters:
name - the name of the menu as specified in the panel definition
Returns:
a MenuManager or null if not found
Since:
v4r5m0
See Also:
MenuManager

getTitle

public java.lang.String getTitle()
Returns the panel's title.

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

Specified by:
getTitle in interface PaneManager
Returns:
The title which appears in the panel's title bar.
Since:
v4r2m0
See Also:
PaneManager, setTitle(java.lang.String)

loadData

public void loadData()
Called during initialization to load data into the panel.
Specified by:
loadData in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

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.
Specified by:
activatePanel in interface PaneManager
Since:
v4r2m0
See Also:
setVisible(boolean), PaneManager

showPane

public void showPane(java.lang.String paneName)
Displays the specified pane. This method has no implementation, since PanelManager's single pane is always visible.
Specified by:
showPane in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

getComponent

public java.awt.Component getComponent(java.lang.String name)
Returns the panel component identified by name.
Specified by:
getComponent in interface PaneManager
Parameters:
name - the name of the component as specified in the panel definition
Returns:
a Component having the name specified
Since:
v4r2m0
See Also:
PaneManager

setEnabled

public void setEnabled(java.lang.String name,
                       boolean b)
Enables the panel component identified by name.
Parameters:
name - the name of the component as specified in the panel definition
b - If true, this component is enabled; otherwise this component is disabled.
Since:
v5r1m0

isEnabled

public boolean isEnabled(java.lang.String name)
Determines whether the panel component identified by name is Enabled.
Parameters:
name - the name of the component as specified in the panel definition
Returns:
true if the component is enabled; false otherwise.
Since:
v5r1m0

setVisible

public void setVisible(java.lang.String name,
                       boolean b)
Shows or hides the panel component identified by name.
Parameters:
name - the name of the component as specified in the panel definition
b - If true, this component is shown; otherwise this component is hidden.
Since:
v5r1m0

isVisible

public boolean isVisible(java.lang.String name)
Determines whether the panel component identified by name is Enabled.
Parameters:
name - the name of the component as specified in the panel definition
Returns:
true if the component is shown; false otherwise.
Since:
v5r1m0

getComponentDescriptor

public com.ibm.as400.ui.framework.java.JavaComponentDescriptor getComponentDescriptor(java.lang.String name)
Returns the JavaComponentDescriptor for the specified panel component.
Specified by:
getComponentDescriptor in interface PaneManager
Parameters:
name - the name of the component as specified in the panel definition
Returns:
a JavaComponentDescriptor for the component
Since:
v4r2m0
See Also:
PaneManager

getDelegateManager

public PaneManager getDelegateManager(java.lang.String paneName)
Returns the PaneManager to which the receiver is delegating management of the specified subpane.
Specified by:
getDelegateManager in interface PaneManager
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
Since:
v4r2m0
See Also:
PaneManager

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.
Specified by:
setAggregateManager in interface PaneManager
Parameters:
mgr - the PaneManager with which the receiver is to be associated
Since:
v4r2m0
See Also:
PaneManager

getAggregateManager

public PaneManager getAggregateManager()
Returns the owning PaneManager for the receiver.
Specified by:
getAggregateManager in interface PaneManager
Returns:
the PaneManager with which the receiver is associated when this object is participating in an aggregate user interface, or null if this PaneManager is not part of an aggregate.
Since:
v4r5m0
See Also:
PaneManager

getRootManager

public PaneManager getRootManager()
Returns the root PaneManager for the receiver.
Specified by:
getRootManager in interface PaneManager
Returns:
the PaneManager for the main panel that is managing the aggregate user interface, or null if this PaneManager is not part of an aggregate.
Since:
v4r5m0
See Also:
PaneManager

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.

Specified by:
applyChanges in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

applyChanges

public void applyChanges(java.lang.String componentName)
                  throws IllegalUserDataException
Transmits changes to user data to the DataBeans which manage the data. Calls the settor methods for the UI component identified by name.

Parameters:
componentName - The name of the component to write changes for.
Since:
v5r1m0
See Also:
applyChanges()

prepareToCommit

public void prepareToCommit(java.util.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.

Specified by:
prepareToCommit in interface PaneManager
Parameters:
preparedDataBeans - a list of DataBeans which have already been prepared on the current commit operation
Since:
v4r2m0
See Also:
PaneManager

commit

public void commit(java.util.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.

Specified by:
commit in interface PaneManager
Parameters:
committedDataBeans - a list of DataBeans which have already been saved on the current commit operation
Since:
v4r2m0
See Also:
PaneManager

getWindow

public java.awt.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.
Specified by:
getWindow in interface WindowManager
Returns:
the main window for this panel
Since:
v4r2m0
See Also:
WindowManager

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.

Specified by:
setModalRelativeTo in interface WindowManager
Parameters:
mgr - the WindowManager managing the panel in relation to which this object's panel location is determined
Since:
v4r2m0
See Also:
WindowManager

getOwnerManager

public WindowManager getOwnerManager()
Returns the WindowManager in relation to which the receiver has been set modal, or null if the receiver is not modal relative to another window.
Specified by:
getOwnerManager in interface WindowManager
Returns:
the WindowManager managing the window in relation to which this object's window location is determined
Since:
v4r5m0
See Also:
WindowManager

getTableRow

public int getTableRow(java.lang.String treeTableName,
                       NodeDescriptor nd)
Returns the table row number containing the specified tree node
Parameters:
treeTableName - the attribute name of the tree table component
node - the NodeDescriptor describing a tree node
Returns:
the index of table row containing the specified tree node (-1 if not found)
Since:
v5r2m0
See Also:
WindowManager

getNode

public NodeDescriptor getNode(java.lang.String treeTableName,
                              int row)
Returns the tree node in the specified table row
Parameters:
treeTableName - the attribute name of the tree table component
row - index of table row
Returns:
the NodeDescriptor describing the tree node in the specified table row
Since:
v5r2m0
See Also:
WindowManager

addExpansionListener

public void addExpansionListener(java.lang.String treeTableName,
                                 java.lang.Object listener)
Adds a TreeExpansionListener which is notified when the user expands a node in the specified tree table.

Parameters:
treeTableName - the PDML attribute name of the tree table
listener - the instance of TreeExpansionListener to be notified
Since:
v5r2m0
See Also:
WindowManager

removeExpansionListener

public void removeExpansionListener(java.lang.Object listener)
Removes a TreeExpansionListener from the 'active list'

Parameters:
listener - the instance of TreeExpansionListener to be notified
Since:
v5r2m0
See Also:
WindowManager

setExpanded

public void setExpanded(java.lang.String treeTableName,
                        NodeDescriptor nd,
                        boolean bExpand)
Programmatically expand or collapse a node in a tree component
Parameters:
treeTableName - the name of the tree table containing the node to be expanded or collapsed (as specified in the PDML definition for the panel)
node - the NodeDescriptor of the tree node to be expanded or collapsed
bExpand - desired state of the node - true to expand, false to collapse
Since:
v5r2m0

addCommitListener

public void addCommitListener(java.awt.event.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.

Specified by:
addCommitListener in interface WindowManager
Parameters:
listener - the instance of java.awt.event.ActionListener to be notified
Since:
v4r2m0
See Also:
WindowManager

addCommitListener

public void addCommitListener(java.lang.Object listener)
Specified by:
addCommitListener in interface WindowManager
Since:
v5r1m0

addCancelListener

public void addCancelListener(java.awt.event.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.

Specified by:
addCancelListener in interface WindowManager
Parameters:
listener - the instance of java.awt.event.ActionListener to be notified
Since:
v4r2m0
See Also:
WindowManager

addCancelListener

public void addCancelListener(java.lang.Object listener)
Specified by:
addCancelListener in interface WindowManager
Since:
v5r1m0

dispose

public void dispose()
Closes the panel and releases all resources used by the panel and its associated UI components.
Specified by:
dispose in interface WindowManager
Since:
v5r1m0
See Also:
WindowManager

handleDataException

public void handleDataException(IllegalUserDataException ex)
Provides the default handling for an IllegalUserDataException. If the exception message is non-null it will be displayed to the user in a message box. After the message box is closed, focus is set to the component identified in the exception object so that the user can change the data to a valid value.

Specified by:
handleDataException in interface WindowManager
Parameters:
ex - The IllegalUserDataException for which default handling is requested.
Since:
v5r1m0
See Also:
WindowManager, applyChanges()

handleDataException

public static void handleDataException(IllegalUserDataException ex,
                                       java.awt.Container messageOwner)
Provides the default handling for an IllegalUserDataException. If the exception message is non-null it will be displayed to the user in a message box. After the message box is closed, focus is set to the component identified in the exception object so that the user can change the data to a valid value.

This is a static version of the method that can be called for PDML types that do not have their own handleDataException methods (like TabbedPaneManager). This method is the same as the non-static version except that with this method, you pass in the owner of the message. Note: In this version the component containing the invalid data cannot be specified by name in the IllegalUserDataException object.

Parameters:
ex - The IllegalUserDataException for which default handling is requested.
messageOwner - The Container which will be the owner of any message displayed.
Since:
v5r1m0
See Also:
WindowManager, applyChanges()

displayHelp

public void displayHelp()
Displays the overview help for the panel.
Since:
v4r4m0

getMenuBar

public javax.swing.JMenuBar getMenuBar()
Returns the menu bar defined for this panel.
Returns:
an instance of JMenuBar, or null if no menu bar was defined.
Since:
v4r5m0

getToolBar

public javax.swing.JToolBar getToolBar()
Returns the toolbar defined for this panel.
Returns:
an instance of JToolBar, or null if no toolbar was defined.
Since:
v4r5m0

getToolBarButton

public javax.swing.AbstractButton getToolBarButton(java.lang.String name)
Returns a JComponent from the ToolBar
Parameters:
name - the name of the Button
Returns:
an instance of AbstractButton, or null if no button with this name was defined.
Since:
v5r1m0

setToolBarIcon

public void setToolBarIcon(javax.swing.ImageIcon icon)
Sets the Icon to be displayed right justified on the toolbar
Parameters:
icon - the icon to be displayed
Since:
v5r1m0

getSaveOnThread

public boolean getSaveOnThread()
Indicates whether calls to the save method on the application's DataBean objects will be called on a non-UI thread.

Returns:
true if the save method will be called on a non-UI thread; false if the save methods will be called on the AWT event dispatch thread.
Since:
v5r1m0
See Also:
setSaveOnThread(boolean)

setSaveOnThread

public void setSaveOnThread(boolean saveOnThread)
Controls whether calls to the save method on the application's DataBean objects will be called on a non-UI thread. The default is false.

In general, requesting save method calls on a non-UI thread is the recommended approach. This is because save is typically a long-running method, and if it executes on the UI thread the application's UI will not respond to user input until the save operation completes. Requesting a non-UI thread solves this problem - the panel managed by this PanelManager will be disabled for the duration of the save operation, but the application's other windows will be unaffected and continue to behave normally.

The downside to calling save on a thread is that any UI calls in the save method must be queued on the UI thread via the SwingUtilities.invokeLater mechanism. A convenient way to do this is to bracket UI code with the following:

 SwingUtilities.invokeLater(new Runnable() {
     public void run() {
        <your UI code here>
     }
 });
 
Using this technique the UI code still has access to member fields of the enclosing class. Local variables should either be enclosed in the inner class or declared final.

Parameters:
saveOnThread - If true, call the save method on a non-UI thread; otherwise, call the save method on the AWT event dispatch thread.
Since:
v5r1m0
See Also:
getSaveOnThread()

addHelpListener

public void addHelpListener(HelpListener listener)
Identifies an alternate help system. The HelpListener object will be notified when context or panel help has been requested. If the listener is null, the default help system is used. Only one HelpListener can be defined for a panel.
Parameters:
listener - the object that will be notified when help is requested.
Since:
v5r1m0
See Also:
HelpEvent

addActionListener

public void addActionListener(java.lang.String componentName,
                              java.awt.event.ActionListener al)
Adds an ActionListener to the component identified by componentName These listeners will not be notified when DataBean updating occurs through calls to loadData() or refreshComponent().
Parameters:
componentName - the identifier of the component to add the listener to
al - the ActionListener to be added
Throws:
java.lang.IllegalArgumentException - if the component defined by componentName does not fire an ActionEvent
Since:
v5r1m0
See Also:
removeActionListener(java.lang.String, java.awt.event.ActionListener)

removeActionListener

public void removeActionListener(java.lang.String componentName,
                                 java.awt.event.ActionListener al)
Removes an ActionListener from the component identified by componentName
Parameters:
componentName - the identifier of the component to remove the listener from
al - the ActionListener to be removed
Throws:
java.lang.IllegalArgumentException - if the component defined by componentName does not fire an ActionEvent
Since:
v5r1m0
See Also:
addActionListener(java.lang.String, java.awt.event.ActionListener)

getName

public java.lang.String getName()
Gets this PanelManager's name
Since:
v5r1m0

setName

public void setName(java.lang.String name)
Sets the name of this PanelManager This method should only be used for PanelManagers that will be added to PropertySheets or Wizards and must be called before they are added
Parameters:
name - The new name for this PanelManager
Throws:
java.lang.IllegalArgumentException - if name is null or "" or if this PanelManager has an aggregate
Since:
v5r1m0