feat(v3): add cross-platform application lifecycle events (Resumed/Paused/Backgrounded/Foregrounded) - #5886
Conversation
github-actions
Bot
added
Documentation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Plus Run ID: 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (7)
WalkthroughThe change adds four common application lifecycle events. Android, Darwin, and iOS lifecycle callbacks map to these events. Event identifiers, JavaScript names, registry entries, and documentation are updated. ChangesApplication lifecycle events
Estimated code review effort: 2 (Simple) | ~10 minutes Sequence Diagram(s)sequenceDiagram
participant PlatformLifecycle
participant EventMappings
participant CommonEvents
participant JavaScript
PlatformLifecycle->>EventMappings: emit platform lifecycle callback
EventMappings->>CommonEvents: map callback to common event
CommonEvents->>JavaScript: expose common:event name
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Warning There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure. 🔧 golangci-lint (2.12.2)level=error msg="[linters_context] typechecking error: pattern ./...: directory prefix . does not contain main module or its selected dependencies" Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/src/content/docs/guides/events-reference.mdx`:
- Around line 426-429: Update the documentation entries for
common:ApplicationResumed, common:ApplicationPaused,
common:ApplicationBackgrounded, and common:ApplicationForegrounded to state that
they are supported only on Android, iOS, and macOS, matching the mappings in
events_common_android.go, events_common_ios.go, and events_common_darwin.go; do
not describe them as available on all platforms unless Windows and Linux
forwarding mappings are also added.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro Plus
Run ID: c31cfc6f-09ac-4b85-8214-bbb0bf8e6561
📒 Files selected for processing (7)
docs/src/content/docs/guides/events-reference.mdxv3/pkg/application/events_common_android.gov3/pkg/application/events_common_darwin.gov3/pkg/application/events_common_ios.gov3/pkg/events/events.gov3/pkg/events/events.txtv3/pkg/events/known_events.go
Add four new Common events that map platform-specific lifecycle
transitions to a unified cross-platform contract:
- ApplicationResumed (app became active/interactive)
- ApplicationPaused (app losing focus, going inactive)
- ApplicationBackgrounded (app fully moved to background)
- ApplicationForegrounded (app returning from background)
Platform mappings:
Android: ActivityResumed/Paused/Stopped/Started → Common
iOS: DidBecomeActive/WillResignActive/DidEnterBackground/WillEnterForeground → Common
macOS: DidBecomeActive/DidResignActive/DidHide/WillUnhide → Common
The same Go listener now works on all three platforms:
app.Event.OnApplicationEvent(events.Common.ApplicationPaused, func(e *application.ApplicationEvent) {
// save state, pause expensive ops — works on Android, iOS, and macOS
})
Windows and Linux do not have equivalent app-level lifecycle events and
are left unmapped (they already map SystemWillSleep/SystemDidWake for
machine-level suspend/resume).
Documentation updated in the events reference guide.
d9942eb to
2b3c159
Compare
|
Good catch. Fixed in the force-push: the lifecycle events are now in their own subsection titled "Application Lifecycle Events (Android, iOS, macOS)" with an explicit note that Windows and Linux don't emit them (and a pointer to The "These events work on all platforms" table header now covers only the events that actually work everywhere. |
2 participants
Description
Mobile and macOS apps need to react to lifecycle transitions (backgrounding, foregrounding, pausing, resuming), but Wails v3 only exposes these as platform-specific events (
events.Android.ActivityPaused,events.IOS.ApplicationDidEnterBackground,events.Mac.ApplicationDidResignActive). Writing cross-platform code requires build-tagged listeners for each platform.This adds four new
Commonevents that map the platform-specific lifecycle transitions to a unified cross-platform contract:ApplicationResumedActivityResumedDidBecomeActiveDidBecomeActiveApplicationPausedActivityPausedWillResignActiveDidResignActiveApplicationBackgroundedActivityStoppedDidEnterBackgroundDidHideApplicationForegroundedActivityStartedWillEnterForegroundWillUnhideWindows and Linux do not have equivalent app-level lifecycle events and are left unmapped (they already map
SystemWillSleep/SystemDidWakefor machine-level suspend/resume).The implementation uses the existing
commonApplicationEventMappattern that already mapsApplicationStarted,ThemeChanged,BatteryChanged, etc. — no new plumbing, just 4 new map entries per platform.Type of change
How Has This Been Tested?
android/arm64via NDK) — compiles clean.setupCommonEvents+commonApplicationEventMap) is the same proven pattern used by the existing Common events (ApplicationStarted,ThemeChanged,BatteryChanged, etc.) since the mobile stack was introduced.iOS compile-verified via the fork's macOS CI runner (same workflow used for #5808).
Linux: Ubuntu 24.04.4 LTS (build host).
Test Configuration
Checklist:
website/src/pages/changelog.mdxwith details of this PRNotes:
docs/src/content/docs/guides/events-reference.mdx) with all 4 new events, descriptions, and "when to use" guidance.setupCommonEventstest path. Adding a device-level integration test would require an emulator (planned in a separate test-infrastructure PR). The mechanism is identical to the already-provenApplicationStarted/ThemeChangedforwarding.Summary by CodeRabbit
New Features
Documentation