Class DefaultScriptedPlugin
- java.lang.Object
-
- ca.cgjennings.apps.arkham.plugins.DefaultScriptedPlugin
-
- All Implemented Interfaces:
Plugin
,ScriptedPlugin
public class DefaultScriptedPlugin extends java.lang.Object implements Plugin, ScriptedPlugin
The standard implementation ofScriptedPlugin
that executes JavaScript-based plug-ins.- Since:
- 2.1
- Author:
- Chris Jennings
-
-
Constructor Summary
Constructors Constructor Description DefaultScriptedPlugin(java.lang.String scriptId)
Creates a new scripted plug-in for the script identified byscriptId
, 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:.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description 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.java.lang.String
getDefaultAcceleratorKey()
Scripted Plug-in Notes: The default implementation returns the result of calling the script'sgetDefaultAcceleratorKey()
function, if any, and otherwise returnsnull
.java.lang.String
getPluginDescription()
Scripted Plug-in Notes: Returns the previously cached plug-in description (seeinitializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)
).ThemedIcon
getPluginIcon()
Returns an icon that may be used to represent the plug-in on a menu or toolbar.java.lang.String
getPluginName()
Scripted Plug-in Notes: Returns the previously cached plug-in name (seeinitializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)
).int
getPluginType()
Scripted Plug-in Notes: Returns the previously cached plug-in type (seeinitializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)
).float
getPluginVersion()
Scripted Plug-in Notes: Returns the previously cached plug-in version (seeinitializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)
).java.lang.String
getScriptFile()
Returns the script resource identifier for the script that is providing plug-in functionality.ScriptMonkey
getScriptMonkey()
Returns theScriptMonkey
used to manage the execution of the plug-in's script code.boolean
initializePlugin(PluginContext context)
Scripted Plug-in Notes: The script will be evaluated (so any code with global scope will be run).boolean
isPluginShowing()
Scripted Plug-in Notes: Returns the value of calling the script'sisShowing()
function, if any.boolean
isPluginUsable()
Scripted Plug-in Notes: The default implementation returns the result of calling the script'sisUsable()
function, if any, and otherwise returnstrue
.void
showPlugin(PluginContext context, boolean show)
Scripted Plug-in Notes: If called withshow == true
, calls the script'srun()
function, if any.void
unloadPlugin()
Scripted Plug-in Notes: Calls the script'sunload()
function, if any.-
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
-
Methods inherited from interface ca.cgjennings.apps.arkham.plugins.Plugin
getRepresentativeImage
-
-
-
-
Constructor Detail
-
DefaultScriptedPlugin
public DefaultScriptedPlugin(java.lang.String scriptId)
Creates a new scripted plug-in for the script identified byscriptId
, 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 aninitialize()
function, it will be called, and if it returnsfalse
, then this method will returnfalse
. Otherwise, the plug-in's name, description, type, and version will be obtained and cached by calling the functionsgetName()
,getDescription()
,getPluginType()
, andgetVersion()
, 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 returnsfalse
, 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 thePluginContext.isInformationProbe()
method of the providedcontext
.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 interfacePlugin
- Parameters:
context
- aPluginContext
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'sunload()
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:
- It is not guaranteed that this method will be called if the program terminates abnormally.
- This method will never be called more than once for a given
instance of a plug-in. (More than one instance of an
ACTIVATED
orINJECTED
plug-in may be created during a session.) - For
ACTIVATED
plug-ins that are currently showing,Plugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean)
will be called withfalse
(in order to hide the plug-in) before this method is called.
- Specified by:
unloadPlugin
in interfacePlugin
-
getPluginName
public java.lang.String getPluginName()
Scripted Plug-in Notes: Returns the previously cached plug-in name (seeinitializePlugin(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 interfacePlugin
- 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 (seeinitializePlugin(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 interfacePlugin
- 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 (seeinitializePlugin(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 interfacePlugin
- 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 withshow == true
, calls the script'srun()
function, if any. If called withshow == false
, calls the script'shide()
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 byPlugin.isPluginShowing()
. If the plug-in uses a modeless dialog box, thenisPluginShowing
should thus returntrue
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 returnfalse
.Notes: This method is never called for
EXTENSION
plug-ins. It is only called once, after initialization, forINJECTED
plug-ins.- Specified by:
showPlugin
in interfacePlugin
- Parameters:
context
- a validPluginContext
show
- iftrue
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'sisShowing()
function, if any. Otherwise, returnsfalse
.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 interfacePlugin
- 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 (seeinitializePlugin(ca.cgjennings.apps.arkham.plugins.PluginContext)
).Returns the type identifier of the plug-in. This must be one of
ACTIVATED
,INJECTED
, orEXTENSION
.- Specified by:
getPluginType
in interfacePlugin
- 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 interfaceScriptedPlugin
- Returns:
- the script file for this plug-in's script
-
getScriptMonkey
public ScriptMonkey getScriptMonkey()
Returns theScriptMonkey
used to manage the execution of the plug-in's script code.- Specified by:
getScriptMonkey
in interfaceScriptedPlugin
- Returns:
- the monkey bound to the plug-in 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 callargs
- 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 interfacePlugin
- 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 returnstrue
.Returns
true
if it is currently valid to activate this plug-in by callingPlugin.showPlugin(ca.cgjennings.apps.arkham.plugins.PluginContext, boolean)
. For example, a plug-in that only works on components from a certain game might returnfalse
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 interfacePlugin
- 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 returnsnull
.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 anACTIVATED
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 interfacePlugin
- Returns:
- a description of the preferred default accelerator
-
-