ilog.views.util.swing
Class IlvSwingUtil

java.lang.Object
  ilog.views.util.swing.IlvSwingUtil

public class IlvSwingUtil
extends Object

The IlvSwingUtil class provides utility methods for Swing.

This class is a singleton with static methods. Instances of this class cannot be created.

Since:

JViews 5.5

Nested Class Summary

static class

IlvSwingUtil.Version The class IlvSwingUtil.Version represents a version of Swing.

Method Summary

static Point	convertPoint(Component source, Point aPoint, Component destination) Converts a aPoint in source coordinate system to destination coordinate system.
static void	convertPointFromScreen(Point p, Component comp) Converts a point from screen coordinates to a component's coordinate system.
static void	convertPointToScreen(Point p, Component comp) Converts a point from component's coordinate system to screen coordinates.
static Rectangle	convertRectangle(Component source, Rectangle aRectangle, Component destination) Converts the rectangle aRectangle in source coordinate system to destination coordinate system.
static String	createMultiLineToolTipText(String[] lines, int alignment) Creates an HTML text string that will render lines as a multiline tooltip.
static String	escapeForHTMLAttribute(String s, boolean forExternal) Converts a string to HTML syntax, for including in an HTML attribute.
static String	escapeForHTMLElement(String s, boolean forExternal) Converts a string to HTML syntax, for including in an HTML element.
static Locale	getDefaultLocale() Returns the default locale used to initialize each JComponent's locale property upon creation.
static Point	getLocationOnScreen(Component comp) Returns the screen coordinates of a component.
static URL	getRelativeURL(JApplet applet, String spec) Returns an URL that points to a file location relative to an applet location.
static IlvSwingUtil.Version	getSwingVersion() Returns the currently running version of Swing.
static void	invokeAndWait(Runnable runnable) This method executes runnable.run() synchronously on the AWT event dispatching thread.
static void	invokeAndWaitForIdle(Runnable runnable) This method executes runnable.run() synchronously on the AWT event dispatching thread.
static void	invokeNowOrLater(Runnable task) Executes the given task in the current AWT/Swing event thread, if not already executing in this thread.
static boolean	isDispatchThread() Returns true if the calling thread is the current AWT/Swing event dispatch thread.
static boolean	isHTMLToolTipsSupported() Returns whether the currently running version of Swing supports HTML tooltips.
static void	setDefaultLocale(Locale locale) Sets the default locale used to initialize each JComponent's locale property upon creation.
static void	showDialog(Component parent, String message, Object additionalComp, int dialogType, Throwable th) Pops a dialog of the specified dialogType, with a specified parent component and showing the specified message, additional component and exception.
static void	showErrorDialog(Component parent, String message) Pops an error dialog with a specified parent component and showing the specified message.
static void	showErrorDialog(Component parent, String message, Throwable th) Pops an error dialog with a specified parent component and showing the specified message and exception.
static void	showErrorDialog(Component parent, Throwable th) Pops an error dialog with a specified parent component and showing the specified exception.
static void	showInformationDialog(Component parent, String message) Pops an information dialog with a specified parent component and showing the specified message.
static void	showInformationDialog(Component parent, String message, Object additionalComp) Pops an information dialog with a specified parent component and showing the specified message.
static int	showOptionDialog(Component parentComponent, Object message, String title, int optionType, int messageType, Icon icon, Object[] options, Object initialValue, Component bottomComponent, HashMap keyShortCuts) Brings up a dialog with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.
static void	showWarningDialog(Component parent, String message) Pops a warning dialog with a specified parent component and showing the specified message.
static void	showWarningDialog(Component parent, String message, Object additionalComp) Pops a warning dialog with a specified parent component and showing the specified message.
static int	showYesNoCancelDialog(Component parentComponent, Object message, String title, Icon icon) Brings up a confirmation dialog with the buttons 'YES', 'NO' and 'CANCEL'.
static int	showYesNoDialog(Component parentComponent, Object message, String title, Icon icon) Brings up a confirmation dialog with the buttons 'YES' and 'NO'.
static void	updateComponentTreeOrientation(Component component, ComponentOrientation orientation) Sets the ComponentOrientation property of the specified component and all of its children.

Methods inherited from class java.lang.Object

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

Method Detail

isHTMLToolTipsSupported

public static boolean isHTMLToolTipsSupported()

Returns whether the currently running version of Swing supports HTML tooltips.

escapeForHTMLElement

public static String escapeForHTMLElement(String s,
                                          boolean forExternal)

Converts a string to HTML syntax, for including in an HTML element.

Note: The resulting string is not a valid HTML document; you need to wrap it in <html>.../<html> if you want a complete HTML document.

Parameters:

s - The string to be converted. It should not contain tab characters.

forExternal - If true, the resulting string can be serialized as a pure ASCII string. Pass false if the resulting string will only be used in the same JVM.

Since:

JViews 8.1

escapeForHTMLAttribute

public static String escapeForHTMLAttribute(String s,
                                            boolean forExternal)

Converts a string to HTML syntax, for including in an HTML attribute.

Note: You usually need to wrap the resulting string in double-quotes.

Parameters:

s - The string to be converted. It should not contain tab or newline characters.

forExternal - If true, the resulting string can be serialized as a pure ASCII string. Pass false if the resulting string will only be used in the same JVM.

Since:

JViews 8.1

createMultiLineToolTipText

public static String createMultiLineToolTipText(String[] lines,
                                                int alignment)

Creates an HTML text string that will render lines as a multiline tooltip.

Parameters:

lines - The array of text strings. Each string will be formatted as a separate HTML paragraph. Each string should be valid HTML; if you want to show a simple line of text, some characters need to be escaped, see escapeForHTMLElement(java.lang.String, boolean).

alignment - The horizontal alignment of the text. It must be one of the constants: LEFT, RIGHT, or CENTER defined in the class javax.swing.SwingConstants.

Since:

JViews 8.1

getDefaultLocale

public static Locale getDefaultLocale()

Returns the default locale used to initialize each JComponent's locale property upon creation. This method is equivalent to JComponent.getDefaultLocale which has "AppContext" scope.

Since:

JViews 5.5

See Also:

setDefaultLocale(java.util.Locale)

setDefaultLocale

public static void setDefaultLocale(Locale locale)

Sets the default locale used to initialize each JComponent's locale property upon creation. This method is equivalent to calling the three methods:

• Locale.setDefault, which has JVM scope.
• JComponent.setDefaultLocale, which has "AppContext" scope.
• UIDefaults.setDefaultLocale, which has "AppContext" scope.

The initial value is the JVM's default locale.

Note that the locale of a component does not automatically set its ComponentOrientation. All components are initialized to ComponentOrientation.UNKNOWN which behaves as a left-to-right orientation. In order to set the orientation of a component tree to match a locale, you must do something like this:

 Locale locale = rootComponent.getLocale();
 ComponentOrientation co = ComponentOrientation.getOrientation(locale);
 IlvSwingUtil.updateComponentTreeOrientation(rootComponent, co);
 

Parameters:

locale - The locale for new components.

Since:

JViews 5.5

See Also:

getDefaultLocale(), updateComponentTreeOrientation(java.awt.Component, java.awt.ComponentOrientation)

updateComponentTreeOrientation

public static void updateComponentTreeOrientation(Component component,
                                                  ComponentOrientation orientation)

Sets the ComponentOrientation property of the specified component and all of its children. This method is equivalent to calling Component.applyComponentOrientation followed by component.repaint().

Note that the locale of a component does not automatically set its ComponentOrientation. All components are initialized to ComponentOrientation.UNKNOWN which behaves as a left-to-right orientation. In order to set the orientation of a component tree to match a locale, you must do something like this:

 Locale locale = rootComponent.getLocale();
 ComponentOrientation co = ComponentOrientation.getOrientation(locale);
 IlvSwingUtil.updateComponentTreeOrientation(rootComponent, co);
 

Parameters:

component - The root of the component tree to update.

orientation - The new component orientation.

Since:

JViews 5.5

getRelativeURL

public static URL getRelativeURL(JApplet applet,
                                 String spec)
                          throws MalformedURLException

Returns an URL that points to a file location relative to an applet location. This is approximately the same to URL(applet.getDocumentBase(), spec), however it works as well when a program written as applet actually runs as application.

Parameters:

applet - the applet that delivers the document base context.

spec - the String to parse as a URL. This must be a relative location.

Throws:

MalformedURLException

Since:

JViews 6.0

getSwingVersion

public static IlvSwingUtil.Version getSwingVersion()

Returns the currently running version of Swing.

showErrorDialog

public static void showErrorDialog(Component parent,
                                   String message)

Pops an error dialog with a specified parent component and showing the specified message.

Parameters:

parent - The parent component of the error dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the error dialog.

Since:

JViews 6.0

See Also:

showErrorDialog(java.awt.Component, java.lang.String, java.lang.Throwable)

showErrorDialog

public static void showErrorDialog(Component parent,
                                   Throwable th)

Pops an error dialog with a specified parent component and showing the specified exception.

Parameters:

parent - The parent component of the error dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

th - The Throwable to be shown by the error dialog, or null if none.

Since:

JViews 6.0

See Also:

showErrorDialog(java.awt.Component, java.lang.String, java.lang.Throwable)

showErrorDialog

public static void showErrorDialog(Component parent,
                                   String message,
                                   Throwable th)

Pops an error dialog with a specified parent component and showing the specified message and exception.

Parameters:

parent - The parent component of the error dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the error dialog, or null if none.

th - The Throwable to be shown by the error dialog, or null if none.

Since:

JViews 6.0

See Also:

showErrorDialog(java.awt.Component, java.lang.String)

showWarningDialog

public static void showWarningDialog(Component parent,
                                     String message)

Pops a warning dialog with a specified parent component and showing the specified message.

Parameters:

parent - The parent component of the warning dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the warning dialog, or null if none.

Since:

JViews 6.0

See Also:

showWarningDialog(java.awt.Component, java.lang.String, java.lang.Object)

showWarningDialog

public static void showWarningDialog(Component parent,
                                     String message,
                                     Object additionalComp)

Pops a warning dialog with a specified parent component and showing the specified message.

Parameters:

parent - The parent component of the warning dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the warning dialog, or null if none.

additionalComp - The additional component to be shown in the dialog, or null if none.

Since:

JViews 6.0

See Also:

showWarningDialog(java.awt.Component, java.lang.String)

showInformationDialog

public static void showInformationDialog(Component parent,
                                         String message)

Pops an information dialog with a specified parent component and showing the specified message.

Parameters:

parent - The parent component of the information dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the information dialog, or null if none.

Since:

JViews 6.0

See Also:

showInformationDialog(java.awt.Component, java.lang.String, java.lang.Object)

showInformationDialog

public static void showInformationDialog(Component parent,
                                         String message,
                                         Object additionalComp)

Pops an information dialog with a specified parent component and showing the specified message.

Parameters:

parent - The parent component of the information dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the information dialog, or null if none.

additionalComp - The additional component to be shown in the dialog, or null if none.

Since:

JViews 6.0

See Also:

showInformationDialog(java.awt.Component, java.lang.String)

showDialog

public static void showDialog(Component parent,
                              String message,
                              Object additionalComp,
                              int dialogType,
                              Throwable th)

Pops a dialog of the specified dialogType, with a specified parent component and showing the specified message, additional component and exception.

Parameters:

parent - The parent component of the dialog. The parent component determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used.

message - The message to be shown in the dialog, or null if none.

additionalComp - The additional component to be shown in the dialog, or null if none.

dialogType - An integer designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel. The valid values are those defined on the class javax.swing.JOptionPane: ERROR_MESSAGE, INFORMATION_MESSAGE, WARNING_MESSAGE, QUESTION_MESSAGE, or PLAIN_MESSAGE.

th - The Throwable to be shown by the dialog, or null if none.

Since:

JViews 6.0

See Also:

showErrorDialog(java.awt.Component, java.lang.String)

showYesNoCancelDialog

public static int showYesNoCancelDialog(Component parentComponent,
                                        Object message,
                                        String title,
                                        Icon icon)
                                 throws HeadlessException

Brings up a confirmation dialog with the buttons 'YES', 'NO' and 'CANCEL'. This method can be used as replacement to JOptionPane.showConfirmDialog(Component, Object, String, int) with option type JOptionPane.YES_NO_CANCEL_OPTION. The dialog reacts on keystrokes 'Y' and 'N' while dialogs created via JOptionPane usually react only on 'ALT Y' and 'ALT N'.

Parameters:

parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used

message - the Object to display

title - the title string for the dialog

icon - the icon to display in the dialog

Returns:

an integer indicating the option chosen by the user, or JOptionPane.CLOSED_OPTION if the user closed the dialog

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless returns true

Since:

JViews 7.5

See Also:

JOptionPane.showConfirmDialog(Component, Object, String, int), GraphicsEnvironment.isHeadless()

showYesNoDialog

public static int showYesNoDialog(Component parentComponent,
                                  Object message,
                                  String title,
                                  Icon icon)
                           throws HeadlessException

Brings up a confirmation dialog with the buttons 'YES' and 'NO'. This method can be used as replacement to JOptionPane.showConfirmDialog(Component, Object, String, int) with option type JOptionPane.YES_NO_OPTION. The dialog reacts on keystrokes 'Y' and 'N' while dialogs created via JOptionPane usually react only on 'ALT Y' and 'ALT N'.

Parameters:

parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used

message - the Object to display

title - the title string for the dialog

icon - the icon to display in the dialog

Returns:

an integer indicating the option chosen by the user, or JOptionPane.CLOSED_OPTION if the user closed the dialog

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless returns true

Since:

JViews 7.5

See Also:

JOptionPane.showConfirmDialog(Component, Object, String, int), GraphicsEnvironment.isHeadless()

showOptionDialog

public static int showOptionDialog(Component parentComponent,
                                   Object message,
                                   String title,
                                   int optionType,
                                   int messageType,
                                   Icon icon,
                                   Object[] options,
                                   Object initialValue,
                                   Component bottomComponent,
                                   HashMap keyShortCuts)
                            throws HeadlessException

Brings up a dialog with a specified icon, where the initial choice is determined by the initialValue parameter and the number of choices is determined by the optionType parameter.

This method can be used as replacement to JOptionPane.showOptionDialog(java.awt.Component, java.lang.Object, java.lang.String, int, int, javax.swing.Icon, java.lang.Object[], java.lang.Object). It allows to provide a map of keystroke shortcuts that are additionally installed at the dialog.

Parameters:

parentComponent - determines the Frame in which the dialog is displayed; if null, or if the parentComponent has no Frame, a default Frame is used

message - the Object to display

title - the title string for the dialog

optionType - an integer designating the options available on the dialog: JOptionPane.YES_NO_OPTION, or JOptionPane.YES_NO_CANCEL_OPTION

messageType - an integer designating the kind of message this is, primarily used to determine the icon from the pluggable Look and Feel: JOptionPane.ERROR_MESSAGE, JOptionPane.INFORMATION_MESSAGE, JOptionPane.WARNING_MESSAGE, JOptionPane.QUESTION_MESSAGE, or JOptionPane.PLAIN_MESSAGE

icon - the icon to display in the dialog

options - an array of objects indicating the possible choices the user can make; if the objects are components, they are rendered properly; non-String objects are rendered using their toString methods; if this parameter is null, the options are determined by the Look and Feel

initialValue - the object that represents the default selection for the dialog; only meaningful if options is used; can be null

bottomComponent - an additional component that is shown at the bottom of the dialog, below the option buttons.

keyShortCuts - a mapping from KeyStroke to selection objects; if options is null, use Integer objects; the integer is returned if the key is typed.

Returns:

an integer indicating the option chosen by the user, or JOptionPane.CLOSED_OPTION if the user closed the dialog

Throws:

HeadlessException - if GraphicsEnvironment.isHeadless returns true

Since:

JViews 7.5

See Also:

JOptionPane.showOptionDialog(java.awt.Component, java.lang.Object, java.lang.String, int, int, javax.swing.Icon, java.lang.Object[], java.lang.Object), GraphicsEnvironment.isHeadless()

isDispatchThread

public static boolean isDispatchThread()

Returns true if the calling thread is the current AWT/Swing event dispatch thread.

This is like EventQueue.isDispatchThread() or SwingUtilities.isEventDispatchThread(), except that it also takes into account a possible redirection of the AWT/Swing event thread to an SWT event thread.

Since:

JViews 7.5

invokeNowOrLater

public static void invokeNowOrLater(Runnable task)

Executes the given task in the current AWT/Swing event thread, if not already executing in this thread.

This is like EventQueue.invokeLater(task) or SwingUtilities.invokeLater(task), except that it may run the task immediately, and also takes into account a possible redirection of the AWT/Swing event thread to an SWT event thread.

Since:

JViews 7.5

invokeAndWait

public static void invokeAndWait(Runnable runnable)

This method executes runnable.run() synchronously on the AWT event dispatching thread. If the current thread is the event dispatch thread (EDT) then runnable.run() is executed immediately. Otherwise, if the current thread is not the EDT then runnable.run() is posted to execute on the EDT and this method will block until the runnable has been processed. This method is similar to calling SwingUtilities.invokeAndWait(), except for the following points:

• This method can be safely called from the event dispatching thread or any other thread. SwingUtilities.invokeAndWait() and Robot.waitForIdle() can only be called from a thread that is not the event dispatching thread.
• If runnable.run() throws an exception, SwingUtilities.invokeAndWait() will rethrow it wrapped in a checked InvocationTargetException. This method will instead rethrow the exception as an unchecked runtime exception that has the stack frames related to posting the runnable onto the AWT event queue and waiting for its execution removed for clarity.

Parameters:

runnable - The method to run on the event dispatch thread.

Since:

JViews 8.1

invokeAndWaitForIdle

public static void invokeAndWaitForIdle(Runnable runnable)

This method executes runnable.run() synchronously on the AWT event dispatching thread. If the current thread is the event dispatch thread (EDT) then runnable.run() is executed immediately. Otherwise, if the current thread is not the EDT then runnable.run() is posted to execute on the EDT and this method will block until the runnable and all subsequent AWT events have been processed. This method is similar to calling SwingUtilities.invokeAndWait() followed by Robot.waitForIdle(), except for the following points:

• This method can be safely called from the event dispatching thread or any other thread. SwingUtilities.invokeAndWait() and Robot.waitForIdle() can only be called from a thread that is not the event dispatching thread.
• If runnable.run() throws an exception, SwingUtilities.invokeAndWait() will rethrow it wrapped in a checked InvocationTargetException. This method will instead rethrow the exception as an unchecked runtime exception that has the stack frames related to posting the runnable onto the AWT event queue and waiting for its execution removed for clarity.

Parameters:

runnable - The method to run on the event dispatch thread.

Since:

JViews 8.1

getLocationOnScreen

public static Point getLocationOnScreen(Component comp)

Returns the screen coordinates of a component.

This is like Component.getLocationOnScreen(), except that it also works with SWT-embedded components.

Since:

JViews 7.5

convertPointToScreen

public static void convertPointToScreen(Point p,
                                        Component comp)

Converts a point from component's coordinate system to screen coordinates.

This is like SwingUtilities.convertPointToScreen, except that it also works with SWT-embedded components.

Since:

JViews 7.5

convertPointFromScreen

public static void convertPointFromScreen(Point p,
                                          Component comp)

Converts a point from screen coordinates to a component's coordinate system.

This is like SwingUtilities.convertPointFromScreen, except that it also works with SWT-embedded components.

Since:

JViews 7.5

convertPoint

public static Point convertPoint(Component source,
                                 Point aPoint,
                                 Component destination)

Converts a aPoint in source coordinate system to destination coordinate system.

This method is like SwingUtilities.convertPoint, except that it is faster and also works with SWT-embedded components.

If sourceis null, aPoint is assumed to be in destination's root component coordinate system.

If destinationis null, aPoint will be converted to source's root component coordinate system.

If both source and destination are null, returns aPoint without any conversion.

Since:

JViews 7.5

convertRectangle

public static Rectangle convertRectangle(Component source,
                                         Rectangle aRectangle,
                                         Component destination)

Converts the rectangle aRectangle in source coordinate system to destination coordinate system.

This method is like SwingUtilities.convertRectangle, except that it is faster and also works with SWT-embedded components.

If sourceis null, aRectangle is assumed to be in destination's root component coordinate system.

If destinationis null, aRectangle will be converted to source's root component coordinate system.

If both source and destination are null, returns aRectangle without any conversion.

Since:

JViews 7.5