docs: PR #131 review — lifecycle ordering contract (item 9)
Documents the ImplantApp lifecycle ordering and the nav-stack state guarantee at each hook: - Class-level docstring on implant_app.gd describes on_install, on_open, on_close, and on_insert_deactivated: when each fires, what nav state subclasses can rely on, and what is safe to do (construct + register_screen in on_install; data refresh + read nav.current() in on_open; pause timers in on_close; no close_app manual call in on_insert_deactivated — call super or replicate the guard). - Arch doc gains a "Lifecycle hooks" subsection under ImplantApp base class with a four-row contract table plus explanatory notes on two load-bearing invariants: why on_install sees an empty stack (bottom-up _ready order, no open signal yet); why on_close must not push/pop (would destroy preserved position on reopen). Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -3,7 +3,34 @@ extends Control
|
||||
## Base class for all implant apps. Absorbs HudGroups boilerplate; subclasses
|
||||
## override lifecycle hooks only (#844, D-191).
|
||||
##
|
||||
## Subclass _ready() pattern:
|
||||
## === Lifecycle ordering ===
|
||||
##
|
||||
## on_install() — called once from _ready(), after nav is created but BEFORE any
|
||||
## HudGroups open event fires. The nav stack is EMPTY at this point. Use this
|
||||
## hook to: construct screens and call register_screen(id, screen), set
|
||||
## nav.set_default("..."), wire intra-screen signals. Do NOT rely on
|
||||
## current_screen_id() here — no screen has been pushed yet.
|
||||
##
|
||||
## on_open(mode) — called every time HudGroups activates this app (FULLSCREEN or
|
||||
## INSERT). By the time on_open fires, the base has ensured the nav stack is
|
||||
## non-empty: if preserves_state=false, nav.reset_to_default() was called; if
|
||||
## preserves_state=true and the stack was empty, nav.push_default() was called.
|
||||
## nav.current() returns the visible screen id. Safe to read navigation state
|
||||
## and trigger data refreshes here.
|
||||
##
|
||||
## on_close() — called every time HudGroups deactivates this app (GAMEPLAY mode
|
||||
## or another app taking focus). Nav stack state is preserved here — do not
|
||||
## push or pop screens in on_close. Use this hook for: pausing timers, stopping
|
||||
## animations, unsubscribing from high-frequency feeds. The stack survives
|
||||
## intact for the next on_open (if preserves_state=true).
|
||||
##
|
||||
## on_insert_deactivated() — called by SnapshotConsumers when the server drops
|
||||
## insert state. The base implementation closes the app only if it is currently
|
||||
## active in INSERT mode. FULLSCREEN apps inherit a no-op; override to add
|
||||
## custom handling (e.g. save draft, emit warning). Do not call close_app()
|
||||
## manually — call super() or replicate the guard condition.
|
||||
##
|
||||
## === Subclass _ready() pattern ===
|
||||
## func _ready() -> void:
|
||||
## manifest = load("res://ui/implant/apps/my_app/app.tres")
|
||||
## super._ready()
|
||||
|
||||
Reference in New Issue
Block a user