API Overview
Now let’s discuss Svetka API in detail.
Evaluator Pool
Main logic is accommodated in ru.hwl.svetka.Evaluator class. To obtain new evaluator instance you have to invoke ru.hwl.svetka.EvaluatorPool#newEvaluator(id : String) method, where id specifies evaluator id. Evaluator id is used internally to distinguish different evaluation contexts on the JS-side. Also can retrieve already created evaluator by invoking ru.hwl.svetka.EvaluatorPool#getEvaluator(id : String).
Evaluator pool itself is a singleton which can be obtained by calling static method ru.hwl.svetka.EvaluatorPool.instance(namePrefix : String). namePrefix specifies a name prefix to attach to the beginning variables’ names to avoid naming conflicts with existing variables as on the JS-side as on the AS-side. Its default value is "__" and can be reffered as ru.hwl.svetka.EvaluatorPool.DEFAULT_NAME_PREFIX. In most cases you can omit namePrefix parameter. However, if on HTML page containing your Flash movie you deal with variables starting with __, or inside your !ActionScript you deal with variables or methods starting with __, it’s strongly recommended to specify another name prefix.
import ru.hwl.svetka.Evaluator;
import ru.hwl.svetka.EvaluatorPool;
...
var pool : !EvaluatorPool = !EvaluatorPool.instance("_");
var evl : Evaluator = pool.newEvaluator("evl");
After EvaluatorPool has been instantiated namePrefix parameter is ignored in following EvaluatorPool.instance(String) calls. You can always get specified namePrefix by calling ru.hwl.svetka.EvaluatorPool#getNamePrefix().
As we’ve already mentioned, evaluator pool is a singleton thus it is bound to particular Flash movie. To get movie id (see here to learn what is it) call ru.hwl.svetka.EvaluatorPool#getMovieId().
Evaluator
Once you’ve obtained evaluator instance you can call its methods. Perhaps the most important one is ru.hwl.svetka.Evaluator#multiEval(expression : String), where expression specifies expressions to evaluate. The expressions must be separated by the rules of !JavaScript (usually with semicolon). The method returns the value stored in __result variable in JS expression (assuming namePrefix to be "__").
var myObj : !MyCoolObject = new !MyCoolObject();
evl.expose(myObj, "myCoolObject");
var res : int = evl.multiEval("__result = 0; for (var i = 0; i < 10; i++) { __result += myCoolObject.myCoolMethod(i); }");
The expression is implicitly embraced in try block and all caught JS-side errors are wrapped into ru.hwl.svetka.EvaluatorError and rethrown by multiEval on the AS-side. See Error Handling for the details.
Another important method mentioned in the above listing is ru.hwl.svetka.Evaluator#expose(obj : Object, exposedName : String). It makes a variable or an object available during the evaluation under the specified alias (exposedName). With its help we could reference myObj as myCoolObject in !JavaScript.
ru.hwl.svetka.Evaluator#evaluate(expression : String) provides more comfortable way to evaluate JS. Besides wrapping an expression into try-catch it appends to the beginning the following: “__result = ” (assuming namePrefix to be "__"). Thus expression should be valid JS expression – not a number of expressions, not a loop, function definition, try-catch block etc.
// incorrect
// var res1 : int = evl.evaluate("for (var i = 0; i < 10; i++) { __result += myCoolObject.myCoolMethod(i); }");
// correct
var res1 : int = evl.evaluate("2+3");
One more useful method is ru.hwl.svetka.Evaluator#removeEntries(). It clears evaluation context on both sides (AS and JS) i.e. deletes the links to utilized variables to allow garbage collectors to collect unused objects to free the memory.
Next
Now read about error handling in Svetka., if you haven’t done it yet.