Skip to content

CATROID-1668 Enhance shortcut management with UI integration and testing#5221

Open
harshsomankar123-tech wants to merge 26 commits into
Catrobat:developfrom
harshsomankar123-tech:feature/pin-to-home-screen
Open

CATROID-1668 Enhance shortcut management with UI integration and testing#5221
harshsomankar123-tech wants to merge 26 commits into
Catrobat:developfrom
harshsomankar123-tech:feature/pin-to-home-screen

Conversation

@harshsomankar123-tech

@harshsomankar123-tech harshsomankar123-tech commented Jun 27, 2026

Copy link
Copy Markdown
Member

JIRA TICKET: https://catrobat.atlassian.net/browse/CATROID-1668

Screen-Recordings of Main Feature

Screen.Recording.2026-04-24.at.05.59.50.mov

Screen Recording of delete and rename Feature

Screen.Recording.2026-04-24.at.06.01.30.mov
Screen.Recording.2026-04-24.at.06.02.14.mov

For Xiaomi Devices which needs manual permission first

https://youtube.com/shorts/sYn-YLzpNK0?feature=share

Summary

This PR introduces the ability for users to pin Catroid projects as shortcuts directly on their Android home screen. Tapping a pinned shortcut launches the project immediately via a lightweight trampoline activity, bypassing the main app navigation. It includes robust OEM-specific handling, specifically addressing MIUI permission restrictions and completely hiding the feature on unsupported POCO devices.

Core Implementation

  • ShortcutHelper.kt: The central utility for managing shortcut creation, updates, and removals.
    • Uses the encoded directory name as a stable shortcut ID.
    • Implements an OOM-resilient icon decoding mechanism (falls back from ARGB_8888 to RGB_565 at half-resolution).
  • ShortcutTrampolineActivity.kt: A transparent launcher activity that acts as a secure entry point. It validates intents, rejects null/blank project names, resolves the target, and seamlessly forwards to ProjectActivity.
  • ProjectListFragment.kt: Integrates the "Pin to Home Screen" option into the project settings popup menu. Manages lifecycle syncs (rename/delete) and implements an auto-restore flow that reopens the pin dialog when a user returns from MIUI settings.
  • StageActivity.java: Added the EXTRA_IS_FROM_SHORTCUT flag so that pressing "back" after a shortcut launch cleanly exits the app instead of showing the stage dialog.
  • XmlHeader.java: Added a stable projectUuid (auto-generated UUID) to future-proof shortcut identity tracking.

OEM Compatibility & Device Handling

  • Xiaomi / Redmi (MIUI):
    • Uses a Reflection Check via MIUI's internal AppOpsManager (OpCode 10017) to accurately detect if the "Install shortcut" permission is granted.
    • Implements a Silent Probe fallback (pushes a temporary dynamic shortcut and checks for OS acceptance with a 200ms delay for MIUI sync throttle) before cleaning up.
    • Uses a Cascading Settings Fallback to guide users to enable permissions, trying PermissionsEditorActivity first before falling back to ACTION_APPLICATION_DETAILS_SETTINGS.
  • POCO Devices:
    • Feature is fully hidden. isShortcutSupported() forcibly returns false, ensuring the menu option does not appear at all to prevent silent system rejections.

UI & Resources

  • Added dialog_shortcut_pin.xml for a custom floating dialog displaying the project icon, name, pin action, and a specific MIUI warning container.
  • Added supporting drawables (bg_shortcut_dialog.xml, etc.), a borderless ShortcutPinDialog style, and relevant string/color resources.

Testing

  • Unit Tests (13): Covers OOM bitmap fallback, rename/delete synchronization, shortcut ID stability, MIUI reflection safety, silent probe cleanup, and POCO device exclusion logic.
  • Integration Tests (5): Validates intent security (null/blank project rejections), missing directory handling, and lifecycle transitions using Robolectric.
  • UI/Espresso Tests (4): Verifies dialog auto-restore flows and Snackbars. (Note: Two StageActivity back-press tests are @Ignore'd because they require a full OpenGL/GPU context tied to the libGDX AndroidApplication constraint).
  • Build: Added kotlinx-coroutines-test for testing suspend functions.

How to Test

  1. Open Catroid and navigate to the Project List.
  2. Tap the ⋮ menu on any project and select "Pin to Home Screen".
  3. Confirm via the dialog; verify the shortcut appears on the Android home screen.
  4. Tap the newly created shortcut to ensure the project opens directly.
  5. Sync testing: Rename a project and verify the shortcut label updates. Delete a project and verify the shortcut is disabled/removed.
  6. Xiaomi/Redmi specifics: On a MIUI device without shortcut permissions, verify the dialog shows a warning with an "Open Settings" button. Grant permission, return to the app, and verify the dialog auto-reopens.
  7. POCO specifics: On a POCO device, verify the "Pin to Home Screen" option is entirely absent from the popup menu.

Note: This feature behaves differently across devices, so testing may vary by manufacturer. I have tested it on Redmi, Motorola, Samsung, and OnePlus devices, and all features are working as expected on these. I will continue testing on more devices, but if you have a device from a different brand, please test this feature and let me know if you encounter any issues.

Your checklist for this pull request

Please review the contributing guidelines and wiki pages of this repository.

  • Include the name of the Jira ticket in the PR’s title
  • Include a summary of the changes plus the relevant context
  • Choose the proper base branch (develop)
  • Confirm that the changes follow the project’s coding guidelines
  • Verify that the changes generate no compiler or linter warnings
  • Perform a self-review of the changes
  • Verify to commit no other files than the intentionally changed ones
  • Include reasonable and readable tests verifying the added or changed behavior
  • Confirm that new and existing unit tests pass locally
  • Check that the commits’ message style matches the project’s guideline
  • Stick to the project’s gitflow workflow
  • Verify that your changes do not have any conflicts with the base branch
  • After the PR, verify that all CI checks have passed
  • Post a message in the catroid-stage or catroid-ide Slack channel and ask for a code reviewer

…sion dialog

- Add a cancel button to dialog_shortcut_pin.xml below the pin button
- Rewrite showShortcutPermissionDialog to use the custom dialog layout
  with MIUI container (project icon, name, warning, styled buttons)
  instead of plain MaterialAlertDialogBuilder
- Wire up cancel buttons in both showPinShortcutDialog and
  showShortcutPermissionDialog to dismiss the dialog
- Fix empty unsupported_launcher test with @ignore and honest reason
- Add POCO device exclusion unit tests (isShortcutSupported, menu hiding)
- Add duplicate pin guard in ShortcutHelper.pinProject() + test
- Add intent flags (FLAG_ACTIVITY_NEW_TASK | CLEAR_TASK) to trampoline
- Add XmlHeader projectUuid generation tests (null, repeated, blank, compat)
- Add cancel button dialog dismiss stub test
- Add shortcut_already_pinned string resource

@github-advanced-security github-advanced-security AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

detekt found more than 20 potential problems in the proposed changes. Check the Files changed tab for more details.

Comment thread catroid/src/main/res/values/strings.xml Fixed
Comment thread catroid/src/main/res/values/strings.xml Fixed
@harshsomankar123-tech harshsomankar123-tech changed the title Enhance shortcut management with UI integration and testing CATROID-1668 Enhance shortcut management with UI integration and testing Jun 27, 2026
@sonarqubecloud

Copy link
Copy Markdown

@harshsomankar123-tech harshsomankar123-tech marked this pull request as ready for review June 27, 2026 08:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants