StateLayout

https://liangjingkanji.github.io/StateLayout/
Admin
An Android framework for managing and displaying UI states (loading, empty, error, content) with...
Tokens:4,984
Snippets:80
Trust Score:9.7
Update:5 months ago
Show doc for...
Tokens:
Raw
### Custom Retry Listener in Lifecycle Callback

Source: https://liangjingkanji.github.io/StateLayout/retry.html

Implement custom retry logic by setting click listeners on views within lifecycle callbacks. This example shows how to set an OnClickListener on an image view to trigger showLoading() when an error state occurs.

```kotlin
binding.state.onError {
    findViewById<View>(R.id.image).setOnClickListener {
        binding.state.showLoading()
    }
}

```

--------------------------------

### Configure State Layouts via Code

Source: https://liangjingkanji.github.io/StateLayout/index.html?q=

Set custom layouts for empty, error, and loading states programmatically using the apply extension function.

```kotlin
state.apply {
    emptyLayout = R.layout.layout_empty // 配置空布局
    errorLayout = R.layout.layout_error // 配置错误布局
    loadingLayout = R.layout.layout_loading // 配置加载中布局
}

```

--------------------------------

### Trigger Refresh and Show Loading

Source: https://liangjingkanji.github.io/StateLayout/callback.html

Use onRefresh to initiate network requests and then call showLoading() to display the loading state. This is common for handling asynchronous network tasks.

```kotlin
state.onRefresh {
    // 执行请求
}.showLoading()
```

--------------------------------

### Applying Fade-In Animation to Default Pages

Source: https://liangjingkanji.github.io/StateLayout/animation.html?q=

Applies the custom `startAnimation` to all default page states (onError, onEmpty, onContent, onLoading) using StateConfig.

```kotlin
StateConfig.apply {
    onError {
        startAnimation()
    }
    onEmpty {
        startAnimation()
    }
    onContent {
        startAnimation()
    }
    onLoading {
        startAnimation()
    }
}
```

--------------------------------

### Configure State Layouts via XML

Source: https://liangjingkanji.github.io/StateLayout/index.html?q=

Define custom layouts for empty, error, and loading states directly in the StateLayout's XML attributes.

```xml
<com.drake.statelayout.StateLayout
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/state"
    app:empty_layout="@layout/layout_empty"
    app:error_layout="@layout/layout_error"
    app:loading_layout="@layout/layout_loading"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="com.example.statelayout.MainActivity">

    <TextView
        android:id="@+id/tv_content"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:text="加载成功" />

</com.drake.statelayout.StateLayout>

```

--------------------------------

### Initialize Global StateLayout Configuration

Source: https://liangjingkanji.github.io/StateLayout/config.html

Apply global configurations to StateLayout in your Application class. This includes setting custom layouts for empty, error, and loading states, defining global retry IDs, and configuring callbacks for state changes.

```kotlin
StateConfig.apply {
    emptyLayout = R.layout.layout_empty
    errorLayout = R.layout.layout_error
    loadingLayout = R.layout.layout_loading

    setRetryIds(R.id.msg) // 全局的重试Id

    onLoading {

    }

    onEmpty {

    }

    onError {

    }
}

```

--------------------------------

### Activity.state()

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Extension function to create and attach a StateLayout to an Activity, managing its content states.

```APIDOC
## Function Activity.state()

### Description
Creates a default page to wrap the Activity. It is recommended to create StateLayout in XML.

### Returns
StateLayout - The created StateLayout instance.

### Type
fun Activity.state(): StateLayout
```

--------------------------------

### StateConfig

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Global configuration object for StateLayout, allowing customization of default page layouts and behavior across the application.

```APIDOC
## Object StateConfig

### Description
Global default page layout StateLayout configuration.

### Type
object StateConfig
```

--------------------------------

### View.state()

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Extension function to create and attach a StateLayout to a View, enabling state management for that specific view.

```APIDOC
## Function View.state()

### Description
Creates a default page to wrap the View. It is recommended to create StateLayout in XML.

### Returns
StateLayout - The created StateLayout instance.

### Type
fun View.state(): StateLayout
```

--------------------------------

### Global Error Listener for StateConfig

Source: https://liangjingkanji.github.io/StateLayout/tag.html

Configure a global error listener using `StateConfig` to handle `ResponseException` across the application. This is useful for centralized error management.

```kotlin
StateConfig.onError {
    if (it is ResponseException) {
        findViewById<TextView>.text = "错误码: ${it.code}, 错误信息: ${it.msg}"
    }
}
```

--------------------------------

### Create StateLayout Programmatically

Source: https://liangjingkanji.github.io/StateLayout/index.html?q=

Instantiate StateLayout directly in your Activity, Fragment, or View. Note: This method is not recommended due to potential performance issues with repeated calls.

```kotlin
stateCreate() // 可在 Activity/Fragment/View 中使用

```

--------------------------------

### Listen to Default State Changes

Source: https://liangjingkanji.github.io/StateLayout/callback.html

Register callbacks for different state changes like empty, error, loading, and refresh. These callbacks allow you to perform actions or update UI when specific states are shown.

```kotlin
state.onEmpty {

}.onError {

}.onLoading {

}.onRefresh {

}
```

--------------------------------

### Fragment.state()

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Extension function to create and attach a StateLayout to a Fragment, facilitating state management within the fragment's view hierarchy.

```APIDOC
## Function Fragment.state()

### Description
Creates a default page to wrap the Fragment. It is recommended to create StateLayout in XML.

### Returns
StateLayout - The created StateLayout instance.

### Type
fun Fragment.state(): StateLayout
```

--------------------------------

### View Extension for Fade-In Animation

Source: https://liangjingkanji.github.io/StateLayout/animation.html?q=

A Kotlin extension function to hide a view and then fade it in over 800 milliseconds. Use this for default page animations.

```kotlin
private fun View.startAnimation() {
    // 先将视图隐藏然后在800毫秒内渐变显示视图
    animate().setDuration(0).alpha(0F).withEndAction {
        animate().setDuration(800).alpha(1F)
    }
}
```

--------------------------------

### Show Error with Exception Tag

Source: https://liangjingkanji.github.io/StateLayout/multi-state.html

Pass an exception object as a tag to differentiate error states. This allows for specific handling of different types of errors.

```kotlin
showError(NetNetworkingException()) // 传递异常对象作为标签
```

--------------------------------

### Configure Global Error View Callback

Source: https://liangjingkanji.github.io/StateLayout/multi-state.html

Configure a global callback for error states to customize the error view based on the exception type. This is useful for displaying specific images or views for different network errors.

```kotlin
StateConfig.onError {
    if (it is NetNetworkingException) {
        // 为无网络异常展示不同图片, 当然你也可以addView
        findViewById<View>(R.id.iv_error).setImageResource(R.drawable.ic_networking_error)
    }
}
```

--------------------------------

### Display Different States

Source: https://liangjingkanji.github.io/StateLayout/index.html?q=

Control the visibility of loading, empty, error, and content views using simple function calls. These functions accept an optional tag for custom display.

```kotlin
state.showLoading()
state.showEmpty()
state.showError()
state.showContent()

```

--------------------------------

### Show Error with Tag

Source: https://liangjingkanji.github.io/StateLayout/tag.html

Use `showError` with a `ResponseException` to display an error state with a specific code and message.

```kotlin
state.showError(ResponseException(code = 403, msg = "请求参数错误"))
```

--------------------------------

### Declare StateLayout in XML

Source: https://liangjingkanji.github.io/StateLayout/index.html?q=

Define the StateLayout in your XML layout file. This view will wrap your main content and manage state transitions.

```xml
<com.drake.statelayout.StateLayout
    xmlns:app="http://schemas.android.com/apk/res-auto"
    xmlns:tools="http://schemas.android.com/tools"
    android:id="@+id/state"
    android:layout_width="match_parent"
    android:layout_height="match_parent"
    tools:context="com.example.statelayout.MainActivity">

    <TextView
        android:id="@+id/tv_content"
        android:layout_width="wrap_content"
        android:layout_height="wrap_content"
        android:layout_gravity="center"
        android:text="加载成功" />

</com.drake.statelayout.StateLayout>

```

--------------------------------

### Assigning a Custom StateChangedHandler (Singleton)

Source: https://liangjingkanji.github.io/StateLayout/callback.html?q=

Assign a custom StateChangedHandler to the state object to completely take over the default default page switching logic. This allows for custom animations and layout parameters.

```kotlin
state.stateChangedHandler = StateChangedHandler()
```

--------------------------------

### StateLayout

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

A FrameLayout that manages and displays different states (loading, empty, error, content) for its child views.

```APIDOC
## Class StateLayout

### Description
Applies global default page settings. Singleton configuration. Local default page data transfer. Listens to the display lifecycle of the default page. Custom animations. Layout or code declaration is acceptable. Quickly configure click-to-retry. Display error page immediately when there is no network.

### Constructor
@JvmOverloads constructor(context: Context, attrs: AttributeSet?, defStyleAttr: Int)

### Type
class StateLayout : FrameLayout
```

--------------------------------

### Global Configuration of StateChangedHandler

Source: https://liangjingkanji.github.io/StateLayout/animation.html?q=

Configures the `FadeStateChangedHandler` globally for all StateLayout instances by setting it on `StateConfig`.

```kotlin
StateConfig.stateChangedHandler = StateChangedHandler()
```

--------------------------------

### Implement Custom State Handling

Source: https://liangjingkanji.github.io/StateLayout/callback.html

Assign a StateChangedHandler to completely take over the default state change logic. This allows for custom animations, layout parameters, and view management (e.g., using visibility instead of add/remove views).

```kotlin
state.stateChangedHandler = StateChangedHandler()
```

```kotlin
StateConfig.stateChangedHandler = StateChangedHandler()
```

--------------------------------

### Quickly Configure Retry IDs Globally

Source: https://liangjingkanji.github.io/StateLayout/retry.html

Set retryable view IDs globally for the StateLayout. This allows any view with the specified ID to trigger a retry when clicked in an error or empty state.

```kotlin
state.setRetryIds(R.id.msg)

```

```kotlin
StateConfig.setRetryIds(R.id.msg)

```

--------------------------------

### Global Error Listener for State

Source: https://liangjingkanji.github.io/StateLayout/tag.html

Set a global error listener for the `state` object to handle `ResponseException` globally. This listener will be triggered for any errors encountered.

```kotlin
state.onError {
    if (it is ResponseException) {
        findViewById<TextView>.text = "错误码: ${it.code}, 错误信息: ${it.msg}"
    }
}
```

--------------------------------

### StatePair

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

A data class used to pair a View with an associated object, often used for passing data related to a specific state.

```APIDOC
## Data Class StatePair

### Description
Pairs a View with an associated object.

### Properties
- **first**: View - The associated View.
- **second**: Any? - The associated object.

### Type
data class StatePair(first: View, second: Any?) : Serializable
```

--------------------------------

### Status Enum

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Enumeration representing the possible states of a StateLayout, such as CONTENT, EMPTY, ERROR, and LOADING.

```APIDOC
## Enum Status

### Description
Enumeration for the status of the default page.

### Values
- CONTENT
- EMPTY
- ERROR
- LOADING

### Type
enum Status : Enum<Status>
```

--------------------------------

### FadeStateChangedHandler for State Transitions

Source: https://liangjingkanji.github.io/StateLayout/animation.html?q=

A custom `StateChangedHandler` that provides a fade transition animation between states. It handles removing the old state with a fade-out and adding the new state with a fade-in.

```kotlin
/**
 * 切换状态时使用渐变透明动画过渡
 * @param duration 动画执行时间
 */
open class FadeStateChangedHandler(var duration: Long = 400) : StateChangedHandler {

    private var stateLayout: WeakReference<StateLayout> = WeakReference(null)

    /**
     * StateLayout删除缺省页, 此方法比[onAdd]先执行
     * @param container StateLayout
     * @param state 将被删除缺省页视图对象
     * @param status 当前状态
     * @param tag 显示状态传入的tag
     */
    override fun onRemove(container: StateLayout, state: View, status: Status, tag: Any?) {
        if (container != stateLayout.get() && status == Status.LOADING) {
            return super.onRemove(container, state, status, tag)
        }
        state.animate().setDuration(duration).alpha(0f).setListener(object : AnimatorListenerAdapter() {
            override fun onAnimationEnd(animation: Animator) {
                // 等待动画执行完毕后删除旧的缺省页视图
                StateChangedHandler.onRemove(container, state, status, tag)
            }
        }).start()
    }

    /**
     * StateLayout添加缺省页
     * @param container StateLayout
     * @param state 将被添加缺省页视图对象
     * @param status 当前状态
     * @param tag 显示状态传入的tag
     */
    override fun onAdd(container: StateLayout, state: View, status: Status, tag: Any?) {
        // 初次加载不应用动画
        if (container != stateLayout.get() && status == Status.LOADING) {
            stateLayout = WeakReference(container)
            return StateChangedHandler.onAdd(container, state, status, tag)
        }
        super.onAdd(container, state, status, tag)
        state.alpha = 0f
        state.animate().setDuration(duration).alpha(1f).start()
    }
}
```

--------------------------------

### StateChangedHandler

Source: https://liangjingkanji.github.io/StateLayout/api/-state-layout/com.drake.statelayout/index.html

Handles state changes in StateLayout, allowing custom logic for view visibility, creation, or animation during state transitions.

```APIDOC
## Class StateChangedHandler

### Description
Provides richer handling for default page switching. You can decide whether to delete, hide, or dynamically create layout parameters and even state transition animations for the default page.

### Type
open class StateChangedHandler
```
Tokens:
Raw