Home

Welcome to the retention-magic wiki!

Understand the definitions

@Retain

This retains the annotated value over destroy/create cycles with a saved instance state (i.e. when the device is rotated or when the app is "shut down" temporarily because another app has come to the foreground).

@Retain(permanent = true)

This retains the value of the annotated field permanently. It means the value is stored in the shared preferences when an activity or fragment is destroyed and it's loaded from the shared preferences when the activity or fragment is created. This is useful to restore the last value of this field after the activity or fragment has been closed completely. Of course it also covers the previous case.

This can be done per instance. So if you have multiple instances of the same fragment (i.e. like in a pager) you can add the parameter instanceNSField = "mInstance" where mInstance is a field that holds an identifier for the current instance. The only requirement is that mInstance can be converted to a string, because it will become part of the key.

@Parameter(key = EXTRA_VALUE)

This initializes the annotated field with the value of an extra (in case of an activity) or the argument (in case of a fragment) of the same key. That happens when the activity or fragment are created for the first time (i.e. without saved instance state). but not when it's recreated with a saved instance state (i.e. when the device is rotated).

Check out our task app or color picker. You can find more examples in there.