Lightning Launcher Scripting API

Introduction

Starting at version 10 (alpha 9.9), Lightning Launcher has support for extending its behavior through JavaScript. This is an advanced and extremly powerful feature, and for this reason it requires some care.

The description of LL script APIs can be found here {@link net.pierrox.lightning_launcher.script.api}. The {@link LL} objet is the entry point for most things.

Available Android classes

Some Android classes can be directly used through scripting (creation of new instances, access to static fields - aka constants - and method calls). The list of supported classes are:

Bundle
Color
ComponentName
Context
Intent
LinearGradient
Matrix
MotionEvent
Paint
Path
PorterDuff
PorterDuffXfermode
RadialGradient
RectF
Region
Shader
SweepGradient
Toast
TypeFace
Uri

These third party classes are also available:

TaskerIntent
ActionCodes

Other classes can be accessed through their fully qualified name. For instance, should you need to access accelerometers, you may want to use android.hardware.Sensor.TYPE_ACCELEROMETER. Using LL.bindClass(String name) will conveniently suppress the need for explicit package naming (Sensor.TYPE_ACCELEROMETER would be enough if LL.bindClass("android.hardware.Sensor"); has been called previously.

Things to be aware of

Use the new Script Editor icon (in your app drawer) to quickly edit scripts. No need to configure events and select run a script: just launch the script editor and it will open on the last edited script.

DOs and DON'Ts

Use and absuse from variables

API calls are expensive, and you never know what is hidden behind. It is a good idea to keep return values in local variables to minimize API calls. For instance:

    alert(LL.getEvent().getTouchX()+" / "+LL.getEvent().getTouchY()); /* BAD */

    var e = LL.getEvent();
    alert(e.getTouchX()+" / "+e.getTouchY()); /* BETTER */

Not suitable for (smooth) animations

While it is possible to move, rotate or change items configuration, performances may not be enough to sustain a 60Hz animation rate.

Timers

It is possible to set timers using setTimeout. Pay special attention to clear these timers when needed, LL won't do this for you. If you don't clear timers, you may severly increase CPU use and battery consumption.

Object references

Avoid keeping references to objects returned by LL APIs in the script side, otherwise you may leak data. It is possible to use

self

to store data that are kept between two script execution (and can be shared between scripts), but try to avoid this as much as possible.