Splitties Documentation

Splitties Views DSL allows you to create Android UIs using readable Kotlin code instead of XML. It is designed as a collection of extension functions and properties rather than a new class hierarchy, making it easy to discover and use within existing Android projects.

Key characteristics:

• Interoperability: Seamlessly works with existing android.view.View objects and XML layouts.
• Stability: The API is stable and built on the foundation of the standard Android View API.
• Simplicity: You don't need to learn a new framework; you simply use extension functions to configure views.

Example of creating a button:

val launchDemoBtn = button {
    textResource = R.string.go_to_the_demo
}

The material-lists module provides Android View implementations for Material Design list components and controls. These views are designed to be used within a RecyclerView to implement standard Material Design list patterns.

Available list item View implementations:

• IconOneLineListItem
• IconTwoLinesListItem
• IconTwoLinesSwitchListItem
• IconTwoLinesCheckBoxListItem
• SwitchTwoLinesIconListItem

The views-selectable module provides selectable versions of LinearLayout and platform TextView. These are useful for list items or other UI elements that require visual feedback when clicked.

They include a foregroundSelector property that behaves like the foreground property on API 23+ views. By default, this is set to android.R.attr.selectableItemBackground, which provides a ripple effect on Android Lollipop and newer versions.

The views-dsl core module can be extended with specialized modules to provide support for specific Android components and styling systems:

• AppCompat: Provides proper styling for standard widgets like Button, TextView, EditText, and others.
• ConstraintLayout: Adds support for ConstraintLayout.LayoutParams when laying out views.
• IDE preview: Enables the ability to preview user interfaces directly within the IDE.
• Material: Provides extensions specifically for Material Components.
• RecyclerView: Provides extensions for handling scrollbars and managing proper itemView layout parameters.

The checkedlazy module provides specialized Lazy delegates that execute a validation check every time the property is accessed.

While standard Kotlin lazy only runs the initializer once, checkedLazy runs the provided check function on every access. This is primarily used on Android to enforce thread safety (e.g., ensuring UI-related objects are only touched on the Main thread) or to catch illegal access patterns during development.

Note: In many modern Android use cases, Kotlin Coroutines can replace the need for these specific splits.

The lParams() extension function on ConstraintLayout provides a DSL for defining child layout parameters. It differs from LinearLayout or FrameLayout extensions in two ways:

1. Default Dimensions: The default width and height are set to matchConstraints instead of wrapContent. You must explicitly set height = wrapContent for components like TextView or Button if you don't want them to stretch.
2. Optimized matchParent: Using matchParent is automatically rewritten as matchConstraints with the appropriate parent-relative constraints. This avoids the performance penalties associated with using match_parent in XML-based ConstraintLayout.

The Ui interface is a core abstraction in Splitties Views DSL designed to decouple UI code from business logic (like Activity or Fragment classes). Instead of writing UI logic inside a 'god' class, you implement the Ui interface in a dedicated class. This promotes modularity, makes testing easier, and allows for easy A/B testing or multi-form factor support by swapping implementations of the same interface.

The interface consists of two mandatory properties:

• ctx: The Context required to create Android Views.
• root: The top-level View that represents the UI hierarchy.

By using interfaces to define UI contracts, you can separate the what (the symbols exposed to the controller) from the how (the specific View-based implementation).

interface Ui {
    val ctx: Context
    val root: View
}

The splitties-collections module provides extension functions for List that allow iteration without allocating an Iterator object. This is specifically designed for performance-critical scenarios, such as code executed within an onDraw method or code running on the UI thread.

Available extension functions:

• forEachByIndex: Iterates through the list providing only the index.
• forEachWithIndex: Iterates through the list providing both the index and the element.
• forEachReversedByIndex: Iterates through the list in reverse order providing only the index.
• forEachReversedWithIndex: Iterates through the list in reverse order providing both the index and the element.