improved documentation

.scripts/release.sh

@@ -1,9 +1,25 @@
 #!/bin/bash
+
+# This script builds all variants of µLauncher to create a release, namely:
+# - app-release.apk (GitHub release; used by F-Droid for reproducible builds)
+# - launcher-accrescent.apks (Accrescent)
+# - app-release.aab (Play Store)
+
+# This is only intended to work on my (@jrpie) computer.
+# To use this script for building a fork you need to:
+#   - install bundletool.jar and
+#   - create a keystore and modify the variables below accordingly
+
 export JAVA_HOME="/usr/lib/jvm/java-21-openjdk/"
 OUTPUT_DIR="$HOME/launcher-release"
 BUILD_TOOLS_DIR="$HOME/Android/Sdk/build-tools/35.0.0"
+
+# keystore for the default release
 KEYSTORE="$HOME/data/keys/launcher_jrpie.jks"
+# keystore for the default accrescent release
 KEYSTORE_ACCRESCENT="$HOME/data/keys/launcher_jrpie_accrescent.jks"
+
+# keepassxc-password is a custom script to fetch passwords from my password manager
 KEYSTORE_PASS=$(keepassxc-password "android_keys/launcher")
 KEYSTORE_ACCRESCENT_PASS=$(keepassxc-password "android_keys/launcher-accrescent")
 
@@ -11,12 +27,11 @@ if [[ $(git status --porcelain) ]]; then
     echo "There are uncommitted changes."
 
     read -p "Continue anyway? (y/n) " -n 1 -r
-    echo    # (optional) move to a new line
+    echo
     if ! [[ $REPLY =~ ^[Yy]$ ]]
     then
         exit 1
     fi
-
 fi
 
 rm -rf "$OUTPUT_DIR"

app/src/main/res/values/strings.xml

@@ -159,9 +159,9 @@
 
     <string name="settings_launcher_section_functionality">Functionality</string>
 
-    <string name="settings_enabled_gestures_double_swipe">Double swipe actions</string>
+    <string name="settings_enabled_gestures_double_swipe">Double swipe gestures</string>
     <string name="settings_enabled_gestures_double_swipe_summary">Swipe with two fingers</string>
-    <string name="settings_enabled_gestures_edge_swipe">Edge swipe actions</string>
+    <string name="settings_enabled_gestures_edge_swipe">Edge swipe gestures</string>
     <string name="settings_enabled_gestures_edge_swipe_summary">Swipe at the edge of the screen</string>
     <string name="settings_enabled_gestures_edge_swipe_edge_width">Edge width</string>
     <string name="settings_functionality_auto_launch">Launch search results</string>

docs/Contributing.md

@@ -1,17 +0,0 @@
-# Contributing
-
-## Ways to contribute
-
-- Found a **bug** or have an idea for a **new feature**? [Join the chat](https://s.jrpie.de/launcher-chat) or open an [issue](https://github.com/jrpie/Launcher/issues/).
-
-    > Please note that I work on this project in my free time. Thus I might not respond immediately and not all ideas will be implemented.
-
-- Implement a new feature yourself:
-
-    1. [Fork](https://github.com/jrpie/launcher/fork) this repository.
-    2. Create a **new branch** named *feature/\<your feature\>* or *fix/\<your fix\>* and commit your changes.
-    3. Open a new pull request.
-
-- Add or improve [translations](https://toolate.othing.xyz/projects/jrpie-launcher/).
-
-![translation status](https://toolate.othing.xyz/widget/jrpie-launcher/launcher/horizontal-auto.svg)

docs/Gestures-and-Bindings.md

@@ -1,58 +0,0 @@
-# Gestures and Bindings
-
-## Available Gestures
-
-### Swipes
-
-- Up, down, left, or right.
-- Up, down, left, or right with two fingers.
-- Up or down on the left or right edge.
-- Left or right on the top or bottom edge.
-
-### Taps
-
-- Tap on date or time.
-- Double tap.
-- Long tap.
-
-### Tap-then-Swipes
-
-Tap then swipe up, down, left, or right
-
-### Complex Gestures
-
-- Draw <, >, V, or Λ.
-- Draw <, >, V, or Λ in reverse direction.
-
-### Hardware Buttons as Gestures
-
-- Back button.
-- Volume up or down button.
-
-***
-
-## Available Bindings
-
-Any of the above gestures can be bound to any of the following bindings.
-
-### Launcher Bindings
-
-- Open µLauncher settings.
-- Open a list of all*, favorite, or private* apps.
-
-### App Bindings
-
-- Launch an app.
-- Launch another Home Screen.
-
-### Android / Device Bindings
-
-- Toggle private space lock.
-- Lock the screen.
-- Toggle the torch (flashlight)
-- Raise or lower volume.
-- Skip to previous or next audio track.
-- Open Notifications shade.
-- Open Quick Settings shade.
-
-> \* excludes apps hidden by the user

docs/Work-Profile.md

@@ -1,4 +0,0 @@
-# Android Enterprise Work Profile
-
-µLauncher is compatible with [work profile](https://www.android.com/enterprise/work-profile/), so apps like [Shelter](https://gitea.angry.im/PeterCxy/Shelter) can be used.
-

docs/actions-and-gestures.md

@@ -0,0 +1,71 @@
+# Gestures and Actions
+
+µLauncher's central mechanism for accessing important functionality quickly
+is to bind actions (e.g. launching an app) to gestures (e.g. swiping up).
+These bindings can be configured in µLauncher Settings > ACTIONS.
+
+
+## Available Gestures
+
+### Swipes
+
+- Basic swipes: Swipe up, down, left, or right
+- Double swipes: Swipe up, down, left, or right with two fingers
+- Edge swipes:
+  - Swipe up or down on the left or right edge
+  - Swipe left or right on the top or bottom edge
+
+  The size of the edges is configurable in settings.
+  For a swipe to be detected as an edge swipe, the finger must not leave the respective edge region while swiping.
+
+### Taps
+
+- Tap on date or time
+- Double tap
+- Long click
+
+### Tap-then-Swipes
+
+- Tap then swipe up, down, left, or right
+
+    To execute these gesture consistently, it is helpful to think of them as double taps,
+    where the finger stays on the screen after the second tap and then does a swipe.
+    The swipe must start very shortly after the tap ended.
+
+### Complex Gestures
+
+- Draw <, >, V, or Λ
+- Draw <, >, V, or Λ in reverse direction
+
+### Hardware Buttons as Gestures
+
+- Back button (or back gesture if gesture navigation is enabled)
+- Volume buttons
+
+***
+
+## Available Actions
+
+To any of the available gestures, one of the following actions can be bound:
+
+- Launch an app (or a pinned shortcut)
+- Open a widget panel.
+    Widget panels can hold widgets that are not needed on the home screen itself.
+    They can be created and managed in µLauncher Settings > Manage Widget Panels
+- Open a list of all, favorite, or private apps (hidden apps are excluded).
+    Actions related to private space are only shown if private space is set up on the device.
+    µLauncher's settings can be accessed from those lists.
+    If private space is set up, an icon to (un)lock it is shown on the top right.
+- Open µLauncher's settings
+- Toggle private space lock
+- Lock the screen: This allows to lock the screen.
+    There are two mechanisms by which the screen can be locked, accessibility service and device admin.
+- Toggle the flashlight
+- Raise, lower or adjust volume
+- Play or pause media playback
+- Skip to previous or next audio track
+- Open notifications panel: Might be useful if the top of your screen is broken.
+- Open quick settings panel: Why swipe down twice?
+- Open [recent apps](https://developer.android.com/guide/components/activities/recents): Requires accessibility service. Can be used as a workaround for a Android bug.
+- Launch another home screen: Allows using another installed home screen temporarily.
+- Do nothing: Just prevents showing the message saying that no action is bound to this gesture.

docs/build.md

@@ -42,4 +42,4 @@ for further instructions. How to
 ## CI Pipeline
 
 The [CI pipeline](https://github.com/jrpie/Launcher/actions) automatically creates debug builds.
-> Note: These builds are *not* signed.
+> Note: These builds are *not* signed. They are in built in debug mode and only suitable for testing.

docs/changes-fork.md

@@ -14,12 +14,15 @@ The decision to create a hard fork was made two years later.-->
 
 - Compatible with [work profile](https://www.android.com/enterprise/work-profile/), so apps like [Shelter](https://gitea.angry.im/PeterCxy/Shelter) can be used.
 - Compatible with [private space](https://source.android.com/docs/security/features/private-space)
+- Support for [app widgets](https://developer.android.com/develop/ui/views/appwidgets/overview)
+- Support for [pinned shortcuts](https://developer.android.com/develop/ui/views/launch/shortcuts/creating-shortcuts)
 - Option to rename apps
 - Option to hide apps
 - Favorite apps
 - New actions:
   - Toggle Torch
   - Lock screen
+  - Open a widget panel
 - The home button now works as expected.
 - Improved gesture detection.
 
@@ -48,6 +51,6 @@ The complete list of changes can be viewed [here](https://github.com/jrpie/launc
 
 ---
 
-\[original-repo\]: [https://github.com/finnmglas/Launcher](https://github.com/finnmglas/Launcher) 
+\[original-repo\]: [https://github.com/finnmglas/Launcher](https://github.com/finnmglas/Launcher)
 
 \[hack-font\]: [https://sourcefoundry.org/hack/](https://sourcefoundry.org/hack/)

docs/contributing.md

@@ -0,0 +1,24 @@
+# Contributing
+
+There are several ways to contribute to this app:
+* You can add or improve [translations][toolate].
+     <br><img src="https://toolate.othing.xyz/widget/jrpie-launcher/launcher/horizontal-auto.svg" alt="translation status">
+* If you found a bug or have an idea for a new feature you can [join the chat][chat] or open an [issue][issues].
+
+    > Please note that I work on this project in my free time. Thus I might not respond immediately and not all ideas will be implemented.
+
+* You can implement a new feature yourself:
+  - Create a [fork][fork] of this repository.
+  - Create a new branch named `feature/<your feature>` or `fix/<your fix>` and commit your changes.
+  - Open a new pull request.
+
+
+See [build.md](build.md) for instructions how to build this project.
+The [CI pipeline](https://github.com/jrpie/Launcher/actions) automatically creates debug builds.
+
+
+---
+  [fork]: https://github.com/jrpie/Launcher/fork/
+  [issues]: https://github.com/jrpie/Launcher/issues/
+  [chat]: https://s.jrpie.de/launcher-chat
+  [toolate]: https://toolate.othing.xyz/projects/jrpie-launcher/

docs/home.md

@@ -1,12 +1,12 @@
-# Welcome to the μLauncher wiki
+# Welcome to the μLauncher Documentation
 
-We're thrilled you're here and confident you'll love your new Android launcher! Check out this wiki to get familiar with your new app.
+## What is μLauncher?
 
-## What is μLauncher
+µLauncher is an *minimal* and *distraction-free* Android home screen that lets you launch apps using [swipe gestures and button presses](docs/actions-and-gestured.md).
 
-µLauncher is an *minimal* and *distraction-free* Android home screen that lets you launch apps using *efficient* swipe gestures and button presses. This project is a fork of [finnmglas's app Launcher](https://github.com/finnmglas/Launcher). An incomplete list of changes can be found [here](https://github.com/wassupluke/Launcher/blob/master/docs/launcher.md).
+This project is a fork of [finnmglas's app Launcher](https://github.com/finnmglas/Launcher). An incomplete list of changes can be found [here](https://github.com/wassupluke/Launcher/blob/master/docs/launcher.md).
 
-## Where can I get μLauncher
+## Where can I get μLauncher?
 
 [![Get it on F-Droid](https://fdroid.gitlab.io/artwork/badge/get-it-on.png)](https://f-droid.org/packages/de.jrpie.android.launcher/)
 
@@ -18,6 +18,11 @@ We're thrilled you're here and confident you'll love your new Android launcher!
 
 > You can also [get it on Google Play](https://play.google.com/store/apps/details?id=de.jrpie.android.launcher), but this is not recommend.
 
+
+## How can I contribute?
+
+See [docs/contribute](docs/contribute.md)
+
 ## Screenshots
 
 ![μLauncher Home Screen screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/1.jpg)

docs/profiles.md

@@ -0,0 +1,21 @@
+# Work Profile
+
+µLauncher is compatible with [work profile](https://www.android.com/enterprise/work-profile/), so apps like [Shelter](https://gitea.angry.im/PeterCxy/Shelter) can be used.
+Apps from the work profile are shown in the usual app list.
+
+
+# Private Space
+
+µLauncher is compatible with [private space](https://source.android.com/docs/security/features/private-space).
+
+
+The private space can be (un)locked by a dedicated action.
+
+It is configurable whether apps from private space are
+
+1. shown in the usual app list
+    (in this case, (un)locking is accessible through a lock icon on the top right of the app drawer)
+    or
+2. only shown in a separate list.
+
+

docs/settings.md

@@ -4,13 +4,14 @@ Tweaks and customizations can be made from within the Launcher Settings page.
 
 These settings let you change wallpapers, change colors and fonts, enable monochrome app icons, change the app drawer layout, and much more.
 
-In the following documentation, 'app drawer' will be used to refer to the 'All Apps' and 'Favorite Apps' views.
+In the following documentation, 'app drawer' will be used to refer to the 'All Apps', 'Favorite Apps' and 'Private Space' views.
 
 ## Appearance
 
 > ### Choose a wallpaper
 
-Lets you change the wallpaper using a photos app, file explorer, or native wallpaper setting app.
+This triggers Android's mechanism to change the wallpaper using a photos app, file explorer, or native wallpaper setting app.
+µLauncher uses the system-wide wallpaper, i.e. this change also affects other launchers.
 
 > ### Font (in-app font)
 
@@ -92,11 +93,15 @@ Place the current time above the current date on the home screen.
 
 Launches any app that matches user keyboard input when no other apps match.
 
-As you type inside the app drawer, the app narrows down the list of apps shown based on the app title matching your text input. For example, if you type, `a`, the app list narrows to any apps with a title containing the letter `a`. Continuing the example, if you then follow your `a` with the letter `m`, the list now shows only apps containing the letter combination `am` in that order. If the only app matching this combination was, for example, `Amazon`, simply typing `am` in the app drawer would immediately launch the `Amazon` app for you.
+As you type inside the app drawer, the app narrows down the list of apps shown based on the app title matching your text input.
+With the 'launch search results' setting, once only one matching app remains, it is launched immediately.
+Usually it suffices to type two or three characters the single out the desired app.
 
-This feature becomes more powerful when combined with [renaming](https://github.com/wassupluke/Launcher/wiki/Launcher-Settings/_edit#additional-settings) apps, effectively letting you define custom app names that could be considered 'aliases' or shortcuts. For instance, if you wanted to "bind" the keyboard input `gh` to open your `GitHub` app, you could rename `GitHub` to `GitHub gh`, `gh GitHub`, or simply `gh`. Assuming no other installed apps have the `gh` combination of letters in them, opening the app drawer and typing `gh` would immediately launch your `GitHub` app.
+This feature becomes more powerful when combined with [renaming](#additional-settings) apps, effectively letting you define custom app names that could be considered 'aliases' or shortcuts.
+For instance, if you want the keyboard input `gh` to open your `GitHub` app, you could rename `GitHub` to `GitHub gh`, `gh GitHub`, or simply `gh`.
+Assuming no other installed apps have the `gh` combination of letters in them, opening the app drawer and typing `gh` would immediately launch your `GitHub` app.
 
-Press space to temporarily disable this feature and allow text entry without prematurely launching an app. Useful when combined with the [Search the web](https://github.com/wassupluke/Launcher/wiki/Launcher-Settings/_edit#search-the-web) feature.
+Press space to temporarily disable this feature and allow text entry without prematurely launching an app. Useful when combined with the [Search the web](#search-the-web) feature.
 
 **type:** `toggle`
 
@@ -112,15 +117,15 @@ Automatically open the keyboard when the app drawer is opened.
 
 **type:** `toggle`
 
-> ### Double swipe actions
+> ### Double swipe gestures
 
-Enable double swipe (two finger) actions as bindable gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
+Enable double swipe (two finger) gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
 
 **type:** `toggle`
 
-> ### Edge swipe actions
+> ### Edge swipe gestures
 
-Enable edge swipe (near edges of screen) actions as bindable gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
+Enable edge swipe (near edges of screen) gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
 
 **type:** `toggle`
 
@@ -167,6 +172,7 @@ Reduces redundancy and tidies up app drawer.
 > ### Hide paused apps
 
 Remove paused apps from the app drawer.
+For example an app belonging to the work profile is paused when the work profile is inactive.
 
 **type:** `toggle`
 
@@ -178,7 +184,12 @@ Remove private space from app drawer.
 
 > ### Layout of app list
 
-Change how the apps are displayed when accessing the app drawer. By `Default`, all apps in the drawer will show in a vertically-scrolled list with their app icon and title. `Text` removes the app icons, shows only app titles in the drawer as a vertically-scrolled list. `Grid` shows apps with their app icon and title in a grid layout.
+Changes how the apps are displayed when accessing the app drawer.
+
+- `Default`: All apps in the drawer will show in a vertically-scrolled list with their app icon and title.
+- `Text`: Removes the app icons, shows only app titles in the drawer as a vertically-scrolled list.
+    Work profile and private space apps are distinguished by a different label instead of a badge.
+- `Grid`: Shows apps with their app icon and title in a grid layout.
 
 **type:** `dropdown`
 
@@ -186,7 +197,8 @@ Change how the apps are displayed when accessing the app drawer. By `Default`, a
 
 > ### Reverse the app list
 
-Enable Z-A sorting of apps in the app drawer. Useful for keeping apps within easier reach from the keyboard.
+Enable reverse alphabetical sorting of apps in the app drawer.
+Useful for keeping apps within easier reach from the keyboard.
 
 **type:** `toggle`