Package ca.cgjennings.apps.arkham.plugins

Class AbstractPlugin

    • Constructor Summary

      Constructors 
      Constructor Description
      AbstractPlugin()  

    • 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.
      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.
      protected java.lang.String getPluginIconBaseName()
      Returns a base class path to use to locate the default icon, including a base file name but no extension.
      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.
      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 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

      • AbstractPlugin

        public AbstractPlugin()

    • Method Detail

      • initializePlugin

        public 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).

        The abstract implementation returns true.

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

        The abstract implementation does nothing.

        Specified by:
        unloadPlugin in interface Plugin

      • getPluginName

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

        The abstract implementation returns the name of the class, with spaces inserted between character pairs whenever a lower case letter is followed by an upper case letter. For example: 

         MyNiftyThing -> My Nifty Thing
        Specified by:
        getPluginName in interface Plugin
        Returns:
        a string that identifies this plug-in for end users

      • getPluginDescription

        public 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".

        The abstract implementation returns null.

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

      • getPluginVersion

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

        The abstract implementation returns 1.

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

      • getPluginType

        public int getPluginType()
        Returns the type identifier of the plug-in. This must be one of ACTIVATED, INJECTED, or EXTENSION.

        The abstract implementation returns Plugin.ACTIVATED.

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

      • showPlugin

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

        The abstract implementation does nothing.

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

        The abstract implementation returns false.

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

      • isPluginUsable

        public 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). 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.

        The abstract implementation returns true.

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

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

        The abstract base class looks for an image in the same package and with the same base file name as the class file.

        Specified by:
        getPluginIcon in interface Plugin
        Returns:
        an icon representing the plugin

      • getPluginIconBaseName

        protected java.lang.String getPluginIconBaseName()
        Returns a base class path to use to locate the default icon, including a base file name but no extension.
        Returns:
        package path to the class or script to use to locate an icon

      • getDefaultAcceleratorKey

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

        The abstract implementation returns null.

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