The display¶

Keeping the screen on while a recipe is read, a ticket at full brightness, a video with nothing around it, and which way up a screen is.

from apkpy_lib import *

home = Screen(id="home")
label("Lemon risotto", id="title", screen=home)


def opened():
    display.keep_on()


lifecycle(home, on_mount=opened)
run(start_screen=home, orientation="portrait")

Call
`display.keep_on()`	The phone does not dim or lock while this screen is on show. `display.keep_on(False)` lets it sleep again.
`display.brightness(0.9)`	How bright this screen is, from `0` to `1`. `display.brightness("auto")` gives the level back to the phone.
`display.immersive()`	Hide the status bar and the navigation bar. `display.immersive(False)` brings them back.
`display.orientation("landscape")`	Which way up this screen is: `"portrait"`, `"landscape"` or `"auto"`.
`Screen(id="player", orientation="landscape")`	Which way up a screen opens.
`run(start_screen=home, orientation="portrait")`	The same, for every screen that does not say.

None of it asks the person for anything or needs a permission.

The four calls answer "ok", or "invalid" — and change nothing — for a level that is not from 0 to 1 or a way up that is not one of the three. A level or a way up written in the code is checked when the app is built, and a wrong one stops the build with the line (U2048): display.brightness(90) says For 90%, write 0.9.

It is the screen's¶

What a screen asks of the display is its own:

another screen opened on top of it has none of it — its own bars, the phone's brightness, the phone sleeping as usual — and coming back, the first screen has again what it asked for;
closing the screen ends it;
turning the phone, or changing the theme, does not: Android builds the screen again, and it keeps what it asked for.

So a player that hides the bars and keeps the phone awake gives both back when the person leaves it, with nothing to undo:

player = Screen(id="player", orientation="landscape")


def playing():
    display.keep_on()
    display.immersive()


lifecycle(player, on_mount=playing)

Ask from a function — the screen's on_mount, or a button. A call at the top of the file would run before there is a screen for it to belong to, and stops the build (U2048); inside a background job, where there is no screen at all, it stops the build too (J7004).

Kept on¶

display.keep_on() keeps the screen from dimming and locking while this screen is on show: a recipe, a map, a score being read from a music stand.

It is not a wake lock. The power button still turns the screen off, and leaving the app lets the phone sleep as it always does; nothing runs with the screen off and no battery goes behind the person's back. Coming back to the screen, it stays on again.

A switch hands its on_change "true" or "false", which keep_on() takes as they come:

def cook(on):
    display.keep_on(on)


inputs("Keep the screen on", id="awake", type="switch", on_change=cook, screen=home)

Brightness¶

display.brightness(1) is as bright as the phone goes and 0 the darkest — for a ticket or a code someone scans at a gate. It is this screen's brightness: the phone's own setting is not touched, and when the person leaves the screen the brightness they had is back. display.brightness("auto") gives it back before then.

A level that the app works out while it runs, and that is not from 0 to 1, answers "invalid" and changes nothing — it is not cut down to fit.

Without the bars¶

display.immersive() hides the status bar and the navigation bar, and the screen has the whole display: a video, a photo, a game, a page to read.

A swipe from the top or the bottom edge brings the bars back for a moment, over the screen, and they go again by themselves. That is Android's, and an app cannot turn it off: the person can always get out.

Which way up¶

Three places say it, and each one wins over the one before:

run(start_screen=home, orientation="portrait") — every screen;
Screen(id="player", orientation="landscape") — that screen;
display.orientation(...) — that screen, from then on.


`"portrait"`	Upright.
`"landscape"`	On its side — either side: turning the phone right round turns the screen too.
`"auto"`	Turns with the phone, if the person has auto-rotate on. What a screen does when nothing says otherwise.

The first two are written into the app, so the screen opens the right way up with nothing turning on the way in. display.orientation() is for a screen that changes its mind — a reader with a "lock rotation" button, a player that goes full screen:

def full_screen():
    display.orientation("landscape")
    display.immersive()

When the way up changes, Android builds the screen again, as when the phone is turned: what it shows is kept, and so is what it asked of the display.

Tablets and foldables¶

On a display 600dp wide or more — a tablet, a foldable opened out — Android 16 no longer lets an app say which way up it is: what the app says is ignored there, and the screen turns with the device and can be resized. Phones are not affected. ApkPy apps are built for Android 16, so a screen that is held upright on a phone still has to look right on its side on a tablet.

In the Previewer¶

A cup in the status bar while the screen keeps the phone on, and a sun while it sets its own brightness. Neither is anything a phone draws: point at one and it says what it stands for, and the level. The window is not dimmed or brightened.
display.immersive() takes the status bar away, and the app has the whole window.
A screen on its side turns the window on its side.
Ctrl+Left and Ctrl+Right turn the phone, as in the Android emulator. A screen that turns with the phone turns; one that holds its way up stays, and says so: This screen stays in portrait.
With device("Tablet") nothing holds its way up, as on a tablet. With device("responsive"), "fullscreen" or "maximized" the window is yours to size, and nothing turns it.

What it is not for¶

Work that has to go on with the screen off: that is a background_job.
Keeping what is on the screen out of screenshots: secure_screen(), in Data security.