Package ptolemy.gui

Class UndeferredGraphicalMessageHandler

  • All Implemented Interfaces:
    java.lang.Thread.UncaughtExceptionHandler
    Direct Known Subclasses:
    GraphicalMessageHandler
    public class UndeferredGraphicalMessageHandler
extends MessageHandler
    This is a message handler that reports errors in a graphical dialog box. When an applet or application starts up, it should call setContext() to specify a component with respect to which the display window should be created. This ensures that if the application is iconified or deiconified, that the display window goes with it. If the context is not specified, then the display window is centered on the screen, but iconifying and deiconifying may not work as desired.

    Note that to display a window with an error message, this graphical handler must be registered by calling MessageHandler.setMessageHandler(MessageHandler). For example: 

     GraphicalMessageHandler handler = new GraphicalMessageHandler();
 GraphicalMessageHandler.setMessageHandler(handler);
 GraphicalMessageHandler.error("My error", new Exception("My Exception"));
    If setMessageHandler() is not called, then the error() call will use the default handler and possibly display the message on standard error.

    This class is based on (and contains code from) the diva GUIUtilities class.

    Since:
    Ptolemy II 8.0
    Version:
    $Id$
    Author:
    Edward A. Lee, Steve Neuendorffer, John Reekie, and Elaine Cheong
    Pt.AcceptedRating:
    Red (reviewmoderator)
    Pt.ProposedRating:
    Yellow (eal)

    • Field Summary

      Fields 
      Modifier and Type Field Description
      protected static java.lang.ref.WeakReference _context
      The context.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      protected java.lang.Object[] _checkThrowableNameable​(java.lang.Object[] options, java.lang.Throwable throwable)
      Return an updated array of button names if the throwable meets certain conditions.
      protected void _error​(java.lang.String info)
      Show the specified error message.
      protected void _error​(java.lang.String info, java.lang.Throwable throwable)
      Show the specified message and throwable information.
      protected void _message​(java.lang.String info)
      Show the specified message in a modal dialog.
      protected void _showNameable​(java.lang.Throwable throwable)
      Open the level of hierarchy of the model that contains the Nameable referred to by the KernelException or KernelRuntimeException.
      protected void _showStackTrace​(java.lang.Throwable throwable, java.lang.String info)
      Display a stack trace dialog.
      protected void _warning​(java.lang.String info)
      Show the specified message in a modal dialog.
      protected void _warning​(java.lang.String info, java.lang.Throwable throwable)
      Show the specified message and throwable information in a modal dialog.
      protected boolean _yesNoCancelQuestion​(java.lang.String question, java.lang.String trueOption, java.lang.String falseOption, java.lang.String exceptionOption)
      Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one.
      protected boolean _yesNoQuestion​(java.lang.String question)
      Ask the user a yes/no question, and return true if the answer is yes.
      static java.awt.Component getContext()
      Get the component set by a call to setContext(), or null if none.
      static void setContext​(java.awt.Component context)
      Set the component with respect to which the display window should be created.

      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

    • Field Detail

      • _context

        protected static java.lang.ref.WeakReference _context
        The context.

    • Constructor Detail

      • UndeferredGraphicalMessageHandler

        public UndeferredGraphicalMessageHandler()

    • Method Detail

      • getContext

        public static java.awt.Component getContext()
        Get the component set by a call to setContext(), or null if none.
        Returns:
        The component with respect to which the display window is iconified, or null if none has been specified.
        See Also:
        setContext(Component)

      • setContext

        public static void setContext​(java.awt.Component context)
        Set the component with respect to which the display window should be created. This ensures that if the application is iconified or deiconified, that the display window goes with it. This is maintained in a weak reference so that the frame can be garbage collected.
        Parameters:
        context - The component context.
        See Also:
        getContext()

      • _checkThrowableNameable

        protected java.lang.Object[] _checkThrowableNameable​(java.lang.Object[] options,
                                                     java.lang.Throwable throwable)
        Return an updated array of button names if the throwable meets certain conditions. In this base class, the options argument is returned. In derived classes, this method could check to see if the throwable is a KernelException or KernelRuntimeException, then add "Go To Actor" to the options array.
        Parameters:
        options - An array of Strings, suitable for passing to JOptionPane.showOptionDialog().
        throwable - The throwable.
        Returns:
        An array of Strings. In this base class, return the value of the options parameter. Derived classes may add a new array with an additional String that labels an additional button.

      • _error

        protected void _error​(java.lang.String info)
        Show the specified error message. This is deferred to execute in the swing event thread if it is called outside that thread.
        Overrides:
        _error in class MessageHandler
        Parameters:
        info - The message.

      • _error

        protected void _error​(java.lang.String info,
                      java.lang.Throwable throwable)
        Show the specified message and throwable information. If the throwable is an instance of CancelException, then it is not shown. By default, only the message of the throwable is thrown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button. This is deferred to execute in the swing event thread if it is called outside that thread.
        Overrides:
        _error in class MessageHandler
        Parameters:
        info - The message.
        throwable - The throwable.
        See Also:
        CancelException

      • _message

        protected void _message​(java.lang.String info)
        Show the specified message in a modal dialog. This is deferred to execute in the swing event thread if it is called outside that thread.
        Overrides:
        _message in class MessageHandler
        Parameters:
        info - The message.

      • _showNameable

        protected void _showNameable​(java.lang.Throwable throwable)
        Open the level of hierarchy of the model that contains the Nameable referred to by the KernelException or KernelRuntimeException. In this base class, do nothing.
        Parameters:
        throwable - The throwable that may be a KernelException or KernelRuntimeException.

      • _warning

        protected void _warning​(java.lang.String info)
                 throws CancelException
        Show the specified message in a modal dialog. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings. NOTE: If this is called outside the swing event thread, then no cancel button is presented and no CancelException will be thrown. This is because the displaying of the message must be deferred to the swing event thread, according to the swing architecture, or we could get deadlock or rendering problems.
        Overrides:
        _warning in class MessageHandler
        Parameters:
        info - The message.
        Throws:
        CancelException - If the user clicks on the "Cancel" button.

      • _warning

        protected void _warning​(java.lang.String info,
                        java.lang.Throwable throwable)
                 throws CancelException
        Show the specified message and throwable information in a modal dialog. If the user clicks on the "Cancel" button, then throw an exception. This gives the user the option of not continuing the execution, something that is particularly useful if continuing execution will result in repeated warnings. By default, only the message of the throwable is shown. The stack trace information is only shown if the user clicks on the "Display Stack Trace" button. NOTE: If this is called outside the swing event thread, then no cancel button is presented and no CancelException will be thrown. This is because the displaying of the message must be deferred to the swing event thread, according to the swing architecture, or we could get deadlock or rendering problems.
        Overrides:
        _warning in class MessageHandler
        Parameters:
        info - The message.
        throwable - The throwable.
        Throws:
        CancelException - If the user clicks on the "Cancel" button.

      • _yesNoQuestion

        protected boolean _yesNoQuestion​(java.lang.String question)
        Ask the user a yes/no question, and return true if the answer is yes. If the length of the question is greater than StringUtilities.ELLIPSIS_LENGTH_LONG, then the question is displayed in a JTextArea.
        Overrides:
        _yesNoQuestion in class MessageHandler
        Parameters:
        question - The yes/no question.
        Returns:
        True if the answer is yes.

      • _yesNoCancelQuestion

        protected boolean _yesNoCancelQuestion​(java.lang.String question,
                                       java.lang.String trueOption,
                                       java.lang.String falseOption,
                                       java.lang.String exceptionOption)
                                throws CancelException
        Ask the user a question with three possible answers; return true if the answer is the first one and false if the answer is the second one; throw an exception if the user selects the third one. The default (selected by return and escape) is the third (the cancel option).
        Overrides:
        _yesNoCancelQuestion in class MessageHandler
        Parameters:
        question - The question.
        trueOption - The option for which to return true.
        falseOption - The option for which to return false.
        exceptionOption - The option for which to throw an exception.
        Returns:
        True if the answer is the first option, false if it is the second.
        Throws:
        CancelException - If the user selects the third option.

      • _showStackTrace

        protected void _showStackTrace​(java.lang.Throwable throwable,
                               java.lang.String info)
        Display a stack trace dialog. The "info" argument is a string printed at the top of the dialog instead of the Throwable message.
        Parameters:
        throwable - The throwable.
        info - A message.