Power¶

Nativella\Power tells whether the computer runs on battery, and how much is left, so you can put off a heavy sync until it is plugged in, or warn before a long export. It also keeps the computer awake while it works.

if ($power->isOnBattery() && $power->battery()?->level < 0.2) {
    $notification->send('Low battery', 'The backup will run once the computer is plugged in.');
}

Method
`isOnBattery(): bool`	Whether the computer runs on its battery. It is false on mains, and without a battery.
`battery(): ?Battery`	The battery, null without one (a desktop computer). Several batteries count as one.

A Battery has a level, from 0 to 1, a state (BatteryState::Charging, Discharging, Full, Empty, NotCharging when a charge limit holds it on mains, or Unknown), and timeToEmpty and timeToFull in seconds, when the system has an estimate.

Keeping the computer awake¶

$power->keepAwake('Exporting the notes');
try {
    $exporter->export($notes);
} finally {
    $power->allowSleep();
}

Method
`keepAwake(string $reason): void`	Keeps the screen on and the computer awake, until `allowSleep()` or until the application quits. `$reason` is what the system shows the user. Calling it again replaces the reason.
`allowSleep(): void`	Lets the computer sleep again.

The user can still put the computer to sleep, or close its lid. On Linux, Nativella asks the desktop's screen saver and systemd-logind not to go idle, and systemd-inhibit --list shows it, with the application's name and the reason. macOS and Windows go through the same library, untested.

Events¶

Event	When
`PowerSourceChanged`	The computer went on battery, or back on mains: `$event->onBattery`.
`PowerResumed`	The computer woke from sleep, so data fetched before may be stale, and a connection may be dead.

Nativella looks every 5 seconds, and reports sleeps of 15 seconds or more. On Linux, it reads how long the computer slept from the system. Elsewhere, it compares the wall clock to the monotonic one. Setting the clock forward looks like a sleep, and Windows, whose monotonic clock runs during sleep, never reports one.

Power is desktop only. On a phone, it throws a NativeCallException.