/Users/richardallenbair/Documents/Source/Projects/nonsense/swingx/src/beaninfo/JXErrorDialog_API.java
package org.jdesktop.swingx;

/**
 * <p>JXErrorDialog is a common error dialog suitable for displaying information
 * about errors, warnings, and exceptional behavior in an application to users.
 * The common usage scenario for <code>JXErrorDialog</code> is to show collected
 * data about some incident (such as an <code>Exception</code> to the user. You
 * may also want to configure the <code>JXErrorDialog</code> to allow the user
 * to take one of several actions, including sending an error report via email
 * or some other means.</p>
 *
 * <p>Data about each incident is encapsulated in the {@link IncidentInfo} class.
 * JXErrorDialog displays each property of the <code>IncidentInfo</code> in a
 * specific way:
 * <ul>
 *  <li><code><b>header: </b></code> becomes the title of the 
 *      <code>JXErrorDialog</code></li>
 *  <li><code><b>basicErrorMessage: </b></code> the main message in the error
 *      dialog</li>
 *  <li><code><b>detailedErrorMessage: </b></code> if non null, then a button
 *      will be displayed allowing the user to view details. Details are shown
 *      in a component capable of rendering simply HTML.</li>
 *  <li><code><b>errorException: </b></code> if non null and
 *      <code>detailedErrorMessage</code> is null, then this will form the
 *      <code>detailedErrorMessage</code>. The "details" button will be shown
 *      the same as noted above.</li>
 *  <li><code><b>errorLevel: </b></code> if <code>Level.SEVERE</code> then the
 *      error icon will be shown, otherwise a warning icon will be shown.</li>
 * </ul></p>
 *
 * <p>Because <code>JXErrorDialog</code> is a Java Bean, it may be instantiated
 * and properties can be modified on the dialog prior to showing the dialog. For
 * example, if you wanted to modify the icon that was shown with a particular
 * instance of a <code>JXErrorDialog</code> prior to showing an error, you might
 * do the following:
 * <pre><code>
 *              //myWindow is the JFrame/JDialog that is going to be the
 *              //"parent" for the JXErrorDialog
 *              JXErrorDialog dlg = new JXErrorDialog(myWindow);
 *              dlg.setErrorIcon(myErrorIcon);
 *              dlg.setIncidentInfo(new IncidentInfo("Fatal Error", exception));
 *              dlg.pack();
 *              dlg.setVisible(true);
 * </code></pre></p>
 *
 * <p>Several static methods are included as part of the JXErrorDialog API to
 * simplify showing errors. These methods are convenient to use from within
 * catch blocks. For example:
 * <pre><code>
 *              try {
 *                  //do stuff.... something throws an exception in here
 *              } catch (Exception e) {
 *                  JXErrorDialog.showDialog(myWindow, "Fatal Error", e);
 *              }
 * </code></pre></p>
 *
 * <p>While this is the simpliest usage, it is not the recommended approach for
 * most errors since it yields the most obtuse messages for users. Users
 * should not be presented with details that include a stack trace! Instead, you
 * should provide a more useful message to users. For example, if I were creating
 * a URL (which may cause a MalformedURLException):
 * <pre><code>
 *              URL url = null;
 *              try {
 *                  url = new URL(userSuppliedUrl);
 *              } catch (MalformedURLException e) {
 *                  String msg = "The web resource you entered is not formatted"
 *                              + " correctly.";
 *                  String details = "&th;html&gt;Web resources should begin with \"http://\""
 *                              + " and cannot contain any spaces. Below are a few"
 *                              + " more guidelines.&lt;ul&gt;"
 *                              + getURLGuidelines()
 *                              + "&lt;/ul&gt;&th;/html&gt;";
 *                  JXErrorDialog.showDialog(myWindow, "Unknown Resource", msg, details, e);
 *                  return false;
 *              }
 * </code></pre></p>
 *
 * <p><code>JXErrorDialog 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 {@link ErrorReporter} class. Simply instantiate {@link LogErrorReporter},
 * {@link JdicEmailErrorReporter}, {@link JavaEmailErrorReporter}, or some custom
 * subclass of <code>ErrorReporter</code> and pass the <code>ErrorReporter</code>
 * instance into the {@link #setErrorReporter} method.</p>
 *
 * @author Richard Bair
 * @author Alexander Zuev
 * @author Shai Almog
 */
public class JXErrorDialog extends JDialog {
    //--------------------------------------------------------- constructors

    /**
     * Create a new <code>JXErrorDialog</code>.
     */
    public JXErrorDialog();
    
    /**
     * Create a new <code>JXErrorDialog</code> with the given <code>Frame</code>
     * as the owner.
     *
     * @param owner Owner of this error dialog.
     */
    public JXErrorDialog(Frame owner);
    
    /**
     * Create a new <code>JXErrorDialog</code> with the given <code>Dialog</code>
     * as the owner.
     *
     * @param owner Owner of this error dialog.
     */
    public JXErrorDialog(Dialog owner);
    
    //-------------------------------------------- public methods/properties
    
    /**
     * Sets the IncidentInfo for this dialog
     *
     * @param info IncidentInfo that incorporates all the details about the error
     */
    public void setIncidentInfo(IncidentInfo info);
    
    /**
     * Gets the <code>JXErrorDialog</code>'s <code>IncidentInfo</code>
     *
     * @return <code>IncidentInfo</code> assigned to this dialog
     */
    public IncidentInfo getIncidentInfo();
    
    /**
     * Sets the <code>ErrorReporter</code> to use with this instance of 
     * <code>JXErrorDialog</code>.
     * If not specified, the default error reporter is used (as specified
     * by the setDefaultErrorReporter() static method) which by default is
     * null.
     *
     * @param rep the error reporter to use. May be null.
     */
    public void setErrorReporter(ErrorReporter rep);
    
    /**
     * Returns the error reporter in use with this instance of <code>JXErrorDialog.</code>
     *
     * @return the ErrorReporter in use. May be null
     */
    public ErrorReporter getErrorReporter();
    
    /**
     * Specifies the icon to use if the IncidentInfo is Level.SEVERE
     *
     * @param icon the Icon to use. May be null.
     */
    public void setErrorIcon(Icon icon);
    
    /**
     * Returns the Icon in use if the IncidentInfo is Level.SEVERE
     *
     * @return the Icon
     */
    public Icon getErrorIcon();
    
    /**
     * Specifies the icon to use if the IncidentInfo is not Level.SEVERE
     *
     * @param icon the Icon to use. May be null.
     */
    public void setWarningIcon(Icon icon);
    
    /**
     * Returns the Icon in use if the IncidentInfo is not Level.SEVERE
     *
     * @return the Icon
     */
    public Icon getWarningIcon();
    
    /**
     * Sets the Action that will be executed to report an error/warning.
     *
     * @param action The Action to execute if the user attempts to report a problem
     */
    public void setReportAction(Action action);
    
    /**
     * @return the Action that is executed if the user attempts to report a problem
     */
    public Action getReportAction();
    
    //------------------------------------------------------- static methods
    
    /**
     * Constructs and shows the error dialog for the given exception.  The exceptions message will be the
     * errorMessage, and the stacktrace will be the details.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param title Title of the error dialog
     * @param e Exception that contains information about the error cause and stack trace
     */
    public static void showDialog(Component owner, String title, Throwable e);
    
    /**
     * Constructs and shows the error dialog for the given exception.  The exceptions message is specified,
     * and the stacktrace will be the details.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param title Title of the error dialog
     * @param errorMessage Message for the error dialog
     * @param e Exception that contains information about the error cause and stack trace
     */
    public static void showDialog(Component owner, String title, String errorMessage, Throwable e);
    
    /**
     * Show the error dialog.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param title Title of the error dialog
     * @param errorMessage Message for the error dialog
     * @param details Details to be shown in the detail section of the dialog.  This can be null
     * if you do not want to display the details section of the dialog.
     */
    public static void showDialog(Component owner, String title, String errorMessage, String details);
    
    /**
     * Show the error dialog.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param title Title of the error dialog
     * @param errorMessage Message for the error dialog
     * @param details Details to be shown in the detail section of the dialog.  This can be null
     * if you do not want to display the details section of the dialog.
     * @param e Exception that contains information about the error cause and stack trace
     */
    public static void showDialog(Component owner, String title, String errorMessage, String details, Throwable e);
    
    /**
     * Show the error dialog.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param title Title of the error dialog
     * @param errorMessage Message for the error dialog
     */
    public static void showDialog(Component owner, String title, String errorMessage);
    
    /**
     * Show the error dialog.
     * @param owner Owner of this error dialog. Determines the Window in which the dialog
     *          is displayed; if the <code>owner</code> has
     *          no <code>Window</code>, a default <code>Frame</code> is used
     * @param info <code>IncidentInfo</code> that incorporates all the information about the error
     */
    public static void showDialog(Component owner, IncidentInfo info);
    
    /**
     * Returns the current reporting engine that will be used to report a problem if
     * user clicks on 'Report' button or <code>null</code> if no reporting engine set.
     *
     * @return reporting engine
     */
    public static ErrorReporter getDefaultErrorReporter();
    
    /**
     * Set reporting engine which will handle error reporting if user clicks 'report' button.
     *
     * @param rep <code>ErrorReporter</code> to be used or <code>null</code> to turn reporting facility off.
     */
    public static void setDefaultErrorReporter(ErrorReporter rep);
}