Releases: LouisCAD/Splitties
3.0.0-alpha07
Compiled with Kotlin 1.3.72 and kotlinx.coroutines 1.3.8.
This release introduces 2 new splits:
- Alert Dialog Material (Android only) Thanks @ivoberger for the contribution!
- Coroutines (supports macOS, iOS, JS, JVM & Android)
Alert Dialog and Alert Dialog AppCompat
Added
Add isCancellable
parameter (defaults to true
, as when unspecified) to alertDialog
builders.
Arch Lifecycle
Added
viewModels { … }
forFragmentActivity
andFragment
activityViewModels { … }
forFragment
Changed
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.
Deprecated
AndroidX Lifecycle KTX artifacts caught up with features that this split originally provided, so we've deprecated that overlap:
activityScope()
forActivity
->viewModels()
activityScope()
forFragment
->activityViewModels()
fragmentScope()
forFragment
->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.)
Collections
Added
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.
Dimensions
Changed
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 Coroutines
Added
Lifecycle.isStartedFlow()
Lifecycle.isStartedFlow(timeout: Duration)
Lifecycle.isResumedFlow()
Lifecycle.isResumedFlow(timeout: Duration)
Lifecycle.stateFlow(): Flow<Lifecycle.State>
Changed
The following extension functions for Lifecycle
have been promoted to @ExperimentalSplittiesApi
(from @PotentialFutureAndroidXLifecycleKtxApi
):
createScope
createJob
awaitResumed
awaitStarted
awaitCreated
awaitState
Deprecated
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.
Main Thread
Added
Now supports macOS, iOS and JS.
Material Lists
Changed
- Ensure all
TextView
s in the list items are at least one line tall, even if the text is empty. - Support enabled/disabled state by making child views duplicate parent state.
Permissions
Added
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.
Preferences
Added
- Now supports macOS and iOS (backed by
NSUserDefaults
, but supports custom implementation too, just like on Android). - Added
preferences
property toPrefDelegate
s. - Added
key
property toPrefDelegate
s. - Added
valueFlow()
function toPrefDelegate
s to get current value and changes of a pref field.
Changed
- The
availableAtDirectBoot
parameter has been renamed toandroidAvailableAtDirectBoot
. - The
XxxPref
classes (e.g.BoolPref
,StringPref
, etc.) are no longer inner classes but are now part of thePrefDelegate
sealed class hierarchy.
Resources
Added
- New
resolveThemeAttribute
extension function forContext
. This is the replacement forwithStyledAttributes
.
Deprecated
withStyledAttributes
must be replaced by newresolveThemeAttribute
that also has an implementation that is working reliably in IDE Preview. It will be removed in a future release.
Snackbar
Changed
- The
snack
,longSnack
andsnackForever
extension functions now work with anyView
instead of justCoordinatorLayout
.
System Services
Added
- Add
biometricManager
from API 29. - Add
roleManager
from API 29.
Views AppCompat
Added
configActionBar
extension function forAppCompatActivity
.homeAsUp
extension read/write property forActionBar
.
Changed
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.
Deprecated
ActionBar.showHomeAsUp
has been deprecated and must be replaced byhomeAsUp
. It will be removed in a future release.
Views Coroutines & Views Coroutines Material
Bug fixes
- Fix a very rare crash that would occur when performing two clicks or long clicks in a row (e.g. by calling
performClick
twice without a UI thread dispatch) when usingView.awaitOneClick()
,View.awaitOneLongClick()
orFloatingActionButton.showAndAwaitOneClickThenHide()
.
Views DSL
Added
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.- The
isInPreview
extension properties forUi
andView
allow you to condition content to show based on whether it's the actual app or the IDE preview. Note that it statically evaluates tofalse
in release builds (unlikeView.isInEditmode
), so the compiler will remove any code placed in the branch of anif (isInPreview)
condition, and will allow R8 to remove any code that was only used in IDE preview. - There's 2 new overloads of the
ViewGroup.add
extension functions that take either abeforeChild
or anafterChild
parameter. You must use the parameter name to call one of these overloads. It comes handy inViewGroup
s where the order of the childView
s matters (e.g.FrameLayout
andLinearLayout
). space
to create anandroid.widget.Space
from aUi
, aView
or aContext
reference. Thanks to @Miha-x64 for the contribution!
Changed
UiPreView
now shows known error cases in the preview itself with a red warning triangle icon.
Views DSL ConstraintLayout
Added
- Add new extensions:
above
,below
,before
andafter
forConstraintLayout.LayoutParams
.
Views DSL Material
Added
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.
Views DSL IDE preview
This module has been deprecated. It will no longer published in future releases.
Its content has been moved to the main "Views DSL" split.
3.0.0-alpha06
3.0.0-alpha05
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.
Alert Dialog & Alert Dialog AppCompat
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.
Fragments
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.
Lifecycle Coroutines
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.
Material Lists
A new IconTwoLinesCheckBoxListItem
class has been added. What it does is self-explanatory.
Also, all the list items are now fully xml friendly.
Resources
The colorSL
and appColorSL
extension functions no longer return the nullable version of ColorStateList
.
Views DSL ConstraintLayout
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.
Views Material
Two set-only extensions properties have been added for MaterialButton
:
iconResource
and iconTintAndTextColor
.
3.0.0-alpha04
Compiled with Kotlin 1.3.21.
New features
- The
wrapContent
andmatchParent
extensions forViewGroup
now apply forView
too. - Add
wrapInScrollView
andwrapInHorizontalScrollView
extension functions forView
. - Add experimental multiplatform support with initial Kotlin/JS support for the
Bit Flags
andCollections
splits.
Changes
- Rename
LifecycleOwner.coroutineScope
tolifecycleScope
. This change is binary compatible. - Make
wrapInRecyclerView
lambda inline. This change is not binary compatible.
Fixes
- Remove contract in the
Intents
split that would cause compilation to fail when used.
3.0.0-alpha03
This release introduces a new split: Views Coroutines.
New features
- Added
radioGroup { ... }
functions in Views DSL. - Added first class support for
ConstraintLayout
barriers, guidelines and groups. - New
styledView
function for use when making an API for xml styles usage in Kotlin. See an example in AppCompatStyles. - The MaterialComponentsStyles class brings access to all the xml styles defined in Google's Material Components library for Android in a typesafe way.
- Add
materialCardView { ... }
functions in Views DSL Material. - Add
navigationView { ... }
functions in Views DSL Material. - Make
EditText
inputType typesafe with the set onlytype
extension property and theInputType
inline class. - Views DSL IDE Preview now supports
CoroutineContext
andCoroutineScope
as constructor parameters forUi
subclasses. - Added contracts for all the
lParams
functions from Views DSL and variants. Also added to theroomDb
function from Arch Room as well as theverticalListLayoutParams
andhorizontalListLayoutParams
functions from Views DSL RecyclerView. - Add support for unsigned numbers in Bit Flags (i.e.
UByte
,UShort
,UInt
andULong
).
Changes
- When using the
button
function from Views DSL,MaterialButton
is now automatically used in place ofAppCompatButton
if you also use Views DSL Material. - Make
mainHandler
async by default to avoid vSync delays. It is used forDispatchers.MainAndroid
, so it will result in speed improvements when using Lifecycle Coroutines. If you really need sync behavior, you can use the newmainHandlerSync
top level property instead. - Make
Dispatchers.MainAndroid
of typeMainCoroutineDispatcher
so theimmediate
property is available. - Make the
awaitState
function from Lifecycle Coroutines safe to use off the main thread, and document it. - Call
validate()
from thelParams { ... }
function forConstraintLayout
. - Make xml styles related classes inline again (thanks to compiler bug fixed in Kotlin 1.3.20).
- The reified generic variant of
view
from Views DSL is now an internal API. ViewFactory
and related symbols are now an internal API.- Mark some SystemServices as nullable to be instant app tolerant. That includes
WallpaperManager
,WifiManager
,WifiP2pManager
,UsbManager
,DevicePolicyManager
,FingerprintManager
,ShortcutManager
andWifiAwareManager
. - The Views DSL IDE Preview documentation now states that running the
compileDebugKotlin
gradle task is enough to update the preview. This is faster than a full build.
Fixes
- Make
viewFactory
from Views DSL internal API compatible with IDE Preview.
Deprecation
- The
illegal
top level function from Exceptions has been deprecated in favor oferror
from Kotlin stdlib.
New artifact
This release has the following new artifact:
"com.louiscad.splitties:splitties-views-coroutines:3.0.0-alpha03"
3.0.0-alpha02
This release introduces a new split: Lifecycle Coroutines.
New artifact
This release has the following new artifact:
"com.louiscad.splitties:splitties-lifecycle-coroutines:3.0.0-alpha02"
3.0.0-alpha01
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.
Migration to AndroidX
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.
Migrating your project to AndroidX in a `fun` way. (Click to expand)
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:
- Replace the support libraries dependencies by AndroidX dependencies (and update Splitties ones if you already used it).
- Add the following two snippets on separate lines to your project's
gradle.properties
file:android.useAndroidX=true
andandroid.enableJetifier=true
. That will ensure you can still use libraries still relying on the old support libraries. - Copy paste the two files linked above at the root of the gradle project.
- Edit the
expectedNumberOfModules
property defined in theAndroidX-migrator.gradle.kts
file to match the number of modules that your project has. - Make sure you have
kotlinc
1.3+ available (see easy installation in official docs here). - Open a terminal at the root of the gradle project.
- Run
kotlinc -script AndroidX-migrator.gradle.kts
and wait for completion. - Sync gradle project.
- Build the project to ensure everything has migrated properly, or fix and try again.
Improved API to use xml styles defined in Android or AppCompat
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.
Package name changes and replaced artifacts
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.
New artifacts
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"
Removed artifacts
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"
Splitties v2.1.1
This release is compiled with Kotlin 1.3.10.
Changes
- Enforce read-only in the
withExtras
extension function forActivity
. Any attempt to mutate
a property inside it will result in anIllegalStateException
to be thrown, because this should be
done inputExtras
instead. You can see more info in the updated KDoc of these functions. - Add a
withExtras
extension function forIntent
(previously only available forActivity
). - Add a
putExtras
extension function forActivity
(previously only available forIntent
). - Fix nullability warning in FragmentArgDelegate.
- Add KDoc to all public symbols from the Activities split.
- Add KDoc to all public symbols from the AlertDialog split.
- Add KDoc to all public symbols from the AlertDialog AppCompat split.
Splitties v2.1.0
This release targets Android SDK 28, and splits depending on support libraries use version 28.0.0.
Changes
- System Services from API 28 are now included into the same named split.
- Update
ConfigChangesHandlingCollapsingToolbarLayout
from View DSL Design to be compatible with design support library version 28.0.0. - Update for nullability warnings brought by SDK 28.
Splitties v2.0.0
This release targets Android SDK 27, and splits depending on support libraries use version 27.1.1.
Changes
- Room updated to version 1.1.1 in Arch Room.
- Lambdas of
onCreate
andonOpen
functions in Arch Room are nowcrossinline
. - The
LifecycleObserver
class is now marked as experimental.