Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

org.jdesktop.swingx
Class JXErrorPane

java.lang.Object
  extended by java.awt.Component
      extended by java.awt.Container
          extended by javax.swing.JComponent
              extended by org.jdesktop.swingx.JXErrorPane
All Implemented Interfaces:
ImageObserver, MenuContainer, Serializable
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):

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

See Also:
Serialized Form
Review status:
REVIEWED

Nested Class Summary
 
Nested classes/interfaces inherited from class javax.swing.JComponent
JComponent.AccessibleJComponent
 
Nested classes/interfaces inherited from class java.awt.Container
Container.AccessibleAWTContainer
 
Nested classes/interfaces inherited from class java.awt.Component
Component.AccessibleAWTComponent, Component.BltBufferStrategy, Component.FlipBufferStrategy
 
Field Summary
static String FATAL_ACTION_KEY
          Name of the Action used for fatal errors
static String REPORT_ACTION_KEY
          Name of the Action used for reporting errors
static String uiClassID
          UI Class ID
 
Fields inherited from class javax.swing.JComponent
accessibleContext, listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
 
Fields inherited from class java.awt.Component
BOTTOM_ALIGNMENT, CENTER_ALIGNMENT, LEFT_ALIGNMENT, RIGHT_ALIGNMENT, TOP_ALIGNMENT
 
Fields inherited from interface java.awt.image.ImageObserver
ABORT, ALLBITS, ERROR, FRAMEBITS, HEIGHT, PROPERTIES, SOMEBITS, WIDTH
 
Constructor Summary
JXErrorPane()
          Create a new JXErrorPane.
 
Method Summary
static JDialog createDialog(Component owner, JXErrorPane pane)
          Constructs and returns an error dialog, using the given JXErrorPane for the view portion of the dialog.
static JFrame createFrame(Component owner, JXErrorPane pane)
          Constructs and returns an error frame, using the given JXErrorPane for the view portion of the frame.
static JInternalFrame createInternalFrame(Component owner, JXErrorPane pane)
          Constructs and returns an error frame, using the given JXErrorPane for the view portion of the frame.
 ErrorInfo getErrorInfo()
          Gets the JXErrorPane's ErrorInfo
 ErrorReporter getErrorReporter()
          Gets the ErrorReporter delegate in use.
 Icon getIcon()
          Returns the Icon used
 ErrorPaneUI getUI()
           
 String getUIClassID()
          Returns the name of the L&F class that renders this component.
 void setErrorInfo(ErrorInfo info)
          Sets the ErrorInfo for this dialog.
 void setErrorReporter(ErrorReporter reporter)
          Sets the ErrorReporter delegate to use.
 void setIcon(Icon icon)
          Specifies the icon to use
 void setUI(ErrorPaneUI ui)
          Sets the look and feel (L&F) object that renders this component.
static void showDialog(Component owner, ErrorInfo info)
          Constructs and shows the error dialog, using the given ErrorInfo to initialize the view.
static void showDialog(Component owner, JXErrorPane pane)
          Constructs and shows the error dialog, using the given JXErrorPane for the view portion of the dialog.
static void showDialog(Throwable e)
          Constructs and shows the error dialog for the given exception.
static void showFrame(Component owner, ErrorInfo info)
          Constructs and shows the error frame, using the given ErrorInfo to initialize the view.
static void showFrame(Component owner, JXErrorPane pane)
          Constructs and shows the error frame, using the given JXErrorPane for the view portion of the frame.
static void showFrame(Throwable e)
          Constructs and shows the error frame for the given exception.
static void showInternalFrame(Component owner, ErrorInfo info)
          Constructs and shows the error frame, using the given ErrorInfo to initialize the view.
static void showInternalFrame(Component owner, JXErrorPane pane)
          Constructs and shows the error frame, using the given JXErrorPane for the view portion of the frame.
static void showInternalFrame(Throwable e)
          Constructs and shows the error frame for the given exception.
 void updateUI()
          Notification from the UIManager that the L&F has changed.
 
Methods inherited from class javax.swing.JComponent
addAncestorListener, addNotify, addVetoableChangeListener, computeVisibleRect, contains, createToolTip, disable, enable, firePropertyChange, firePropertyChange, firePropertyChange, fireVetoableChange, getAccessibleContext, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBorder, getBounds, getClientProperty, getComponentGraphics, getComponentPopupMenu, getConditionForKeyStroke, getDebugGraphicsOptions, getDefaultLocale, getFontMetrics, getGraphics, getHeight, getInheritsPopupMenu, getInputMap, getInputMap, getInputVerifier, getInsets, getInsets, getListeners, getLocation, getMaximumSize, getMinimumSize, getNextFocusableComponent, getPopupLocation, getPreferredSize, getRegisteredKeyStrokes, getRootPane, getSize, getToolTipLocation, getToolTipText, getToolTipText, getTopLevelAncestor, getTransferHandler, getVerifyInputWhenFocusTarget, getVetoableChangeListeners, getVisibleRect, getWidth, getX, getY, grabFocus, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingTile, isRequestFocusEnabled, isValidateRoot, paint, paintBorder, paintChildren, paintComponent, paintImmediately, paintImmediately, paramString, print, printAll, printBorder, printChildren, printComponent, processComponentKeyEvent, processKeyBinding, processKeyEvent, processMouseEvent, processMouseMotionEvent, putClientProperty, registerKeyboardAction, registerKeyboardAction, removeAncestorListener, removeNotify, removeVetoableChangeListener, repaint, repaint, requestDefaultFocus, requestFocus, requestFocus, requestFocusInWindow, requestFocusInWindow, resetKeyboardActions, reshape, revalidate, scrollRectToVisible, setActionMap, setAlignmentX, setAlignmentY, setAutoscrolls, setBackground, setBorder, setComponentPopupMenu, setDebugGraphicsOptions, setDefaultLocale, setDoubleBuffered, setEnabled, setFocusTraversalKeys, setFont, setForeground, setInheritsPopupMenu, setInputMap, setInputVerifier, setMaximumSize, setMinimumSize, setNextFocusableComponent, setOpaque, setPreferredSize, setRequestFocusEnabled, setToolTipText, setTransferHandler, setUI, setVerifyInputWhenFocusTarget, setVisible, unregisterKeyboardAction, update
 
Methods inherited from class java.awt.Container
add, add, add, add, add, addContainerListener, addImpl, addPropertyChangeListener, addPropertyChangeListener, applyComponentOrientation, areFocusTraversalKeysSet, countComponents, deliverEvent, doLayout, findComponentAt, findComponentAt, getComponent, getComponentAt, getComponentAt, getComponentCount, getComponents, getComponentZOrder, getContainerListeners, getFocusTraversalKeys, getFocusTraversalPolicy, getLayout, getMousePosition, insets, invalidate, isAncestorOf, isFocusCycleRoot, isFocusCycleRoot, isFocusTraversalPolicyProvider, isFocusTraversalPolicySet, layout, list, list, locate, minimumSize, paintComponents, preferredSize, printComponents, processContainerEvent, processEvent, remove, remove, removeAll, removeContainerListener, setComponentZOrder, setFocusCycleRoot, setFocusTraversalPolicy, setFocusTraversalPolicyProvider, setLayout, transferFocusBackward, transferFocusDownCycle, validate, validateTree
 
Methods inherited from class java.awt.Component
action, add, addComponentListener, addFocusListener, addHierarchyBoundsListener, addHierarchyListener, addInputMethodListener, addKeyListener, addMouseListener, addMouseMotionListener, addMouseWheelListener, bounds, checkImage, checkImage, coalesceEvents, contains, createImage, createImage, createVolatileImage, createVolatileImage, disableEvents, dispatchEvent, enable, enableEvents, enableInputMethods, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, firePropertyChange, getBackground, getBounds, getColorModel, getComponentListeners, getComponentOrientation, getCursor, getDropTarget, getFocusCycleRootAncestor, getFocusListeners, getFocusTraversalKeysEnabled, getFont, getForeground, getGraphicsConfiguration, getHierarchyBoundsListeners, getHierarchyListeners, getIgnoreRepaint, getInputContext, getInputMethodListeners, getInputMethodRequests, getKeyListeners, getLocale, getLocation, getLocationOnScreen, getMouseListeners, getMouseMotionListeners, getMousePosition, getMouseWheelListeners, getName, getParent, getPeer, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, hide, imageUpdate, inside, isBackgroundSet, isCursorSet, isDisplayable, isEnabled, isFocusable, isFocusOwner, isFocusTraversable, isFontSet, isForegroundSet, isLightweight, isMaximumSizeSet, isMinimumSizeSet, isPreferredSizeSet, isShowing, isValid, isVisible, keyDown, keyUp, list, list, list, location, lostFocus, mouseDown, mouseDrag, mouseEnter, mouseExit, mouseMove, mouseUp, move, nextFocus, paintAll, postEvent, prepareImage, prepareImage, processComponentEvent, processFocusEvent, processHierarchyBoundsEvent, processHierarchyEvent, processInputMethodEvent, processMouseWheelEvent, remove, removeComponentListener, removeFocusListener, removeHierarchyBoundsListener, removeHierarchyListener, removeInputMethodListener, removeKeyListener, removeMouseListener, removeMouseMotionListener, removeMouseWheelListener, removePropertyChangeListener, removePropertyChangeListener, repaint, repaint, repaint, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusUpCycle
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

REPORT_ACTION_KEY

public static final String REPORT_ACTION_KEY
Name of the Action used for reporting errors

See Also:
Constant Field Values

FATAL_ACTION_KEY

public static final String FATAL_ACTION_KEY
Name of the Action used for fatal errors

See Also:
Constant Field Values

uiClassID

public static final String uiClassID
UI Class ID

See Also:
Constant Field Values
Constructor Detail

JXErrorPane

public JXErrorPane()
Create a new JXErrorPane.

Method Detail

getUI

public ErrorPaneUI getUI()

setUI

public void setUI(ErrorPaneUI ui)
Sets the look and feel (L&F) object that renders this component.

Parameters:
ui - the ErrorPaneUI L&F object
See Also:
UIDefaults.getUI(javax.swing.JComponent)
This class has associated bean info for instrumenting visual editors named
bound: true hidden: true attribute: visualUpdate true description: The UI object that implements the Component's LookAndFeel.

getUIClassID

public String getUIClassID()
Returns the name of the L&F class that renders this component.

Overrides:
getUIClassID in class JComponent
Returns:
the string uiClassID
See Also:
JComponent.getUIClassID(), UIDefaults.getUI(javax.swing.JComponent)

updateUI

public void updateUI()
Notification from the UIManager that the L&F has changed. Replaces the current UI object with the latest version from the UIManager.

Overrides:
updateUI in class JComponent
See Also:
JComponent.updateUI()

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.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD