API reference

This section describes the $ui API. Most functions must be called in "ui"; mode.

$ui.layout(xml)

• xml {XML} | {string} Layout XML or XML string

Render the layout XML into a View object and set it as the current content view.

$ui.layoutFile(xmlFile)

• xml {string} Layout XML file path

Similar to ui.layout, but renders from an XML file path.

$ui.inflate(xml[, parent = null, attachToParent = false])

• xml {string} | {XML} Layout XML or XML string
• parent {View} Parent view
• attachToParent {boolean} Whether to attach the rendered View to parent. Default false.
• Returns {View}

Render the layout XML into a View object. If the View will be used as a child of another View, it is recommended to pass parent so layout attributes that depend on the parent can be applied correctly.

Use this function to create and display Views dynamically.

"ui";

$ui.layout(<linear id="container"></linear>);

// Dynamically create 3 Text views and add them to the container
// This is only an example. In real apps, avoid building lists this way:
// use a list component instead. Creating dozens of Views dynamically may cause UI jank.
for (let i = 0; i < 3; i++) {
  let textView = $ui.inflate(
    <text textColor="#000000" textSize="14sp" />,
    $ui.container,
  );
  textView.attr("text", "Text view " + i);
  $ui.container.addView(textView);
}

$ui.registerWidget(name, widget)

• name {string} Widget name
• widget {Function} Widget factory

Register a custom widget. See examples → UI widgets → Custom widget.

$ui.isUiThread()

• Returns {boolean}

Returns whether the current thread is the UI thread.

"ui";

log($ui.isUiThread()); // => true

$threads.start(function () {
  log($ui.isUiThread()); // => false
});

$ui.findView(id)

• id {string} View id
• Returns {View}

Find and return a view by id in the current view hierarchy. Returns null if there is no current view, or if the id does not exist.

Usually you can access a view by ui.xxx where the id is xxx. If xxx conflicts with an existing ui property, use $ui.findView() instead.

$ui.finish()

Finish the current activity and destroy the UI.

$ui.setContentView(view)

• view {View}

Set the given view as the current content view.

$ui.post(callback[, delay = 0])

• callback {Function} Callback
• delay {number} Delay in milliseconds

Enqueue callback into the UI thread message loop and run it after approximately delay milliseconds (timing is not guaranteed).

Use this to delay work on the UI thread (you can’t call sleep on the UI thread), or to update the UI from a worker thread.

"ui";

ui.layout(
    <frame>
        <text id="result"/>
    </frame>
);

ui.result.attr("text", "Calculating…");
// Compute 1 + ... + 1000000 on a worker thread
threads.start({
    let sum = 0;
    for (let i = 0; i < 1000000; i++) {
        sum += i;
    }
    // UI cannot be updated from a worker thread; post back to the UI thread
    ui.post(() => {
        ui.result.attr("text", String(sum));
    });
});

$ui.run(callback)

• callback {Function} Callback
• Returns {any} Return value of callback

Run callback on the UI thread. If already on the UI thread, it runs immediately; otherwise it posts to the UI thread (queued at the end of the UI message loop) and waits until it finishes (blocks current thread).

$ui.statusBarColor(color)

• color {string | number} Color

Set the status bar color for the current UI.

"ui";
ui.statusBarColor("#000000");

$ui.useAndroidResources()

Enable using Android resources such as layout, drawable, anim, and style. After enabling, configure project.json as below so you can write UI similarly to native Android:

{
  // ...
  "androidResources": {
    "resDir": "res", // resources folder
    "manifest": "AndroidManifest.xml" // AndroidManifest file path
  }
}

The res folder typically has this structure:

-res -
  layout - // layout resources
  drawable - // images, shapes, etc.
  menu - // menu resources
  values; // styles, strings, etc.
// ...

See examples → Complex UI → Native Android UI.

$ui.imageCache.clearDiskCache()

[Added in Pro 8.8.16]

Clear UI image file cache, typically for images downloaded via URL (e.g. images loaded by img using a URL).

This can also be used to clear image file cache for image widgets in a custom splash screen.

This is unrelated to image/color searching and will not clear caches used by image/color matching.

If called on the UI thread, it automatically switches to an IO thread and runs asynchronously. So returning does not mean the disk cache has been fully cleared yet.

$ui.imageCache.clearMemory()

[Added in Pro 8.8.16]

Clear UI image memory cache.

This is unrelated to image/color searching and will not clear caches used by image/color matching.