Skip to content

LayerStackManager

class LayerStackManager(parentComposition: CompositionContext, screenLocals: @Composable



 (content: @Composable



 () -> Unit) -> Unit)

Manages an ordered stack of Layers for a single screen.

The stack determines the rendering order (bottom to top) and input-dispatch priority (top layer receives events first). Overlays such as dialogs, dropdowns, and tooltips are each their own layer on top of the base screen content.

Obtain an instance via the LocalLayerManager composition local.

Parameters

  • parentComposition: The CompositionContext from the host screen, required when creating child Compositions for each layer.

  • screenLocals: Wraps every layer's content in whatever CompositionLocalProvider the host screen needs visible screen-wide (e.g. LocalScreen, LocalVanillaScreen, LocalLayerManager). Each layer is its own top-level Composition parented directly to parentComposition rather than nested inside another layer's, so ordinary composition-local scoping - a CompositionLocalProvider wrapping only the base layer's own content, say - never reaches a later-pushed modal/dropdown/tooltip layer. push applies this to every layer it creates so all such locals stay implicitly shared across the whole stack instead of each caller needing to remember which ones to re-supply.

Constructors

LayerStackManager

constructor(parentComposition: CompositionContext, screenLocals: @Composable



 (content: @Composable



 () -> Unit) -> Unit)

Parameters

  • parentComposition: The CompositionContext from the host screen, required when creating child Compositions for each layer.

  • screenLocals: Wraps every layer's content in whatever CompositionLocalProvider the host screen needs visible screen-wide (e.g. LocalScreen, LocalVanillaScreen, LocalLayerManager). Each layer is its own top-level Composition parented directly to parentComposition rather than nested inside another layer's, so ordinary composition-local scoping - a CompositionLocalProvider wrapping only the base layer's own content, say - never reaches a later-pushed modal/dropdown/tooltip layer. push applies this to every layer it creates so all such locals stay implicitly shared across the whole stack instead of each caller needing to remember which ones to re-supply.

Properties

layers

val layers: SnapshotStateList<Layer>

The ordered list of active layers. Layers are rendered bottom-to-top.

rootTheme

The ThemeData a newly-pushed layer (modal, dropdown, tooltip) should inherit: the innermost net.kernelpanicsoft.archie.gui.theme.Theme scope currently mounted in this screen's base layer, per themeStack. null until the base layer's first Theme {} mounts. Read back by the screen's screenLocals wrapping so every later-pushed layer inherits it too, instead of silently falling back to net.kernelpanicsoft.archie.gui.theme.LocalTheme's own default - each later layer is its own top-level androidx.compose.runtime.Composition (see this class's own doc), so it would otherwise never see a Theme {} that only wraps the base layer's content.

screenPos

Represents the top-left position of the screen, calculated based on the root container nodes of all active layers within the layer stack.

The result aggregates the minimum x and y coordinates across all layers. If no root container nodes are found, the default position is (0, 0).

The position is determined by folding over all layers and comparing the x and y positions of their root container nodes, if present. The computation ensures that the resulting coordinates account for the smallest bounds of the visible layers in the stack.

screenSize

Represents the total size of the screen, calculated based on the dimensions of all active layers.

This property computes the maximum width and height among all the root container nodes from the layers managed by the containing class. It aggregates these dimensions by traversing the active layers and comparing their widths and heights.

If a layer does not have a root container node, it is skipped in the calculation.

Return

A Size object representing the combined width and height required to encapsulate all visible layers.

top

val top: Layer?

The topmost (most recently pushed) layer, which receives input events first. null if the stack is empty.

Functions

alertDialog

fun alertDialog(
    title: Component = Component.literal("Alert"), 
    message: Component, 
    confirmText: Component = Component.literal("OK"), 
    onConfirm: () -> Unit = {}
)

Pushes a modal presenting an AlertDialog with a single acknowledgement action.

Parameters

  • onConfirm: Invoked when the user acknowledges the alert.

choiceDialog

fun <T> choiceDialog(
    title: Component = Component.literal("Choose an Option"), 
    message: Component? = null, 
    choices: List<ModalChoice<T>>, 
    cancelText: Component = Component.literal("Cancel"), 
    onSelected: (T) -> Unit, 
    onCancel: () -> Unit = {}
)

Pushes a modal presenting a ChoiceDialog listing choices for the user to pick from.

Parameters

  • choices: The selectable options.

  • onSelected: Invoked with the chosen value's ModalChoice.value when a choice is picked.

  • onCancel: Invoked when the user cancels without choosing.

confirmDialog

fun confirmDialog(
    title: Component = Component.literal("Confirm Dialog"), 
    confirmText: Component = Component.literal("Confirm"), 
    cancelText: Component = Component.literal("Cancel"), 
    onConfirm: () -> Unit = {}, 
    onCancel: () -> Unit = {}, 
    content: @Composable



 () -> Unit
)

Pushes a modal presenting a ConfirmDialog with confirm/cancel actions. The modal animates out and dismisses itself after either action runs.

Parameters

  • onConfirm: Invoked when the user confirms.

  • onCancel: Invoked when the user cancels.

  • content: Additional body content shown above the actions.

fun modal(
    alignment: Alignment = Alignment.Center, 
    dismissOnClickOutside: Boolean = true, 
    transitionSpec: ModalTransitionSpec = ModalTransitionSpec(), 
    onDismissRequest: () -> Unit = {}, 
    content: @Composable



 ModalScope.() -> Unit
)

Pushes a new modal layer onto the stack.

Modals are opinionated, input-blocking overlays ideal for dialogs and confirmation prompts. A click outside the modal content area triggers onDismissRequest and, when dismissOnClickOutside is true, automatically removes the layer.

Parameters

  • alignment: Alignment of the modal within the full screen. Default Alignment.Center.

  • dismissOnClickOutside: Whether clicking outside the modal content closes it.

  • onDismissRequest: Optional callback invoked when the modal is dismissed.

  • content: The modal UI, a composable lambda with ModalScope receiver.

pop

fun pop(): Unit?

Removes and disposes the topmost layer.

popById

fun popById(id: UUID)

Removes and disposes the layer identified by id.

Does nothing if no layer with that id exists.

Parameters

  • id: The UUID of the layer to remove.

promptDialog

fun promptDialog(
    title: Component = Component.literal("Enter Value"), 
    initialValue: String = "", 
    prompt: Component = Component.literal("Enter a value:"), 
    confirmText: Component = Component.literal("Confirm"), 
    cancelText: Component = Component.literal("Cancel"), 
    validator: (String) -> Boolean = { true }, 
    onConfirm: (String) -> Unit, 
    onCancel: () -> Unit = {}
)

Pushes a modal presenting a PromptDialog for single-line text input.

Parameters

  • initialValue: Text prefilled in the input field.

  • validator: Predicate controlling whether the confirm action is enabled.

  • onConfirm: Invoked with the entered text when the user confirms.

  • onCancel: Invoked when the user cancels.

push

fun push(layerContent: @Composable



 (dismiss: () -> Unit) -> Unit): () -> Unit

Pushes a new generic layer onto the stack.

The content lambda receives a dismiss function it can call to remove itself from the stack. This overload is suitable for persistent overlays and custom layer types.

Return

A dismiss handle; call it to imperatively remove the layer.

Parameters

  • layerContent: The composable content for the new layer.

wizardDialog

fun wizardDialog(
    pages: List<WizardPage>, 
    contentWidth: Int = 9 * 18, 
    contentHeight: Int? = null, 
    onFinish: () -> Unit = {}, 
    onCancel: () -> Unit = {}
)

Pushes a modal presenting a WizardDialog - a multi-page flow with Back/Cancel/forward navigation, a horizontal slide between pages, and per-page validation gating the forward button.

Not dismissable by clicking outside: a wizard holds part-finished input across several steps, and losing it to a stray click is worse than making the reader press Cancel.

Parameters

  • pages: The steps, in order.

  • onFinish: Invoked when the reader completes the final page.

  • onCancel: Invoked when the reader cancels.