statusbartweak/README.md

# StatusBarTweak

StatusBarTweak is an Xposed/LSPosed module for Samsung SystemUI. It focuses on
making the status bar, lockscreen, and Always On Display more configurable while
still keeping Samsung's own icons and visual style where possible.

The project is currently tested only on a Samsung Galaxy Z Fold5 running One UI
8.0 / Android 16. Expect device- and One UI-version-specific behaviour.

## AI Assistance

This project was developed with help from AI-assisted coding tools. The design
decisions, physical device testing, and final behaviour are still manually reviewed.

## What It Does

- Custom status bar layout for the unlocked screen, lockscreen, and AOD.
- Independent placement of clock, carrier text, notification icons, status
  icons, and Samsung status chips.
- Separate notification display handling for Samsung's cards, icons, and dot
  modes.
- Configurable icon sizes, vertical offsets, ordering, spacing, truncation, and
  cutout handling.
- Hide selected notification icons by app, separately for AOD, lockscreen, and
  unlocked mode.
- Hide selected status icons such as NFC, Bluetooth, hotspot, location, VPN,
  battery, and similar SystemUI indicators.
- Optional custom clock text with multi-line formatting, colours, font families,
  and cutout-aware split alignment.
- Battery bar with configurable position, alignment, thickness, colours, and
  threshold colours.
- Controls for Samsung status chips such as media, navigation, and call chips.
- Debug tools for generating test notifications, visualizing layout containers,
  and restarting SystemUI during development.

## Custom Clock Text

The custom clock uses Java-style date/time patterns such as `HH:mm`,
`EEE d MMM HH:mm`, or `HH:mm:ss`.

It also supports lightweight markup:

- HTML-like tags: `<i>`, `<u>`, `<small>`, `<big>`, and `<font ...>`.
- Shorthand blocks such as `{#FA0 big @sans-serif-condensed}HH:mm`.
- Multi-line text using `\n` or `{\\n12}`; numbered line breaks use statusbar units.
- Pipe alignment with `|`, useful for aligning split clock rows around a camera
  cutout.
- Colour variants and reverse Polish notation colour math for light/dark status
  bar states, for example `color(#batterybar 1.2 *RGB ; #batterybar 0.5 *RGB)`, which uses the batterybar's dynamic colour as its base. For the bright tint, it brightens it up some more, while for the dark tint, it is darkened.

The in-app clock page has the full syntax help and examples.

## Requirements

- A rooted Android device or emulator.
- A modern Xposed implementation such as LSPosed or another libxposed-compatible runtime.
- Xposed API 101 or newer.
- SystemUI access for the module scope.

The module is currently developed and manually tested on a Samsung Galaxy Z
Fold5 running One UI 8.0 / Android 16. Other Android versions and non-Samsung
SystemUI builds are being investigated, but should be treated as experimental
until the compatibility matrix says otherwise.

## Device Compatibility

Some behavior cannot be fully verified on emulators. In particular, smooth
transitions between AOD, lockscreen, unlocked mode, and fullscreen apps may need
physical-device testing. Emulator testing can still verify whether hooks load,
whether SystemUI stays stable, whether settings apply, whether excessive
background work appears in logs, and whether the steady state looks the way it
should.

| Feature | Galaxy Z Fold5<br>One UI 8 / Android 16 | AOSP API 34<br>Android 14 | AOSP API 35<br>Android 15 | AOSP API 36<br>Android 16 | Google APIs API 35<br>Android 15 | Google APIs API 36<br>Android 16 | LineageOS 22<br>Android 15 | LineageOS 23<br>Android 16 |
| --- | --- | --- | --- | --- | --- | --- | --- | --- |
| Module loads in SystemUI | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Settings app opens and writes settings | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Custom unlocked statusbar layout | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Custom lockscreen statusbar layout | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Custom AOD statusbar layout | ✅ | Untested | Untested | ❌ OneUI AOD hooks only | Untested | Untested | Untested | Untested |
| Notification icons mode | ✅ | Untested | Untested | ✅ unlocked and lockscreen hosts verified; AOD unsupported | Untested | Untested | Untested | Untested |
| Notification cards mode | ✅ | Untested | Untested | ❌ OneUI cards mode only | Untested | Untested | Untested | Untested |
| Notification dot mode and read-state behavior | ✅ | Untested | Untested | Untested; lockscreen/AOD style detection is OneUI-specific | Untested | Untested | Untested | Untested |
| Hide notification icons by app | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Hide status icons | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Dual-SIM status icon handling | ✅ | Untested | Untested | Untested; emulator has no dual-SIM signal state | Untested | Untested | Untested | Untested |
| Samsung status chips: media/navigation/call | ✅ | Untested | Untested | ❌ OneUI-only | Untested | Untested | Untested | Untested |
| Samsung charging chip handling | ✅ | Untested | Untested | ❌ OneUI-only | Untested | Untested | Untested | Untested |
| Privacy indicator stability | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Custom statusbar clock text | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Custom drawer clock/date text | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Stored clock pattern previews | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Battery bar: base statusbar modes | ✅ | Untested | Untested | ✅ unlocked and lockscreen verified; AOD unsupported | Untested | Untested | Untested | Untested |
| Battery bar: fullscreen and transparent statusbar modes | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Battery bar: curved top-edge geometry | ✅ | Untested | Untested | Untested; emulator has no curved screen edge | Untested | Untested | Untested | Untested |
| Battery bar threshold colours and colour math | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |
| Camera cutout and under-display-camera handling | ✅ | Untested | Untested | Untested; emulator has no cutout/UDC | Untested | Untested | Untested | Untested |
| Rotation and fold/unfold handling | ✅ | Untested | Untested | ✅ rotation verified; fold/unfold not applicable to this emulator | Untested | Untested | Untested | Untested |
| Drawer scrolling and background-work performance | ✅ | Untested | Untested | ✅ no excessive work seen in emulator drawer test; physical smoothness not verified | Untested | Untested | Untested | Untested |
| Debug visualizers and debug notifications | ✅ | Untested | Untested | ✅ | Untested | Untested | Untested | Untested |

Current emulator targets use rooted LSPosed snapshots in a local test lab. They
are useful for compatibility work, but the matrix above is intentionally not
optimistic: until a target has been tested, it remains `Untested`.

## Build

The project is a standard Gradle Android project:

```bash
./gradlew assembleDebug
```

Release builds require local signing configuration:

```bash
./gradlew assembleRelease
```

## Test Harness

The repository also includes a small companion app for compatibility testing.
It is not required for normal use of the module. It creates repeatable
statusbar scenarios such as opaque, transparent, fullscreen, privacy-indicator,
and notification states:

```bash
./gradlew :test-harness:assembleDebug
adb install -r test-harness/build/outputs/apk/debug/test-harness-debug.apk
adb shell am start -n se.ajpanton.statusbartweak.harness/.MainActivity
```

Automation can launch scenarios directly:

```bash
adb shell am start -n se.ajpanton.statusbartweak.harness/.ScenarioActivity --es scenario fullscreen_landscape
adb shell am start -n se.ajpanton.statusbartweak.harness/.MainActivity --es command post_normal
```

Useful scenario values include `opaque_light`, `opaque_dark`, `transparent`,
`fullscreen_portrait`, `fullscreen_landscape`, `camera`, `microphone`, and
`camera_microphone`.

Useful command values include `post_normal`, `post_ongoing`, `post_grouped`,
`update`, `start_chronometer`, `start_churn`, `stop_churn`, `start_media`,
`start_foreground`, `stop_service`, and `clear`.

Battery charging state is controlled by Android system commands rather than by
the harness APK:

```bash
adb shell cmd battery set status 2
adb shell cmd battery set level 80
adb shell cmd battery reset
```