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

java.lang.Object
  |
  +--com.ibm.as400.ui.framework.java.PropertySheetManager
All Implemented Interfaces:
PaneManager, WindowManager

public class PropertySheetManager
extends java.lang.Object
implements PaneManager, WindowManager

Creates a property sheet containing a tabbed pane with one or more tabbed windows. Each window consists of a panel defined using the Panel Definition Markup Language (PDML). The property sheet may be either a standalone window or a modal dialog.

PropertySheetManager performs the following processing on behalf of the application:

The total size of the property sheet is a function of the size of the largest panel.

To locate a property sheet definition, PropertySheetManager needs three pieces of information:

The framework first searches the specified location for a file with a name matching the property sheet name, and an extension of .pdml.ser. If the serialized property sheet 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 property sheet MyPropertySheet is defined in the file TestPanels.pdml, and that a properties file TestPanels.properties is associated with the property sheet 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 property sheet and displays it:

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

 import com.ibm.as400.ui.framework.java.*;
 import java.awt.Frame;
  
 // Instantiate the objects which supply data to the property sheet
 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 property sheet manager. Parameters:
 // 1. Resource name of the property sheet definition
 // 2. Name of property sheet
 // 3. List of DataBeans
 // 4. Owner frame window
  
 Frame owner;
 ...
 PropertySheetManager psm = null;
 try {
 psm = new PropertySheetManager("com.ourCompany.ourPackage.TestPanels",
                                "MyPropertySheet",
                                dataBeans,
                                owner);
 }
 catch (DisplayManagerException e) {
 e.displayUserMessage(null);
 System.exit(-1);
 }
  
 // Display the property sheet
 psm.setVisible(true);
 

Command Line Interface

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

-locale <language code>_<country code>_<variant>
Identifies the locale which should be used to locate the property sheet 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 property sheet.

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

<property sheet name>
The name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document.

Examples:

Test a base sample property sheet:

java com.ibm.as400.ui.framework.java.PropertySheetManager com.ourCompany.ourPackage.TestPanels MyPropertySheet

Serialize the base property sheet:

java com.ibm.as400.ui.framework.java.PropertySheetManager -serialize com.ourCompany.ourPackage.TestPanels MyPropertySheet

Test the UK version:

java com.ibm.as400.ui.framework.java.PropertySheetManager -locale en_UK com.ourCompany.ourPackage.TestPanels MyPropertySheet

Serialize the UK version:

java com.ibm.as400.ui.framework.java.PropertySheetManager -serialize -locale en_UK com.ourCompany.ourPackage.TestPanels MyPropertySheet

Since:
v4r2m0
See Also:
DisplayManagerException, PanelManager

Field Summary
static int APPLY_BUTTON
          Used to identify the Apply button on the property sheet.
static int CANCEL_BUTTON
          Used to identify the Cancel button on the property sheet.
static int HELP_BUTTON
          Used to identify the Help button on the property sheet.
protected  int m_windowMinHeight
           
protected  int m_windowMinWidth
           
static int OK_BUTTON
          Used to identify the OK button on the property sheet.
 
Fields inherited from interface com.ibm.as400.ui.framework.java.WindowManager
OFFSET_FROM_OWNER
 
Constructor Summary
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName)
          Constructs a PropertySheetManager object for the specified property sheet, and then serializes the property sheet definition.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans, boolean resize)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Container container)
          Constructs a PropertySheetManager for the specified property sheet, using the specified container.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Container container, boolean resize)
          Constructs a PropertySheetManager for the specified property sheet, using the specified container.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Frame owner)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.util.Locale locale, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Frame owner, boolean resize)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans, boolean resize)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Container container)
          Constructs a PropertySheetManager for the specified property sheet, using the specified container.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Container container, boolean resize)
          Constructs a PropertySheetManager for the specified property sheet, using the specified container.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Frame owner)
          Constructs a PropertySheetManager object for the specified property sheet.
PropertySheetManager(java.lang.String baseName, java.lang.String propertySheetName, DataBean[] dataBeans, java.awt.Frame owner, boolean resize)
          Constructs a PropertySheetManager object for the specified property sheet.
 
Method Summary
 void activatePanel()
          Runs the activation handlers for the currently selected pane.
 void addButtons(int flags)
          Adds the OK, Cancel or Help buttons to the property sheet if they have been previously removed.
 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 addPage(PanelManager pm, int index)
          Adds a panel to the property sheet managed by the receiver.
 void addUserButton(java.lang.String buttonId, java.lang.String text, java.awt.event.ActionListener listener)
          Adds a user defined button to the property sheet in addition to the standard OK, Cancel, Apply, and Help buttons.
 void applyChanges()
          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 disableButtons(int flags)
          Disables the OK, Cancel, Apply or Help buttons on the property sheet.
 void disableUserButton(java.lang.String buttonId)
          Disable (gray out) a user defined button that was previously added with addUserButton.
 void dispose()
          Closes the panel and releases all resources used by the panel and its associated UI components.
 void enableButtons(int flags)
          Enables the OK, Cancel or Help buttons on the property sheet if they have been previously disabled.
 void enableUserButton(java.lang.String buttonId)
          Enable a user defined button that was previously added with addUserButton.
 boolean fireCancelListeners()
          Processes all CancelListeners.
 void fireCommitListeners()
          Processes all CommitListeners.
 PaneManager getAggregateManager()
          Returns the owning PaneManager for the receiver.
 java.awt.event.ActionListener getCancelHandler()
          Returns the cancel handler which will bypass normal cancel handling, if one is set.
 java.awt.Component getComponent(java.lang.String componentName)
          Returns the requested user interface component.
 com.ibm.as400.ui.framework.java.JavaComponentDescriptor getComponentDescriptor(java.lang.String componentName)
          Returns the JavaComponentDescriptor for the specified user interface component.
 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 property sheet is closed.
 DataFormatter getFormatter(java.lang.String componentName)
          Returns the data formatter associated with the specified user interface component.
 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.
 PanelManager getPage(int index)
          Returns the PanelManager for the specified property page.
 PanelManager getPage(java.lang.String name)
          Returns the PanelManager for the specified property page.
 java.awt.Dimension getPreferredSize()
          Gets the preferred size of this property sheet.
 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.
 javax.swing.JTabbedPane getTabbedPane()
          Returns the JTabbedPane for the specified property sheet manager.
 java.lang.String getTitle()
          Returns the property sheet's title.
 javax.swing.JButton getUserButton(java.lang.String buttonId)
          Returns one of the property sheet's user defined buttons.
 java.awt.Window getWindow()
          Returns the main property sheet window.
 void handleDataException(IllegalUserDataException ex)
          Provides the default handling for an IllegalUserDataException.
 boolean isLoadOnThread()
          Determines whether secondary pages are loaded in the background.
 boolean isPageSwitchValidation()
          Determines whether the PropertySheetManager checks the information on a page and saves it in the data bean before switching to another page.
 boolean isVisible()
          Determines whether this property sheet is visible.
 void loadData()
          Called during initialization to load data into the panel.
protected  void loadPagesData()
          Causes the initialization of the pages by loading each of the page's data.
static void main(java.lang.String[] args)
          Provides a command line interface to PropertySheetManager.
 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 pressButton(int button)
          Programatically press a predefined button
 void refreshComponent(java.lang.String qualifiedName)
          Calls the associated dataBeans gettor method for a component.
 void removeButtons(int flags)
          Removes the OK, Cancel, Apply or Help buttons from the property sheet.
 void removePage(int index)
          Removes a panel from the property sheet managed by the receiver.
 void removePage(java.lang.String name)
          Removes a panel from the property sheet managed by the receiver.
 void removeUserButton(java.lang.String buttonId)
          Remove a user defined button that was previously added with addUserButton.
 void serialize()
          Serializes the property sheet definition.
 void setAggregateManager(PaneManager mgr)
          Sets the owning PaneManager for the receiver.
 void setCancelHandler(java.awt.event.ActionListener handler)
          Sets a cancel handler which will bypass normal cancel handling.
 void setExitOnClose(boolean exit)
          Controls whether the application exits when the property sheet is closed, based on the value of parameter exit.
 void setFormatter(java.lang.String componentName, DataFormatter formatter, boolean required)
          Sets the data formatter associated with the specified user interface component.
 void setHelpPath(java.lang.String path)
          Base location for help files.
 void setLoadOnThread(boolean loadOnThread)
          Controls whether secondary pages are loaded in the background.
 void setMinimumWindowSize(int width, int height)
          Sets the minimum size of the application window owned by this PropertySheet.
 void setModalRelativeTo(WindowManager mgr)
          Sets the location of the panel being managed relative to a panel managed by the specified WindowManager.
 void setPageSwitchValidation(boolean validate)
          Controls whether the PropertySheetManager checks the information on a page and saves it in the data bean before switching to another page.
 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 property sheet title defined in the property sheet definition.
 void setVisible(boolean show)
          Shows or hides the property sheet, depending on the value of parameter show.
 void showPage(int index)
          Shows the Panel for the specified property page.
 void showPage(java.lang.String name)
          Shows the Panel for the specified property page.
 void showPane(java.lang.String paneName)
          Displays the specified pane.
 void validatePage(int index)
          Validates the changes to data displayed on the panel.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

OK_BUTTON

public static final int OK_BUTTON
Used to identify the OK button on the property sheet.

CANCEL_BUTTON

public static final int CANCEL_BUTTON
Used to identify the Cancel button on the property sheet.

HELP_BUTTON

public static final int HELP_BUTTON
Used to identify the Help button on the property sheet.

APPLY_BUTTON

public static final int APPLY_BUTTON
Used to identify the Apply button on the property sheet.

m_windowMinWidth

protected int m_windowMinWidth

m_windowMinHeight

protected int m_windowMinHeight
Constructor Detail

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modeless.

The default locale will be used to load the property sheet definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r2m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modeless.

The default locale will be used to load the property sheet definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modeless.
Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
locale - the desired locale to be used to load the property sheet definition
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r2m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modeless.
Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
locale - the desired locale to be used to load the property sheet definition
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Frame owner)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the property sheet 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 define the property sheet specification
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (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)

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Frame owner,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the property sheet 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 define the property sheet specification
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML document
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
owner - the owning frame
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException, setVisible(boolean)

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Frame owner)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the property sheet has closed.
Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
locale - the desired locale to be used to load the property sheet definition
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (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)

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Frame owner,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet. The property sheet will be modal, with the specified Frame as its owner. The application will block on the call to setVisible until the property sheet has closed.
Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
locale - the desired locale to be used to load the property sheet definition
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
owner - the owning frame
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException, setVisible(boolean)

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Container container)
                     throws DisplayManagerException
Constructs a PropertySheetManager for the specified property sheet, 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 property sheet definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the property sheet specification
panelName - the name of the panel, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
container - the application's container
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r2m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Container container,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager for the specified property sheet, 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 property sheet definition.

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which defines the property sheet specification
panelName - the name of the panel, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
container - the application's container
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Container container)
                     throws DisplayManagerException
Constructs a PropertySheetManager for the specified property sheet, 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 property sheet specification
locale - the desired locale to be used to load the property sheet definition
panelName - the name of the panel, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
container - the application's container
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r2m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName,
                            DataBean[] dataBeans,
                            java.awt.Container container,
                            boolean resize)
                     throws DisplayManagerException
Constructs a PropertySheetManager for the specified property sheet, 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 property sheet specification
locale - the desired locale to be used to load the property sheet definition
panelName - the name of the panel, as specified on the PROPERTYSHEET tag in the PDML
dataBeans - a list of DataBeans which supply data to the property sheet (may be null)
container - the application's container
resize - specifies whether the property sheet should be dynamically resizable
Throws:
DisplayManagerException - if an error was encountered accessing the panel definition
Since:
v4r5m0
See Also:
DisplayManagerException

PropertySheetManager

public PropertySheetManager(java.lang.String baseName,
                            java.util.Locale locale,
                            java.lang.String propertySheetName)
                     throws DisplayManagerException
Constructs a PropertySheetManager object for the specified property sheet, and then serializes the property sheet definition. This constructor cannot be used to display the property sheet.

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

Parameters:
baseName - the resource name of the PDML document/resource bundle combination which define the property sheet specification
locale - the desired locale to be used to load the property sheet definition (may be null)
propertySheetName - the name of the property sheet, as specified on the PROPERTYSHEET 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 PropertySheetManager. See the class description.
Since:
v4r2m0

serialize

public void serialize()
               throws java.io.IOException
Serializes the property sheet definition. The filename of the serialized file will be of the form
 <property sheet name>_<locale string>.pdml.ser
 
where <property sheet name> is the name of the property sheet as specified on the PROPERTYSHEET 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

getTabbedPane

public javax.swing.JTabbedPane getTabbedPane()
Returns the JTabbedPane for the specified property sheet manager.
Returns:
the JTabbedPane for the property sheet manager
Since:
v4r5m0

getPage

public PanelManager getPage(int index)
Returns the PanelManager for the specified property page.
Parameters:
index - the index of the property page
Returns:
the PanelManager instance for the page
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of the specified index is not less than the page count
Since:
v4r5m0

getPage

public PanelManager getPage(java.lang.String name)
Returns the PanelManager for the specified property page.
Parameters:
name - the name of the property page as specified in the PDML
Returns:
the PanelManager instance for the page, or null if the specified page is not found
Since:
v4r5m0

showPage

public void showPage(int index)
Shows the Panel for the specified property page.
Parameters:
index - the index of the property page to show
Since:
v4r2m0

showPage

public void showPage(java.lang.String name)
Shows the Panel for the specified property page.
Parameters:
name - the name of the property page to show
Since:
v5r1m0

setExitOnClose

public void setExitOnClose(boolean exit)
Controls whether the application exits when the property sheet is closed, based on the value of parameter exit. The default value is false.

This method should be called before the property sheet is made visible.

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 property sheet 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 property sheet title defined in the property sheet definition.

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

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

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

loadPagesData

protected void loadPagesData()
Causes the initialization of the pages by loading each of the page's data. Called automatically by setVisible(true). Primarily useful for subclasses which override setVisible.

Loads secondary pages on a background thread if isLoadOnThread is true.

Since:
v5r1m0
See Also:
setVisible(boolean)

setVisible

public void setVisible(boolean show)
Shows or hides the property sheet, depending on the value of parameter show. If an owner frame was specified on the constructor indicating that the property sheet is modal, the application will block on the call to setVisible until the property sheet has closed.
Specified by:
setVisible in interface WindowManager
Parameters:
show - If true, shows the property sheet; otherwise, hides the property sheet.
Since:
v4r2m0
See Also:
isVisible(), WindowManager

isVisible

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

getPreferredSize

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

setPageSwitchValidation

public void setPageSwitchValidation(boolean validate)
Controls whether the PropertySheetManager checks the information on a page and saves it in the data bean before switching to another page. The default value is false for backward compatability.
Parameters:
validate - If true, check and save pages before switching; if false, do no checking
Since:
v5r1m0
See Also:
isPageSwitchValidation(), validatePage(int)

isPageSwitchValidation

public boolean isPageSwitchValidation()
Determines whether the PropertySheetManager checks the information on a page and saves it in the data bean before switching to another page.
Returns:
true if pages will be checked; false otherwise.
Since:
v5r1m0
See Also:
setPageSwitchValidation(boolean), validatePage(int)

setLoadOnThread

public void setLoadOnThread(boolean loadOnThread)
Controls whether secondary pages are loaded in the background. If true, the primary page is loaded on the main thread and subsequent pages are loaded on worker threads. If a page is selected to be displayed and the background loading is not complete, the thread associated with the selected page is given priority, when it completes it is displayed. If false all pages are loaded before any are displayed.

The default value is false for backward compatability.

When using threaded loading, content of secondary pages may or may not be available from the primary page at a given time. In particular, default selection models may be replaced as threading procedes and should not be referenced by other pages.

Parameters:
loadOnThread - If true, load secondary pages in background; if false, load all pages before display.
Since:
v5r1m0
See Also:
isLoadOnThread()

isLoadOnThread

public boolean isLoadOnThread()
Determines whether secondary pages are loaded in the background.
Returns:
true, if secondary pages are loaded in the background
Since:
v5r1m0
See Also:
setLoadOnThread(boolean)

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()

getTitle

public java.lang.String getTitle()
Returns the property sheet'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 property sheet'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. This method has no implementation, since PropertySheetManager doesn't participate in aggregates.
Specified by:
loadData in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

activatePanel

public void activatePanel()
Runs the activation handlers for the currently selected pane. This method has no implementation, since PropertySheetManager isn't managed as a subpanel.
Specified by:
activatePanel in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

showPane

public void showPane(java.lang.String paneName)
Displays the specified pane. This method has no implementation, since PropertySheetManager isn't managed as a subpanel.
Specified by:
showPane in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

getComponent

public java.awt.Component getComponent(java.lang.String componentName)
Returns the requested user interface component. The name of the component must be of the form
<panel_name>.<component_name>
where panel_name is the name of the panel containing the desired component, and component_name is the name of the component, as defined in the PDML for the panel definition.
Specified by:
getComponent in interface PaneManager
Parameters:
componentName - the fully-qualified name of the user interface component
Returns:
the desired Component, or null if the component cannot be found
Since:
v4r2m0
See Also:
PaneManager

refreshComponent

public void refreshComponent(java.lang.String qualifiedName)
Calls the associated dataBeans gettor method for a component. The name of the component must be of the form
<panel_name>.<component_name>
where panel_name is the name of the panel containing the desired component, and component_name is the name of the component, as defined in the PDML for the panel definition.
Parameters:
qualifiedName - the fully-qualified name of the user interface component
Since:
v4r2m0
See Also:
PanelManager.refreshComponent(java.lang.String)

getComponentDescriptor

public com.ibm.as400.ui.framework.java.JavaComponentDescriptor getComponentDescriptor(java.lang.String componentName)
Returns the JavaComponentDescriptor for the specified user interface component. The name of the component must be of the form
<panel_name>.<component_name>
where panel_name is the name of the panel containing the desired component, and component_name is the name of the component, as defined in the PDML for the panel definition.
Specified by:
getComponentDescriptor in interface PaneManager
Parameters:
componentName - the fully-qualified name of the user interface component
Returns:
the desired JavaComponentDescriptor, or null if the descriptor cannot be found
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. This method has no implementation, since PropertySheetManager doesn't participate in aggregates.
Specified by:
setAggregateManager in interface PaneManager
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()
Transmits changes to user data to the DataBeans which manage the data. This method has no implementation, since PropertySheetManager doesn't participate in aggregates.
Specified by:
applyChanges in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

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. This method has no implementation, since PropertySheetManager doesn't participate in aggregates.
Specified by:
prepareToCommit in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

commit

public void commit(java.util.Vector committedDataBeans)
Commits the changes to data displayed on the panel. This method has no implementation, since PropertySheetManager doesn't participate in aggregates.
Specified by:
commit in interface PaneManager
Since:
v4r2m0
See Also:
PaneManager

validatePage

public void validatePage(int index)
                  throws IllegalUserDataException
Validates the changes to data displayed on the panel. Formatters are called for each field of the panel, and the data is save in the bean. Any errors cause the exception thrown by the formatter to be displayed, and the focus placed back on the failing field. The exception is then re-thrown.
Parameters:
index - the index of the property page to validate
Throws:
IllegalUserDataException - if an error was discovered during validation
Since:
v4r2m0

setFormatter

public void setFormatter(java.lang.String componentName,
                         DataFormatter formatter,
                         boolean required)
Sets the data formatter associated with the specified user interface component. The name of the component must be of the form
<panel_name>.<component_name>
where panel_name is the name of the panel containing the desired component, and component_name is the name of the component, as defined in the PDML for the panel definition.
Specified by:
setFormatter in interface PaneManager
Parameters:
componentName - the fully-qualified name of the user interface component
formatter - a reference to the data formatter to be associated with the component
required - whether a value is required to be entered
Since:
v4r2m0
See Also:
DataFormatter

getFormatter

public DataFormatter getFormatter(java.lang.String componentName)
Returns the data formatter associated with the specified user interface component. The name of the component must be of the form
<panel_name>.<component_name>
where panel_name is the name of the panel containing the desired component, and component_name is the name of the component, as defined in the PDML for the panel definition.
Specified by:
getFormatter in interface PaneManager
Parameters:
componentName - the fully-qualified name of the user interface component
Returns:
the associated DataFormatter, or null if the component cannot be found
Since:
v4r2m0
See Also:
DataFormatter

getWindow

public java.awt.Window getWindow()
Returns the main property sheet window. The window may be either an instance of JDialog or JFrame, depending on whether the property sheet is modal or modeless.
Specified by:
getWindow in interface WindowManager
Returns:
the main window for this property sheet
Since:
v4r2m0

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 PropertySheetManager is centered on the screen.

This method has no effect if it is called after this property sheet 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

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

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 property sheet. 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 property sheet 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()

addPage

public void addPage(PanelManager pm,
                    int index)
Adds a panel to the property sheet managed by the receiver. This method has no effect if it is called after the property sheet is made visible.
Parameters:
pm - the PanelManager for the new panel
index - the position at which the new page will be inserted
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of the specified index exceeds the current page count
Since:
v4r5m0

removePage

public void removePage(java.lang.String name)
Removes a panel from the property sheet managed by the receiver. This method has no effect if it is called after the property sheet is made visible.
Parameters:
name - the name of the property page as specified in the PDML
Since:
v4r5m0

removePage

public void removePage(int index)
Removes a panel from the property sheet managed by the receiver. This method has no effect if it is called after the property sheet is made visible.
Parameters:
index - the index of the page to be removed
Throws:
java.lang.ArrayIndexOutOfBoundsException - if the value of the specified index exceeds the current page count minus 1
Since:
v4r5m0

addButtons

public void addButtons(int flags)
Adds the OK, Cancel or Help buttons to the property sheet if they have been previously removed.
Parameters:
flags - button constants indicating which buttons should be added
Since:
v4r5m0

removeButtons

public void removeButtons(int flags)
Removes the OK, Cancel, Apply or Help buttons from the property sheet.
Parameters:
flags - button constants indicating which buttons should be removed
Since:
v4r5m0

enableButtons

public void enableButtons(int flags)
Enables the OK, Cancel or Help buttons on the property sheet if they have been previously disabled.
Parameters:
flags - button constants indicating which buttons should be enabled
Since:
v4r5m0

pressButton

public void pressButton(int button)
Programatically press a predefined button
Parameters:
button - the button to be programmatically pressed
Since:
v5r1m0
See Also:
OK_BUTTON, CANCEL_BUTTON, APPLY_BUTTON, HELP_BUTTON

disableButtons

public void disableButtons(int flags)
Disables the OK, Cancel, Apply or Help buttons on the property sheet.
Parameters:
flags - button constants indicating which buttons should be disabled
Since:
v4r5m0

addUserButton

public void addUserButton(java.lang.String buttonId,
                          java.lang.String text,
                          java.awt.event.ActionListener listener)
                   throws java.lang.IllegalArgumentException
Adds a user defined button to the property sheet in addition to the standard OK, Cancel, Apply, and Help buttons.
Parameters:
buttonId - the String that will be used to identify this button in subsequent calls.
text - the String that is to appear on the button.
listener - the ActionListener to be notified when the button is pressed.
Throws:
java.lang.IllegalArgumentException -
  • if the text parameter is a duplicate for a button that already exists.
  • if the buttonId is null.
  • if the text is null.
  • if the listener is null.
Since:
v5r1m0
See Also:
removeUserButton(java.lang.String), enableUserButton(java.lang.String), disableUserButton(java.lang.String), getUserButton(java.lang.String)

removeUserButton

public void removeUserButton(java.lang.String buttonId)
                      throws java.lang.IllegalArgumentException
Remove a user defined button that was previously added with addUserButton.
Parameters:
buttonId - the same String that was passed in as the buttonId on the addUserButton call.
Throws:
java.lang.IllegalArgumentException - if the requested user defined button does not exist or if the buttonId parameter is null.
Since:
v5r1m0
See Also:
addUserButton(java.lang.String, java.lang.String, java.awt.event.ActionListener), enableUserButton(java.lang.String), disableUserButton(java.lang.String), getUserButton(java.lang.String)

getUserButton

public javax.swing.JButton getUserButton(java.lang.String buttonId)
                                  throws java.lang.IllegalArgumentException
Returns one of the property sheet's user defined buttons.
Parameters:
text - the same String that was passed in on the addUserButton call.
Returns:
an instance of the user defined button identified by the string passed in.
Throws:
java.lang.IllegalArgumentException - if the requested user defined button does not exist or if the buttonId parameter is null.
Since:
v5r1m0
See Also:
addUserButton(java.lang.String, java.lang.String, java.awt.event.ActionListener), removeUserButton(java.lang.String), enableUserButton(java.lang.String), disableUserButton(java.lang.String)

enableUserButton

public void enableUserButton(java.lang.String buttonId)
                      throws java.lang.IllegalArgumentException
Enable a user defined button that was previously added with addUserButton.
Parameters:
buttonId - the same String that was passed in as the buttonId on the addUserButton call.
Throws:
java.lang.IllegalArgumentException - if the requested user defined button does not exist or if the buttonId parameter is null.
Since:
v5r1m0
See Also:
disableUserButton(java.lang.String), addUserButton(java.lang.String, java.lang.String, java.awt.event.ActionListener), removeUserButton(java.lang.String), getUserButton(java.lang.String)

disableUserButton

public void disableUserButton(java.lang.String buttonId)
                       throws java.lang.IllegalArgumentException
Disable (gray out) a user defined button that was previously added with addUserButton.
Parameters:
buttonId - the same String that was passed in as the buttonId on the addUserButton call.
Throws:
java.lang.IllegalArgumentException - if the requested user defined button does not exist or if the buttonId parameter is null.
Since:
v5r1m0
See Also:
enableUserButton(java.lang.String), addUserButton(java.lang.String, java.lang.String, java.awt.event.ActionListener), removeUserButton(java.lang.String), getUserButton(java.lang.String)

setMinimumWindowSize

public void setMinimumWindowSize(int width,
                                 int height)
Sets the minimum size of the application window owned by this PropertySheet. Attempts to resize the window smaller than the specified size will fail.
Parameters:
width - The minimum width of the window
height - The minimum height of the window
Since:
v5r1m0

fireCommitListeners

public final void fireCommitListeners()
Processes all CommitListeners.
Since:
v5r2m0

fireCancelListeners

public final boolean fireCancelListeners()
Processes all CancelListeners. Returns true if Listeners were processed with no exceptions.
Returns:
true if CancelListeners were processed with no exceptions.
Since:
v5r2m0

setCancelHandler

public void setCancelHandler(java.awt.event.ActionListener handler)
Sets a cancel handler which will bypass normal cancel handling. A value of null indicates the standard cancel handler should be used.
Parameters:
handler - the cancel handler to use, or null to use the default handler.
Since:
v5r2m0

getCancelHandler

public java.awt.event.ActionListener getCancelHandler()
Returns the cancel handler which will bypass normal cancel handling, if one is set.
Returns:
the cancel handler, or null, if one is not set.
Since:
v5r2m0