An event handler is a function or method that is called when a certain event takes place in the life of the application or a specific game component. Most event handlers are added by implementing a listener interface and then adding that interface as a listener for the event. Two events can be set by adding a private setting on a component (for example, using Patch.card) that consists of a string of JavaScript code that defines the handler function. The benefit of adding a handler as a private setting is that the handler will be saved and loaded with the component. The install event handler is of particular interest: since it can be set as a script, and since it is executed when the component is installed into an editor, an install event handler can be used to bootstrap any of the other event handlers into place when a component is loaded.
Executing the following script in the Quickscript window will cause a system beep every time the component is drawn:
function onPaint( g, comp, sheet ) { java.awt.Toolkit.defaultToolkit.beep(); } Patch.card( Component, "on-paint", onPaint.toSource() );
This example takes advantage of the fact that JavaScript functions have a toSource function that returns the source code for the function as a string.
Install events occur when an component is "installed" into an editor by calling the editor's replaceEditedComponent method. Since this method is called as part of opening a file, setting an install event allows you to alter a component or its editor whenever that component is opened, before it is visible to the user. To add an install event handler, set the on-install private setting of the component to a string that contains a function named onInstall. This function is called with two arguments, the editor and the component, although you can also use the standard Editor and Component variables as usual.
Blight cards, which are actually a customized version of Ally cards, use an install event handler to refresh the card's custom settings each time it is loaded. Blight cards have their own settings keys in the SE resources, and their values are copied over the equivalent Ally settings for the Blight card when it is created. However, without the install event handler, the settings on the card would not be updated if, at some point in the future, the standard settings for Blight cards were changed in the SE resources. The install event handler ensures that the settings are re-copied every time the file is opened, so it is kept up to date automatically.
Note: the install event handler is not currently called when the card is opened in a deck, because it is not attached to an editor when inside a deck and therefore replaceEditedComponent is never called. For future compatibility, check whether the passed in editor is null or a deck editor before trying to modify it.
Paint events occur whenever a card face is rendered. Adding a paint event handler allows you to customize how a card is drawn by drawing overtop of each card face once normal drawing is complete. To add a paint event handler, set the on-paint private setting of the component to string that contains a function named onPaint. This function is called with three arguments: a Graphics2D context, the component being drawn, and the CharacterSheet object that is responsible for drawing the current face. By examining the class of the sheet object, it is generally possible to tell whether the front or back face is currently being drawn (the same event handler is called for all faces of the component). Another way to determine the sheet is by locating its index within the array returned by the component's getSheets method. For example, if component.getSheets()[0] == sheet is true, then this event is for the front side.
The on-paint-sandbox.js example lets you edit a component's paint event interactively.
In addition to a scripted event, a call-back method can be set on each sheet that serves a similar function but which can be set from a compiled class. Unlike an event listener, only one (or no) call back can be set at a time on a given sheet. The call back is set using CharacterSheet.setPaintingCallback and must implement CharacterSheet.PaintingCallback. This interface consists of a single method, which has an identical name and signature to the onPaint script function.
The exact drawing order for a GameComponent is as follows: the component graphics, the callback function (if set), the function in on-paint (if set), and finally the component's expansion symbol (if any).
These handlers are standard event listeners that are set by calling the appropriate addXXXListener method, usually in an editor or the main application. They can be added from either compiled code or script code. (For script code, call the add method with the function you want to handle the event, e.g.:
Eons.addEditorAddedListener( function( editor ) { println( "New editor added: " + editor ); });
These listeners are called whenever the active plug-ins are loaded or unloaded. A typical use is to modify a user interface depending on whether a certain plug-in is available.
These listeners are called whenever a new editor is opened in Strange Eons.
Called at the preview update rate, this listener lets you signal that the user has made changes to the custom content you have added to a base component.
Called when a component's content has been copied to an editor's controls. This gives you an opportunity to copy any new features you have added into your custom controls.
Settings and PropertyChangeListeners
You can add a listener to a Settings object in order to be informed when a a setting value is set on it. (The PropertyChangeListener interface is part of the standard Java 6 API.)