5

Icon pack support

SuperDragonXD edited this page 2025-08-23 16:49:53 +08:00

Table of Contents

• Icon Pack Support
• The ADW Icon Pack Standard
• Core Specification
• Manifest Declaration
• appfilter.xml
• drawable.xml
• Static Icons
• Extensions to the Standard
• Dynamic Calendars
• Dynamic Clocks
• Autogenerated Fallback Icons
• Modern Metadata Extensions
• org.icontheme.CHANGES_WITH_MATERIAL_YOU_COLORS
• org.icontheme.CHANGES_WITH_DARK_MODE
• org.icontheme.FALLBACK_TO_THEMED_ICON
• The Google Themed Icon Standard
• Core Mechanism
• grayscale_icon_map.xml
• Limitation: Per-Package Specificity
• Lawnchair Implementation Details
• Decoupled Feature Model
• ADW Standard Support
• Themed Icon Extensions
• For Icon Pack Developers
• Acknowledgements

Icon Pack Support

Lawnchair supports two distinct standards for icon theming: the ADW Icon Pack standard and the Google Themed Icon standard. This document provides the technical specification for both systems and describes Lawnchair's implementation details.

The ADW Icon Pack Standard

The ADW standard is a widely adopted format for third-party icon packs. It provides a rich and specific mapping system based on XML resources.

Core Specification

This section defines the baseline components required for an application to function as a basic icon pack.

Manifest Declaration

For an application to be recognized as an icon pack, its AndroidManifest.xml must contain an activity with one or more of the following intent filters:

<activity android:name=".IconPackActivity" android:exported="true">
    <intent-filter>
        <action android:name="org.adw.ActivityStarter.THEMES" />
    </intent-filter>
    <!-- For additional extension features -->
    <intent-filter>
        <action android:name="com.novalauncher.THEME" />
    </intent-filter>
</activity>

appfilter.xml

The core of the standard is appfilter.xml, a resource file that maps application components to icon pack drawables.

• Location:

  • res/xml/appfilter.xml (Recommended)
  • res/raw/appfilter.xml
  • assets/appfilter.xml

• Structure:

  <?xml version="1.0" encoding="utf-8"?>
  <resources>
      <!-- Icon mappings are defined here -->
  </resources>
  

The component attribute targets a full ComponentInfo string (package.name/activity.class.name), allowing for per-activity theming within a single application package.

drawable.xml

For icons to be discoverable in a launcher's manual icon picker, a drawable.xml file must be provided at res/xml/drawable.xml.

• Structure:

  <?xml version="1.0" encoding="utf-8"?>
  <resources>
      <item drawable="messages" />
      <category title="System" />
      <item drawable="settings" />
      <item drawable="settings_alt_1" />
  </resources>
  

The <category> elements are for organizational purposes and are not currently utilized by Lawnchair.

Static Icons

The fundamental mapping is for static icons, defined by an <item> tag.

<item component="ComponentInfo{com.android.deskclock/com.android.deskclock.DeskClockTabActivity}" drawable="clock" />

• component: The target activity's ComponentInfo.
• drawable: The name of the drawable resource within the icon pack.

Extensions to the Standard

The core ADW standard has been extended over time by various launchers to support more advanced functionality.

Dynamic Calendars

Lawnchair supports the dynamic calendar standard popularized by Nova Launcher.

• appfilter.xml Entry:

  <calendar component="ComponentInfo{com.google.android.calendar/com.android.calendar.LaunchActivity}" prefix="calendar_" />
  

• prefix: The prefix for the icon drawables. The icon pack must provide 31 drawables named calendar_1, calendar_2, ..., calendar_31.

Note

Single-digit day drawables must not be zero-padded (e.g., calendar_1 is correct; calendar_01 is not). All 31 drawables must be present.

Dynamic Clocks

Dynamic clock support requires two entries in appfilter.xml: a standard <item> and a <dynamic-clock> definition.

• appfilter.xml Entries:

  <item component="ComponentInfo{com.google.android.deskclock/com.android.deskclock.DeskClockTabActivity}" drawable="clock" />
  <dynamic-clock
      drawable="clock"
      hourLayerIndex="0"
      minuteLayerIndex="1"
      secondLayerIndex="2"
      defaultHour="10"
      defaultMinute="10"
      defaultSecond="30" />
  

The icon drawable must be a LayerDrawable or an AdaptiveIconDrawable containing a LayerDrawable as its foreground. The layerIndex attributes map the drawable's layers to the clock hands. For animation to function correctly, each clock hand layer must be a RotateDrawable with fromDegrees and toDegrees values that adhere to a specific formula based on the drawable's level.

Note

For a detailed explanation of the required RotateDrawable values, see the clock icons section in Kvaesitso's icon pack documentation.

Autogenerated Fallback Icons

For unthemed applications, launchers can generate a fallback icon using components defined in appfilter.xml, a standard also used by Nova Launcher.

• <iconback img="icon_background" />: A drawable placed behind the original app icon.
• <iconmask img="icon_mask" />: A shape used to mask the original icon.
• <iconupon img="icon_overlay" />: A drawable placed on top of the original icon.
• <scale factor="0.8" />: A scaling factor applied to the original icon.

Multiple images can be provided for each component (e.g., img1, img2) to allow the launcher to randomize the generated background.

Modern Metadata Extensions

A set of metadata flags, defined in the icon pack's AndroidManifest.xml, allow launchers to enable advanced behaviors related to modern Android features.

org.icontheme.CHANGES_WITH_MATERIAL_YOU_COLORS

This flag signals that the icon pack contains drawables which reference system-level Material You color attributes. A compatible launcher should listen for system theme changes and trigger a refresh of the icon pack to apply the new colors.

Note

For Icon Pack Developers: Enabling this flag does not automatically color your icons. It is a signal that your icons are designed to use Material You colors. Misusing this flag may cause unnecessary icon reloading on theme changes, impacting performance.

org.icontheme.CHANGES_WITH_DARK_MODE

This flag signals that the icon pack provides different assets for light and dark UI modes. A compatible launcher should listen for system UI mode changes and trigger an icon refresh to display the appropriate assets.

Note

For Icon Pack Developers: This flag should only be enabled if your pack includes distinct drawables for different UI modes. Misusing it can lead to unnecessary performance overhead.

org.icontheme.FALLBACK_TO_THEMED_ICON

This flag instructs the launcher to use its own Google Themed Icon implementation as a fallback for any application not explicitly defined in the icon pack's appfilter.xml.

Note

For Icon Pack Developers: This should be enabled only if the visual style of your icon pack is designed to be aesthetically compatible with the monochrome style of Google's Themed Icons.

The Google Themed Icon Standard

Introduced in Android 12, this is a platform-level system for generating monochrome icons that adapt to the system wallpaper.

Core Mechanism

The system generates single-color, silhouette-style icons tinted by the launcher.

1. The primary method is for an application developer to include a <monochrome> element within their app's adaptive icon drawable. The operating system will use this drawable when Themed Icons are enabled.
2. As a fallback for apps that do not provide a <monochrome> drawable, a launcher can provide its own mapping via a grayscale_icon_map.xml file.

grayscale_icon_map.xml

This file is a launcher-level resource that maps packages to specific monochrome drawables.

• Location: res/xml/grayscale_icon_map.xml

• Structure:

  <?xml version="1.0" encoding="UTF-8"?>
  <icons>
      <icon package="com.android.google" drawable="@drawable/themed_google" />
  </icons>
  

Limitation: Per-Package Specificity

The grayscale_icon_map.xml standard maps icons on a per-package basis. It does not support per-component mapping. Consequently, all activities within a single application package will resolve to the same themed icon.

Lawnchair Implementation Details

Lawnchair's theming engine integrates both standards. The implementation reflects the current state of the underlying iconloaderlib and will evolve as the library is updated.

Decoupled Feature Model

The two standards are exposed to the user as two independent features, not as a single choice between icon pack types.

• Icon Pack: This setting controls the global replacement of application icons. It uses the ADW standard, reading appfilter.xml from the selected pack to apply custom, multi-color icons throughout the launcher.

• Themed Icons: This setting is a cosmetic overlay that applies a monochrome, wallpaper-adaptive theme. It is powered exclusively by a grayscale_icon_map.xml source, as the current icon loader library does not yet support parsing app-provided <monochrome> drawables.

An icon pack like Lawnicons can provide resources for both features, but the user controls them independently.

ADW Standard Support

Lawnchair's current implementation of the ADW standard supports:

• Static Icons (<item>)
• Dynamic Calendars (<calendar>)

Note

Support for <dynamic-clock> and autogenerated fallback icons (<iconback>, <iconmask>, etc.) is not yet implemented.

Themed Icon Extensions

To bridge the feature gap in the Google standard, Lawnchair's implementation of grayscale_icon_map.xml supports non-standard extensions for dynamic icons.

• Structure:

  <icons>
      <icon package="com.google.android.calendar" drawable="@array/grayscale_calendar_icons" />
      <icon package="com.google.android.deskclock" drawable="@array/grayscale_clock_icons" />
  </icons>
  

These entries point to <array> resources which contain the necessary drawables and configuration data for Lawnchair to render dynamic calendars and clocks in the monochrome Themed Icon style.

For Icon Pack Developers

• The ADW standard with a comprehensive appfilter.xml is the recommended foundation for maximum compatibility and feature support.
• To allow an icon pack to be used as a source for Lawnchair's "Themed Icons" feature, its AndroidManifest.xml must include the following intent filter:

  <intent-filter>
      <action android:name="app.lawnchair.icons.THEMED_ICON" />
  </intent-filter>
  

  The pack must also provide a grayscale_icon_map.xml file.
• The Lawnicons project serves as a reference implementation. It extends the appfilter.xml format with a name="" attribute to facilitate build processes that can generate multiple output formats from a single source of truth.

Acknowledgements

This guide is based on and inspired by the icon pack documentation for Kvaesitso Launcher.