Easylauncher Gradle Plugin

Apply the plugin to your application module's build.gradle file.

If you encounter a Could not resolve all artifacts error (specifically Could not find com.android.tools.build:gradle:x.x.x), apply the plugin to the root project first to ensure correct dependency resolution, then apply it to your application module.

Alternatively, you can use a Gradle Version Catalog.

// Standard application module setup
// in app/build.gradle
plugins {
    id "com.starter.easylauncher" version "${{version}}"
}

// Troubleshooting: Root project setup for dependency resolution
// in root project's build.gradle 
buildscript {
    repositories.google()
}
plugins {
    id "com.starter.easylauncher" version "${{version}}" apply false
}

// Troubleshooting: Application module setup after root setup
// in app/build.gradle 
plugins {
    id "com.starter.easylauncher"
}

// Using Version Catalog
// in libs.versions.toml
[plugins]
starter-easylauncher = { id = "com.starter.easylauncher", version.ref = "easylauncher" }

The easylauncher configuration block allows you to customize how launcher icons are modified across different build types, product flavors, and specific variants.

Hierarchy and Precedence:

• productFlavors: Filters defined here are added to filters defined in buildTypes.
• buildTypes: Filters defined here are added to filters defined in productFlavors.
• variants: Filters defined here override all other filters defined for that specific variant.

Key Options:

• defaultFlavorNaming: If true, uses the flavor name for default ribbons instead of the build type name.
• showWarnings: If true, the plugin shows warnings during configuration time.
• enable: Set to false to disable all filters for a specific configuration.
• iconNames: A list of icon resource names (e.g., ["@mipmap/custom_icon"]). If provided, the plugin disables automatic discovery and only applies filters to these specific icons.

easylauncher {
    defaultFlavorNaming = true
    showWarnings = true
    iconNames = ["@mipmap/custom_launcher_icon"]

    productFlavors {
        register("qa") {
            filters redRibbonFilter()
        }
    }

    buildTypes {
        register("beta") {
            filters = [
                    customRibbon(ribbonColor: "#0000FF"),
                    overlayFilter(file("example-custom/launcherOverlay/beta.png"))
            ]
        }
        register("canary") {
            enable = false
        }
    }

    variants {
        register("productionDebug") {
            filters = orangeRibbonFilter("custom")
        }
    }
}

The Canvas class provides a managed drawing surface for implementing custom icon filters. It wraps a Graphics2D object and handles padding calculations to ensure drawing operations respect the image boundaries, especially when dealing with adaptive icons.

Key Concepts

• Viewport vs. Full Size: For adaptive icons, the Canvas calculates a viewport (the inner 72dp of a 108dp icon) and applies padding to the remaining area. For legacy icons, the viewport is the full image size.
• Lifecycle: A Canvas is intended to be used once. After executing drawing operations, the underlying graphics context is disposed of automatically.
• Adaptive Scaling: When adaptive = true is passed during creation, the canvas uses an ADAPTIVE_SCALE (72/108f) to define the drawable area.

// Example of creating a canvas for an adaptive icon
val canvas = Canvas(image, adaptive = true)

// Perform drawing operations
// Note: The 'use' method is internal, so you typically interact with the graphics
// via the provided Canvas properties or within the plugin's filter lifecycle.

The easylauncher plugin is configured using the EasyLauncherExtension. This extension allows you to define variant-specific configurations, including enabled status, filters (like ribbons or chrome-like filters), and custom icon names.

Key Configuration Concepts:

• Variant Matching: The plugin looks for configurations in the variants block that match the Android variant name. If no specific variant configuration is found, it attempts to find matches within productFlavors or buildTypes.
• Icon Names: You can define iconNames globally for the entire project or specifically within a variant configuration. Variant-specific names take precedence.
• Automatic Ribbon: If no filters are explicitly provided for a debuggable variant, the plugin automatically adds a greenRibbonFilter using either the flavor name or the build type (depending on your isDefaultFlavorNaming setting).