Package org.jdesktop.swingx

Class JXErrorPane

java.lang.Object
java.awt.Component
java.awt.Container
javax.swing.JComponent
org.jdesktop.swingx.JXErrorPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
@JavaBean public class JXErrorPane extends JComponent

JXErrorPane is a common error component suitable for displaying errors, warnings, and exceptional application behavior to users.

User interaction with the JXErrorPane includes the ability to view details associated with the error. This is the primary feature that differentiates JXErrorPane from JOptionPane. In addition, JXErrorPane specializes in handling unrecoverable errors. If you need an error dialog that allows the user to take some action to recover from an error (such as "Repair Disk", "Replace All", etc) then you should use JOptionPane.

Data and application state associated with an error are encapsulated in the ErrorInfo class. The JXErrorPane displays the data contained in the ErrorInfo. In addition, ErrorInfo is passed to the ErrorReporter if the user decides to report the incident.

Basic Usage

Typically, the JXErrorPane is not created and displayed directly. Instead, one of the static showXXX methods are called that create and display the JXErrorPane in a JDialog, JFrame, or JInternalFrame.

These static showXXX methods all follow the same pattern, namely ( where XXX could be one of Dialog, Frame, or InternalFrame):

  • showXXX(Throwable e): This usage allows you to show a default error window, detailing the error
  • showXXX(Component owner, ErrorInfo info): This usage shows an error dialog based on the given ErrorInfo. The component argument is the component over which the dialog should be centered.
  • showXXX(Component owner, JXErrorPane pane): This usage shows an error dialog using the given error pane. This allows you to completely modify the pane (perhaps installing a custom UI delegate, etc) to present to the user
  • createXXX(Component owner, JXErrorPane pane): Creates and returns a dialog for presenting the given JXErrorPane, but does not show it. This allows the developer to modify properties of the dialog prior to display

Following are some examples and further discussion regarding some of these static methods. Example of the most basic usage: 


      try {
          //do stuff.... something throws an exception in here
      } catch (Exception e) {
          JXErrorPane.showDialog(e);
      }
. Alternatively there are showFrame and showInternalFrame variants of each of the showDialog methods described in this API.

While this is the simplest usage, it is not the recommended approach for most errors since it yields the most difficult messages for users to understand. Instead it is recommended to provide a more useful message for users. For example: 


      URL url = null;
      try {
          url = new URL(userSuppliedUrl);
      } catch (MalformedURLException e) {
          String msg = "The web resource you entered is not formatted"
                      + " correctly.";
          String details = "<html>Web resources should begin with \"http://\""
                      + " and cannot contain any spaces. Below are a few"
                      + " more guidelines.<ul>"
                      + getURLGuidelines()
                      + "</ul></html>";
          JXErrorPane.showDialog(myWindow, "Unknown Resource", msg, details, e);
          return false;
      }

Before showing the JXErrorPane in a frame or dialog, you may modify the appearance and behavior of the JXErrorPane by setting one or more of its bean properties. For example, to modify the icon shown with a particular instance of a JXErrorPane, you might do the following: 


      JXErrorPane pane = new JXErrorPane();
      pane.setErrorIcon(myErrorIcon);
      pane.setErrorInfo(new ErrorInfo("Fatal Error", exception));
      JXErrorPane.showDialog(null, pane);

JXErrorPane may also be configured with a "Report" button which allows the user to send a bug report, typically through email. This is done through the pluggable ErrorReporter class. Simply instantiate some custom subclass of ErrorReporter and pass the instance into the setErrorReporter(org.jdesktop.swingx.error.ErrorReporter) method.

JXErrorPane can also be used for displaying fatal error messages to users. Fatal messages indicate a serious error in the application that cannot be corrected and that must result in the termination of the application. After the close of a fatal error dialog, the application should automatically exit. Fatal messages are identified by the Level of the ErrorInfo being ErrorLevel.FATAL.

By default, when Fatal error dialogs are closed the application exits with a code of "1". In other words, System.exit(1). If you wish to implement custom handling, you can replace the default fatal action in the ActionMap of the JXErrorPane instance. If you specify a custom fatal action, then the default action of calling System.exit will not occur. You are therefore responsible for shutting down the application.

UI Default Keys

TODO

JXErrorPane.errorIcon or, if not specified, JOptionPane.errorIcon JXErrorPane.warningIcon or, if not specified, JOptionPane.warningIcon JXErrorPane.details_contract_text (ignored on Mac OS X) JXErrorPane.details_expand_text (ignored on Mac OS X) JXErrorPane.mac.details_contract_text JXErrorPane.mac.details_expand_text Tree.expandedIcon (on Mac OS X) Tree.collapsedIcon (on Mac OS X)

Customizing the Look and Feel

TODO

Author:
Richard Bair, Alexander Zuev, Shai Almog, rah003
See Also:

  • Field Details

  • Constructor Details

    • JXErrorPane

      public JXErrorPane()
      Create a new JXErrorPane.

  • Method Details

    • getUI

      public ErrorPaneUI getUI()
      Returns the look and feel (LaF) object that renders this component.
      Overrides:
      getUI in class JComponent
      Returns:
      the ErrorPaneUI object that renders this component

    • setUI

      public void setUI(ErrorPaneUI ui)
      Sets the look and feel (LaF) object that renders this component.
      Parameters:
      ui - the ErrorPaneUI LaF object
      See Also:

    • getUIClassID

      public String getUIClassID()
      Returns the name of the LaF class that renders this component.
      Overrides:
      getUIClassID in class JComponent
      Returns:
      the string uiClassID
      See Also:

    • updateUI

      public void updateUI()
      Notification from the UIManager that the LaF has changed. Replaces the current UI object with the latest version from the UIManager.
      Overrides:
      updateUI in class JComponent
      See Also:

    • setErrorInfo

      public void setErrorInfo(ErrorInfo info)
      Sets the ErrorInfo for this dialog. ErrorInfo can't be null.
      Parameters:
      info - ErrorInfo that incorporates all the details about the error. Null value is not supported.

    • getErrorInfo

      public ErrorInfo getErrorInfo()
      Gets the JXErrorPane's ErrorInfo
      Returns:
      ErrorInfo assigned to this dialog

    • setIcon

      public void setIcon(Icon icon)
      Specifies the icon to use
      Parameters:
      icon - the Icon to use. May be null.

    • getIcon

      public Icon getIcon()
      Returns the Icon used
      Returns:
      the Icon

    • setErrorReporter

      public void setErrorReporter(ErrorReporter reporter)
      Sets the ErrorReporter delegate to use. This delegate is called automatically when the report action is fired.
      Parameters:
      reporter - the ErrorReporter to use. If null, the report button will not be shown in the error dialog.

    • getErrorReporter

      public ErrorReporter getErrorReporter()
      Gets the ErrorReporter delegate in use.
      Returns:
      the ErrorReporter. May be null.

    • showDialog

      public static void showDialog(Throwable e)

      Constructs and shows the error dialog for the given exception. The exceptions message will be the errorMessage, and the stacktrace will form the details for the error dialog.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the dialog shown will be modal. Otherwise, this thread will block until the error dialog has been shown and hidden on the EDT.

      Parameters:
      e - Exception that contains information about the error cause and stack trace

    • showDialog

      public static void showDialog(Component owner, ErrorInfo info)

      Constructs and shows the error dialog, using the given ErrorInfo to initialize the view.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the dialog shown will be modal. Otherwise, this thread will block until the error dialog has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error dialog. Determines the Window in which the dialog is displayed; if the owner has no Window, a default Frame is used
      info - ErrorInfo that incorporates all the information about the error

    • showDialog

      public static void showDialog(Component owner, JXErrorPane pane)

      Constructs and shows the error dialog, using the given JXErrorPane for the view portion of the dialog.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the dialog shown will be modal. Otherwise, this thread will block until the error dialog has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error dialog. Determines the Window in which the dialog is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the dialog.

    • createDialog

      public static JDialog createDialog(Component owner, JXErrorPane pane)

      Constructs and returns an error dialog, using the given JXErrorPane for the view portion of the dialog.

      This method may be called from any thread. It does not block. The caller is responsible for ensuring that the dialog is shown and manipulated on the AWT event dispatch thread. A common way to do this is to use SwingUtilities.invokeAndWait or SwingUtilities.invokeLater().

      Parameters:
      owner - Owner of this error dialog. Determines the Window in which the dialog is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the dialog.
      Returns:
      a JDialog configured to display the error.

    • showFrame

      public static void showFrame(Throwable e)

      Constructs and shows the error frame for the given exception. The exceptions message will be the errorMessage, and the stacktrace will form the details for the error dialog.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      e - Exception that contains information about the error cause and stack trace

    • showFrame

      public static void showFrame(Component owner, ErrorInfo info)

      Constructs and shows the error frame, using the given ErrorInfo to initialize the view.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the frame is displayed; if the owner has no Window, a default Frame is used
      info - ErrorInfo that incorporates all the information about the error

    • showFrame

      public static void showFrame(Component owner, JXErrorPane pane)

      Constructs and shows the error frame, using the given JXErrorPane for the view portion of the frame.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the dialog is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the frame.

    • createFrame

      public static JFrame createFrame(Component owner, JXErrorPane pane)

      Constructs and returns an error frame, using the given JXErrorPane for the view portion of the frame.

      This method may be called from any thread. It does not block. The caller is responsible for ensuring that the frame is shown and manipulated on the AWT event dispatch thread. A common way to do this is to use SwingUtilities.invokeAndWait or SwingUtilities.invokeLater().

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the frame is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the frame.
      Returns:
      a JFrame configured to display the error.

    • showInternalFrame

      public static void showInternalFrame(Throwable e)

      Constructs and shows the error frame for the given exception. The exceptions message will be the errorMessage, and the stacktrace will form the details for the error dialog.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      e - Exception that contains information about the error cause and stack trace

    • showInternalFrame

      public static void showInternalFrame(Component owner, ErrorInfo info)

      Constructs and shows the error frame, using the given ErrorInfo to initialize the view.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the frame is displayed; if the owner has no Window, a default Frame is used
      info - ErrorInfo that incorporates all the information about the error

    • showInternalFrame

      public static void showInternalFrame(Component owner, JXErrorPane pane)

      Constructs and shows the error frame, using the given JXErrorPane for the view portion of the frame.

      This method may be called from any thread. It will actually show the error dialog on the AWT event dispatch thread. This method blocks. If called on the EDT, the frame shown will be modal. Otherwise, this thread will block until the error frame has been shown and hidden on the EDT.

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the dialog is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the frame.

    • createInternalFrame

      public static JInternalFrame createInternalFrame(Component owner, JXErrorPane pane)

      Constructs and returns an error frame, using the given JXErrorPane for the view portion of the frame.

      This method may be called from any thread. It does not block. The caller is responsible for ensuring that the frame is shown and manipulated on the AWT event dispatch thread. A common way to do this is to use SwingUtilities.invokeAndWait or SwingUtilities.invokeLater().

      Parameters:
      owner - Owner of this error frame. Determines the Window in which the frame is displayed; if the owner has no Window, a default Frame is used
      pane - JXErrorPane which will form the content area of the frame.
      Returns:
      a JInternalFrame configured to display the error.