Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/square/curtains
Lift the curtain on Android Windows!
https://github.com/square/curtains
Last synced: 3 months ago
JSON representation
Lift the curtain on Android Windows!
- Host: GitHub
- URL: https://github.com/square/curtains
- Owner: square
- License: apache-2.0
- Created: 2021-02-01T19:24:16.000Z (almost 4 years ago)
- Default Branch: main
- Last Pushed: 2024-01-16T21:22:35.000Z (10 months ago)
- Last Synced: 2024-07-11T17:09:53.170Z (4 months ago)
- Language: Kotlin
- Homepage:
- Size: 2.05 MB
- Stars: 597
- Watchers: 14
- Forks: 30
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: .github/CONTRIBUTING.md
- License: LICENSE.md
- Code of conduct: .github/CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
- awesome-list - square/curtains - Lift the curtain on Android Windows! (Kotlin)
README
# Curtains
_Lift the curtain on Android Windows!_
Curtains provides centralized APIs for dealing with Android windows.
Here are a few use cases that Curtains enables:
* Intercepting touch events on all activities and dialogs: for logging, detecting frozen frames on touch,
fixing known [bugs](https://issuetracker.google.com/issues/156666934) or ignoring touch events
during transitions.
* Knowing when root views are detached, e.g. to detect if they might be leaking ([LeakCanary](https://github.com/square/leakcanary)).
* Listing all attached root views for debugging ([Radiography](https://github.com/square/radiography)) or test purposes ([Espresso](https://github.com/android/android-test/blob/master/espresso/core/java/androidx/test/espresso/base/RootsOracle.java)).
## Table of contents
* [Usage](#usage)
* [FAQ](#faq)
* [License](#license)
## Usage
Add the `curtains` dependency to your library or app's `build.gradle` file:
```gradle
dependencies {
implementation 'com.squareup.curtains:curtains:1.2.5'
}
```
The library has two main entry points, [Curtains.kt](https://github.com/square/curtains/blob/main/curtains/src/main/java/curtains/Curtains.kt) and [Windows.kt](https://github.com/square/curtains/blob/main/curtains/src/main/java/curtains/Windows.kt).
### Curtains.kt
[Curtains.kt](https://github.com/square/curtains/blob/main/curtains/src/main/java/curtains/Curtains.kt)
provides access to the current root views (`Curtains.rootViews`), as well as the ability to set
listeners to get notified of additions and removals:
```kotlin
Curtains.onRootViewsChangedListeners += OnRootViewsChangedListener { view, added ->
println("root $view ${if (added) "added" else "removed"}")
}
```
### Windows.kt
[Windows.kt](https://github.com/square/curtains/blob/main/curtains/src/main/java/curtains/Windows.kt)
provides window related extension functions.
New Android windows are created by calling
[WindowManager.addView()](https://developer.android.com/reference/android/view/WindowManager),
and the Android Framework calls `WindowManager.addView()` for you in many different places.
`View.windowType` helps figure out what widget added a root view:
```kotlin
when(view.windowType) {
PHONE_WINDOW -> TODO("View attached to an Activity or Dialog")
POPUP_WINDOW -> TODO("View attached to a PopupWindow")
TOOLTIP -> TODO("View attached to a tooltip")
TOAST -> TODO("View attached to a toast")
UNKNOWN -> TODO("?!? is this view attached? Is this Android 42?")
}
```
If `View.windowType` returns `PHONE_WINDOW`, you can then retrieve the corresponding
`android.view.Window` instance:
[Windows.kt](https://github.com/square/curtains/blob/main/curtains/src/main/java/curtains/Windows.kt)
provides window related extension functions.
```kotlin
val window: Window? = view.phoneWindow
```
Once you have a `android.view.Window` instance, you can easily intercept touch events:
```kotlin
window.touchEventInterceptors += TouchEventInterceptor { event, dispatch ->
dispatch(event)
}
```
Or intercept key events:
```kotlin
window.keyEventInterceptors += KeyEventInterceptor { event, dispatch ->
dispatch(event)
}
```
Or set a callback to avoid the side effects of calling Window.getDecorView() too early:
```kotlin
window.onDecorViewReady { decorView ->
}
```
Or react when `setContentView()` is called:
```kotlin
window.onContentChangedListeners += OnContentChangedListener {
}
```
### All together
We can combine these APIs to log touch events for all `android.view.Window` instances:
```kotlin
class ExampleApplication : Application() {
override fun onCreate() {
super.onCreate()
Curtains.onRootViewsChangedListeners += OnRootViewAddedListener { view ->
view.phoneWindow?.let { window ->
if (view.windowAttachCount == 0) {
window.touchEventInterceptors += OnTouchEventListener { motionEvent ->
Log.d("ExampleApplication", "$window received $motionEvent")
}
}
}
}
}
}
```
Or measure the elapsed time from when a window is added to when it is fully draw:
```kotlin
// Measure the time from when a window is added to when it is fully drawn.
class ExampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val handler = Handler(Looper.getMainLooper())
Curtains.onRootViewsChangedListeners += OnRootViewAddedListener { view ->
view.phoneWindow?.let { window ->
val windowAddedAt = SystemClock.uptimeMillis()
window.onNextDraw {
// Post at front to fully account for drawing time.
handler.postAtFrontOfQueue {
val duration = SystemClock.uptimeMillis() - windowAddedAt
Log.d("ExampleApplication", "$window fully drawn in $duration ms")
}
}
}
}
}
}
```
## FAQ
### What's an Android window anyway?
No one knows exactly. Here are some window facts:
* Every floating thing you see on your phone is managed by a distinct window. Every activity, every
dialog, every floating menu, every toast
([until Android Q](https://cs.android.com/android/platform/superproject/+/master:frameworks/base/core/java/android/widget/Toast.java;l=108-114;drc=8fe35e5f2195e416f250ba5332bce676c362b210)),
the status bar, the notification bar, the keyboard, the text selection toolbar, etc.
* Every window is associated to a surface, in which a view hierarchy can draw.
* Every window is associated to an input event socket. As touch events come in, the window manager
service dispatches them to the right window and corresponding input event socket.
* Android apps don't have anything that represents the concept of a window within their
own process. That concept lives within the WindowManager service which sits in the `system_server` process.
* The Android Framework offers an API to create a new Window: [WindowManager.addView()](https://developer.android.com/reference/android/view/WindowManager).
Notice how the API to create a _window_ is named `addView()`. This means _please create a window and
let this view be the root of its view hierarchy_.
* All standard Android components (Activity, dialog, menus) take care of creating a window for you.
* [android.view.Window](https://developer.android.com/reference/android/view/Window) is not a window.
It provides shared helper code and public API surface for [Activity](https://developer.android.com/reference/android/app/Activity), [Dialog](https://developer.android.com/reference/android/app/Dialog) and [DreamService](https://developer.android.com/reference/android/service/dreams/DreamService) (lol).
**This is important**: some Android widgets create floating windows using a `Dialog` (which wraps a `android.view.Window`) while others use a [PopupWindow](https://developer.android.com/reference/android/widget/PopupWindow).
`android.widget.PopupWindow` is entirely separate from `android.view.Window`.
* Inside an Android app, the class that best represents a window is
[ViewRootImpl](https://cs.android.com/android/platform/superproject/+/master:frameworks/base/core/java/android/view/ViewRootImpl.java;l=194;drc=d31ee388115d17c2fd337f2806b37390c7d29834).
Every call to `WindowManager.addView()` triggers the creation of a new `ViewRootImpl` instance which
sits in between WindowManager and the view provided to `WindowManager.addView()`. This class is internal and
you will be yelled at if you mess with it.
### Will this library break my app?
First things first, see the [License](#license): unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
The hooks leveraged by this library are also used by [Espresso](https://github.com/android/android-test/blob/master/espresso/core/java/androidx/test/espresso/base/RootsOracle.java),
which makes it unlikely that they'll break in the future. On top of that, Curtains has
comprehensive UI test coverage across API levels 16 to 30.
### Does the Android Framework provide official APIs we can use instead of this?
Sadly, no.
Android developers are never in control of the entirety of their code:
* App developers constantly leverage 3rd party libraries and work in code bases which high
complexity and many collaborators.
* Library developers write code that gets integrated within app code they do not control.
Android developers need APIs to manage components in a centralized way, unfortunately, the Android
Framework lacks many such APIs: tracking the lifecycle of Android windows (e.g. you can't know if a
library shows a dialog), tracking the lifecycle of Android manifest components (services, providers,
broadcast receiver) or accessing view state without subclassing.
### Who named this library?
I ([@pyricau](http://github.com/pyricau)) initially named it
[vasistas](https://www.grammarphobia.com/blog/2013/11/vasistas.html) but that was too hard to
pronounce for English speakers. [Christina Lee](https://github.com/christinalee) suggested that
curtains are useful add-ons to windows in the real world and hence this library is now _Curtains_.
## License
Copyright 2021 Square Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.