The floaty module provides functions for floating windows (overlay windows). You can show custom UI on top of the screen and control the window’s size and position.

Floating windows are automatically closed when the script stops. To keep a floating window alive, you can use an empty setInterval, for example:

setInterval(() => {}, 1000);

floaty.window(layout)

• layout {xml} | {View} Floating window UI XML or View

Create and show a floating window using layout, and return a FloatyWindow object.

This window includes built-in controls for close/resize/reposition. Use setAdjustEnabled() to show or hide those controls.

The layout parameter can be an XML layout or a View. For details, see the ui module docs.

Example:

var w = floaty.window(
  <frame gravity="center">
    <text id="text">Floating text</text>
  </frame>
);
setTimeout(() => {
  w.close();
}, 2000);

This code shows floating text on the screen and closes it after 2 seconds.

Also note: your script thread is not the UI thread, and all widget updates must run on the UI thread. Use ui.run, for example:

ui.run(function () {
  w.text.setText("Text");
});

For the returned FloatyWindow, see the FloatyWindow section below.

floaty.rawWindow(layout)

• layout {xml} | {View} Floating window UI XML or View

Create and show a raw floating window using layout, and return a FloatyRawWindow object.

Unlike floaty.window(), a raw window adds no extra facilities (e.g. resize/position buttons). You can implement any layout you need.

It also supports full-screen overlays and can cover the status bar, which can be used for things like an eye-protection overlay.

var w = floaty.rawWindow(
  <frame gravity="center">
    <text id="text">Floating text</text>
  </frame>
);

w.setPosition(500, 500);

setTimeout(() => {
  w.close();
}, 2000);

This code shows floating text on the screen and closes it after 2 seconds.

For the returned FloatyRawWindow, see the FloatyRawWindow section below.

floaty.closeAll()

Close all floating windows created by the current script.

floaty.checkPermission()

• Returns {boolean}

Returns whether the app currently has floating-window (overlay) permission. (Does not trigger a permission request.)

floaty.requestPermission()

Navigate to the system overlay-permission screen.

if (!$floaty.checkPermission()) {
  // No overlay permission: prompt user and navigate to settings
  toast(
    "This script needs overlay permission to show floating windows. Please allow it on the next screen and rerun the script."
  );
  $floaty.requestPermission();
  exit();
} else {
  console.log("Overlay permission already granted");
}

Note: this function is non-blocking and does not wait for the permission to be granted.

FloatyWindow

Floating window object. You can access elements via window.{id}. For example, if a widget’s id is aaa, then window.aaa gets that widget (similar to ui).

window.setAdjustEnabled(enabled)

• enabled {boolean} Whether to enable floating-window adjustment (size/position)

If enabled is true, adjustment handles will be shown on the top-left and top-right corners (similar to the console). If false, they are hidden.

window.isAdjustEnabled()

• Returns {boolean}

Returns whether floating-window adjustment (size/position) is enabled.

window.adjustEnabled

• {boolean}

Shortcut property for whether adjustment is enabled, equivalent to window.isAdjustEnabled().

window.setPosition(x, y)

• x {number} x
• x {number} y

Set the floating window position.

window.getX()

Return the X coordinate of the floating window position.

window.getY()

Return the Y coordinate of the floating window position.

window.x

• {number}

Shortcut property for X coordinate, equivalent to window.getX().

window.y

• {number}

Shortcut property for Y coordinate, equivalent to window.getY().

window.position

• {Object}

Shortcut property object for position (usually contains x, y).

window.setSize(width, height)

• width {number} Width
• height {number} Height

Set the floating window size.

window.getWidth()

Return the floating window width.

window.getHeight()

Return the floating window height.

window.width

• {number}

Shortcut property for width, equivalent to window.getWidth().

window.height

• {number}

Shortcut property for height, equivalent to window.getHeight().

window.size

• {Object}

Shortcut property object for size (usually contains width, height).

window.close()

Close the floating window. If it is already closed, this function does nothing.

A closed floating window cannot be shown again.

window.close([bool])

• bool {boolean} Optional underlying close behavior flag

Close the floating window (overload with parameter). If you don’t have special needs, prefer window.close() without arguments.

window.exitOnClose()

Exit the script automatically when the floating window is closed.

window.disableFocus()

Disable focus for the floating window.

window.requestFocus()

Request focus for the floating window.

window.findView(id)

• id {string} View id
• Returns {android.view.View}

Find a view inside the floating window by id. Usually you can also access it directly via window.{id}.

let view = window.findView("text");
log(view);

FloatyRawWindow

Raw floating window object. You can access elements via window.{id}. For example, if a widget’s id is aaa, then window.aaa gets that widget (similar to ui).

window.setTouchable(touchable)

• touchable {Boolean} Whether the window is touchable

Set whether the floating window is touchable. If true, the window receives touch/click events and they will not pass through to the underlying UI. If false, touch/click events pass through to whatever is beneath the floating window. For security reasons, events captured by the floating window cannot be forwarded further down.

This can be used to implement an “eye protection” overlay script.

var w = floaty.rawWindow(<frame gravity="center" bg="#44ffcc00" />);

w.setSize(-1, -1);
w.setTouchable(false);

setTimeout(() => {
  w.close();
}, 4000);

window.setPosition(x, y)

• x {number} x
• x {number} y

Set the floating window position.

window.getX()

Return the X coordinate of the floating window position.

window.getY()

Return the Y coordinate of the floating window position.

window.setSize(width, height)

• width {number} Width
• height {number} Height

Set the floating window size.

In particular, -1 means full screen, and -2 means wrap content. Example:

var w = floaty.rawWindow(
  <frame gravity="center" bg="#77ff0000">
    <text id="text">Floating text</text>
  </frame>
);

w.setSize(-1, -1);

setTimeout(() => {
  w.close();
}, 2000);

window.getWidth()

Return the floating window width.

window.getHeight()

Return the floating window height.

window.close()

Close the floating window. If it is already closed, this function does nothing.

A closed floating window cannot be shown again.

window.exitOnClose()

Exit the script automatically when the floating window is closed.