Property delegates that enable you to associate properties with lifecycle-aware components.
Add dependency to the module-level build.gradle file:
dependencies {
implementation("io.github.pubiqq:lifecycleprops:latest.release")
}Make sure you have mavenCentral() repository in the list of repositories.
To associate a property to the lifecycle of a LifecycleOwner object (such as AppCompatActivity, Fragment,
NavBackStackEntry, etc.), use the lifecycleAware function:
class MyActivity : AppCompatActivity() {
// Associates the read-only property with the `MyActivity` lifecycle
val locationService: MyLocationService by lifecycleAware(
initializer = { MyLocationService(context, locationCallback) },
onStart = { start() },
onStop = { stop() }
)
// Associates the read/write property with the `MyActivity` lifecycle
var banner: MyBanner by lifecycleAware(
onStart() = { start() },
onResume() = { resume() },
onPause() = { pause() },
onStop() = { stop() }
)
// ...
banner = MyBanner.Builder(context).build() // manual initialization of the read/write property
}To associate a property with the Fragment's view lifecycle, use viewLifecycleAware:
class MyFragment : Fragment() {
// Associates the read-only property with the `MyFragment`'s view lifecycle
val locationService: MyLocationService by viewLifecycleAware(
initializer = { MyLocationService(context, locationCallback) },
onStart = { start() },
onStop = { stop() }
)
// Associates the read/write property with the `MyFragment`'s view lifecycle
var banner: MyBanner by viewLifecycleAware(
onStart() = { start() },
onResume() = { resume() },
onPause() = { pause() },
onStop() = { stop() }
)
// ...
banner = MyBanner.Builder(context).build() // manual initialization of a read/write property
}Important
The API that provides configurations support for lifecycle-aware delegates is marked with the
ExperimentalConfigurationApi annotation.
Usages of such API will be reported as warnings unless an explicit opt-in with the OptIn annotation, e.g.
@OptIn(ExperimentalConfigurationApi::class), or with the
-opt-in=com.pubiqq.lifecycleprops.ExperimentalConfigurationApi compiler option is given.
By default, lifecycle-aware delegates for read-only properties:
- Lazily initialize the associated property.
- Close (if
AutoCloseable) and null out the property value when anON_DESTROYevent occurs.
Lifecycle-aware delegates for read/write properties:
- Ensure that a value will not be reassigned to an already initialized property (otherwise an
IllegalStateExceptionwill be thrown). - Ensure that each provided event handler will be invoked for the property (otherwise an
IllegalStateExceptionwill be thrown). - Close (if
AutoCloseable) and null out the property value when anON_DESTROYevent occurs.
If you want to change the behavior of the lifecycle-aware property, you can specify your own custom configuration:
@file:OptIn(ExperimentalConfigurationApi::class)
// Custom configuration for read-only properties
class MyLifecycleAwareReadOnlyConfiguration<in T : Any> : LifecycleAwareReadOnlyConfiguration<T> {
override val initializationStrategy: LifecycleAwareInitializationStrategy =
LifecycleAwareInitializationStrategy.OnAnyAccess
override val allowSkipHandlerAccessToUninitializedProperty: Boolean = false
override val shouldNullOutTheProperty: Boolean = true
override fun onClear(value: T) = Unit
}
// Custom configuration for read/write properties
class MyLifecycleAwareReadWriteConfiguration<in T : Any> : LifecycleAwareReadWriteConfiguration<T> {
override val allowReassign: Boolean = true
override val allowSkipHandlerAccessToUninitializedProperty: Boolean = true
override val shouldNullOutTheProperty: Boolean = true
override fun onClear(value: T) = Unit
}and apply it to the target property:
@file:OptIn(ExperimentalConfigurationApi::class)
class MyActivity : AppCompatActivity() {
// Associates the read-only property with the `MyActivity` lifecycle (`MyLifecycleAwareReadOnlyConfiguration` is used)
val locationService: MyLocationService by lifecycleAware(
configuration = MyLifecycleAwareReadOnlyConfiguration(),
initializer = { MyLocationService(context, locationCallback) },
onStart = { start() },
onStop = { stop() }
)
// Associates the read/write property with the `MyActivity` lifecycle (`MyLifecycleAwareReadWriteConfiguration` is used)
var banner: MyBanner by lifecycleAware(
configuration = MyLifecycleAwareReadWriteConfiguration(),
onStart() = { start() },
onResume() = { resume() },
onPause() = { pause() },
onStop() = { stop() }
)
// ...
banner = MyBanner.Builder(context).build() // manual initialization of the read/write property
}Also, you can set configurations globally, in which case they will be applied to lifecycle-aware properties by default:
@file:OptIn(ExperimentalConfigurationApi::class)
with(LifecycleProps) {
// Sets default configurations for lifecycle-aware properties
setLifecycleAwareConfigurations(
readOnlyPropsConfiguration = MyLifecycleAwareReadOnlyConfiguration(),
readWritePropsConfiguration = MyLifecycleAwareReadWriteConfiguration()
)
}
with(LifecyclePropsAndroid) {
// Sets default configurations for Android-specific lifecycle-aware properties
setViewLifecycleAwareConfigurations(
readOnlyPropsConfiguration = MyLifecycleAwareReadOnlyConfiguration(),
readWritePropsConfiguration = MyLifecycleAwareReadWriteConfiguration()
)
}Check out the sample project to see the library in action. Also see:
Copyrig
5E34
ht 2021 pubiqq
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.