add termux example to docs (see #147 and #149)

app/src/main/java/de/jrpie/android/launcher/ui/widgets/manage/ManageWidgetsActivity.kt

@@ -147,13 +147,17 @@ class ManageWidgetsActivity : UIObject, Activity() {
     private fun createWidget(data: Intent) {
         Log.i("Launcher", "creating widget")
         val appWidgetManager = (application as Application).appWidgetManager
+        val appWidgetHost = (application as Application).appWidgetHost
         val appWidgetId = data.extras?.getInt(AppWidgetManager.EXTRA_APPWIDGET_ID) ?: return
 
-        val provider = appWidgetManager.getAppWidgetInfo(appWidgetId)
-
         val display = windowManager.defaultDisplay
 
         val widgetInfo = appWidgetManager.getAppWidgetInfo(appWidgetId)
+        if (widgetInfo == null) {
+            Log.w("Launcher", "can't access widget")
+            appWidgetHost.deleteAppWidgetId(appWidgetId)
+            return
+        }
 
         val position = WidgetPosition.findFreeSpace(
             WidgetPanel.byId(panelId),
@@ -161,7 +165,7 @@ class ManageWidgetsActivity : UIObject, Activity() {
             max(3, (GRID_SIZE * (widgetInfo.minHeight) / display.height.toFloat()).roundToInt())
         )
 
-        val widget = AppWidget(appWidgetId, position, panelId, provider)
+        val widget = AppWidget(appWidgetId, position, panelId, widgetInfo)
         LauncherPreferences.widgets().widgets(
             (LauncherPreferences.widgets().widgets() ?: HashSet()).also {
                 it.add(widget)

docs/actions-and-gestures.md

@@ -1,4 +1,4 @@
-# Gestures and Actions
+# Actions and Gestures
 
 µLauncher's central mechanism for accessing important functionality quickly
 is to bind actions (e.g. launching an app) to gestures (e.g. swiping up).

docs/alternatives.md

@@ -0,0 +1,3 @@
+
+TODO: move the [hedgedoc](https://pad.abstractnonsen.se/foss-launchers) document here.
+<meta http-equiv="refresh" content="0; url=https://pad.abstractnonsen.se/foss-launchers" />

docs/changes-fork.md

@@ -1,3 +1,7 @@
++++
+title = 'Differences to the original Launcher'
++++
+
 # Notable changes compared to Finn's Launcher
 
 µLauncher is a fork of [finnmglas's app Launcher](https://github.com/finnmglas/Launcher).
@@ -51,6 +55,5 @@ 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)
-
-\[hack-font\]: [https://sourcefoundry.org/hack/](https://sourcefoundry.org/hack/)
+[original-repo]: https://github.com/finnmglas/Launcher
+[hack-font]: https://sourcefoundry.org/hack/

docs/contributing.md

@@ -13,7 +13,7 @@ There are several ways to contribute to this app:
   - Open a new pull request.
 
 
-See [build.md](build.md) for instructions how to build this project.
+See [here](/docs/build) for instructions how to build this project.
 The [CI pipeline](https://github.com/jrpie/Launcher/actions) automatically creates debug builds.
 
 

docs/examples/_index.md

@@ -0,0 +1,2 @@
+# Examples
+This section contains some examples how μLauncher can be tweaked.

docs/examples/termux/index.md

@@ -0,0 +1,23 @@
++++
+  title = 'Integration with Termux'
++++
+
+# Termux
+
+μLauncher has no special support for [Termux](https://termux.dev/).
+However it is possible to run Termux commands from μLauncher by using [Termux:Widget](https://wiki.termux.com/wiki/Termux:Widget) to create a pinned shortcut and bind that to a gesture.
+
+* Install Termux:Widget.
+* Make sure that μLauncher is set as the default home screen.[^1]
+* Put the script you want to run into `~/.shortcuts/`.
+* Run `am start com.termux.widget/com.termux.widget.TermuxCreateShortcutActivity`. This will create a pinned shortcut which is treated like an app by μLauncher, i.e. open μLauncher's activity to create a shortcut.
+
+<img src="./screenshot1.png"
+     alt="screenshot"
+     width="200" height="400">
+<img src="./screenshot2.png"
+     alt="screenshot"
+     width="200" height="400">
+
+
+[^1]: Only the default home screen can access shortcuts.

docs/home.md

@@ -1,43 +0,0 @@
-# Welcome to the μLauncher Documentation
-
-## What is μLauncher?
-
-µLauncher is an *minimal* and *distraction-free* Android home screen that lets you launch apps using [swipe gestures and button presses](/actions-and-gestured.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?
-
-[![Get it on F-Droid](https://fdroid.gitlab.io/artwork/badge/get-it-on.png)](https://f-droid.org/packages/de.jrpie.android.launcher/)
-
-[![Get it on Accrescent](https://accrescent.app/badges/get-it-on.png)](https://accrescent.app/app/de.jrpie.android.launcher.accrescent)
-
-[![Get it on Obtainium](https://raw.githubusercontent.com/ImranR98/Obtainium/b1c8ac6f2ab08497189721a788a5763e28ff64cd/assets/graphics/badge_obtainium.png)](https://apps.obtainium.imranr.dev/redirect?r=obtainium://app/{%22id%22:%22de.jrpie.android.launcher%22,%22url%22:%22https://github.com/jrpie/Launcher%22,%22author%22:%22jrpie%22,%22name%22:%22%c2%b5Launcher%22,%22additionalSettings%22:%22{\%22apkFilterRegEx\%22:\%22release\%22,\%22invertAPKFilter\%22:false,\%22about\%22:\%22%c2%b5Launcher%20is%20a%20minimal%20home%20screen.\%22}%22})
-
-[![Get it on GitHub](https://raw.githubusercontent.com/NeoApplications/Neo-Backup/034b226cea5c1b30eb4f6a6f313e4dadcbb0ece4/badge_github.png)](https://github.com/jrpie/launcher/releases/latest)
-
-> 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](/contribute.md)
-
-## Screenshots
-
-![μLauncher Home Screen screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/1.jpg)
-
-![μLauncher Settings screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/2.jpg)
-
-![μLauncher All Apps list view with icons screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/3.jpg)
-
-![μLauncher Favorite Apps list view with icons screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/4.jpg)
-
-![μLauncher Choose App to bind to gesture screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/5.jpg)
-
-![μLauncher App options card from list view with icons screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/7.jpg
-)
-
-![μLauncher All Apps list view without icons screenshot](https://github.com/jrpie/launcher/blob/master/fastlane/metadata/android/en-US/images/phoneScreenshots/8.jpg)
-
-<!-- missing μLauncher grid view screenshot-->

docs/settings.md

@@ -1,19 +1,18 @@
-# Launcher Settings
+# Settings
 
-Tweaks and customizations can be made from within the Launcher Settings page.
+Tweaks and customizations can be made from within the settings page.
+The settings can be opened by binding the Settings action to a gesture (this is especially useful when configuring μLauncher for the first time) or from the settings icon in the app drawer.[^1]
 
-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', 'Favorite Apps' and 'Private Space' views.
+[^1]: i.e. the 'All Apps', 'Favorite Apps' and 'Private Space' views.
 
 ## Appearance
 
-> ### Choose a wallpaper
+### Choose a wallpaper
 
 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)
+### Font (in-app font)
 
 Set the font used within the app settings. This setting does not affect the date/time home screen font.
 
@@ -21,17 +20,17 @@ Set the font used within the app settings. This setting does not affect the date
 
 **options:** `Hack`,`System default`,`Sans serif`,`Serif`,`Monospace`,`Serif monospace`
 
-> ### Text Shadow
+### Text Shadow
 
 **type:** `toggle`
 
-> ### Background (app list and setting)
+### Background (app list and setting)
 
 **type:** `dropdown`
 
 **type:** `Transparent`,`Dim`,`Blur`,`Solid`
 
-> ### Monochrome app icons
+### Monochrome app icons
 
 Remove coloring from all app icons. Can help decrease visual stimulus when enabled.
 
@@ -39,49 +38,56 @@ Remove coloring from all app icons. Can help decrease visual stimulus when enabl
 
 ## Date & Time
 
-> ### Font (home screen)
+These settings effect the clock shown on the home screen (or on widget panels).
+If the clock is removed, the settings are not used.
 
-Set the home screen font for date and time. This setting does not affect the in-app font.
+### Font (home screen)
+
+Set the home screen font for date and time. This setting does not affect the font of other components.
 
 **type:** `dropdown`
 
 **options:** `Hack`,`System default`,`Sans serif`,`Serif`,`Monospace`,`Serif monospace`
 
-> ### Color [`[bug]`](https://github.com/jrpie/launcher/issues/151)
+### Color
 
 Set the color for the home screen date and time.
 
-Accepts a HEX color code (consisting of a '#' followed by three sets of two alphanumeric (letters and numbers) characters. A fourth set of two alphanumeric characters may be added to set the transparency of the color.
+Accepts an 6 digit RGB or or 8 digit ARGB color code characters.[^2]
+Note that on Android the ARGB color format is used, i.e. the alpha component is specified first.
+This differs from the more common RGBA, which is used in web development.
 
-[Color wheel picker](https://rgbacolorpicker.com/color-wheel-picker)
 
-**type:** `HEX`,`RGBA`
+[^2]: More precisely, everything that is vaild input for [parseColor](https://developer.android.com/reference/android/graphics/Color#parseColor(java.lang.String)) can be used.
 
-> ### Use localized date format
 
-Adapt the display of dates and times to the specific conventions of a particular locale or region. Different locales use different date orders (e.g., MM/DD/YYYY in the US, DD/MM/YYYY in Europe).
+**type:** `ARGB`
+
+### Use localized date format
+
+Adapt the display of dates and times to the specific conventions of a particular locale or region as set by the system. Different locales use different date orders (e.g., MM/DD/YYYY in the US, DD/MM/YYYY in Europe).
 
 **type:** `toggle`
 
-> ### Show time
+### Show time
 
 Show the current time on the home screen.
 
 **type:** `toggle`
 
-> ### Show seconds
+### Show seconds
 
 Show the current time down to the second on the home screen.
 
 **type:** `toggle`
 
-> ### Show date
+### Show date
 
 Show the current date on the home screen.
 
 **type:** `toggle`
 
-> ### Flip date and time
+### Flip date and time
 
 Place the current time above the current date on the home screen.
 
@@ -89,7 +95,7 @@ Place the current time above the current date on the home screen.
 
 ## Functionality
 
-> ### Launch search results
+### Launch search results
 
 Launches any app that matches user keyboard input when no other apps match.
 
@@ -105,37 +111,37 @@ Press space to temporarily disable this feature and allow text entry without pre
 
 **type:** `toggle`
 
-> ### Search the web
+### Search the web
 
-Press return/enter while searching the app list to launch a web search.
+Press return while searching the app list to launch a web search.
 
 **type:** `toggle`
 
-> ### Start keyboard for search
+### Start keyboard for search
 
 Automatically open the keyboard when the app drawer is opened.
 
 **type:** `toggle`
 
-> ### Double swipe gestures
+### Double swipe gestures
 
 Enable double swipe (two finger) gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
 
 **type:** `toggle`
 
-> ### Edge swipe gestures
+### Edge swipe gestures
 
 Enable edge swipe (near edges of screen) gestures in launcher settings. Does not erase gesture bindings if accidentally turned off.
 
 **type:** `toggle`
 
-> ### Edge width
+### Edge width
 
 Change how large a margin is used for detecting edge gestures. Shows the edge margin preview when using the slider.
 
 **type:** `slider`
 
-> ### Choose method for locking the screen
+### Choose method for locking the screen
 
 There are two methods to lock the screen and unfortunately both have downsides.
 
@@ -157,11 +163,11 @@ There are two methods to lock the screen and unfortunately both have downsides.
 
 ## Apps
 
-> ### Hidden apps
+### Hidden apps
 
 Open an app drawer containing only hidden apps.
 
-> ### Don't show apps that are bound to a gesture in the app list
+### Don't show apps that are bound to a gesture in the app list
 
 Remove certain apps from the app drawer if they are already accessible via a gesture.
 
@@ -169,20 +175,21 @@ Reduces redundancy and tidies up app drawer.
 
 **type:** `toggle`
 
-> ### Hide paused apps
+### 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`
 
-> ### Hide private space from app list
+### Hide private space from app list
 
 Remove private space from app drawer.
+Private space apps can be accessed using a separate app drawer which can be opened with the Private Space action.
 
 **type:** `toggle`
 
-> ### Layout of app list
+### Layout of app list
 
 Changes how the apps are displayed when accessing the app drawer.
 
@@ -195,7 +202,7 @@ Changes how the apps are displayed when accessing the app drawer.
 
 **options:** `Default`,`Text`,`Grid`
 
-> ### Reverse the app list
+### Reverse the app list
 
 Enable reverse alphabetical sorting of apps in the app drawer.
 Useful for keeping apps within easier reach from the keyboard.
@@ -204,21 +211,21 @@ Useful for keeping apps within easier reach from the keyboard.
 
 ## Display
 
-> ### Rotate screen
+### Rotate screen
 
 **type:** `toggle`
 
-> ### Keep screen on
+### Keep screen on
 
 **type:** `toggle`
 
-> ### Hide status bar
+### Hide status bar
 
 Remove the top status bar from the home screen.
 
 **type:** `toggle`
 
-> ### Hide navigation bar
+### Hide navigation bar
 
 Remove the navigation bar from the home screen. Enabling this setting may make it difficult to use the device if gestures are not setup properly.
 
@@ -226,7 +233,7 @@ Remove the navigation bar from the home screen. Enabling this setting may make i
 
 ## Additional Settings
 
-> ### App Drawer Long Press on App
+### App Drawer Long Press on App
 
 Access additional per-app details and settings. To use, open the app drawer and long press on any app.
 

docs/widgets.md

@@ -0,0 +1,27 @@
++++
+  title = 'Widgets'
++++
+
+# Widgets
+
+μLauncher allows to add [app widgets](https://developer.android.com/develop/ui/views/appwidgets/overview) to the home screen and to widget panels.
+
+Widgets can be added, moved, removed and configured in `Settings > Manage Widgets`.
+
+It is configurable whether or not interaction with a widget should be enabled.
+
+* If interaction is enabled, touch events are forwarded to the widget as usual.
+However, μLauncher [gestures](/docs/actions-and-gestures/) can not be executed in areas where such a widget is present.
+
+* If interaction is disabled, the widget does not respond to any touch events.
+    This is recommended when using a widget only to display information.
+
+μLauncher's clock behaves similar as an app widget and can be managed in the same way.[^1]
+
+[^1]: However, it is technically not an app widget and cannot be used with other launchers.
+
+# Widget Panels
+
+Widget panels can contain widgets that are not needed on the home screen.
+They can be managed in `Settings > Manage Widget Panels`.
+Widget panels can be opened by using the [Open Widget Panel](/docs/actions-and-gestures/#available-actions) action.