Class JXErrorPane
- java.lang.Object
-
- java.awt.Component
-
- java.awt.Container
-
- javax.swing.JComponent
-
- org.jdesktop.swingx.JXErrorPane
-
- All Implemented Interfaces:
java.awt.image.ImageObserver
,java.awt.MenuContainer
,java.io.Serializable
public class JXErrorPane extends javax.swing.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 differentiatesJXErrorPane
fromJOptionPane
. 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 useJOptionPane
.Data and application state associated with an error are encapsulated in the
ErrorInfo
class. TheJXErrorPane
displays the data contained in theErrorInfo
. In addition,ErrorInfo
is passed to theErrorReporter
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 theJXErrorPane
in aJDialog
,JFrame
, orJInternalFrame
.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:
. Alternatively there aretry { //do stuff.... something throws an exception in here } catch (Exception e) { JXErrorPane.showDialog(e); }
showFrame
andshowInternalFrame
variants of each of theshowDialog
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 theJXErrorPane
by setting one or more of its bean properties. For example, to modify the icon shown with a particular instance of aJXErrorPane
, 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 pluggableErrorReporter
class. Simply instantiateorg.jdesktop.swingx.error.EmailErrorReporter
or some custom subclass ofErrorReporter
and pass the instance into thesetErrorReporter(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 theLevel
of theErrorInfo
beingErrorLevel
.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 theActionMap
of theJXErrorPane
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
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
FATAL_ACTION_KEY
Name of the Action used for fatal errorsstatic java.lang.String
REPORT_ACTION_KEY
Name of the Action used for reporting errorsstatic java.lang.String
uiClassID
UI Class ID-
Fields inherited from class javax.swing.JComponent
listenerList, TOOL_TIP_TEXT_KEY, ui, UNDEFINED_CONDITION, WHEN_ANCESTOR_OF_FOCUSED_COMPONENT, WHEN_FOCUSED, WHEN_IN_FOCUSED_WINDOW
-
-
Constructor Summary
Constructors Constructor Description JXErrorPane()
Create a newJXErrorPane
.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static javax.swing.JDialog
createDialog(java.awt.Component owner, JXErrorPane pane)
Constructs and returns an error dialog, using the givenJXErrorPane
for the view portion of the dialog.static javax.swing.JFrame
createFrame(java.awt.Component owner, JXErrorPane pane)
Constructs and returns an error frame, using the givenJXErrorPane
for the view portion of the frame.static javax.swing.JInternalFrame
createInternalFrame(java.awt.Component owner, JXErrorPane pane)
Constructs and returns an error frame, using the givenJXErrorPane
for the view portion of the frame.ErrorInfo
getErrorInfo()
Gets theJXErrorPane
'sErrorInfo
ErrorReporter
getErrorReporter()
Gets theErrorReporter
delegate in use.javax.swing.Icon
getIcon()
Returns the Icon usedErrorPaneUI
getUI()
java.lang.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 theErrorReporter
delegate to use.void
setIcon(javax.swing.Icon icon)
Specifies the icon to usevoid
setUI(ErrorPaneUI ui)
Sets the look and feel (L&F) object that renders this component.static void
showDialog(java.awt.Component owner, ErrorInfo info)
Constructs and shows the error dialog, using the givenErrorInfo
to initialize the view.static void
showDialog(java.awt.Component owner, JXErrorPane pane)
Constructs and shows the error dialog, using the givenJXErrorPane
for the view portion of the dialog.static void
showDialog(java.lang.Throwable e)
Constructs and shows the error dialog for the given exception.static void
showFrame(java.awt.Component owner, ErrorInfo info)
Constructs and shows the error frame, using the givenErrorInfo
to initialize the view.static void
showFrame(java.awt.Component owner, JXErrorPane pane)
Constructs and shows the error frame, using the givenJXErrorPane
for the view portion of the frame.static void
showFrame(java.lang.Throwable e)
Constructs and shows the error frame for the given exception.static void
showInternalFrame(java.awt.Component owner, ErrorInfo info)
Constructs and shows the error frame, using the givenErrorInfo
to initialize the view.static void
showInternalFrame(java.awt.Component owner, JXErrorPane pane)
Constructs and shows the error frame, using the givenJXErrorPane
for the view portion of the frame.static void
showInternalFrame(java.lang.Throwable e)
Constructs and shows the error frame for the given exception.void
updateUI()
Notification from theUIManager
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, getActionForKeyStroke, getActionMap, getAlignmentX, getAlignmentY, getAncestorListeners, getAutoscrolls, getBaseline, getBaselineResizeBehavior, 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, hide, isDoubleBuffered, isLightweightComponent, isManagingFocus, isOpaque, isOptimizedDrawingEnabled, isPaintingForPrint, isPaintingOrigin, 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, 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, getAccessibleContext, 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, getPropertyChangeListeners, getPropertyChangeListeners, getSize, getToolkit, getTreeLock, gotFocus, handleEvent, hasFocus, 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, requestFocus, requestFocus, requestFocusInWindow, resize, resize, setBounds, setBounds, setComponentOrientation, setCursor, setDropTarget, setFocusable, setFocusTraversalKeysEnabled, setIgnoreRepaint, setLocale, setLocation, setLocation, setMixingCutoutShape, setName, setSize, setSize, show, show, size, toString, transferFocus, transferFocusBackward, transferFocusUpCycle
-
-
-
-
Field Detail
-
REPORT_ACTION_KEY
public static final java.lang.String REPORT_ACTION_KEY
Name of the Action used for reporting errors- See Also:
- Constant Field Values
-
FATAL_ACTION_KEY
public static final java.lang.String FATAL_ACTION_KEY
Name of the Action used for fatal errors- See Also:
- Constant Field Values
-
uiClassID
public static final java.lang.String uiClassID
UI Class ID- See Also:
- Constant Field Values
-
-
Method Detail
-
getUI
public ErrorPaneUI getUI()
- Overrides:
getUI
in classjavax.swing.JComponent
-
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)
-
getUIClassID
public java.lang.String getUIClassID()
Returns the name of the L&F class that renders this component.- Overrides:
getUIClassID
in classjavax.swing.JComponent
- Returns:
- the string
uiClassID
- See Also:
JComponent.getUIClassID()
,UIDefaults.getUI(javax.swing.JComponent)
-
updateUI
public void updateUI()
Notification from theUIManager
that the L&F has changed. Replaces the current UI object with the latest version from theUIManager
.- Overrides:
updateUI
in classjavax.swing.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 theJXErrorPane
'sErrorInfo
- Returns:
ErrorInfo
assigned to this dialog
-
setIcon
public void setIcon(javax.swing.Icon icon)
Specifies the icon to use- Parameters:
icon
- the Icon to use. May be null.
-
getIcon
public javax.swing.Icon getIcon()
Returns the Icon used- Returns:
- the Icon
-
setErrorReporter
public void setErrorReporter(ErrorReporter reporter)
Sets theErrorReporter
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 theErrorReporter
delegate in use.- Returns:
- the ErrorReporter. May be null.
-
showDialog
public static void showDialog(java.lang.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(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedinfo
-ErrorInfo
that incorporates all the information about the error
-
showDialog
public static void showDialog(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the dialog.
-
createDialog
public static javax.swing.JDialog createDialog(java.awt.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
orSwingUtilities.invokeLater()
.- Parameters:
owner
- Owner of this error dialog. Determines the Window in which the dialog is displayed; if theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the dialog.- Returns:
- a
JDialog
configured to display the error.
-
showFrame
public static void showFrame(java.lang.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(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedinfo
-ErrorInfo
that incorporates all the information about the error
-
showFrame
public static void showFrame(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the frame.
-
createFrame
public static javax.swing.JFrame createFrame(java.awt.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
orSwingUtilities.invokeLater()
.- Parameters:
owner
- Owner of this error frame. Determines the Window in which the frame is displayed; if theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the frame.- Returns:
- a
JFrame
configured to display the error.
-
showInternalFrame
public static void showInternalFrame(java.lang.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(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedinfo
-ErrorInfo
that incorporates all the information about the error
-
showInternalFrame
public static void showInternalFrame(java.awt.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 theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the frame.
-
createInternalFrame
public static javax.swing.JInternalFrame createInternalFrame(java.awt.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
orSwingUtilities.invokeLater()
.- Parameters:
owner
- Owner of this error frame. Determines the Window in which the frame is displayed; if theowner
has noWindow
, a defaultFrame
is usedpane
-JXErrorPane
which will form the content area of the frame.- Returns:
- a
JInternalFrame
configured to display the error.
-
-