DOCSEARCHbyAlgolia
Submit Docs

Kongzue DialogX Documentation

repository·master·Indexed 25 days ago

https://github.com/kongzue/dialogx

An Android dialog component library for creating customizable, themed UI interactions. It features thread-safe execution, automatic lifecycle management to prevent WindowLeaked errors, and diverse implementation modes (View, Window, or DialogFragment). The library includes blocking components like MessageDialog, InputDialog, WaitDialog, and BottomMenu, as well as non-blocking components like PopTip and PopNotification. It utilizes a decoupled theme architecture supporting Material, Material You, iOS, MIUI, and Kongzue styles with light/dark mode switching.

Tokens
3.3K
Snippets
3
Records
16
Agent score
79%

What's inside Kongzue DialogX

  1. Overview of Kongzue DialogX

    master

    Kongzue DialogX is a highly customizable and extensible dialog component library for Android. It provides a superior user experience compared to native dialogs by offering diverse implementation modes (View, Window, or DialogFragment), automatic UI thread management, and one-line startup without requiring a context parameter.

    Key features include:

    • Thread Safety: Automatically runs on the UI thread regardless of where it is called.
    • Customization: Full control over titles, content, text, buttons, menus, input fields, and custom layouts.
    • Theming: Includes a default Material theme with optional extensions for iOS, MIUI, Material You, and Kongzue styles. Supports light/dark mode switching.
    • Lifecycle Management: Automatically handles destruction to prevent WindowLeaked memory leaks when Activities are closed.
    • Rich Animations: Features non-linear animations and smooth transitions (e.g., between loading and error states).
    • Data Penetration: Supports data passing via "Temporary Storage" and action control via "Quick Function Keys."

  2. DialogX Theme System

    master

    DialogX uses a theme separation architecture. The core framework includes only the Material design style components. To use other styles, you must introduce additional theme packages.

    Supported Themes & Features:

    • Default: Material design.
    • Extensions: Material You, iOS, Kongzue, MIUI, and more.
    • Modes: Every theme supports both Light and Dark modes.
    • Customization: Developers can implement custom themes or modify existing ones using the provided theme customization interface.
    • Switching: Light/Dark mode can be switched globally via DialogX settings.

  3. How DialogX Themes Work

    master

    DialogX uses a decoupled theme architecture. The core framework includes the Material Design style by default. To use other visual styles, you must import additional theme packages.

    Supported/Available Themes:

    • Material (Built-in)
    • Material You
    • iOS
    • MIUI
    • Kongzue
    • Custom Themes (can be developed by the user)

    Every theme supports both Light and Dark modes, which can be toggled via DialogX settings or automatically adapted to the system settings. Developers can also create their own themes using the provided theme customization interfaces.

  4. Use DialogX Extension Packs

    master

    DialogX provides a core library for basic dialog implementations to keep your application lightweight. For common advanced features, you can use separate extension packs. These modules are imported individually so you only include the resources you need.

    Commonly available features in extension packs include:

    • Address selection
    • Date selection
    • "Share to" dialogs

    Extension packs are currently in early development. You can preview them or suggest improvements via the DialogXSample repository.

  5. DialogX Component Types

    master

    DialogX provides a variety of specialized dialog components to suit different UI requirements:

    • MessageDialog & InputDialog: Basic dialogs for messages and user input. InputDialog extends the basic functionality with input boxes, customizable prompts, and input style callbacks.
    • WaitDialog & TipDialog: Blocking wait dialogs with circular or progress animations. They are single-instance, allowing seamless transitions between a waiting state (WaitDialog) and a success/warning/error tip state (TipDialog).
    • BottomDialog & BottomMenu: BottomDialog provides pop-ups from the bottom of the screen. BottomMenu extends this with menu functions, icons, and selection capabilities.
    • PopTip: A non-blocking, Toast-like text prompt that allows users to continue interacting with the interface. Supports custom icons, buttons, and duration settings.
    • PopNotification: A non-blocking in-app notification alert for in-app notifications (not a replacement for system notifications).
    • FullScreenDialog: A highly customizable pop-up that covers the screen, typically used for custom layouts with a sunken background effect.
    • CustomDialog: Offers flexible alignment options (center, bottom, top, left, right) with corresponding pop-up animations.
    • GuideDialog: Used for creating operation guides or tutorials. It can implement masks, stage light effects (round, square, or rectangle modes) around specific UI components.

  6. Understand DialogX Expansion Packs

    master

    DialogX provides a minimal core implementation to prevent application bloat. For advanced features, you can use separate extension modules. These modules are introduced individually so you only include the resources you need.

    Common features available via expansion packs include:

    • Address selection
    • Date selection
    • "Share to" dialogs

    To preview available extensions, you can visit the DialogXSample repository.

  7. Available DialogX Dialog Components

    master

    DialogX provides a wide range of pre-built components for different interaction scenarios:

    • MessageDialog & InputDialog: Basic dialogs for alerts (title, message, 1/2/3 buttons) and user input (custom hint text, input styles, and callbacks).
    • WaitDialog & TipDialog: Blocking dialogs for loading states. WaitDialog shows a circular progress animation, and it can seamlessly transition to TipDialog to show success, warning, or error states.
    • BottomDialog & BottomMenu: Dialogs that slide up from the bottom. BottomMenu extends this with menu items, icons, and single-selection capabilities.
    • PopTip: A non-blocking, toast-like text notification with customizable icons, buttons, and duration.
    • PopNotification: A non-blocking, notification-style alert for in-app notifications (does not replace system notifications).
    • FullScreenDialog: A highly customizable full-screen dialog that slides up from the bottom.
    • CustomDialog: A component for completely custom layouts. Supports various ALIGN options (Center, Bottom, Top, Left, Right) with corresponding entrance animations.
    • GuideDialog: Used for user onboarding/guides. It can create a mask over the UI with a 'spotlight' effect (circular or rectangular) to highlight specific components.

  8. Use DialogX Extension Packages

    master
    DialogX provides a core library containing only basic dialog implementations to keep your application lightweight. For common advanced features like Address Selection, Date Selection, or "Share To" dialogs, you can import specific extension packages. Each module is imported separately so you only include the resources you need.

  9. How DialogX Theming Works

    master

    DialogX uses a decoupled theme architecture. The core framework only includes the Material design style. To use other visual styles, you must include additional theme packages as dependencies.

    Available Themes:

    • Material (Built-in)
    • Material You (Extension)
    • iOS (Extension)
    • MIUI (Extension)
    • Kongzue (Extension)

    Key Theming Capabilities:

    • Light/Dark Mode: Every theme includes both light and dark versions. You can switch between them globally via DialogX settings.
    • Custom Themes: Developers can implement the DialogX theme interface to create entirely new styles or modify existing ones to reduce App size by only including necessary styles.

  10. DialogX Dialog Component Types

    master

    DialogX provides a wide range of specialized dialog components to suit different UX requirements:

    Blocking Dialogs (Interrupt user flow)

    • MessageDialog: Basic dialog for titles, messages, and 1/2/3 buttons (vertical or horizontal).
    • InputDialog: An extension of MessageDialog that includes an input field with customizable hint text, styles, and callbacks.
    • WaitDialog & TipDialog: A singleton pair for seamless transitions. WaitDialog shows a loading animation, which can transition smoothly into TipDialog to show success, warning, or error states.
    • BottomDialog: A dialog that slides up from the bottom. Supports custom layouts and swipe-to-close/expand in Material themes.
    • BottomMenu: An extension of BottomDialog adding menu items with icons and single-select functionality.
    • FullScreenDialog: A highly customizable full-screen overlay that pops up from the bottom.
    • CustomDialog: A completely user-defined layout component. Supports various ALIGN options (Center, Bottom, Top, Left, Right) and custom animations.
    • GuideDialog (Beta): Used for onboarding/tutorials. It can create a mask over the UI and highlight specific components using "spotlight" effects (Circular, Square, or Rectangular modes).

    Non-Blocking Dialogs (Allow user interaction)

    • PopTip: A highly customizable text hint similar to a Toast. Supports icons, control buttons, and custom durations. Does not block user interaction.
    • PopNotification: An in-app notification style similar to system notifications. Supports icons, buttons, and custom durations. Does not block user interaction.

  11. Install DialogX via MavenCentral

    master

    To include DialogX in your Android project using MavenCentral, follow these two steps:

    1. Add mavenCentral() to your allprojects block in the project-level build.gradle file. Note: If you are using Android Studio Arctic Fox or newer, you must add this configuration to settings.gradle instead.

    2. Add the DialogX dependency to the dependencies block in your app-level build.gradle file.

    Note: The version used in the examples below is 0.0.49. Check MavenCentral for the latest version.

    // 1. Project-level build.gradle
allprojects {
    repositories {
        google()
        mavenCentral()
    }
}

// 2. App-level build.gradle
def dialogx_version = "0.0.49"
implementation "com.kongzue.dialogx:DialogX:${dialogx_version}"

  12. Install DialogX via Jitpack

    master

    To include DialogX in your Android project using Jitpack, follow these two steps:

    1. Add the Jitpack Maven URL to your allprojects block in the project-level build.gradle file. Note: If you are using Android Studio Arctic Fox or newer, you must add this configuration to settings.gradle instead.

    2. Add the DialogX dependency to the dependencies block in your app-level build.gradle file.

    Note: The version used in the examples below is 0.0.49. Check Jitpack for the latest version.

    // 1. Project-level build.gradle
allprojects {
    repositories {
        google()
        maven { url 'https://jitpack.io' }
    }
}

// 2. App-level build.gradle
def dialogx_version = "0.0.49"
implementation "com.github.kongzue.DialogX:DialogX:${dialogx_version}"