Icon Requests System

Lawnicons allows users to request icons for apps that are not yet themed. This feature involves detecting unthemed apps installed on the user's device, preparing a list, and then guiding the user to submit this list via email with a ZIP file containing the app icons and component data.

How it works: User perspective

1. The user navigates to the "Icon Request" screen from the home screen's bottom toolbar.
2. If icon requests are currently disabled by the Lawnicons maintainers (a setting fetched from the Lawnicons website), a message informs the user.
3. If requests are enabled and the user has unthemed apps:
   • A list of unthemed apps is displayed with selection checkboxes.
   • The user can select individual apps, select all, or clear the selection.
   • Tapping the request button creates a ZIP file containing the selected app icons and component list, and opens an email intent to send the request.
   • The user can also save the ZIP file locally or share it via other apps.
   • A "Copy components" option copies the formatted component list to the clipboard.
4. Announcements specific to icon requests (fetched from the website) may be displayed at the top of the screen.

Key components and their roles

• UI Layer (ui/ package):
  • destination/iconrequest/IconRequest.kt: The main screen Composable for the icon request feature.
    • Displays the list of requestable (unthemed) apps with selection UI.
    • Provides actions: request, save, share, copy components, select all, clear selection.
    • Shows announcements filtered for the IconRequest location.
  • destination/home/Home.kt: The home screen checks HomeUiState.Success.hasIconRequests to decide whether to show a navigation entry to the icon request screen.
• ViewModel Layer (ui/destination/iconrequest/ package):
  • IconRequestViewModel.kt:
    • Exposes availableIcons (StateFlow<List<SystemIconInfo>>): The list of unthemed apps detected by the IconRequestRepository.
    • Exposes isEnabled (StateFlow<Boolean>): Reflects the global icon request enable/disable setting fetched from the website.
    • Manages selectedIcons (StateFlow<List<SystemIconInfo>>): Tracks which icons the user has selected for request.
    • Manages isSavingInProgress for loading state during ZIP creation.
    • Provides toggleSelection(), selectAll(), clearSelection(), requestIcons(), saveFile(), shareFile(), and copyComponents() functions.
    • requestIcons() creates a ZIP file via IconRequestRepository, formats the component list, and delegates to IconRequestHandler.execute() to open an email intent.
    • Also fetches announcements filtered for the AnnouncementLocation.IconRequest from AnnouncementsRepository.
• Data Layer (data/repository/iconrequest/ package):
  • IconRequestRepository.kt / IconRequestRepositoryImpl.kt:
    • In its init block, fetches all Lawnicons-supported icons and the list of user-installed apps (via GetSystemPackageList.kt), then compares the two.
    • Identifies installed apps that do not have a corresponding themed icon in Lawnicons.
    • Exposes the list via iconRequestList: StateFlow<IconRequestModel?>.
    • Exposes isEnabled: StateFlow<Boolean> after checking the IconRequestSettingsAPI.
    • Provides createIconRequestZip() to bundle selected app icons into a ZIP file.
  • IconRequestHandler.kt / ArcticonsDashboardHandler:
    • Handles the actual submission — creates an email Intent with the ZIP file as an attachment, device info, and the component list as email body.
  • GetSystemPackageList.kt: Provides the list of all launchable applications installed on the user's device.
  • AdaptiveIconBitmap.kt: Utility for extracting app icon bitmaps for inclusion in the ZIP file.
• Data Layer (data/repository/ package):
  • PreferenceManager.kt:
    • forceEnableIconRequest: A debug preference to allow developers to test the request flow even if globally disabled.
    • iconRequestsEnabled: Stores the last fetched global status.
• Model Layer (data/model/ package):
  • SystemIconInfo.kt: Data class holding the icon, label, and component info for a system-installed app.
  • IconRequestModel.kt: Holds a list of SystemIconInfo objects and the total count.
  • IconRequestSettings.kt: Data class for parsing the JSON response from the website about request status.
  • IconRequestData.kt: Holds the ZIP file and formatted component list string for submission.
• Utility (ui/util/ package):
  • Constants.kt: Defines ICON_REQUEST_EMAIL (the email address for requests).

Data flow for an icon request

1. App Startup: IconRequestRepository determines the list of unthemed apps and updates iconRequestList. It also fetches the global isEnabled status from the website API.
2. Navigation: User navigates to the Icon Request screen from the home screen.
3. IconRequestViewModel: Observes iconRequestRepository.iconRequestList and exposes it as availableIcons. Loads relevant announcements.
4. User Selection: User selects icons to request using toggleSelection(), selectAll(), or clearSelection().
5. Request Submission (requestIcons()):
   • Creates a ZIP file via iconRequestRepository.createIconRequestZip(selectedIcons).
   • Formats the component list via formatIconRequestList().
   • Calls requestHandler.execute() which creates an email intent with the ZIP as an attachment and component list as the email body.
6. Alternative Actions: User can also saveFile() to export the ZIP, shareFile() to share via other apps, or copyComponents() to copy the component list to clipboard.

This system provides a comprehensive icon request workflow that bundles app icons and metadata for easy submission to the Lawnicons maintainers.