Package ca.cgjennings.apps.arkham.plugins

Interface Plugin

  • All Known Implementing Classes:
    AbstractPlugin, DefaultScriptedPlugin, QuickscriptPlugin
    public interface Plugin
    An interface that allows third-party code (plug-ins) to be integrated into Strange Eons at run time. To be valid, a plug-in class must:
    1. be a valid Java class in the classpath
    2. have an accessible no-argument constructor
    3. implement the Plugin interface

    Alternatively, the plug-in can be implemented by script code, with a DefaultScriptedPlugin acting as the plug-in class and forwarding plug-in method calls to the script.

    Since:
    2.0
    Author:
    Chris Jennings

    • Field Detail

      • ACTIVATED

        static final int ACTIVATED
        A plug-in type value. An activated plug-in adds a new command to the application. The command will be made accessible to the user by adding a menu item to the Toolbox menu with the following characteristics:
        • The menu item's label text will be the value of getPluginName().
        • The menu item's tool tip text will be the value of getPluginDescription().
        • If the plug-in has a representative image (and the user enables this feature), then that image will be used to create an icon for the menu item.
        • If isPluginUsable() returns true, the item will be enabled; otherwise disabled.
        • If the plug-in is showing, then the item will have a check mark, otherwise it will not.
        • If the menu item is selected by the user, then the plug-in will either be shown or hidden depending on whether it is currently shown. That is, code similar to the following will be executed:
          showPlugin( pluginContext, !isPluginShowing() )
        See Also:
        Constant Field Values

      • INJECTED

        static final int INJECTED
        A plug-in type value. An INJECTED plug-in fills a role between the ACTIVATED and EXTENSION types. Like an ACTIVATED plug-in, it is loaded and unloaded on demand. However, like an EXTENSION plug-in, there is no explicit predetermined means to activate the effect (i.e., there is no Toolbox menu item). Either the plug-in adds its own explicit activation method(s), or the plug-in is activated passively.

        This type of plug-in is typically used in the following cases:

        • Modifications are being made that are reversible (and do not require the game database to be unlocked).
        • New commands or other features are being added, but they will be accessed by means other than the Toolbox menu. (A common example being new commands for the project system.)

        When loaded, the showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean) method will be called once with show == true, at which time it should install its modifications. These should continue to take effect until unloadPlugin() is called, at which time the modifications should be removed.

        See Also:
        Constant Field Values

      • EXTENSION

        static final int EXTENSION
        A plug-in type value. Extension plug-ins are started exactly once, during application startup and before the game database is locked. Because of this, an extension is allowed to extend the database by, for example, adding new games or component types.

        Extensions are never "shown" (via showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean)); they should do all of their work when initializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext) is called. An extension's unloadPlugin() method will be called at shutdown (unless the program terminates abnormally). This allows the extension to release any system resources that it may be holding or perform other cleanup; unlike an INJECTED plug-in, it is not expected to reverse the changes that it makes.

        To load successfully, an extension plug-in must both identify itself by the EXTENSION type and be packaged in a bundle with the .seext file name extension.

        See Also:
        Constant Field Values

    • Method Detail

      • initializePlugin

        boolean initializePlugin​(PluginContext context)
        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).

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

      • unloadPlugin

        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. 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, 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.

      • getPluginName

        java.lang.String getPluginName()
        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.
        Returns:
        a string that identifies this plug-in for end users

      • getPluginDescription

        java.lang.String getPluginDescription()
        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".
        Returns:
        a string that describes the purpose of this plug-in for end users

      • getPluginVersion

        float getPluginVersion()
        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.
        Returns:
        a number that corresponds to the plug-in's internal version number

      • getPluginType

        int getPluginType()
        Returns the type identifier of the plug-in. This must be one of ACTIVATED, INJECTED, or EXTENSION.
        Returns:
        a plug-in type that describes how the plug-in should be integrated with Strange Eons

      • showPlugin

        void showPlugin​(PluginContext context,
                boolean show)
        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 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.

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

      • isPluginShowing

        boolean isPluginShowing()
        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.

        Returns:
        true to indicate that the plug-in is "active"

      • isPluginUsable

        boolean isPluginUsable()
        Returns true if it is currently valid to activate this plug-in by calling 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 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.

        Returns:
        true if the plug-in can be successfully and meaningfully activated

      • getRepresentativeImage

        @Deprecated
default java.awt.image.BufferedImage getRepresentativeImage()
        Deprecated.
        Prefer getPluginIcon().
        Returns an image that may be used to represent the plug-in.
        Returns:
        an image that can be used as a menu item icon

      • getPluginIcon

        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.
        Returns:
        an icon that can be used to represent this plug-in

      • getDefaultAcceleratorKey

        java.lang.String getDefaultAcceleratorKey()
        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.

        Returns:
        a description of the preferred default accelerator