Provided and Custom LifecycleAware Components

Welcome to Magellan! We're working hard on an update; this is the work-in-progress documentation for that update. For the old documentation, see our old wiki page, Magellan 1.x Home. If you have questions/comments/suggestions for the new documentation, please submit an issue and we'll explain ourselves better.

Available components

Don’t see something you would want? Feel free to create an issue!

Coroutines

• ShownScope: A CoroutineScope that is valid between show() and hide(). Included by default in Step.
• CreatedScope: A CoroutineScope that is valid between create() and destroy().

Miscellaneous

• DialogComponent: A LifecycleAware object for showing and hiding dialogs. It will ensure a dialog is shown while the parent is Shown or Resumed until the dialog is explicitly hidden.
• Navigator: A View-based navigator with a simple backstack. Handles transitions and the lifecycle of child Navigables. Useful for most Journeys.
  • If you want to use a custom Navigator implementation in a Journey of yours, create your own LifecycleAwareComponent that navigates how you want and attach it to a Step of yours. A more in depth guide will come soon, feel free to create an issue to get it prioritized higher.
• ComposeNavigator (coming soon): Same as Navigator above, but for Jetpack Compose.
• LifecycleLimiter and LifecycleRegistry: The components used by LifecycleAwareComponent to keep track of its children. You probably don't want to use these directly.

RxJava

• RxDisposer: An RxJava 2 composite disposable that is disposed in hide().
• RxUnsubscriber: An RxJava 1 composite subscription that is unsubscribed in hide().

Writing a custom component

Writing a custom component is easy! Just extend either LifecycleAwareComponent if you want the ability to have child LifecycleAware objects, or simply LifecycleAware if that's not necessary. Most of the time, you want to use LifecycleAwareComponent so it's easy to add children when necessary.

class MyExampleComponent : LifecycleAwareComponent() {

  val shownScope by lifecycle(ShownScope())

  override fun onShow(context: Context) {
    // Do some set up...
    shownScope.launch { ... }
  }

  override fun onHide(context: Context) {
    // Do some tear down...
  }
}

class MyExampleComponent : LifecycleAware {
  override fun show(context: Context) {
    // Do some set up...
  }

  override fun hide(context: Context) {
    // Do some tear down...
  }
}

Attaching components

• by lifecycle(…): Property delegate that attaches the given LifecycleAware component to this lifecycle immediately. Can be a var to allow for overriding components in tests.
• by lateinitLifecycle<T>(): Property delegate that acts like a lateinit var.
• by lifecycleWithContext { context -> … }: Property delegate that creates a LifecycleAware object using the provided lambda during show(), and removes the reference during hide(). Useful for Views and other Context-dependent objects. Strong guarantee to use an Activity context.
• LifecycleOwner.attachToLifecycle(…): The method that all these property delegates use under the hood. Most of the time, you want to use one of the delegates, but for the times you don't, you can use this.