From bb8a0d4c0de54c02e8fc23d48fee6edd03a8d6f8 Mon Sep 17 00:00:00 2001 From: MM20 <15646950+MM2-0@users.noreply.github.com> Date: Mon, 20 May 2024 14:01:46 +0200 Subject: [PATCH] Update icon pack docs --- .../integrations/icon-packs.md | 52 ++++++++++++++----- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/docs/docs/developer-guide/integrations/icon-packs.md b/docs/docs/developer-guide/integrations/icon-packs.md index 0ddc9a68..b5a1b18c 100644 --- a/docs/docs/developer-guide/integrations/icon-packs.md +++ b/docs/docs/developer-guide/integrations/icon-packs.md @@ -1,3 +1,7 @@ +--- +outline: deep +--- + # Icon Packs Kvaesitso has built-in support for the ADW launcher icon pack format (the format that is nowadays @@ -5,7 +9,7 @@ used by virtually all icon packs and supported by all major custom launchers). ## Get started -### Android Manifest +### AndroidManifest.xml 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`: @@ -26,7 +30,7 @@ the following intent filters in your `AndroidManifest.xml`: ``` -### Appfilter +### appfilter.xml Icons are mapped to apps using a file called `appfilter.xml`. This file must be located in one of these locations: @@ -44,7 +48,27 @@ The file has the following structure: ``` -## Add icons +### drawable.xml + +`drawable.xml` is a file that lists all icons that are included in the icon pack. This file is +required for manual icon picking. +The file lives in `res/xml/drawable.xml`, and looks like this: + +```xml + + + + + + + +``` + +Every icon that should be available for manual icon picking must be listed in this file. You can +optionally group icons by adding `` elements, but these categories aren't used by +Kvaesitso. + +## Static icons Icons are added to the `appfilter.xml` file using the `` tag: @@ -60,7 +84,7 @@ Icons are added to the `appfilter.xml` file using the `` tag: - `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 +## 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: @@ -89,9 +113,9 @@ You can provide multiple variants of each part by adding a number to the `img` a The launcher will then randomly pick one of the variants for each icon. -### Dynamic icons +## Dynamic icons -#### Calendar icons +### Calendar icons Kvaesitso supports Nova launcher's [dynamic calendar icon standard](https://github.com/teslacoil/Example_NovaTheme/blob/master/DynamicCalendarIconAPI.md): @@ -111,7 +135,7 @@ month (`calendar_1`, `calendar_2`, etc. up to `calendar_31`). > Single digit days must not be zero-padded (e.g. `calendar_1` is correct but `calendar_01` is not). > Make sure that all 31 drawables are present, or the launcher will reject the icon. -#### Clock icons +### Clock icons Dynamic clock icons are supported as well but they work a bit differently than calendar icons. A dynamic clock icon needs at least two entries in your `appfilter.xml` file: @@ -168,7 +192,8 @@ Here is an example of a clock icon: ``` -Pay attention to how each of the three clock hand layers is wrapped in a `RotateDrawable` and how there are +Pay attention to how each of the three clock hand layers is wrapped in a `RotateDrawable` and how +there are very specific values set for `android:fromDegrees` and `android:toDegrees`. This is required for launchers @@ -191,7 +216,8 @@ must follow these rules: > [!NOTE] > > `defaultHour`, `defaultMinute` and `defaultSecond` are independent from each other. If you -> set `defaultHour` to 10, then it is expected that the hour hand drawable is rotated by exactly 300°, +> set `defaultHour` to 10, then it is expected that the hour hand drawable is rotated by exactly +> 300°, > regardless of the positions of the minute and second hands even if that means that the clock shows > an impossible time. @@ -213,13 +239,14 @@ must follow these rules: > For the minute layer, one level is equal to one minute so 60 levels are equal to a full rotation. > This means that the total angle must be `360/60 * 10000 = 60000` degrees. > -> For the hour layer, one level is also equal to one minute, so there are `12 * 60 = 720` levels in a +> For the hour layer, one level is also equal to one minute, so there are `12 * 60 = 720` levels in +> a > full rotation. `360/720 * 10000 = 5000` degrees. > > Technically, you could also use other kinds of drawables that support the `android:level` > attribute (such as a `LevelListDrawable`), as long as you follow the rules above. -### Themed icons +## Themed icons Themed icons are monochrome icons that are tinted to match the theme color of the launcher. @@ -240,7 +267,8 @@ Themed icons can be provided in any of the following ways: - If the icon is an adaptive icon, and the drawable has a `` layer, this icon will be used as the themed icon. -- If the icon is an adaptive icon, and it does not have a `` layer, the foreground layer will be used. +- If the icon is an adaptive icon, and it does not have a `` layer, 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