Class ScriptUtil


  • public class ScriptUtil
    extends java.lang.Object
    Script Utilities

    Contains static utility methods to be used in scripts:

    • Logging
    • Dialogs
    • Obtaining PVs from widgets
    • Get workspace file locations and content
    • Field Summary

      Fields 
      Modifier and Type Field Description
      static boolean PHOEBUS
      Flag that indicates running on Phoebus as opposed to Eclipse/RCP
    • Constructor Summary

      Constructors 
      Constructor Description
      ScriptUtil()  
    • Method Summary

      All Methods Static Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      static void closeDisplay​(Widget widget)
      Close a display
      static Widget findWidgetByName​(Widget widget, java.lang.String name)
      Locate a widget by name
      static java.util.logging.Logger getLogger()
      Get logger for scripts.
      static RuntimePV getPrimaryPV​(Widget widget)
      Get primary PV of given widget.
      static RuntimePV getPVByName​(Widget widget, java.lang.String name)
      Get widget's PV by name
      static java.util.Collection<RuntimePV> getPVs​(Widget widget)
      Get all PVs of a widget.
      static java.io.BufferedReader getResourceReader​(Widget widget, java.lang.String resource_name)
      Read a file
      static org.epics.vtype.VType getWidgetValueByName​(Widget widget, java.lang.String name)
      Locate a widget by name, then fetch its value
      static void openDisplay​(Widget widget, java.lang.String file, java.lang.String target, java.util.Map<java.lang.String,​java.lang.String> macros)
      Open a new display
      static void openDisplay​(Widget widget, java.lang.String file, java.lang.String target, java.util.Map<java.lang.String,​java.lang.String> macros, java.lang.String pane)
      Open a new display
      static void openFile​(Widget widget, java.lang.String resource_name)
      Open a file in the default tool.
      static void openWeb​(Widget widget, java.lang.String url)
      Open a web link in the default tool.
      static java.util.concurrent.Future<java.lang.Boolean> playAudio​(Widget widget, java.lang.String audio_file)
      Play audio
      static java.util.List<java.lang.String> readTextFile​(Widget widget, java.lang.String resource_name)
      Read Text file as list of strings
      static org.w3c.dom.Element readXMLFile​(Widget widget, java.lang.String resource_name)
      Read XML file
      static boolean showConfirmationDialog​(Widget widget, java.lang.String question)
      Show confirmation dialog.
      static void showErrorDialog​(Widget widget, java.lang.String error)
      Show an error dialog.
      static void showMessageDialog​(Widget widget, java.lang.String message)
      Show a message dialog.
      static java.lang.String showPasswordDialog​(Widget widget, java.lang.String title, java.lang.String correct_password)
      Show dialog for entering a password.
      static java.lang.String showSaveAsDialog​(Widget widget, java.lang.String initial_value)
      Show file "Save As" dialog for selecting/entering a new file name
      static java.lang.String showSelectionDialog​(Widget widget, java.lang.String title, java.util.List<java.lang.String> options)
      Show dialog for selecting one item from a list.
      static java.lang.String workspacePathToSysPath​(java.lang.String workspace_path)
      Deprecated.
      There is no more "workspace", so no need to get local path
      • Methods inherited from class java.lang.Object

        equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Field Detail

      • PHOEBUS

        public static final boolean PHOEBUS
        Flag that indicates running on Phoebus as opposed to Eclipse/RCP
        See Also:
        Constant Field Values
    • Constructor Detail

      • ScriptUtil

        public ScriptUtil()
    • Method Detail

      • findWidgetByName

        public static Widget findWidgetByName​(Widget widget,
                                              java.lang.String name)
                                       throws java.lang.Exception
        Locate a widget by name
        Parameters:
        widget - Widget used to locate the widget model
        name - Name of widget to find
        Returns:
        Widget or null
        Throws:
        java.lang.Exception - on error
      • getLogger

        public static java.util.logging.Logger getLogger()
        Get logger for scripts.

        The logger is a basic java.util.logging.Logger:

          getLogger().warning("Script has a problem")
          getLogger().info("Script is at step 3")
          
        Returns:
        Logger for scripts
      • openDisplay

        public static void openDisplay​(Widget widget,
                                       java.lang.String file,
                                       java.lang.String target,
                                       java.util.Map<java.lang.String,​java.lang.String> macros)
        Open a new display
        Parameters:
        widget - Widget in 'current' display, used to resolve relative paths
        file - Path to the display
        target - Where to show the display: "REPLACE", "TAB", "WINDOW"
        macros - Macros, may be null
      • openDisplay

        public static void openDisplay​(Widget widget,
                                       java.lang.String file,
                                       java.lang.String target,
                                       java.util.Map<java.lang.String,​java.lang.String> macros,
                                       java.lang.String pane)
        Open a new display
        Parameters:
        widget - Widget in 'current' display, used to resolve relative paths
        file - Path to the display
        target - Where to show the display: "REPLACE", "TAB", "WINDOW"
        macros - Macros, may be null
        pane - Named pane for a new "TAB"
      • closeDisplay

        public static void closeDisplay​(Widget widget)
        Close a display
        Parameters:
        widget - Widget within the display to close
      • showMessageDialog

        public static void showMessageDialog​(Widget widget,
                                             java.lang.String message)
        Show a message dialog.

        Call blocks until the user presses "OK" in the dialog.

        Parameters:
        widget - Widget, used to create and position the dialog
        message - Message to display on dialog
      • showErrorDialog

        public static void showErrorDialog​(Widget widget,
                                           java.lang.String error)
        Show an error dialog.

        Call blocks until the user presses "OK" in the dialog.

        Parameters:
        widget - Widget, used to create and position the dialog
        error - Message to display on dialog
      • showConfirmationDialog

        public static boolean showConfirmationDialog​(Widget widget,
                                                     java.lang.String question)
        Show confirmation dialog.

        Call blocks until the user closes the dialog by selecting either "Yes" or "No" ("Confirm", "Cancel", depending on implementation).

        Parameters:
        widget - Widget, used to create and position the dialog
        question - Message to display on dialog
        Returns:
        true if user selected "Yes" ("Confirm")
      • showSelectionDialog

        public static java.lang.String showSelectionDialog​(Widget widget,
                                                           java.lang.String title,
                                                           java.util.List<java.lang.String> options)
        Show dialog for selecting one item from a list.

        Call blocks until the user closes the dialog by either selecting an item and pressing "OK", or by pressing "Cancel".

        Parameters:
        widget - Widget, used to create and position the dialog
        title - Dialog title
        options - Options to show in dialog
        Returns:
        Selected item or null
      • showPasswordDialog

        public static java.lang.String showPasswordDialog​(Widget widget,
                                                          java.lang.String title,
                                                          java.lang.String correct_password)
        Show dialog for entering a password.

        Call blocks until the user closes the dialog by either entering a password and pressing "OK", or by pressing "Cancel".

        When a correct_password is provided to the call, the password entered by the user is checked against it, prompting until the user enters the correct one.

        When no correct_password is provided to the call, any password entered by the user is returned. The calling script would then check the password and maybe open the dialog again.

        Parameters:
        widget - Widget, used to create and position the dialog
        title - Dialog title
        correct_password - Password to check
        Returns:
        Entered password or null
      • showSaveAsDialog

        public static java.lang.String showSaveAsDialog​(Widget widget,
                                                        java.lang.String initial_value)
        Show file "Save As" dialog for selecting/entering a new file name

        Call blocks until the user closes the dialog by either either entering/selecting a file name, or pressing "Cancel".

        Parameters:
        widget - Widget, used to create and position the dialog
        initial_value - Initial path and file name
        Returns:
        Path and file name or null
      • playAudio

        public static java.util.concurrent.Future<java.lang.Boolean> playAudio​(Widget widget,
                                                                               java.lang.String audio_file)
        Play audio

        Audio file can be a file in the same directory as the display, a workspace path if running under RCP, an absolute file system path, or a http URL.

        Result can be used to await end of playback via `get()`, to poll via 'isDone()', or to `cancel(true)` the playback. Caller should keep a reference to the future until and of playback, because otherwise garbage collection can end the playback.

        Parameters:
        widget - Widget, used to coordinate with toolkit
        audio_file - Audio file
        Returns:
        Handle for controlling the playback
      • getPrimaryPV

        public static RuntimePV getPrimaryPV​(Widget widget)
        Get primary PV of given widget.

        This is the PV that a Text Update widget displays, or the one that a Text Entry widget writes.

        Some widgets have no primary PV (Label, Rectangle, ActionButton), or more then one PV (XY Plot).

        Parameters:
        widget - Widget to get PV of.
        Returns:
        Primary PV of widget; otherwise, if not found, null.
      • getPVs

        public static java.util.Collection<RuntimePV> getPVs​(Widget widget)
        Get all PVs of a widget.

        This includes the primary PV of a widget as well as PVs from scripts and rules assigned to the widget.

        Parameters:
        widget - Widget of which to get PVs
        Returns:
        List of PVs.
      • getPVByName

        public static RuntimePV getPVByName​(Widget widget,
                                            java.lang.String name)
        Get widget's PV by name

        Locates widget's PV by name, including the primary PV as well as PVs from scripts and rules.

        Parameters:
        widget - Widget to get PV from
        name - Name of PV to get
        Returns:
        PV of given widget with given name; otherwise, if not found, null
      • getWidgetValueByName

        public static org.epics.vtype.VType getWidgetValueByName​(Widget widget,
                                                                 java.lang.String name)
                                                          throws java.lang.Exception
        Locate a widget by name, then fetch its value

        Value is the content of the "value" property. If there is no such property, the primary PV of the widget is read.

        Parameters:
        widget - Widget used to locate the widget model
        name - Name of widget to find
        Returns:
        Value of the widget
        Throws:
        java.lang.Exception - on error
      • workspacePathToSysPath

        @Deprecated
        public static java.lang.String workspacePathToSysPath​(java.lang.String workspace_path)
        Deprecated.
        There is no more "workspace", so no need to get local path
        Parameters:
        workspace_path - Path within workspace
        Returns:
        Location in local file system or null
      • getResourceReader

        public static java.io.BufferedReader getResourceReader​(Widget widget,
                                                               java.lang.String resource_name)
                                                        throws java.lang.Exception
        Read a file
        Parameters:
        widget - Widget used to resolve resource that's relative to a display file
        resource_name - Name of resource
        Returns:
        BufferedReader. Keep calling readLine() until it returns null.
        Throws:
        java.lang.Exception - on error
      • readXMLFile

        public static org.w3c.dom.Element readXMLFile​(Widget widget,
                                                      java.lang.String resource_name)
                                               throws java.lang.Exception
        Read XML file
        Parameters:
        widget - Widget used to resolve resource that's relative to a display file
        resource_name - Name of resource
        Returns:
        Root element of the XML document
        Throws:
        java.lang.Exception - on error
      • readTextFile

        public static java.util.List<java.lang.String> readTextFile​(Widget widget,
                                                                    java.lang.String resource_name)
                                                             throws java.lang.Exception
        Read Text file as list of strings
        Parameters:
        widget - Widget used to resolve resource that's relative to a display file
        resource_name - Name of resource
        Returns:
        List with all the lines in the file. null (jython None) for empty lines.
        Throws:
        java.lang.Exception - on error
      • openFile

        public static void openFile​(Widget widget,
                                    java.lang.String resource_name)
                             throws java.lang.Exception
        Open a file in the default tool.
        Parameters:
        widget - Widget used to resolve resource that's relative to a display file
        resource_name - Name of resource
        Throws:
        java.lang.Exception - on error
      • openWeb

        public static void openWeb​(Widget widget,
                                   java.lang.String url)
                            throws java.lang.Exception
        Open a web link in the default tool.
        Parameters:
        widget - Widget used to obtain toolkit
        url - Web address
        Throws:
        java.lang.Exception - on error launching the web browser. Once the web browser has been launched, it might run into follow-up errors when opening the web link, but such errors would then be displayed in the web browser.