A collection of hand-crafted extensions for your Kotlin projects.
Compiled with Kotlin 1.3.72 and kotlinx.coroutines 1.3.8.
This release introduces 2 new splits:
Add isCancellable parameter (defaults to true, as when unspecified) to alertDialog builders.
viewModels { … } for FragmentActivity and Fragment
activityViewModels { … } for Fragment
This split no longer depends on the androidx.lifecycle:lifecycle-extensions artifact that has been deprecated in AndroidX Lifecycle 2.2.0 and is no longer published in later versions.
AndroidX Lifecycle KTX artifacts caught up with features that this split originally provided, so we've deprecated that overlap:
activityScope() for Activity -> viewModels()
activityScope() for Fragment -> activityViewModels()
fragmentScope() for Fragment -> viewModels()
Also, we provided variants of these that took a lambda. Since AndroidX doesn't provide such a facility, they have been kept, but the old naming has been deprecated to match the AndroidX naming.
Note that these changes provide a ReplaceWith clause for easy migration.
Important: Next alpha release will move the deprecation level to error, and the alpha release after will remove them completely. (So it's best to not skip this update if you were using these extensions.)
forEachReversedWithIndex extension for List now has an allowSafeModifications parameter.
When set to true (default is false), you can mutate the list as long as it doesn't prevent the
next iteration from happening (or that you perform a non local return to stop iterating altogether).
As usual, unsafe operations while iterating a list can result in a ConcurrentModificationException
or in an IndexOutOfBoundsException to be thrown.
The dip and dp functions now return the type of their argument (Int or Float).
You'll need to migrate usages of the previous dp function, so they pass a Float. Use "Find in Path" in the IDE to find them before fixing. If you often passed the same value to dp, the "Replace in Path" IDE option can save you even more time.
Lifecycle.isStartedFlow()
Lifecycle.isStartedFlow(timeout: Duration)
Lifecycle.isResumedFlow()
Lifecycle.isResumedFlow(timeout: Duration)
Lifecycle.stateFlow(): Flow<Lifecycle.State>
The following extension functions for Lifecycle have been promoted to @ExperimentalSplittiesApi (from @PotentialFutureAndroidXLifecycleKtxApi):
createScope
createJob
awaitResumed
awaitStarted
awaitCreated
awaitState
Dispatchers.MainAndroid is no longer needed and has been deprecated since the performance issue that affected Dispatchers.Main has been fixed since kotlinx.coroutines 1.3.3.
The following extension properties have been deprecated because they are now provided by AndroidX Lifecycle Runtime KTX:
Lifecycle.coroutineScope
LifecycleOwner.lifecycleScope
Lifecycle.job has also been deprecated even though there's no as-concise replacement because it doesn't satisfy a common use case.
Now supports macOS, iOS and JS.
TextViews in the list items are at least one line tall, even if the text is empty.New ensureAllPermissions function available in top-level and as extension for FragmentActivity and Fragment to request multiple permissions in a row and ensure you have them all granted.
NSUserDefaults, but supports custom implementation too, just like on Android).preferences property to PrefDelegates.key property to PrefDelegates.valueFlow() function to PrefDelegates to get current value and changes of a pref field.availableAtDirectBoot parameter has been renamed to androidAvailableAtDirectBoot.XxxPref classes (e.g. BoolPref, StringPref, etc.) are no longer inner classes but are now part of the PrefDelegate sealed class hierarchy.resolveThemeAttribute extension function for Context. This is the replacement for withStyledAttributes.withStyledAttributes must be replaced by new resolveThemeAttribute that also has an implementation that is working reliably in IDE Preview. It will be removed in a future release.snack, longSnack and snackForever extension functions now work with any View instead of just CoordinatorLayout.biometricManager from API 29.roleManager from API 29.configActionBar extension function for AppCompatActivity.homeAsUp extension read/write property for ActionBar.ActionBar.showTitle now supports reading current value.ActionBar.showHome now supports reading current value.ActionBar.useLogo now supports reading current value.ActionBar.showCustomView now supports reading current value.ActionBar.showHomeAsUp has been deprecated and must be replaced by homeAsUp. It will be removed in a future release.performClick twice without a UI thread dispatch) when using View.awaitOneClick(), View.awaitOneLongClick() or FloatingActionButton.showAndAwaitOneClickThenHide().UiPreView is now included by default, the extra "Views DSL IDE Preview" module is no longer needed. If you never use it in your production code, R8 should remove it from your release app. This has been done to simplify setup.isInPreview extension properties for Ui and View allow you to condition content to show based on whether it's the actual app or the IDE preview. Note that it statically evaluates to false in release builds (unlike View.isInEditmode), so the compiler will remove any code placed in the branch of an if (isInPreview) condition, and will allow R8 to remove any code that was only used in IDE preview.ViewGroup.add extension functions that take either a beforeChild or an afterChild parameter. You must use the parameter name to call one of these overloads. It comes handy in ViewGroups where the order of the child Views matters (e.g. FrameLayout and LinearLayout).space to create an android.widget.Space from a Ui, a View or a Context reference. Thanks to @Miha-x64 for the contribution!UiPreView now shows known error cases in the preview itself with a red warning triangle icon.above, below, before and after for ConstraintLayout.LayoutParams.Add slider, rangeSlider and shapeableImageView extensions for View, Ui and Context. They can instantiate the new widgets from the version 1.2.0 of the material-components-android library.
This module has been deprecated. It will no longer published in future releases.
Its content has been moved to the main "Views DSL" split.
Compiled with Kotlin 1.3.31.
This release introduces 3 new splits:
The most important change though, is how simpler integrating Splitties in your Android projects has become starting from this release, thanks to the new grouping artifacts.
See their content and their maven coordinates in the dedicated part of the README.
There is also new features and changes in existing splits, as detailed below.
The alert functions have been deprecated in favor of a more accurate naming: alertDialog.
These alertDialog functions are now usable on Context (vs previously only on Activity), and they have optional parameters to specify the title, the message and even an icon (using a resource id or a Drawable.
Also, the title and the message properties are now nullable, in respect to their accepted value.
The show and showAsync extension functions allow you to show a DialogFragment without fearing the infamous IllegalStateException if the state has already been saved, because it will wait for the lifecycle to be in the RESUMED state before showing the DialogFragment.
These 2 extension functions are defined for FragmentManager, FragmentActivity and Fragment.
show is a suspending function that resumes after the lifecycle was resumed and the DialogFragment was shown.
showAsync is when you are outside of a coroutine but it is marked as experimental because it has "async" in its name while not returning a Deferred. Feel free to suggest a better name in the issues or in the #splitties channel of Kotlin's Slack.
New suspending inline extensions functions for Lifecycle have been added for convenience:
awaitResumed, awaitStarted & awaitCreated.
They can replace code like awaitState(Lifecycle.State.RESUMED) for improved readability.
A new IconTwoLinesCheckBoxListItem class has been added. What it does is self-explanatory.
Also, all the list items are now fully xml friendly.
The colorSL and appColorSL extension functions no longer return the nullable version of ColorStateList.
All the ConstraintLayout.LayoutParams extension functions now have overloads that allow specifying the margin.
For example, the following code:
centerHorizontally()
horizontalMargin = dip(16)
can now be written on one line: centerHorizontally(margin = dip(16)).
That improves readability as the word "horizontal" is no longer repeated, and it is still explicit.
Two set-only extensions properties have been added for MaterialButton:
iconResource and iconTintAndTextColor.
Compiled with Kotlin 1.3.21.
wrapContent and matchParent extensions for ViewGroup now apply for View too.wrapInScrollView and wrapInHorizontalScrollView extension functions for View.Bit Flags and Collections splits.LifecycleOwner.coroutineScope to lifecycleScope. This change is binary compatible.wrapInRecyclerView lambda inline. This change is not binary compatible.Intents split that would cause compilation to fail when used.This release introduces a new split: Views Coroutines.
radioGroup { ... } functions in Views DSL.ConstraintLayout barriers, guidelines and groups.styledView function for use when making an API for xml styles usage in Kotlin. See an example in AppCompatStyles.materialCardView { ... } functions in Views DSL Material.navigationView { ... } functions in Views DSL Material.EditText inputType typesafe with the set only type extension property and the InputType inline class.CoroutineContext and CoroutineScope as constructor parameters for Ui subclasses.lParams functions from Views DSL and variants. Also added to the roomDb function from Arch Room as well as the verticalListLayoutParams and horizontalListLayoutParams functions from Views DSL RecyclerView.UByte, UShort, UInt and ULong).button function from Views DSL, MaterialButton is now automatically used in place of AppCompatButton if you also use Views DSL Material.mainHandler async by default to avoid vSync delays. It is used for Dispatchers.MainAndroid, so it will result in speed improvements when using Lifecycle Coroutines. If you really need sync behavior, you can use the new mainHandlerSync top level property instead.Dispatchers.MainAndroid of type MainCoroutineDispatcher so the immediate property is available.awaitState function from Lifecycle Coroutines safe to use off the main thread, and document it.validate() from the lParams { ... } function for ConstraintLayout.view from Views DSL is now an internal API.ViewFactory and related symbols are now an internal API.WallpaperManager,WifiManager, WifiP2pManager, UsbManager, DevicePolicyManager, FingerprintManager,ShortcutManager and WifiAwareManager.compileDebugKotlin gradle task is enough to update the preview. This is faster than a full build.viewFactory from Views DSL internal API compatible with IDE Preview.illegal top level function from Exceptions has been deprecated in favor of error from Kotlin stdlib.This release has the following new artifact:
"com.louiscad.splitties:splitties-views-coroutines:3.0.0-alpha03"
This release introduces a new split: Lifecycle Coroutines.
This release has the following new artifact:
"com.louiscad.splitties:splitties-lifecycle-coroutines:3.0.0-alpha02"
This release is compiled with Kotlin 1.3.11.
It is a breaking release (more details in the changes section), and the API is subject to changes as it is back to an alpha stage. APIs that are likely to change have an experimental annotation that triggers a warning (which can be removed by opt-in), to prevent you from using them unintentionally.
All the old support library artifacts have been replaced by AndroidX ones.
If your project has not migrated to AndroidX yet, please follow the quick steps below.
Theoretically, migrating a project to AndroidX is easy: you just select "Migrate to AndroidX" from the "Refactor" menu. Unfortunately, in addition to being unacceptably slow, it didn't work properly for Splitties (except for a past attempt which had to be abandoned for API stability reasons). Our experience was waiting minutes with an unresponsive IDE, then giving up with no other choice than force closing Android Studio, and finally getting a broken project, with some dangling fully qualified references (instead of proper import replacement). We reverted and looked for an alternative that would work properly, and perform faster.
The solution has been a Kotlin script that is a white box, and runs in a matter of seconds. You can use it for your project too, so you can migrate to AndroidX quickly, and in a fun way.
It is available here, and depends on this csv file.
Note that this script doesn't migrate the dependencies, because we changed the way we define dependencies (using constants defined in buildSrc), and it would have been harder to handle all the edge cases, and doing it by hand with Replace in Path from IDE was quick enough for us. If you prefer to have it, you are free to contribute and reach out in the issues or elsewhere.
To use it in your project, follow these simple steps:
gradle.properties file: android.useAndroidX=true and android.enableJetifier=true. That will ensure you can still use libraries still relying on the old support libraries.expectedNumberOfModules property defined in the AndroidX-migrator.gradle.kts file to match the number of modules that your project has.kotlinc 1.3+ available (see easy installation in official docs here).kotlinc -script AndroidX-migrator.gradle.kts and wait for completion.Now, you pass the Context only once to the AndroidStyles or AppCompatStyles constructor, and you no longer have to pass it to the subsequent functions call. It is advised to obviously cache this instance to reduce boilerplate and avoid overhead. This is a breaking change.
The design support library no longer exists in AndroidX. It is replaced by several AndroidX artifacts and the Google Material Components library.
Consequently, the package names no longer reference "design" but "coordinatorlayout" and "material" instead.
As you can see below, the design support library dependent artifacts have been replaced. Note that Views DSL Material has a transitive dependency to Views DSL CoordinatorLayout, so you don't need to add an explicit dependency for the latter if you already use the former.
This release has the following new artifacts:
"com.louiscad.splitties:splitties-views-material:3.0.0-alpha01"
"com.louiscad.splitties:splitties-views-dsl-coordinatorlayout:3.0.0-alpha01"
"com.louiscad.splitties:splitties-views-dsl-material:3.0.0-alpha01"
This release removes these two artifacts:
~"com.louiscad.splitties:splitties-views-design-styles:2.1.1"~
~"com.louiscad.splitties:splitties-views-dsl-design-styles:2.1.1"~
This release is compiled with Kotlin 1.3.10.
withExtras extension function for Activity. Any attempt to mutate
a property inside it will result in an IllegalStateException to be thrown, because this should be
done in putExtras instead. You can see more info in the updated KDoc of these functions.withExtras extension function for Intent (previously only available for Activity).putExtras extension function for Activity (previously only available for Intent).This release targets Android SDK 28, and splits depending on support libraries use version 28.0.0.
ConfigChangesHandlingCollapsingToolbarLayout from View DSL Design to be compatible with design support library version 28.0.0.