UI and layout API¶

A screen in ApkPy is put together from three ideas:

A Screen is one Android screen. Each one becomes its own Activity. Components given screen= go down the screen in the order they are written.
A container groups components. Components given parent= go inside it, and the container's CSS decides how they are arranged: side by side or one under the other, with what gap and what alignment.
responsive() changes the arrangement with the width: a column on a phone, a row on a tablet, from the same components.

A screen, put together¶

from apkpy_lib import Screen, avatar, container, label, list_row, run

profile = Screen(id="profile", scroll=True)

head = container(id="head", screen=profile)
avatar("ana.jpg", size=56, parent=head, describe="Ana Lopes")
names = container(id="names", parent=head)
label("Ana Lopes", id="name", parent=names)
label("ana@example.com", id="email", parent=names)

prefs = container(id="prefs", screen=profile)
list_row("Notifications", subtitle="Sound and badges", icon="notifications", parent=prefs)
list_row("Storage", icon="folder", trailing="2.1 GB", parent=prefs)
list_row("Language", icon="language", trailing="English", trailing_icon="chevron_right", parent=prefs)

style = """
head {
    display: flex;
    flex-direction: row;
    justify-content: flex-start;
    align-items: center;
    gap: 14px;
}

names {
    display: flex;
    flex-direction: column;
    gap: 2px;
}

name {
    font-size: 20px;
    font-weight: bold;
}

prefs {
    border-radius: 16px;
    padding: 0px;
    divider-color: var(--border);
}
"""

run(profile)

head puts the picture and the two names side by side. A flex row with no justify-content centres what it holds, so flex-start starts it at the left edge.
names stacks the name over the address with a small gap.
prefs holds three settings rows and draws a hairline between them.
Each id is also the name the CSS uses. A picture in the app's folder, like ana.jpg, is packaged with the app.

On Android, containers are native view groups, with no WebView. The flex and grid rules are applied by a small layout class that the build adds only to apps that use them. Components and layouts lists every CSS property the layout understands.

Structure¶

API	Purpose
`Screen(id, background_image=None, scroll=False)`	define an Android screen/Activity
`run(start_screen=None, theme=None)`	start the Previewer and set the app entry
`Theme(...)`	global colors, typography, radius and component defaults
`font(family, regular=, bold=, italic=, bold_italic=)`	register a typeface from `.ttf`/`.otf` files
`device(name)`	Previewer device preset or responsive mode

scroll=True lets the screen scroll when its content is taller than the phone. A screen that holds a virtual_collection usually leaves it off: the list scrolls by itself.

Components¶

label, button, inputs, input_field, image, video, avatar, container, card, card_action, list_row, list_view, virtual_collection, carousel, grid, spinner, skeleton, empty_state and error_state.

Since 1.12.0: chips and segmented (options that stay selected), chart (bars, a line, a donut or a ring), pager and tab (tabs that swipe), swipe (what a swiped list row does) and validate (required fields, checked together).

Common component operations are get_value(), set_value(value), show() and hide(). Images also expose source/effect operations; videos expose playback, seek, speed and mute operations.

Layout¶

API	Important arguments
`container(id=None, screen=None, parent=None)`	a parent whose CSS arranges its children
`card(title=None, subtitle=None, image=None, content=None, actions=None)`	grouped content with actions, ready-made or empty
`list_row(text, subtitle=None, icon=None, trailing=None, trailing_icon=None, command=None)`	icon, label, subtitle and a trailing element
`responsive(mobile, tablet=None, landscape=None, breakpoint=600)`	different arrangements for different widths
`row(children)` and `column(children)`	the arrangements given to `responsive()`

responsive(
    mobile=column(profile_panel, details_panel),
    tablet=row(profile_panel, details_panel),
    breakpoint=600,
    screen=home,
)

On Android the build writes the screen four times, for a phone and a tablet, upright and sideways, and Android picks the one that fits the device. breakpoint is the width in dp from which a version takes the tablet arrangement: with the default 600, a tablet and a phone held sideways get the row. landscape=, when given, is what every sideways screen uses.

Every arrangement must hold the same components; only their order and direction change. In the Previewer, device("responsive") lets you resize the window to try it.

on_click_navigate, back, bottom_nav, BottomNav, drawer, app_bar, sliver_app_bar, action and mini_player.

Overlays and feedback¶

bottom_sheet, modal, menu, popup_menu, context_menu, snackbar, tooltip, date_picker, time_picker, toast, alert, confirm and view_image (a picture full screen, with pinch zoom).

Read Components and layouts, Themes and styling, Screens and navigation and Overlays and content states for complete examples; the essential reference has the exact signatures.