Module org.bzdev.desktop
Package org.bzdev.swing

Class SwingErrorMessage

java.lang.Object
org.bzdev.util.ErrorMessage
org.bzdev.swing.SwingErrorMessage
public class SwingErrorMessage extends ErrorMessage
Error-Message Handling with GUI support. This class handles the display of error messages. It is intended for applications that may generate multiple errors or warnings and that might run with or without a GUI.

When a GUI is available, methods support cases where one would use a dialog box, which requires user-interaction after each messages, or a console window to display messages, in which case messages just accumulate in the window. Dialog boxes need a component on which to center themselves, and a default can be specified.

If nothing is configured, the messages by default are printed on System.err. Where the messages are sent can be modified by calling ErrorMessage.setAppendable(Appendable). For methods that have a title as an argument and that do have an argument representing a Swing component, the behavior depends on whether setComponent was called. If setComponent(Component) was not called, the message appears on the designated Appendable (which by default is System.err). If setComponent(Component) has been called, including with a null argument, the message will be shown in a dialog box.

For methods that cause a message to be displayed the order of arguments are:

  1. a Component providing a component indicating where a dialog box should be centered. If null, the dialog box will appear in the center of the screen.
  2. a String giving a title for a dialog box. A dialog box will be provided only if setComponent(Component) has been called, including with a null argument.
  3. a Locale giving the locale to use (null implies the default locale.
  4. a String containing format directives or the message itself
  5. a variable number of Objects providing arguments specified by a format string.
Depending on the method, some of these may be missing. The order is different from that used by JOptionPane. The rationale for a different order is to make any format string used appear directly before its arguments and to keep the order of arguments consistent among methods defined by this class.

While the method ErrorMessage.setStackTrace(boolean) can be used to programatically turn the display of stack traces on and off for Those "display" methods that take a Throwable as an argument, one may wish to control this behavior from a GUI. The class 1 * StackTraceMenuItem will an appropriate menu item. Error messages will often be directed to a console. The documentation for SimpleConsole explains how do do this

See Also:

  • Method Details

    • getErrorMsgOps

      public static ErrorMsgOps getErrorMsgOps()
      Get an instance of ErrorMsgOps.
      Returns:
      an instance of ErrorMsgOps that can be used for reporting error messages or warnings.

    • getTaggingInstance

      public static SwingErrorMessage getTaggingInstance()
      Get the instance of ErrorMessage used as a tag. This object is merely a tag - it has no ErrorMessage-specific methods. It is useful for the case where the source of an event is an object responsible for error messages.
      Returns:
      the instance; null if the graphics environment is headless.

    • addSeparatorIfNeeded

      public static void addSeparatorIfNeeded()
      Add separator if needed.

    • addChangeListener

      public static void addChangeListener(ChangeListener listener)
      Add a state-change listener. State-change listeners will be notified if stack-trace mode has been changed.
      Parameters:
      listener - the listener to add.

    • removeChangeListener

      public static void removeChangeListener(ChangeListener listener)
      Remove a state-change listener
      Parameters:
      listener - the listener to remove

    • addSeparator

      public static void addSeparator()
      Add a separator.

    • setStackTrace

      public static void setStackTrace(boolean value)
      Set stack-trace recording. Determines if a stack trace is shown when a Throwable is displayed.
      Parameters:
      value - true if stack traces should be recorded; false otherwise
      See Also:

    • stackTraceEnabled

      public static boolean stackTraceEnabled()
      Check if stack traces are enabled.
      Returns:
      true if stack traces are enabled; false otherwise
      See Also:

    • setComponent

      public static void setComponent(Component comp)
      Set the component on which to center dialog boxes; null for a system default. If this method is not called this class will assume that no GUI is available so all messages will be passed to an Appendable (by default, System.err).
      Parameters:
      comp - the component; null if no particular component is specified.

    • displayConsoleIfNeeded

      public static void displayConsoleIfNeeded()
      Display a console if there is one, if it is an instance of SimpleConsole, and if there is new text to display. For a SimpleConsole to be available, it must have been passed to ErrorMessage.setAppendable(Appendable).

    • displayFormat

      public static void displayFormat(Component comp, String title, String format, Object... args)
      Display formatted text with a title using the default locale and a specified component. The title is used as the title of a dialog box. See Formatter for a description of the format string.
      Parameters:
      comp - the component; null for the default.
      title - the title; null for the default title
      format - a format string
      args - the arguments to format

    • displayFormat

      public static void displayFormat(String title, Locale locale, String format, Object... args)
      Display formatted text with a title for a specific locale. The title is used as the title of a dialog box when a dialog box is used to display the message, If no component was specified for centering a dialog box, the title is ignored and the message is printed on an Appendable. See Formatter for a description of the format string.
      Parameters:
      title - the title; null for the default title
      locale - the Locale, null for no localization
      format - a format string
      args - the arguments to format

    • displayFormat

      public static void displayFormat(Component comp, String title, Locale locale, String format, Object... args)
      Display formatted text with a title for a specific locale. The title is used as the title of a dialog box when a dialog box is used to display the message, If the Component argument is null, a default location for the dialog box will be used. See Formatter for a description of the format string.
      Parameters:
      comp - the Component on which to center the dialog box.
      title - the title; null for the default title
      locale - the Locale, null for no localization
      format - a format string
      args - the arguments to format

    • display

      public static void display(String title, String msg)
      Display a message with a title. The title is used as the title of a dialog box when a dialog box is used to display the message. If setComponent was not called, the title will be ignored and the message will appear on the Appendable used to log messages.
      Parameters:
      msg - the message to display
      title - the title; null for the default title
      See Also:

    • display

      public static void display(Component comp, String title, String msg)
      Display a message with a title, centering any dialog box on a component. The title is used as the title of a dialog box.
      Parameters:
      comp - the component; null for a default.
      title - the title; null for the default title
      msg - the message to display
      See Also: