common
Standard library of commonly used functions.
Predefined Global Variables
uselibrary( library )
exit()
error( [exception] )
error.handleUncaught( exception ) static
error.missingLibrary( shortName, fileName ) static
prompt( [promptMessage], [initialValue] )
confirm( promptMessage, [title] )
confirm.confirm( promptMessage, [title] ) static
confirm.yesno( promptMessage, [title] ) static
confirm.choose( promptMessage, title, option1, [option2], ... ) static
alert( message, [isErrorMessage] )
sleep( [msDelay] )
Console
Console.print() static
Console.println() static
Console.print() static
Console.printImage( image ) static
Console.printComponent( component ) static
Console.clear() static
Console.history() static
Console.hide() static
Console.queue() static
Console.flush() static
Console.out static read-only
Console.err static read-only
print( obj )
println( obj )
string( key, [args...] )
sprintf( formatString, [args...] )
printf( formatString, [args...] )
subclass( constructor, superConstructor )
usesettings( source )
Patch
Patch.apply( [key1, value1], [key2, value2], ... ) static
Patch.restore( [key1], [key2], ... ) static
Patch.temporary( [key1, value1], [key2, value2], ... ) static
Patch.card( component, [key1, value1], [key2, value2], ... ) static
Patch.cardFrom( component, resource ) static
Patch.cardRestore( component, key1, [key2], ... ) static
breakpoint()
| Eons | a reference to the main application window |
| Editor | a reference to the active component editor |
| Component | a reference to the component currently edited by editor |
| PluginContext | a reference to the PluginContext object |
| sourcefile | the source file of the script being executed |
| ca | convenience for Packages.ca |
| arkham | convenience for Packages.ca.cgjennings.apps.arkham |
| resources | convenience for Packages.resources |
| swing | convenience for the javax.swing package |
| Settings | the class (resources.Settings) used to store setting keys and their values (see the JavaDoc documentation in the plug-in authoring kit) |
| Region | a subclass of java.awt.Rectangle that is easily written to and read from settings |
| Region2D | a subclass of java.awt.Rectangle2D that is easily written to and read from settings |
| Colour | a subclass of java.awt.Color that is easily written to and read from settings |
Import the objects, functions, and variables defined by a library into the
current script. The value of library may either be the simple name
of a built-in library or the URL of a script file. Libraries may safely
be imported multiple times; subsequent calls to uselibrary with
the same library argument will be ignored.
Examples:
uselibrary( "markup" );
uselibrary( "res://myname/myplugin/mylib.js" );
The common library is automatically imported into every script.
| library | the built-in library name or a URL |
Stops executing the script.
Indicates an error condition by throwing an exception.
| exception | a message string or an Error object to throw |
Prints a standard error message to the console to describe an exception.
This function can be called to handle uncaught script errors in script code
that survives the execution of the script that defined it, such as an
interface implementation.
When a script is executed, exceptions that are thrown are caught and displayed
in the console as if the entire script were surrounded by a special
try/catch pair. However, when you implement a Java class
or interface with script code, the function(s) that implement the Java object
"escape" from this try catch. For example, suppose you create an
ActionListener, add it to a JButton, and then add the
button to the application window with Eons.addCustomComponent.
The script ends, but the listener still exists because it is attached to the
button and the still exists. If the listener function throws an exception,
you will not see the error message. To get an error message from this listener,
surround the listener code with a try/catch and call this
function with the thrown exception. For example:
var button = new swing.JButton( "Press Me!" );
button.addActionListener( function listener() {
try {
println( "You pressed me!" );
} catch( ex ) {
error.handleUncaught( ex );
}
});
Eons.addCustomComponent( button );
Note: Although you could use an anonymous function to create this
listener (function(){...}), if you give it a name then that that name
will appear in the stack trace of any error messages.
This function will display a standardized error message to alert the user
when a required SE library has not been installed. It then throws an
exception to end script execution.
| shortName | a short, human-readable description of the library, e.g., Tofu |
| fileName | the library's customary file name, e.g., tofu.selibrary |
Prompts the user for input and returns the result.
This function displays a dialog box with a text field in which the user
may enter text. If the user presses OK, the entered text is returned.
If the user cancels the dialog, null is returned.
| promptMessage | an optional prompt to display |
| initialValue | an optional default value to fill in the text field |
returns the string entered by the user, or null if the dialog
is cancelled
Displays a dialog box containing the promptMessage text along with OK and Cancel
buttons. Returns true if the user selects OK, or false otherwise.
The confirm() function is commonly supported by Web browsers with
JavaScript support. To complement this functionality, two additional
variants are available: confirm.yesno for Yes/No questions,
and confirm.choose to choose from a set of custom options.
These are both described in detail below.
| promptMessage | the prompt text to display |
| title | an optional title for the prompt window |
returns true if user selects OK
This is equivalent to confirm( promptMessage, title ). It is
provided as a parallel to confirm.yesno and
confirm.choose.
Display a dialog box containing the promptMessage text along with OK and Cancel
buttons. Returns true if the user selects OK, or false otherwise.
| promptMessage | the prompt text to display |
| title | an optional title for the prompt window |
returns true if user selects Yes
Display a dialog box with buttons for each of option1, option2,
and so on.
If the user chooses one of the options, the index of the option is returned
(0 for option1, 1 for option2, and so on).
If the user closes the dialog without making a selection, -1
is returned instead.
| promptMessage | the prompt text to display |
| title | a title for the prompt window (may be null) |
| options | a list of one or more options to display |
returns the selected option's index, or -1
Displays a message in a dialog box. The user must press the OK button
to continue. This is not generally a user-friendly act and should only
be used if the user must acknowledge something before being allowed to
continue using the application.
The message dialog is normally formatted as a warning message.
If the isErrorMessage flag is true, it will be
formatted as an error message instead. (Exactly what this means
depends on the platform and selected theme, but typically the
resulting dialog box will feature a different
icon for warnings than for errors.)
| message | the message to display |
| isErrorMessage | an optional flag; if true, an error dialog is displayed |
Pauses script execution for a period of time. Returns true if you interrupt()
the thread from another thread while it is sleeping, otherwise returns false.
| delay | the length of time to pause, in milliseconds (default is 1000) |
The console object allows you to interact with the Script Output
Console window.
Prints an object to the script console. This is identical to the global
print function.
Prints an object to the script console. This is identical to the global
println function.
Prints a formatted string to the script console. This is identical to the global
printf function.
Prints an image or icon (subclass of
java.awt.Image
or
java.awt.Icon)
to Console.out.
| image | an image or icon object to be inserted into the console text |
Prints a user interface component (a subclass of
java.awt.Component)
to Console.out.
| image | an image or icon object to be inserted into the console text |
Clears the script console.
Returns the current text of the script console history
Hides the console window if it is currently visible. Sending output to the
console will cause it to become visible again.
Buffers output to Console.out until a matching call to flush().
This method should be surrounded with a try...finally block
to ensure that the matching call to flush() is always performed.
Immediately flushes pending writes to Console.out. If output is
currently being buffered due to a call to queue(), buffering ends
and the accumulated output is written to the console.
A java.io.PrintWriter that can be used to write to the
console window's output stream.
A java.io.PrintWriter that can be used to write to the
console window's error stream.
Prints an object to the script console. You may pass multiple arguments
to this function; the arguments will be printed in sequence as if they
printed by multiple print statements. This is a convenience for
Console.print.
| obj | an object for which a string representation should be printed |
Prints an object to the script console, followed by a newline.
You may pass multiple arguments
to this function; the arguments will be printed in sequence as if they
printed by multiple print statements then followed by a newline.
This is a convenience for Console.println.
| obj | an object for which a string representation should be printed |
Returns the localized user interface string for a string key.
This is also available through the plug-in context when the active script
is a plug-in. If the key is undefined an error message string is returned
instead.
If the user interface string is a format string, it may be formatted by
passing additional arguments. Note that Number arguments are converted
to java.lang.Doubles; to fill %d format arguments you
must explicitly convert the Number to a Java integer (you can use
n.toInt()).
| key | a key defined in resources/text/interface/eons-text.properties |
| args | a list of zero or more arguments used to format the string |
returns the formatted, localized string resource mapped to by the key
Returns a string formatted using C-style printf syntax.
See Formatter Syntax
for details. Note that Number arguments are converted to java.lang.Double.
| formatString | the string to be formatted using the arguments |
| args | a list of zero or more arguments used to format the string |
returns a formatted string using the specified format string and arguments.
Print a formatted string to the console using C-style printf syntax.
See Formatter Syntax
for details. Note that Number arguments are converted to java.lang.Double.
If you wish to use the %d format, convert the number to java.lang.Integer
using its toInt() function.
| formatString | the string to be formatted using the arguments |
| args | a list of zero or more arguments used to format the string |
Makes objects created with constructor a "subclass" of
the superConstructor by chaining
constructor.prototype to superConstructor.prototype.
Example:
function Super() {
this.x = "super";
}
Super.prototype.getX = function getX() {
return this.x;
}
function Sub() {
Super.call( this );
this.x = "sub";
}
var subobj = new Sub();
println( subobj.getX() );
| constructor | the name of the subclass constructor function |
| superConstructor | the name of the superclass constructor function |
Sets the Settings object that will be used to get and set
settings using the $setting_name syntax. Starting
with Strange Eons 2.00.5, script code may read and write settings
using global variables that start with a dollar sign ($) followed
by the setting name. Setting names that include the hyphen character
should use an underscore instead of a hyphen since hyphens are not
legal in JavaScript identifiers. For example, to print the value of
stamina-text-region, one would write:
println( $stamina_text_region );
Since setting names often contain hyphens (which
are not legal in script variable names), an underscore in the
variable name is converted into a hyphen.
By default, a script that uses this syntax will read and write the
global (shared) settings, except for DIY scripts
which use the private settings of their DIY game component object.
This function allows you to choose a different Settings
object to use. The value of source can either be a
Settings object, which will be used directly, or
else a game component, in which case the private settings of that
component will be used. If source is null or
undefined, then shared settings will be used.
| source | the settings to use for $ script variables |
The Patch object contains static helper methods that modify
(or restore) settings.
This can be used to fix user issues or to modify program behaviour at
runtime, and to create new card types based on existing cards.
Writes zero or more pairs of settings values to user settings and then
saves user settings to disk. The new values will override the default
values for the application and game language.
The arguments must be a sequence of key, value pairs. If the number of
arguments is not even, an exception is thrown.
For example:
Patch.apply( "encounter-bright-adjust", "1" )
| key1, value1, ... | pairs of key and value strings that name the keys to be modified and their new values |
Deletes zero or more user settings and then writes user settings to disk.
| key1, ... | the names of the keys whose values should be restored |
Changes zero or more pairs of settings values until the end of the current
session. The settings will return to their previous value the next time
the application runs.
The arguments must be a sequence of key, value pairs. If the number of
arguments is not even, an exception is thrown.
Assigning a value to a setting using the $-notation is normally
equivalent to calling this function unless the script is a DIY component
or usesettings has been called.
| key1, value1, ... | pairs of key and value strings |
Modifies the private settings of a component.
These settings apply only to component and are saved and loaded
with it.
This can be used by extensions to create custom components based on
existing card types by modifying their images, text, regions, and so on.
| component | the game component to modify |
| key1, value1,� ... | pairs of key and value strings |
Modifies the private settings of a component by merging in all of the settings
stored in a resource file.
| component | the game component to modify |
| resource | the path to a resource file from which settings will be read |
Removes one or more private settings from a component, restoring them to
their default value.
| component | the game component to modify |
| key1, ... | the names of the keys whose values should be restored |
If the script debugger is enabled, create a breakpoint at the next
opportunity. If the script debugger is not enabled, nothing happens.
Index Contents