Scripting

Overview

As of version 10 alpha, Lightning Launcher can be “scripted” using JavaScript, meaning its behavior can be greatly extended through scripting.

Scripts have almost full access to desktops, meaning that scripts can be used for instance to:

  • animate items
  • create customized navigation actions
  • create, modify or delete items, for instance to create a themed desktop
  • execute utility tasks (sort items, layout them in a grid, on a circle, or whatever else)
  • etc.

Scripts can also directly draw things and react to touch events. This can be used to create light on memory widgets, such as a clock or even a sketch pad, directly on your home screen.

Packaging scripts

Features

As of version 10.5, Lightning can load scripts from APK. This is an easy way to share scripts and add features to your home screen.
A script APK is a way to distribute one or more scripts and associate them with a name and an icon, so that the user can easily browse them from the launcher.

These APKs are shown to the user in two places:

  • In the popup menu : tapping on “Scripts…” / “Load a script…” will display the list of installed script APKs
  • As of V14b3, script APKs can be shown in the “Add item” dialog box, in the “Plugins” section.

The place where a script APK appears is configurable (see below).

When LLX loads a script from a package, it can, depending on the package configuration, import the script so that it becomes available in the launcher, possibly execute it right after importing it, and maybe delete it after this initial execution. This last case is useful if the script purpose is to make some initialization (create some item, configure the desktop, etc.) and there is no need to keep the script afterward. Typical use of the possible combinations are:

    • don’t execute, don’t delete: for utility scripts intended to be run at the user demand, for instance a script that would display statistics, such as number of shortcuts, folders…
    • execute, don’t delete: same as above, but executed now, for instance a script that layout items in a specific way.
    • execute, delete: for setup scripts, they are executed once, then no longer needed, for instance a script that create a dockbar with a panel and a few items inside, with a custom style
    • don’t execute, delete: huh ? No use!

When loaded from an APK, a script is also able to load icons and other scripts from the package. This means that a script can really create a complex setup, with images and several utility scripts.

When a script is loaded in LLX, it is either created or updated if it already exist. Make sure the name it unique so that it won’t overwrite another script.

How to configure your package

In order to create your own script package, download the sample package to get started. This needs Android Studio and basic knowledge on building Android packages. This package shows how to import a single script in the launcher, and also includes a sample object oriented plugin, with a custom menu and settings screen (Lightning V14b6 and later). Please use this package as a reference when building plugins.

Another sample is the Clock-2.1 plugin, for Lightning V14b3 and later (download the source package: Clock-2.1.tar.gz). This sample registers itself as a plugin, so that the user is able to select “Add Item / Plugin / Analogic clock”. This sample clock also comes with a custom menu and a settings screen.

Step by step

      1. Download and unzip the sample package (other samples are linked at the bottom of this page)
      2. in the AndroidManifest.xml and app/build.gradle files: change the package name: replace net.pierrox.lightning_launcher.llscript.samplellxscript with your package name, but make sure that it includes the word «llscript» somewhere so that it can be found in the app store.
      3. In the app/src/main/res/values/strings.xml file: change the content of app_name, this is the name of the package visible to the user in the Android application list, and should be usually the name in the Play Store if published there
      4. In the app/src/main/res/values/strings.xml file: change the content of browse_name, this is the name of the script when browsing available script packages
      5. In the app/src/main/res/values/strings.xml file: change the content of script_name, this is the name of the script as seen in the script editor and the script menus
      6. In the directory app/src/main/res/raw/: put your script here, in a text file (utf-8 encoding). The name must fulfill Android constraints: only lower case, a to z, 0 to 9, _ and no other character.
      7. Rename the Hello.java file and replace R.raw.hello withR.raw.your_script_file_without_the_extension. If your file is named my_script.js, then use R.raw.my_script.
      8. Update the ic_launcher.png icon in the app/src/main/res/drawable-* directories: this is the package icon, which is also used when browsing scripts from the launcher
      9. Select where you want the APK to appear in Lightning by setting the intent-filter action in the AndroidManifest.xml file. Use net.pierrox.lightning_launcher.script.ENUMERATE to display it from the “Load a script…” menu, use net.pierrox.lightning_launcher.script.PLUGIN to display it in the “Add item” dialog box, under the plugins section. In that last case the script executed from the APK is expected to create some item. It is possible to use both intent-filters.

It is possible to ship several scripts in a package by duplicating entries in the sample package:

      • Add new strings in app/src/main/res/values/strings.xml to set the new script(s) name(s)
      • Duplicate and rename the Hello.java file
      • Duplicate everything in AndroidManifest.xml between <activity> and </activity>
      • Replace hello everywhere in duplicated things with your new values
      • Possibly add one icon per script to differentiate them (in the drawable-* directories) and in the<activity> tag update android:icon with @drawable/your_icon

It is also possible to import several scripts at once from the script executed as the entry point (see Sketch and Clock samples).

Sample scripts

    • SampleLLXScript-2.0.tar.gz: the most simple script package. It will register a script in the launcher scripts menu that simply says “Hello” when run. It can be used as the basis for a new package. The package also contained a more advanced sample counter plugin (for Lightning V14b6 and later)
    • Clock-2.1.tar.gz (APK here): (for Lightning V14b3 and later) creates a simple analogic clock in your desktop. This script registers itself as a plugin so that the user can simply tap “Add item / plugins / Analog clock”. The script also demonstrates the popup menu customization and the creation of a settings screen using Lightning builtin features.
    • Clock-1.0.tar.gz (old): creates a simple analogic clock in your current desktop. It demonstrates how to set a timer for an item and clear it when needed.
    • Sketch-1.0.tar.gz (old): creates a sketchpad, with a few buttons to change the drawing color and clear the sketchpad. It demonstrates how to create items and set event handlers