From b4d7aa16af21dd4734b065fb96d0cd08fcb14cb9 Mon Sep 17 00:00:00 2001
From: MM20 <15646950+MM2-0@users.noreply.github.com>
Date: Wed, 24 May 2023 22:07:55 +0200
Subject: [PATCH] Docs: add icon pack docs

---
 .../external-apis/_category_.yml              |   2 +-
 .../integrations/_category_.yml               |   5 +
 .../integrations/icon-packs.md                | 142 ++++++++++++++++++
 3 files changed, 148 insertions(+), 1 deletion(-)
 create mode 100644 docs/docs/developer-guide/integrations/_category_.yml
 create mode 100644 docs/docs/developer-guide/integrations/icon-packs.md

diff --git a/docs/docs/developer-guide/external-apis/_category_.yml b/docs/docs/developer-guide/external-apis/_category_.yml
index 6b9dac8a..31eabca3 100644
--- a/docs/docs/developer-guide/external-apis/_category_.yml
+++ b/docs/docs/developer-guide/external-apis/_category_.yml
@@ -1,2 +1,2 @@
 label: External APIs
-position: 2
+position: 2
\ No newline at end of file
diff --git a/docs/docs/developer-guide/integrations/_category_.yml b/docs/docs/developer-guide/integrations/_category_.yml
new file mode 100644
index 00000000..480b7de4
--- /dev/null
+++ b/docs/docs/developer-guide/integrations/_category_.yml
@@ -0,0 +1,5 @@
+label: Integrations
+link:
+  type: generated-index
+  title: Integrations
+  description: In this chapter you will learn how external apps can integrate with Kvaesitso.
\ No newline at end of file
diff --git a/docs/docs/developer-guide/integrations/icon-packs.md b/docs/docs/developer-guide/integrations/icon-packs.md
new file mode 100644
index 00000000..fdc67d06
--- /dev/null
+++ b/docs/docs/developer-guide/integrations/icon-packs.md
@@ -0,0 +1,142 @@
+# Icon Packs
+
+Kvaesitso has built-in support for the ADW launcher icon pack format (the format that is nowadays
+used by virtually all icon packs and supported by all major custom launchers).
+
+## Get started
+
+### Android Manifest
+
+In order to be recognized as an icon pack, your app must declare an activity with at least one of
+the following intent filters in your `AndroidManifest.xml`:
+
+```xml
+
+<activity android:name="[...]">
+    <intent-filter>
+        <action android:name="org.adw.ActivityStarter.THEMES" />
+    </intent-filter>
+    <intent-filter>
+        <action android:name="com.novalauncher.THEME" />
+    </intent-filter>
+    <intent-filter>
+        <!-- Themed icons; only add this if your icon pack supports themed icons -->
+        <action android:name="app.lawnchair.icons.THEMED_ICON" />
+    </intent-filter>
+</activity>
+```
+
+### Appfilter
+
+Icons are mapped to apps using a file called `appfilter.xml`. This file must be located in one of
+these locations:
+
+- `res/xml/appfilter.xml` (recommended)
+- `res/raw/appfilter.xml`
+- `assets/appfilter.xml`
+
+The file has the following structure:
+
+```xml
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <!-- icons are added here -->
+</resources>
+```
+
+## Add icons
+
+Icons are added to the `appfilter.xml` file using the `<item>` tag:
+
+```xml
+<item component="ComponentInfo{com.android.deskclock/com.android.deskclock.DeskClockTabActivity}"
+    drawable="clock" />
+```
+
+- `component` is the component name of the target activity. The short form is also supported if the
+  class' package name starts with the app's package
+  name: `ComponentInfo{com.android.deskclock/.DeskClockTabActivity}`
+- `drawable` is the name of the icon drawable which must be located in the `res/drawable/` folder
+  (or any of its variants, e.g. `res/drawable-hdpi/`)
+
+### Autogenerated icons
+
+The launcher can generate fallback icons for apps that don't have an icon in the icon pack.
+Fallback icons consist of four parts:
+
+```xml
+<resources>
+    <scale factor="1.0" />
+    <iconback img="iconback" />
+    <iconupon img="iconupon" />
+    <iconmask img="iconmask" />
+</resources>
+```
+
+- `scale`: the original icon is scaled by this `factor`
+- `iconback`: this is drawn behind the original icon
+- `iconupon`: this is drawn on top of the original icon
+- `iconmask`: this is used to mask the original icon
+
+You can provide multiple variants of each part by adding a number to the `img` attribute:
+
+```xml
+<iconback img1="iconback" img2="iconback2" />
+```
+
+The launcher will then randomly pick one of the variants for each icon.
+
+
+### Dynamic icons
+
+
+#### Calendar icons
+
+Kvaesitso supports Nova
+launcher's [dynamic calendar icon standard](https://github.com/teslacoil/Example_NovaTheme/blob/master/DynamicCalendarIconAPI.md):
+
+To your `appfilter.xml` file, add the following:
+
+```xml
+<calendar component="ComponentInfo{com.google.android.calendar/com.android.calendar.LaunchActivity}"
+    prefix="calendar_" />
+```
+
+`prefix` is the prefix of the icon drawables. You need to provide one drawable for each day of the
+month (`calendar_1`, `calendar_2`, etc. up to `calendar_31`).
+
+:::note
+Single digit days must not be zero-padded (e.g. `calendar_1` is correct but `calendar_01` is not).
+Make sure all 31 drawables are present, or the launcher will reject the icon.
+:::
+
+#### Clock icons
+
+Dynamic clock icons are not supported yet.
+
+### Themed icons
+
+Themed icons are monochrome icons that are tinted to match the theme color of the launcher.
+
+To declare that your icon pack supports themed icons, add the following intent filter to your
+`AndroidManifest.xml`:
+
+```xml
+<intent-filter>
+    <action android:name="app.lawnchair.icons.THEMED_ICON" />
+</intent-filter>
+```
+
+The launcher will then show a toggle in the icon pack picker which allows the user to enable themed
+icons.
+
+Themed icons can be provided in any of the following ways:
+
+- If the icon is an adaptive icon, the device runs at least Android 13 and the drawable has
+  a `<monochrome>` layer, this icon will be used as the themed icon.
+- If the icon is an adaptive icon, and it does not have a `<monochrome>` layer or the device runs on
+  Android 12 or lower, the foreground layer will be used.
+- If the icon is not an adaptive icon, the entire icon will be used.
+
+In any case, the icon will be tinted using the theme color and the background will be set to a solid
+color.