Skip to main content

Getting started

老猫10/27/23About 2 min

The ui module provides support for building user interfaces.

Tips

Reminder for Android developers and advanced users: Auto.js’s UI system comes from Android, and you can find all properties and methods in Android source/docs. If some APIs or attributes do not appear in Auto.js docs, consult the Android documentation.

Scripts that use UI must start with "ui"; to enable UI mode; otherwise the script will not run in UI mode. Correct example:

"ui";

// other script code

Before the "ui" string, you may have comments, blank lines, and spaces (added in v4.1.0), but no other code is allowed.

A UI is composed of Views. Views are of two kinds: widgets and layouts. Widgets display content such as text, images, and web pages. For example, text shows text, button shows a tappable button, img shows an image from network or files. There are also input, progressbar, checkbox, etc. Layouts are “containers” that hold one or more views and control how they are positioned. For example, vertical arranges children top-to-bottom, horizontal arranges left-to-right, and frame places children at the top-left by default and later children may overlap earlier ones.

We write UIs in XML and pass the layout XML to ui.layout(). For example:

"ui";
$ui.layout(
  <vertical>
    <button text="First button" />
    <button text="Second button" />
  </vertical>,
);

In this example, the XML is the part that describes the UI content. The tag <vertical> ... </vertical> is a vertical layout. Layout tags usually start with <...> and end with </...>, and the content between them are the children, e.g. <frame> ... </frame>. Here, the two <button ... /> lines are children of the vertical layout. Widget tags usually start with <... and end with />, and they contain widget attributes, e.g. <text ... />. Here, text="First button" is a button attribute specifying the button label.

The second button is the same kind of widget, but with the label “Second button”. Because these two widgets are inside a vertical layout, they are arranged vertically, as shown below:

ex1
ex1

If we change the vertical layout to a horizontal layout, i.e.:

"ui";
ui.layout(
  <horizontal>
    <button text="First button" />
    <button text="Second button" />
  </horizontal>,
);

Then the two buttons are arranged horizontally, as shown below:

ex1-horizontal
ex1-horizontal

A widget can have multiple attributes (or even none), separated by spaces. Layouts can also have attributes, for example:

"ui";
ui.layout(
  <vertical bg="#ff0000">
    <button text="First button" textSize="20sp" />
    <button text="Second button" />
  </vertical>,
);

Here, bg="#ff0000" sets the vertical layout background color to red. textSize="20sp" sets the button text size to 20sp (sp is a text size unit in Android). The result looks like:

ex-properties
ex-properties

A UI is composed of layouts and widgets. For easier reading, here are some terms:

  • Child view / child widget: a widget inside a layout is that layout’s child. In fact, a layout can contain other layouts as well, so “child view” is more accurate. In the examples above, the buttons are children of the vertical layout.
  • Parent view / parent layout: the layout that directly contains a widget is its parent. In the examples above, the vertical layout is the buttons’ parent.
Copyright © 2026 老猫