Package ca.cgjennings.apps.arkham.plugins

Class QuickscriptPlugin

  • All Implemented Interfaces:
    Plugin
    public final class QuickscriptPlugin
extends java.lang.Object
implements Plugin
    A plug-in that allows editing and running small scripts from within Strange Eons without the need to create a project or script file. This can be used to test small snippets of code, hack game components, or to experiment with the language or APIs.
    Since:
    2.0
    Author:
    Chris Jennings

    • Constructor Summary

      Constructors 
      Constructor Description
      QuickscriptPlugin()
      Creates a new instance of the plug-in.

    • Method Summary

      All Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.lang.String getDefaultAcceleratorKey()
      Return a string that describes the key stroke that is the preferred default accelerator key for this plug-in.
      CodeEditorBase getEditor()
      Returns the editor component used to edit script files.
      java.lang.String getPluginDescription()
      Returns a description that can be shown to the user for this plug-in.
      ThemedIcon getPluginIcon()
      Returns an icon that may be used to represent the plug-in on a menu or toolbar.
      java.lang.String getPluginName()
      Returns the name that should be shown to the user for this plug-in, ideally in the UI locale.
      int getPluginType()
      Returns the type identifier of the plug-in.
      float getPluginVersion()
      Returns a number representing the version or release number of the plug-in.
      java.awt.Window getWindow()
      Returns the window that is used to display the script editor when the plug-in is activated.
      boolean initializePlugin​(PluginContext context)
      This method will be called once for each registered plug-in before any other methods are called.
      boolean isPluginShowing()
      Returns true if this plug-in's interface is currently showing, or, if it has no interface, if it is currently running.
      boolean isPluginUsable()
      Returns true if it is currently valid to activate this plug-in by calling Plugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean).
      void run​(boolean debugIfAvailable)
      Run the current script.
      void showPlugin​(PluginContext context, boolean show)
      Show (activate) or hide (deactivate) the plug-in.
      void unloadPlugin()
      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.

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • QuickscriptPlugin

        public QuickscriptPlugin()
        Creates a new instance of the plug-in. This is called by the application when the plug-in is being started.

    • Method Detail

      • getWindow

        public java.awt.Window getWindow()
        Returns the window that is used to display the script editor when the plug-in is activated.
        Returns:
        the window displayed by the plug-in

      • getEditor

        public CodeEditorBase getEditor()
        Returns the editor component used to edit script files. This can be used to add custom commands or modify the edited script.
        Returns:
        the source code editor
        Since:
        3.0

      • run

        public void run​(boolean debugIfAvailable)
        Run the current script.
        Parameters:
        debugIfAvailable - if the debugger is enabled, debug the script by activating a breakpoint when the script starts running
        Since:
        2.00.9

      • initializePlugin

        public boolean initializePlugin​(PluginContext context)
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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)
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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

      • getPluginIcon

        public ThemedIcon getPluginIcon()
        Description copied from interface: Plugin
        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.
        Specified by:
        getPluginIcon in interface Plugin
        Returns:
        an icon that can be used to represent this plug-in

      • isPluginUsable

        public boolean isPluginUsable()
        Description copied from interface: Plugin
        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()
        Description copied from interface: Plugin
        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