Skip to content

README_EN.md

Latest commit

 

History

History
111 lines (85 loc) · 7.06 KB

README_EN.md

File metadata and controls

111 lines (85 loc) · 7.06 KB
Raw

FloatingX

FloatingX logo

Codacy Badge Maven Central ktlint AtomGit Star

简体中文 · Wiki · DeepWiki

FloatingX is a flexible and powerful floating window solution for Android.

3.0 is a ground-up rewrite split into opt-in modules; the API is not compatible with 2.x, see Migration from 2.x.

👏 Features

  • Supports Jetpack Compose; each window owns a ViewModelStore / SavedState that survives page changes
  • Supports system windows, in-app windows and scoped windows (ViewGroup / Fragment / Activity)
  • Supports page changes without rebuilding; position, state and animation follow the Activity
  • Supports anchor-based positioning; rotation and content resizing never drift the window
  • Supports edge snapping, half-hide, bounds and no-clip overflow
  • Supports a drag region, drag after long press, and conflict handling with scrolling lists
  • Supports custom show / hide animations
  • Supports saving and restoring the last position (per tag + orientation)
  • Supports blacklist / whitelist to keep the window off given pages
  • Supports modal windows that block outside touches
  • Supports system window permission auto / manual request, with automatic fallback to an in-app window when denied
  • Supports calling show / moveTo before the host is ready; they run once it is
  • Supports a kotlin DSL and a Java-friendly Builder
  • Full logging: enableLog(tag) shows what Fx is doing

👨‍💻‍ Dependencies

dependencies {
    implementation "io.github.petterpx:floatingx-core:3.0.0"      // pulled in by the other modules
    implementation "io.github.petterpx:floatingx-app:3.0.0"       // app-level global window (follows Activity)
    implementation "io.github.petterpx:floatingx-system:3.0.0"    // system window (WindowManager + permission)
    implementation "io.github.petterpx:floatingx-scope:3.0.0"     // local window (Activity / ViewGroup / Fragment)
    implementation "io.github.petterpx:floatingx-compose:3.0.0"   // Jetpack Compose content
}

Only add the modules you use; core comes along with them. minSdk 21 (23 for the compose module). Permissions and the provider are declared in the library manifests, nothing to add on your side.

🚀 Quick start

val control = FloatingX.install("music") {
    layout(R.layout.fx_card)
    anchor(FxGravity.CENTER_END, dy = 120f)
    margin(top = 24f, bottom = 24f)
    adsorb(FxAdsorb.Edges(setOf(FxEdge.START, FxEdge.END), halfHide = FxHalfHide(0.3f)))
    persist(FxSpStorage(app))
    enableLog("Fx-demo")
    appHost(app) {
        // pass a Class, not a class name: matched with isInstance, so subclasses are hit too
        blacklist(SplashActivity::class.java)
    }
}
control.show()

For Java, system windows, local windows and Compose windows, see Getting Started.

📖 Documentation

The full documentation lives in the GitHub Wiki (English-titled pages are English, Chinese-titled pages are Chinese):

🏄‍♀️ Demo GIFs

App host: drag / adsorb / follows pages System host: stays on the launcher Rotation: anchor kept
App host: drag / adsorb / follows pages System host: stays on the launcher Rotation: anchor kept
Resize: anchor stays put (#187) Compose: counter survives pages Scoped: ViewGroup / Fragment
Resize: anchor stays put (#187) Compose: counter survives pages Scoped: ViewGroup / Fragment

📱 Demo

The app module is a full sample and regression harness — ./gradlew app:installDebug installs it; the page list is on Demo.

👍 Thanks

The initial implementation idea of the basic floating window View comes from EnFloatingView's FloatingMagnetView, which was thoroughly refactored and evolved; the navigation-bar measurement code comes from Wenlu and has been further adapted to cover more devices.

About Me

Welcome to follow my public account and look forward to progressing together. If you have any usage problems, you can also add me on WeChat: Petterpx.

Petterp-wechat