ca.cgjennings.apps.arkham.plugins
Interface PluginContext

public interface PluginContext

A plug-in context is passed to a plug-in when it is initialized, shown, or hidden. It allows access to functionality and data from the Strange Eons application that may be of use to the plug-in.

SHIFT

static final int SHIFT

A modifier constant indicating that a Shift key was held down.

See Also:

Constant Field Values

ALT

static final int ALT

A modifier constant indicating that an Alt key was held down.

See Also:

Constant Field Values

CONTROL

static final int CONTROL

A modifier constant indicating that a Control or Ctrl key was held down.

See Also:

Constant Field Values

CTRL

static final int CTRL

A modifier constant indicating that a Control or Ctrl key was held down.

See Also:

Constant Field Values

META

static final int META

A modifier constant indicating that a Meta key was held down.

See Also:

Constant Field Values

COMMAND

static final int COMMAND

A modifier constant indicating that the Command key (on Apple computers) was held down.

See Also:

Constant Field Values

MENU

static final int MENU

A modifier constant indicating that the key used as a menu accelerator key on this platform was held down. (For example, it maps to Ctrl on Windows computers and Command on Apple computers.)

getMajorVersion

int getMajorVersion()

Returns the major version number of Strange Eons. The major and minor version number identify the version of Strange Eons that the plug-in is running within in a way that makes it simple to check whether a plug-in is compatible with the program.

For example, if the version diplayed in the About dialog is "1.80 beta 6", the value returned by getMajorVersion will be 1 and the value returned by getMinorVersion will be 80.

Returns:

the major version number

getMinorVersion

int getMinorVersion()

Returns the minor version number of Strange Eons. See getMajorVersion() for additional details.

Returns:

the minor version number

getVersion

java.lang.String getVersion()

Returns the full version description text for the version of Strange Eons the plug-in is running within. This will be exactly the same as the string printed when the program launches and the version displayed in the About dialog box.

Returns:

the complete version description for the program

Since:

2.00

getMicroversion

java.lang.String getMicroversion()

Returns the microversion of the build of Strange Eons that the plug-in is running within. The microversion is the most accurate revision information available. Two different builds of the program will typically have different microversions even if they have the same official version number.

Returns:

the microversion string, or a placeholder

Since:

2.00

compareMicroversions

int compareMicroversions(java.lang.String lhs,
                         java.lang.String rhs)

Compares two microversions strings. If the lhs version is newer than the rhs version, returns -1. If the lhs version is older, returns 1. If the versions are the same, returns 0.

Parameters:

lhs - the "left-hand" microversion string to compare

rhs - the "right-hand" microversion string to compare

Returns:

a value whose sign indicates which microversion is newer

Since:

2.00.1

getParentFrame

java.awt.Frame getParentFrame()

Returns a Frame that can be used as the parent window for dialog boxes. Typically this will be the main application window. The method might return null, but null is a valid value when specifying a dialog's parent frame.

Returns:

the appropriate parent frame for dialog boxes

getUILocale

java.util.Locale getUILocale()

Returns the preferred locale for user interface (UI) components. If possible, the plug-in's user interface should be localized for this locale.

Returns:

the locale to use for UI localization

getGameLocale

java.util.Locale getGameLocale()

Returns the preferred locale for game text (printed on cards). If possible, material that appears on game components should be localized for this locale.

Returns:

the locale to use for game component localization

getUIPluralizer

IntegerPluralizer getUIPluralizer()

Returns a pluralizer for the user interface (UI) locale.

Returns:

a pluralizer that can generate correct plurals for the UI language, or a default pluralizer

getGamePluralizer

IntegerPluralizer getGamePluralizer()

Returns a pluralizer for the game locale.

Returns:

a pluralizer that can generate correct plurals for the game language, or a default pluralizer

getActiveEditor

StrangeEonsEditor getActiveEditor()

Returns the game component editor that the user has currently activated. If no editor is active, this method returns null. In most cases, plug-ins will actually want to interact with the component rather than the component's editor window, and so should call getActiveComponent() instead.

Returns:

the currently active game component editor, or null

getApplication

StrangeEonsApplication getApplication()

Returns a reference to the StrangeEonsApplication that this plug-in is running within.

Since:

2.00

getActiveComponent

GameObject getActiveComponent()

Get the game component that is edited by the currently active component editor. The object returned is a wrapper around the actual component. It implements the GameObject interface, which can be used to query and modify the actual component.

To work directly with the component instead of through this adapter, use getActiveEditor().getGameComponent(). Alternatively, you may call the GameObject#unwrap() method of the adapter.

Returns:

the currently edited game component, or null if no editor is active

getModifiers

int getModifiers()

Returns the modifier keys held down when the plug-in was activated. If this context was not created in response to an activation of the plug-in, this method returns 0. If a key was held down, the bitwise-and of the key's modifier constants with the value returned by this method will be non-zero.

Returns:

a bitwise-or of the modifier constants

Since:

2.00

createEditor

StrangeEonsEditor createEditor(java.lang.String classMapKey)

Create a new editor for a game component and open it in Strange Eons. The type of editor is determined by the classMapKey, which must be one of the class keys defined in resources/editors/classmap.txt. As a convenience, keys that begin with "app-new-" may leave off this prefix.

Once the editor is created and added, it becomes the active editor. (However, if the plug-in is modeless, the user may activate a different editor at any time.)

Parameters:

classMapKey - the key for the type of editor to create

Throws:

java.lang.IllegalArgumentException - if the key is not valid

Since:

2.00

getPluginSetting

java.lang.String getPluginSetting(java.lang.String settingKey,
                                  java.lang.String defaultValue)

Return the value of one of this plug-in's private settings. Strange Eons allows each plug-in to create a set of private settings that can persist across program runs. This allows plug-ins to store user preferences or other relevant settings.

Parameters:

settingKey - the key name to look up a value for

defaultValue - the default value to use if the key is not defined

Returns:

the last set value of the setting, or the default vlaue if none is set

setPluginSetting

void setPluginSetting(java.lang.String settingKey,
                      java.lang.String settingValue)

Set the value of one of this plug-in's private settings. If the value of settingValue is null, then the key will be deleted if it exists.

Parameters:

settingKey - the key name to set the value of

settingValue - the value to assign to the key, or null to delete the key

getSettings

Settings getSettings()

Returns a Settings instance that can be used to read and write this plug-in's private settings. Note that this is not related in any way to the private settings of any game conponent. If this context is not associated with a plug-in, a shared default settings space is used instead.

Returns:

a Settings instance that uses this plug-in's private settings space

Since:

2.1 alpha 1

createInterfaceComponent

java.awt.Component createInterfaceComponent(PluginContext.ComponentType type)

Create a Strange Eons user interface component that can be added to the plug-in's user interface. This allows you to, for example, use the same spell-checking features provided in the rest of Strange Eons.

Parameters:

type - the type of component to create

Returns:

a newly instantiated component of the requested type

canInsertMarkup

boolean canInsertMarkup()

Return true if mark-up can be inserted into the current editor. Mark-up can be inserted when the last text component that had input focus was a text component on the active editor. Mark-up is inserted by calling insertMarkup(String).

Returns:

true if mark-up

insertMarkup

void insertMarkup(java.lang.String markup)

Insert mark-up text into the edit control of the active editor that has input focus. If there is no appropriate target to insert mark-up into, an IllegalStateException will be thrown. Use canInsertMarkup to check whether there is currently an appropriate target.

Parameters:

markup - the mark-up text to be inserted

Throws:

java.lang.IllegalStateException - if mark-up text cannot be inserted

insertMarkupTags

void insertMarkupTags(java.lang.String prefix,
                      java.lang.String suffix)

Surround the currently selected text in the active edit control of the active editor with mark-up. The current selection will have prefix inserted before it and suffix inserted after it, and the selection will be extended to include the newly inserted text. If the selection already includes the specified mark-up, then the prefix and suffix will be removed from the string. This is most commonly be used to surround the selection with mark-up tags: for example, calling insertMarkupTags( "<b>", "</b>" ) would insert mark-up that would cause the current selection to be displayed in bold.

Parameters:

prefix - the text to insert before the selection

suffix - the text to insert after the selection

Throws:

java.lang.IllegalStateException - if mark-up text cannot be inserted

Since:

2.00

string

java.lang.String string(java.lang.String key)

This method returns the value of one of Strange Eons's internal user interface strings. Normally, a localized plug-in would provide its own localized strings, typically through a ResourceBundle. However, it might be convenient to re-use Strange Eons's own localized text where it already provides a string that you need. Some common examples might be the "cancel", "cut", "copy", and "paste" keys.

If key is not defined in the Strange Eons interface text resources, this method returns a string equivalent to the value of "MISSING UI STRING: " + key.

Parameters:

key - the resource string key to create localized text for

Returns:

the localized text for key, or an error message string

string

java.lang.String string(java.lang.String key,
                        java.lang.Object... formatParameters)

This method returns a formatted string based on the value of one of Strange Eons's internal user interface strings. The result is effectively the same as calling String.format( uiLocale, string(key), formatParameters ), where uiLocale is a Locale representing the current user interface locale.

Parameters:

key - the resource string key to create a localized format string for

formatParameters - the parameters to substitute into the format string

Returns:

a localized, formatted string, or an error message string

addUIText

void addUIText(java.lang.String baseName)

This method loads a resource bundle and adds its definitions to the application's UI text database. Any keys that are already defined in the application will be ignored. After adding the contents of the bundle, the string(java.lang.String) methods will return the values of any new keys in the bundle, based on the UI locale. The base name is a relative URL within the resources folder, except that the file name should consist of only the base name, without a locale or the ".properties" extension. For example, the following baseName points to the standard UI text resource bundle: text/interface/eons-text.

Parameters:

baseName - the base name of the resource bundle to open

Since:

2.00

addUIText

void addUIText(java.util.Locale locale,
               java.lang.String baseName)

This method loads a resource bundle and adds its definitions to the application's UI text database. The specific bundle that is loaded is determined using Locale. For example, to add definitions appropriate for the current game language, one could use code similar to the following:

 PluginContext.addUIText( PluginContext.getGameLocale(), "custom/text/mybundle" );
 

Any keys that are already defined in the application will be ignored. After adding the contents of the bundle, the string(java.lang.String) methods will return the values of any new keys in the bundle. The base name is a relative URL within the resources folder, except that the file name should consist of only the base name, without a locale or the ".properties" extension. For example, the following baseName points to the standard UI text resource bundle: text/interface/eons-text.

Parameters:

baseName - the base name of the resource bundle to open

Since:

2.00

See Also:

#addUIText(java.lang.String)}

isInformationProbe

boolean isInformationProbe()

Provides a hint about whether the plug-in should perform expensive initialization operations. If this method returns true, then the plug-in is only being initialized to determine its name, version, description, and/or type. This instance of the plug-in will not be shown. The plug-in may use this as a hint that it need only perform enough initialization to provide these services.

Returns:

true if the plug-in will only be queried for information

Since:

2.00a15

breakpoint

void breakpoint()

If the debugger is available, generate a breakpoint at the next opportunity. If the debugger is not available, nothing happens. Note that if you wish to generate a breakpoint from within a script (as opposed to a compiled plug-in), it is more convenient to call the global scope breakpoint() function.

Since:

2.00.9

setNamedObject

void setNamedObject(java.lang.String name,
                    java.lang.Object object)

Sets a named object in the database. A named object provides a way for scripts to share objects with other scripts that may be run at a later time. For example, an extension script could define objects that are later used by one or more component creation scripts.

All access to named objects is threadsafe.

Example:

 // store an object for later use (a function, but it could be anything)
 PluginContext.setNamedObject( "test", function hello() { println( "hello" ); } );
 // later, in another script, call the function we stored
 PluginContext.getNamedObject( "test" )();
 

Parameters:

name - an identifier that can be used to recall the specified object later

object - an arbitrary object that will be associated with name

Throws:

java.lang.IllegalArgumentException - if an object with this name has already been set

getNamedObject

java.lang.Object getNamedObject(java.lang.String name)

Gets a named object in the database. A named object provides a way for scripts to share objects with other scripts that may be run at a later time. For example, an extension script could define objects that are later used by one or more component creation scripts.

All access to named objects is threadsafe.

Parameters:

name - an identifier that can be used to recall the specified object later

Returns:

the object that was most recently associated with name

Throws:

java.lang.IllegalArgumentException - if an object with this name has not been set

isNameDefined

boolean isNameDefined(java.lang.String name)

Returns true if an object has been associated with the given name.

All access to named objects is threadsafe.

Parameters:

name - the identifier to test

Returns:

true if an object has been set for name, and not removed

removeNamedObject

void removeNamedObject(java.lang.String name)

End the association between name and an object. Note that the only way to update an existing object is to first remove it, then set it again. This helps prevent use of the same name by multiple plug-ins.

All access to named objects is threadsafe.

Parameters:

name - the identifier to remove

Throws:

java.lang.IllegalArgumentException - if an object with this name has not been set