Package ca.cgjennings.apps.arkham.plugins

Class DefaultScriptedPlugin

    • Constructor Detail

      • DefaultScriptedPlugin

        public DefaultScriptedPlugin​(java.lang.String scriptId)
        Creates a new scripted plug-in for the script identified by scriptId, which is a script identifier in the format specified for plug-in root files, namely a resource path for script file, optionally starting with the prefix script:. (The script file name presented to the script monkey and script debugger will never have this prefix.)
        Parameters:
        scriptId - the script resource identifier

    • Method Detail

      • initializePlugin

        public boolean initializePlugin​(PluginContext context)
        Scripted Plug-in Notes: The script will be evaluated (so any code with global scope will be run). Then, if the script defines an initialize() function, it will be called, and if it returns false, then this method will return false. Otherwise, the plug-in's name, description, type, and version will be obtained and cached by calling the functions getName(), getDescription(), getPluginType(), and getVersion(), respectively.

        This method will be called once for each registered plug-in before any other methods are called. It allows the plug-in to perform any required initialization prior to the plug-in being shown. If initialization succeeds, it should return true. Otherwise, the plug-in will not be made available to the user. If this method returns false, a warning is logged but no other action is taken. This allows the plug-in the opportunity to display its own error message. If this method throws an exception, a dialog is displayed that will include the message text of the exception (if any).

        Sometimes a plug-in is instantiated only in order to determine its name, description, version, and type. In such cases, the plug-in's initializePlugin method is still called, so that a localized plug-in can provide a name and description in the appropriate language. Plug-ins that do not wish to perform a complete initialization in such cases can detect when the plug-in is being created for information purposes only by calling the PluginContext.isInformationProbe() method of the provided context.

        Note: This method will never be called more than once for a given instance of a plug-in class. However, multiple instances of the same plug-in class are often created. Therefore, you should not assume that this method will only be called once per session (unless it is an EXTENSION).

        Specified by:
        initializePlugin in interface Plugin
        Parameters:
        context - a PluginContext instance that can be accessed during initialization
        Returns:
        true if the plug-in was initialized; false if initialization failed

      • unloadPlugin

        public void unloadPlugin()
        Scripted Plug-in Notes: Calls the script's unload() function, if any.

        This method is called when the plug-in is about to be unloaded to give the plug-in the chance to release any resources it may be holding. It will be called prior to ending the application, or whenever the plug-in will be stopped and restarted.

        Notes:

        1. It is not guaranteed that this method will be called if the program terminates abnormally.
        2. This method will never be called more than once for a given instance of a plug-in. (More than one instance of an ACTIVATED or INJECTED plug-in may be created during a session.)
        3. For ACTIVATED plug-ins that are currently showing, Plugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean) will be called with false (in order to hide the plug-in) before this method is called.
        Specified by:
        unloadPlugin in interface Plugin

      • getPluginName

        public java.lang.String getPluginName()
        Scripted Plug-in Notes: Returns the previously cached plug-in name (see initializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)).

        Returns the name that should be shown to the user for this plug-in, ideally in the UI locale. This should be a short name that describes the plug-in's purpose in three words or less. If this is an ACTIVATED plug-in, the returned value should ideally be a verb phrase that describes the effect of activating the plug-in, such as "Select All Lines". It should not include extraneous information, such as the author's name; this kind of information can be included in the description string or, ideally, in the plug-in's catalogue description.

        Specified by:
        getPluginName in interface Plugin
        Returns:
        a string that identifies this plug-in for end users

      • getPluginDescription

        public java.lang.String getPluginDescription()
        Scripted Plug-in Notes: Returns the previously cached plug-in description (see initializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)).

        Returns a description that can be shown to the user for this plug-in. The returned string will be used to describe the purpose of the plug-in to the user. This should be a single short sentence without any terminating punctuation, such as "Selects all lines on the current deck page".

        Specified by:
        getPluginDescription in interface Plugin
        Returns:
        a string that describes the purpose of this plug-in for end users

      • getPluginVersion

        public float getPluginVersion()
        Scripted Plug-in Notes: Returns the previously cached plug-in version (see initializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)).

        Returns a number representing the version or release number of the plug-in. This is primarily for the user's information; the application only compares versions using the date of the CatalogID.

        Specified by:
        getPluginVersion in interface Plugin
        Returns:
        a number that corresponds to the plug-in's internal version number

      • showPlugin

        public void showPlugin​(PluginContext context,
                       boolean show)
        Scripted Plug-in Notes: If called with show == true, calls the script's run() function, if any. If called with show == false, calls the script's hide() function, if any.

        Show (activate) or hide (deactivate) the plug-in. This method is most often called when the user activates the plug-in's menu item.

        Typically, the value of show will be the opposite of the value currently returned by Plugin.isPluginShowing(). If the plug-in uses a modeless dialog box, then isPluginShowing should thus return true when the dialog is showing.

        If a modal dialog is shown, or if an operation that blocks the calling thread is performed, then it will not be possible for the user to activate the command again until this method returns. In that case, isPluginShowing can be implemented to simply return false.

        Notes: This method is never called for EXTENSION plug-ins. It is only called once, after initialization, for INJECTED plug-ins.

        Specified by:
        showPlugin in interface Plugin
        Parameters:
        context - a valid PluginContext
        show - if true show/start the plug-in, otherwise, hide/cancel it
        See Also:
        Plugin.isPluginShowing()

      • isPluginShowing

        public boolean isPluginShowing()
        Scripted Plug-in Notes: Returns the value of calling the script's isShowing() function, if any. Otherwise, returns false.

        Returns true if this plug-in's interface is currently showing, or, if it has no interface, if it is currently running.

        If the plug-in blocks the event thread when shown (for example, if it displays a modal dialog), then this method can simply return false. Notes: This method is only called for ACTIVATED plug-ins.

        Specified by:
        isPluginShowing in interface Plugin
        Returns:
        true to indicate that the plug-in is "active"

      • getPluginType

        public int getPluginType()
        Scripted Plug-in Notes: Returns the previously cached plug-in type (see initializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)).

        Returns the type identifier of the plug-in. This must be one of ACTIVATED, INJECTED, or EXTENSION.

        Specified by:
        getPluginType in interface Plugin
        Returns:
        a plug-in type that describes how the plug-in should be integrated with Strange Eons

      • getScriptFile

        public java.lang.String getScriptFile()
        Returns the script resource identifier for the script that is providing plug-in functionality.
        Specified by:
        getScriptFile in interface ScriptedPlugin
        Returns:
        the script file for this plug-in's script

      • call

        public java.lang.Object call​(java.lang.String name,
                             java.lang.Object[] args)
        This method is provided as a convenience for other scripts that wish to call a function defined in this plug-in.
        Parameters:
        name - the name of the function to call
        args - an array of arguments to pass to the function
        Returns:
        the return value returned by the function, or null

      • getPluginIcon

        public ThemedIcon getPluginIcon()
        Returns an icon that may be used to represent the plug-in on a menu or toolbar. Strange Eons may derive different sizes from this icon to fit the context where it is being displayed.

        Scripted Plug-in Notes: The default implementation will query the script, and if it gets no result, will look for an image file with the same name (and in the same folder) as the plug-in script. If no image file is found with one of these names, or if the image file cannot be read, a default icon is returned.

        Specified by:
        getPluginIcon in interface Plugin
        Returns:
        an icon that can be used to represent this plug-in

      • isPluginUsable

        public boolean isPluginUsable()

        Scripted Plug-in Notes: The default implementation returns the result of calling the script's isUsable() function, if any, and otherwise returns true.

        Returns true if it is currently valid to activate this plug-in by calling Plugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean). For example, a plug-in that only works on components from a certain game might return false if the currently edited component is not from that game.

        Note: Plug-ins must still check for any conditions that are required to hold in Plugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean). The plug-in may be activated without checking this method, or the state may change between the time that this method is called and the time the plug-in is activated.

        Scripted Plug-in Notes: The default implementation returns true.

        Specified by:
        isPluginUsable in interface Plugin
        Returns:
        true if the plug-in can be successfully and meaningfully activated

      • getDefaultAcceleratorKey

        public java.lang.String getDefaultAcceleratorKey()

        Scripted Plug-in Notes: The default implementation returns the result of calling the script's getDefaultAcceleratorKey() function, if any, and otherwise returns null.

        Return a string that describes the key stroke that is the preferred default accelerator key for this plug-in. In most cases, you should return null for no default accelerator. The user can always assign an accelerator key of their choice to an ACTIVATED plug-in through the plug-in manager dialog.

        The format of the string is similar to that used by javax.swing.KeyStroke, but the special modifier menu may be used to describe the standard menu accelerator modifier on this platform (Ctrl, Command, etc.). An invalid descriptor is silently ignored. There is no guarantee that the requested accelerator will actually be assigned. (For example, it might already be in use by another command.)

        Note: An accelerator key is only meaningful for ACTIVATED plug-ins.

        Specified by:
        getDefaultAcceleratorKey in interface Plugin
        Returns:
        a description of the preferred default accelerator