Files

T

SoftwareApp 0743bda29e Let a folder be starred, and put the starred ones on the home screen

The app bar of any folder now carries a star, and a starred folder appears in a Favourites section
on the home screen, above the libraries. Above, because it is the user's own list - and absent
entirely while empty, so someone opening the app for the first time still meets the libraries first,
which is the order they were given for a reason. The star in the row is the removal, which is what a
star means everywhere else: the mark that says "this is a favourite" is the thing you tap to stop it
being one. That avoids a long-press as well, and with it a destructive gesture nobody can see.

A favourite is a reference, not a copy: data/BookmarkStore keeps one path per row and nothing about
the folder's contents, so reading the whole list is one query and no filesystem work, which is what
makes it affordable on every visit to the home screen. It has its own SQLite database rather than a
table in the trash index - one table and three queries do not justify Room in a build that has no
annotation processor, and the two stores have nothing to say to each other. Two behaviours there are
decisions rather than defaults. A folder that has gone is kept and marked (Folder not found) instead
of being deleted: a card out of its slot and a folder deleted in another app are indistinguishable
from here, and silently forgetting someone's list because their SD card was out is the worse of the
two mistakes. And opening the row re-checks existence at that moment, because the flag is as old as
the screen - so the answer is a message rather than an empty listing, which would read as an empty
folder instead of a missing one.

Two smaller refusals came out of the same question. There is no star in a library or on the root
screen, because neither is a folder and there would be nothing to come back to: the distinction that
governs the new-folder button, and one the view model enforces too rather than trusting a stale
screen. And a bookmark has no undo, because Undo means "the last change to the filesystem the app
made" and a favourite is not one - the star is one tap to put back. The row's label comes from the
same place the breadcrumbs do, which is why a starred volume root reads as "Internal storage" rather
than as "0".

Sixteen tests: nine against real SQLite through Robolectric (round trip, ordering, starring twice
neither duplicating nor moving a row, and the same no-drop migration guard the trash index carries),
and seven through the view model (toggling, outliving the view model that added it, newest first,
the missing folder kept and marked, the missing folder refusing to open, and a library refusing to be
starred). 371 JVM tests, lint clean. Verified on the phone: the star appears only inside a folder and
flips from "Add to favourites" to "Remove from favourites" without leaving the screen; the home
screen lists the volume root above the libraries with its own label and its path underneath; the row
opens it with the star already filled; and the row's star takes the whole section away with a
snackbar. The documentation moved with it - CHANGELOG, ROADMAP (M15), README, COMPETITIVE_ANALYSIS
(that gap closes instead of joining the candidates), EDGE_CASE_TESTING, and the generated code map.

2026-10-17 07:48:26 +02:00

12 KiB

Raw Blame History

File Manager

An ad-free, one-time-paid Android file manager. It browses and manages the files on your device — locally, with no ads, no account and no analytics.

Nothing ever leaves the device: the app declares no network permission and contains no advertising or tracking SDKs.

Working title. The display name and the store listing are decided before the first Play upload (see docs/ROADMAP.md, M10). The applicationId is already fixed and can never change after the first release.

Status

M15 — favourites: done. A star in any folder's app bar puts that folder on the home screen, above the libraries, where a folder that has gone is marked not found rather than silently dropped and the row's own star removes it. Before it: M14 — renaming a batch (selecting several files and choosing Rename opens a pattern dialog instead of the single-file one: one name, the number to start at, and a preview of the names it will produce — and the numbering carries on from the folder's own, so series (1) and series (2) already there make the next batch start at 3. A batch that cannot be done is refused before anything moves, naming the file in the way, and the whole batch is one undo step. Before it: M13 — video thumbnails (a video row shows a frame of the video itself rather than a film icon — the platform's own retriever, through Coil, with a frame taken a second in and the icon kept as the fallback when a file cannot be decoded), M12 — duplicate finder (size, then the head of every candidate, then the survivors in full), M11 — library views (a Libraries section on the root screen — Images, Videos, Audio, Documents, Archives and Recent — whose rows open ordinary listings of those files, each carrying a count from the search index), and M10 — store assets: the app is named Plain Files, the icon and feature graphic come from the app's own vectors, and docs/STORE_LISTING.md holds length-checked listing copy. Screenshots exist for 5 phone (1080×2160), 4 on a 7-inch tablet (1200×1920) and 4 on a 10-inch tablet (2560×1600) — but they predate M11, so the home screen in them is the old volume list and they will need re-shooting, which the library views make a privacy question as well as a cosmetic one (docs/STORE_LISTING.md).

Tech stack

Area	Choice
Language	Kotlin 2.4.10 (using AGP 9 built-in Kotlin)
UI	Jetpack Compose, BOM 2026.06.01, Material 3
Build	Gradle 9.3.1, Android Gradle Plugin 9.1.0
Storage access	`MANAGE_EXTERNAL_STORAGE` ("All files access") with a Storage Access Framework fallback
Archives	Apache Commons Compress + XZ for Java (both pure Java — no NDK)
SDK levels	`compileSdk`/`targetSdk` 36, `minSdk` 26

targetSdk is 36 because Google Play requires new apps and updates to target Android 16 (API 36) from 31 August 2026.

Project layout

app/src/main/java/de/softwareapp_hb/filemanager/
├── core/      Pure-Kotlin engine (no Android imports!) — paths, sorting, formatting,
│              search matching, copy/move planning, conflict policy
├── data/      Storage backends (all-files access + SAF), volumes, shares coming in
│              from other apps, the trash index (SQLite), file operations, archives,
│              deletion
├── domain/    Browser + operation controllers, models, permission state
├── service/   Foreground service for long-running file operations
├── ui/        Compose theme, browser screen, components, ViewModels
└── text/      Domain enum → string-resource mapping
app/src/test/java/…            JVM unit tests for the core engine

core/ deliberately has no Android dependencies, so the trickiest logic is covered by fast JVM tests.

The per-file index — what each file holds, and every test name in the suite — is docs/CODE_MAP.md, generated from the source by tools/make-code-map.py (--check fails when it is stale). AGENTS.md is the one-page briefing for whoever picks the repository up: the commands, the layout and its dependency direction, the rules that have tests behind them, and the traps worth knowing before spending an hour on them.

Building

Prerequisites:

JDK 17+ (JDK 25 verified)
Android SDK with platforms;android-36 and build-tools;36.0.0

# Tell Gradle where the SDK lives (this file is git-ignored)
echo "sdk.dir=$HOME/Android/Sdk" > local.properties

./gradlew :app:assembleDebug        # debug APK
./gradlew :app:testDebugUnitTest    # JVM unit tests for the engine
./gradlew :app:lintDebug            # Android Lint
./gradlew :app:bundleRelease        # Play upload bundle (.aab)

Release signing is optional and driven by a git-ignored keystore.properties (see keystore.properties.example); without it the release build still runs R8/minification but produces an unsigned artefact.

Tracked in git

Source, resources and Gradle build files.
docs/ — the roadmap, the generated code map and the release documentation.
PRIVACY.md, CHANGELOG.md, AGENTS.md, and (from M10) store-assets/.

Not tracked: local.properties, keystore.properties, *.jks, build outputs.

Releasing

Release signing is driven by the git-ignored keystore.properties (see keystore.properties.example). Without that file the release build still runs R8 and resource shrinking, but produces an unsigned artefact that cannot be uploaded.

./gradlew :app:bundleRelease                      # Play upload bundle (.aab)
./gradlew :app:assembleRelease                    # APK, for local checks

# Audit what is actually shipped — in particular that there is no INTERNET permission:
$ANDROID_HOME/build-tools/36.0.0/aapt2 dump permissions \
  app/build/outputs/apk/release/app-release.apk

Read docs/PLAY_RELEASE_CHECKLIST.md before uploading. Step 4 is the one that matters most for this app: a file manager must declare "All files access" through Play's Permissions Declaration Form, and have the core purpose documented in its store description. PRIVACY.md is written to match the shipped permissions.

Localisation

All user-visible text lives in app/src/main/res/values/strings.xml, with real <plurals> wherever a count can be one, and the screen and the progress notification resolve their labels through text/TextRes.kt so the two cannot drift apart. English is currently the only locale.

Adding a language is then a file, not a refactor:

app/src/main/res/values-de/strings.xml   # same keys, translated values

Deliberately not localised, and why:

Byte units ("KB", "MB") — symbols, not words, and every file manager and the system Settings app show them the same way.
The timestamp pattern (yyyy-MM-dd HH:mm) — a fixed, sortable format; the zone is passed in explicitly rather than assumed.

Checking that nothing was missed

Two things are easy to get wrong: a literal typed into a composable, and showing an enum constant directly (FileKind.name puts untranslatable English on screen — the details sheet used to do exactly that). The mechanical check is the pseudo-locale:

./gradlew :app:assembleDebug
# Settings > System > Languages > English (XA), then launch the debug build.

The debug build type sets isPseudoLocalesEnabled = true, so every string that came from strings.xml renders accented and bracketed ([Îmàgé]). Anything that looks normal is a string that never went through resources. The release build is unaffected.

One caveat: Google Play's automatic translation translates your store listing, not the app UI. Translated UI text has to be supplied in values-<locale>/.

Known limitations

The trash is a time window, not a bin you manage. A delete stages the item in a hidden .plainfiles-trash folder on the same volume and keeps it for 24 hours; the Trash entry in the overflow menu lists what is still there and puts a whole batch back. There is no "empty it now" action — expired batches are swept the next time something is deleted — and a name taken again in the meantime is never overwritten, so a restored item can arrive beside the new one rather than replacing it.
Where a trashed item came from is remembered in the app's own database, not on the volume. The staged files are the truth and the database is only an index, so the two are reconciled in both directions: an entry whose file has gone is not offered back, and a batch folder no entry mentions is swept.
Sharing a file out only works in the all-files mode. A SAF path is relative to the granted tree rather than a filesystem path, so it cannot be handed to FileProvider. Receiving a share and being picked from another app's chooser work either way: the first needs no filesystem path, and the second falls back to RESULT_CANCELED rather than returning a URI the caller could not read.
RAR, CAB, ISO and WIM are refused, not supported — they need native code, which this project deliberately does not ship. (The Commons Compress jar contains no RAR classes at all.) 7z is different: Commons Compress reads it in pure Java, so it is supported — but the format needs a seekable channel rather than a stream, because its header lives at the end of the file. All-files access can supply one; the SAF fallback cannot, so 7z extraction reports that plainly in folder mode instead of half-working.
7z files can be opened but not created — writing stays ZIP-only.
Archive extraction does not restore original timestamps or permissions, and there is no archive encryption or password support.
Cancellation happens between entries, so a single very large file finishes before a stop is honoured.
A batch rename is refused rather than half-done when one of its names is taken, including when the file holding that name is part of the same batch: a.txt taking a (1).txt while a (1).txt is itself being renamed needs the files shuffled through temporary names, so the dialog names the file in the way instead. Renaming in the other order, or starting the numbering past the block, does what you want.
A library is not restored across process death. The persisted view state holds a path, and a library has none, so a restart returns to the root screen rather than to Images or Recent.
Long-press multi-select is awkward to script from the host. The gesture that opens the selection bar (input swipe x y x y 900) works on the MIUI test device but has also registered as a plain tap, so compress/extract from the UI wants a manual pass (see docs/EDGE_CASE_TESTING.md).
The display name is still the working title — decided before the first upload (M10).

Monetisation

One-time paid: €4.49 base, with a €2.29 launch price for the first 14 days. No ads, no subscription, no in-app purchases, no free tier.

The price lives on the Play listing, not in the build, which is why there is no Billing client in the dependencies and no com.android.vending.BILLING permission in the APK — that is what keeps "no network permission, nothing leaves your device" true of the shipped artefact rather than just the source. Rationale, market anchors, the rejected alternatives and the Console steps: docs/MONETISATION.md.

⚠️ The price must be set before the first upload — Play allows paid → free but never free → paid.

Competitive context

The category leader is File Manager Plus (AlphaInventor; 100 M+ installs, 4.7–4.8★, free with ads and in-app purchases, and a Data Safety form that shares device IDs with third parties). What it offers, what its users praise, what they complain about, and which of those complaints this app can answer without asking for a single new permission: docs/COMPETITIVE_ANALYSIS.md.

12 KiB Raw Blame History Unescape Escape