AutoGUI Application

The main entry point. Use the app object to configure the window, load screens, and handle global logic.

register_screen(name, json_path, main=False) Setup
Loads a JSON layout file and assigns it a name. If main=True, this screen appears immediately.
app.register_screen("login", "login.json", main=True)
switch_screen(screen_name) Action
Switches the visible screen. User input on previous screens is preserved.
app.switch_screen("dashboard")
set_title(title) Config
Sets the text in the window title bar.
app.set_title("My Secure App v1.0")
set_background(hex_color) Config
Sets the background color of the main window.
app.set_background("#f0f2f5")
set_icon(path) Config
Sets the window icon (.ico or .png).
app.set_icon("assets/icon.png")

Button

A standard clickable button with ripple effects. Supports colors, text changes, and scaling.

on_click(callback) Event
Runs a Python function when the button is clicked.
app.home.btn_login.on_click(lambda: print("Logging in..."))
text(new_text=None) Get/Set
Gets current text (if empty) or sets new text.
# Set
app.home.btn1.text("Submit")
# Get
current = app.home.btn1.text()
bg_color(hex_code) Style
Changes the button background color.
app.home.btn1.bg_color("#ef4444")
text_color(hex_code) Style
Changes the text color.
app.home.btn1.text_color("#ffffff")
set_visible(bool) Visibility
Show or hide the button. Hidden buttons cannot be clicked.
app.home.btn1.set_visible(False)
set_enabled(bool) State
Enable or disable the button (grays it out).
app.home.btn1.set_enabled(False)
opacity(value) Style
Sets transparency (0.0 to 1.0).
app.home.btn1.opacity(0.5)

Label

Displays text or Material Icons. Supports dynamic text updates.

text(new_text=None) Get/Set
Updates the label text. If it is an Icon, this updates the icon code.
app.home.lbl_status.text("Connected")
text_color(hex_code) Style
Changes the text or icon color.
app.home.lbl_error.text_color("#ff0000")
font_size(size) Style
Sets the font size. This scales automatically with the window.
app.home.lbl_header.font_size(24)
set_visible(bool) Visibility
Show or hide the label.
app.home.lbl_loading.set_visible(True)

TextBox / TextArea

Input fields for user text. TextBox is single-line, TextArea is multi-line.

text(value=None) Get/Set
Gets the typed text or sets the input field value.
username = app.login.txt_user.text()
app.login.txt_user.text("") # Clear
set_enabled(bool) State
Enable or disable typing.
app.login.txt_user.set_enabled(False)
text_color(hex_code) Style
Changes the color of the typed text.
app.login.txt_user.text_color("#333333")

Image

Display images. Supports transparent backgrounds and loading from URLs.

from_url(url) Network
Downloads and displays an image from the web.
app.profile.avatar.from_url("https://example.com/pic.png")
update_image(source) Update
Updates image from local file path or Base64 string.
app.profile.avatar.update_image("assets/new_avatar.png")
set_fit(mode) Style
How image fits container: "contain", "cover", "fill", or "none".
app.profile.avatar.set_fit("cover")
set_visible(bool) Visibility
Show or hide the image.
app.profile.avatar.set_visible(False)
opacity(value) Style
Sets image transparency (0.0 to 1.0).
app.profile.avatar.opacity(0.8)

CardView / Panel

Containers for layout. Can be made clickable if listed in "hybrids" in JSON.

bg_color(hex_code) Style
Changes the card background color.
app.home.panel_main.bg_color("#ffffff")
border(width, hex_code) Style
Adds a border to the card.
app.home.panel_main.border(2, "#e2e8f0")
on_click(callback) Event
Bind a click event (Only works if component is a 'hybrid' or CardView).
app.home.panel_main.on_click(lambda: print("Card Clicked"))
set_visible(bool) Visibility
Show or hide the entire panel and its children.
app.home.panel_main.set_visible(False)

Checkbox

Standard tick box for boolean selection.

is_checked() Boolean
Returns True if checked, False otherwise.
if app.form.chk_agree.is_checked():
    submit_form()
on_toggle(callback) Event
Runs code when the box is checked or unchecked.
app.form.chk_agree.on_toggle(lambda: validate())

Toggle Switch

Modern sliding switch.

is_on() Boolean
Returns True if switch is ON.
enabled = app.settings.sw_notify.is_on()
on_toggle(callback) Event
Runs code when the switch is toggled.
app.settings.sw_notify.on_toggle(lambda: update_prefs())

Slider

Draggable range selector.

get() Integer
Returns the current slider value.
volume = app.settings.slider_vol.get()
set(value) Update
Sets the slider position.
app.settings.slider_vol.set(50)

ProgressBar

Visual indicator of completion.

set(value) Update
Sets the progress (0 to 100). If attached to a label, updates text to "X%".
app.loader.pbar.set(75)

Spinner

Number input with up/down buttons.

get() Integer
Returns the current number.
qty = app.cart.spin_qty.get()
set(value) Update
Sets the number value.
app.cart.spin_qty.set(1)

RadioGroup

A set of mutually exclusive options.

get() Value
Returns the value of the selected option.
gender = app.form.radio_gender.get()

Animation System

Move and align widgets dynamically. Animations use a "Builder Pattern" where you chain commands together.

app.animate(type) Start
Starts an animation definition. Types: "move to center", "align", "move to position", "restore".
.apply_to(widget_id) Source
The widget you want to move.
.end_at(widget_id) Target
The widget you want to move towards.
.offset_x(val) / .offset_y(val) Adjust
Offsets the final position relative to screen size.
0.1 = 10% of screen size.
Positive X = Right, Negative X = Left.
Positive Y = Up, Negative Y = Down.
.start() Execute
Runs the animation.
# Full Example
app.animate("move to center")\
    .apply_to("game.token")\
    .end_at("game.slot_1")\
    .offset_y(0.05)\
    .with_duration(0.5)\
    .start()

Cloning System

Dynamically duplicate components at runtime (e.g., for shop items or lists).

app.clone(ids).on_base(base_id) Template
Creates a template.
  • ids: Comma-separated list of child widgets (buttons, labels).
  • base_id: The container ID (CardView) that holds the children. This is required for relative positioning.
  • id: Name your template.
# Define Template
app.clone("btn_buy,lbl_price,img_item")\
    .on_base("card_bg")\
    .id("product_item")\
    .execute()
app.create_clone(tmpl, panel) Create
Instantiates the template into a target panel.
  • .cols(n): Number of columns in the grid.
  • .h(px) / .v(px): Horizontal/Vertical spacing.
  • .scale(float): Resize clones (e.g., 0.8 for 80%).
# Create Grid
app.create_clone("product_item", "shop.grid_panel")\
    .cols(3)\
    .h(15).v(15)\
    .scale(0.8)\
    .execute()