Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* Add Insetter skeleton project * Import goo.gle/compose-insets * Split out Padding and Size modifiers * Add some rough docs * Rename library to Insets * Simplify size modifier structure * Fix sample after removing AppCompat * Simplify Sample activity creation * Add insets basic sample * Move to DisposableEffect * Move Insets.toPaddingValues to Padding.kt * Add comment InsetsSizeModifier * Fix code style * More docs * Add very basic tests * Add edge-to-edge lazy list sample * Link to new sample * Fix API * Expand README for insets * Update Edge to Edge sample to use translucent app bar * Tweak website generation for insets * Update insets/README.md Co-authored-by: Nick Butcher <nickbutcher@users.noreply.github.com> Co-authored-by: Nick Butcher <nickbutcher@users.noreply.github.com>
- Loading branch information
1 parent
1ff905b
commit 7329268
Showing
35 changed files
with
1,466 additions
and
155 deletions.
There are no files selected for viewing
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,119 @@ | ||
# Insets for Jetpack Compose | ||
|
||
[![Maven Central](https://maven-badges.herokuapp.com/maven-central/dev.chrisbanes.accompanist/accompanist-insets/badge.svg)](https://search.maven.org/search?q=g:dev.chrisbanes.accompanist) | ||
|
||
Insets for Jetpack Compose takes a lot of the ideas which drove [Insetter][insetter-view] for views, and applies them for use in composables. | ||
|
||
## Usage | ||
To setup Insets in your composables, you need to call the `ProvideWindowInsets` function and | ||
wrap your content. This would typically be done near the top level of your composable hierarchy: | ||
|
||
``` kotlin | ||
setContent { | ||
MaterialTheme { | ||
ProvideWindowInsets { | ||
// your content | ||
} | ||
} | ||
} | ||
``` | ||
|
||
> Note: Whether `ProvideWindowInsets` is called outside or within `MaterialTheme` doesn't particularly matter. | ||
`ProvideWindowInsets` allows the library to set an [`OnApplyWindowInsetsListener`][insetslistener] on your content's host view. That listener is used to update the value of an ambient bundled in this library: `AmbientWindowInsets`. | ||
|
||
`AmbientWindowInsets` holds an instance of `WindowInsets` which contains the value of various [WindowInsets][insets] [types][insettypes]. You can use the values manually like so: | ||
|
||
``` kotlin | ||
@Composable | ||
fun ImeAvoidingBox() { | ||
val insets = AmbientWindowInsets.current | ||
|
||
Box(Modifier.padding(bottom = insets.ime.bottom)) | ||
} | ||
``` | ||
|
||
...but we also provide some easy-to-use [Modifier][modifier]s. | ||
|
||
### Modifiers | ||
|
||
We provide two types of modifiers for easy handling of insets: padding and size. | ||
|
||
#### Padding modifiers | ||
The padding modifiers allow you to apply padding to a composable which matches a specific type of inset. Currently we provide: | ||
|
||
- `Modifier.statusBarsPadding()` | ||
- `Modifier.navigationBarsPadding()` | ||
- `Modifier.systemBarsPadding()` | ||
|
||
These are commonly used to move composables out from under the system bars. The common example would be a [`FloatingActionButton`][fab]: | ||
|
||
``` kotlin | ||
FloatingActionButton( | ||
icon = { Icon(...) }, | ||
modifier = Modifier | ||
.align(Alignment.BottomEnd) | ||
.padding(16.dp) // normal 16dp of padding for FABs | ||
.navigationBarsPadding() // Move it out from under the nav bar | ||
) | ||
``` | ||
|
||
#### Size modifiers | ||
The size modifiers allow you to match the size of a composable to a specific type of inset. Currently we provide: | ||
|
||
- `Modifier.statusBarsHeight()` | ||
- `Modifier.navigationBarsHeight()` | ||
- `Modifier.navigationBarsWidth()` | ||
|
||
These are commonly used to allow composables behind the system bars, to provide background protection, or similar: | ||
|
||
``` kotlin | ||
Spacer( | ||
Modifier | ||
.background(Color.Black.copy(alpha = 0.7f)) | ||
.statusBarsHeight() // Match the height of the status bar | ||
.fillMaxWidth() | ||
) | ||
``` | ||
|
||
### PaddingValues | ||
Compose also provides the concept of [`PaddingValues`][paddingvalues], a data class which contains the padding values to be applied on all dimensions (similar to a rect). This is commonly used with container composables, such as [`LazyColumn`][lazycolumn], to set the content padding. | ||
|
||
You may want to use inset values for content padding, so this library provides the `Insets.toPaddingValues()` extension function to convert between `Insets` and `PaddingValues`. Here's an example of using the system bars insets: | ||
|
||
``` kotlin | ||
LazyColumn( | ||
contentPadding = AmbientWindowInsets.current.systemBars.toPaddingValues() | ||
) | ||
``` | ||
|
||
For a more complex example, see the [`EdgeToEdgeLazyColumn`](./sample/src/main/java/dev/chrisbanes/accompanist/sample/insets/EdgeToEdgeLazyColumn.kt) example: | ||
|
||
<a href="images/edge-to-edge-list.jpg"> | ||
<img src="images/edge-to-edge-list.jpg" width=300> | ||
</a> | ||
|
||
## Download | ||
|
||
```groovy | ||
repositories { | ||
mavenCentral() | ||
} | ||
dependencies { | ||
implementation "dev.chrisbanes.accompanist:accompanist-insets:<version>" | ||
} | ||
``` | ||
|
||
Snapshots of the development version are available in [Sonatype's `snapshots` repository][snap]. These are updated on every commit. | ||
|
||
[compose]: https://developer.android.com/jetpack/compose | ||
[snap]: https://oss.sonatype.org/content/repositories/snapshots/dev/chrisbanes/accompanist/accompanist-insets/ | ||
[insetter-view]: https://github.com/chrisbanes/insetter | ||
[insets]: https://developer.android.com/reference/kotlin/androidx/core/view/WindowInsetsCompat | ||
[insettypes]: https://developer.android.com/reference/kotlin/androidx/core/view/WindowInsetsCompat.Type | ||
[insetslistener]: https://developer.android.com/reference/kotlin/androidx/core/view/OnApplyWindowInsetsListener | ||
[modifier]: https://developer.android.com/reference/kotlin/androidx/ui/core/Modifier | ||
[paddingvalues]: https://developer.android.com/reference/kotlin/androidx/compose/foundation/layout/PaddingValues | ||
[lazycolumn]: https://developer.android.com/reference/kotlin/androidx/compose/foundation/lazy/package-summary#lazycolumn | ||
[fab]: https://developer.android.com/reference/kotlin/androidx/compose/material/package-summary#floatingactionbutton |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,51 @@ | ||
public final class dev/chrisbanes/accompanist/insets/ComposeInsets { | ||
public static final fun ProvideWindowInsets (ZLkotlin/jvm/functions/Function2;Landroidx/compose/runtime/Composer;II)V | ||
public static final fun add-L4cKpv0 (Landroidx/compose/foundation/layout/PaddingValues;FFFF)Landroidx/compose/foundation/layout/PaddingValues; | ||
public static final fun add-L4cKpv0$default (Landroidx/compose/foundation/layout/PaddingValues;FFFFILjava/lang/Object;)Landroidx/compose/foundation/layout/PaddingValues; | ||
public static final fun getAmbientWindowInsets ()Landroidx/compose/runtime/ProvidableAmbient; | ||
public static final fun navigationBarsHeight-wxomhCo (Landroidx/compose/ui/Modifier;F)Landroidx/compose/ui/Modifier; | ||
public static final fun navigationBarsHeight-wxomhCo$default (Landroidx/compose/ui/Modifier;FILjava/lang/Object;)Landroidx/compose/ui/Modifier; | ||
public static final fun navigationBarsPadding (Landroidx/compose/ui/Modifier;ZZZ)Landroidx/compose/ui/Modifier; | ||
public static final fun navigationBarsPadding$default (Landroidx/compose/ui/Modifier;ZZZILjava/lang/Object;)Landroidx/compose/ui/Modifier; | ||
public static final fun navigationBarsWidth-UTaBBDU (Landroidx/compose/ui/Modifier;Ldev/chrisbanes/accompanist/insets/HorizontalSide;F)Landroidx/compose/ui/Modifier; | ||
public static final fun navigationBarsWidth-UTaBBDU$default (Landroidx/compose/ui/Modifier;Ldev/chrisbanes/accompanist/insets/HorizontalSide;FILjava/lang/Object;)Landroidx/compose/ui/Modifier; | ||
public static final fun statusBarsHeight-wxomhCo (Landroidx/compose/ui/Modifier;F)Landroidx/compose/ui/Modifier; | ||
public static final fun statusBarsHeight-wxomhCo$default (Landroidx/compose/ui/Modifier;FILjava/lang/Object;)Landroidx/compose/ui/Modifier; | ||
public static final fun statusBarsPadding (Landroidx/compose/ui/Modifier;)Landroidx/compose/ui/Modifier; | ||
public static final fun systemBarsPadding (Landroidx/compose/ui/Modifier;Z)Landroidx/compose/ui/Modifier; | ||
public static final fun systemBarsPadding$default (Landroidx/compose/ui/Modifier;ZILjava/lang/Object;)Landroidx/compose/ui/Modifier; | ||
public static final fun toPaddingValues (Ldev/chrisbanes/accompanist/insets/Insets;ZZZZLandroidx/compose/runtime/Composer;II)Landroidx/compose/foundation/layout/PaddingValues; | ||
} | ||
|
||
public final class dev/chrisbanes/accompanist/insets/HorizontalSide : java/lang/Enum { | ||
public static final field Left Ldev/chrisbanes/accompanist/insets/HorizontalSide; | ||
public static final field Right Ldev/chrisbanes/accompanist/insets/HorizontalSide; | ||
public static final fun valueOf (Ljava/lang/String;)Ldev/chrisbanes/accompanist/insets/HorizontalSide; | ||
public static final fun values ()[Ldev/chrisbanes/accompanist/insets/HorizontalSide; | ||
} | ||
|
||
public final class dev/chrisbanes/accompanist/insets/Insets { | ||
public fun <init> ()V | ||
public final fun getBottom ()I | ||
public final fun getLeft ()I | ||
public final fun getRight ()I | ||
public final fun getTop ()I | ||
public final fun isVisible ()Z | ||
} | ||
|
||
public final class dev/chrisbanes/accompanist/insets/VerticalSide : java/lang/Enum { | ||
public static final field Bottom Ldev/chrisbanes/accompanist/insets/VerticalSide; | ||
public static final field Top Ldev/chrisbanes/accompanist/insets/VerticalSide; | ||
public static final fun valueOf (Ljava/lang/String;)Ldev/chrisbanes/accompanist/insets/VerticalSide; | ||
public static final fun values ()[Ldev/chrisbanes/accompanist/insets/VerticalSide; | ||
} | ||
|
||
public final class dev/chrisbanes/accompanist/insets/WindowInsets { | ||
public fun <init> ()V | ||
public final fun getIme ()Ldev/chrisbanes/accompanist/insets/Insets; | ||
public final fun getNavigationBars ()Ldev/chrisbanes/accompanist/insets/Insets; | ||
public final fun getStatusBars ()Ldev/chrisbanes/accompanist/insets/Insets; | ||
public final fun getSystemBars ()Ldev/chrisbanes/accompanist/insets/Insets; | ||
public final fun getSystemGestures ()Ldev/chrisbanes/accompanist/insets/Insets; | ||
} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,93 @@ | ||
/* | ||
* Copyright 2020 The Android Open Source Project | ||
* | ||
* 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 | ||
* | ||
* https://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. | ||
*/ | ||
|
||
import dev.chrisbanes.accompanist.buildsrc.Libs | ||
|
||
plugins { | ||
id 'com.android.library' | ||
id 'kotlin-android' | ||
id 'org.jetbrains.dokka' | ||
} | ||
|
||
kotlin { | ||
explicitApi() | ||
} | ||
|
||
android { | ||
compileSdkVersion 30 | ||
|
||
defaultConfig { | ||
minSdkVersion 21 | ||
testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner" | ||
} | ||
|
||
compileOptions { | ||
sourceCompatibility JavaVersion.VERSION_1_8 | ||
targetCompatibility JavaVersion.VERSION_1_8 | ||
} | ||
|
||
buildFeatures { | ||
buildConfig false | ||
compose true | ||
} | ||
|
||
composeOptions { | ||
kotlinCompilerVersion Libs.Kotlin.version | ||
kotlinCompilerExtensionVersion Libs.AndroidX.Compose.version | ||
} | ||
|
||
lintOptions { | ||
textReport true | ||
textOutput 'stdout' | ||
// We run a full lint analysis as build part in CI, so skip vital checks for assemble tasks | ||
checkReleaseBuilds false | ||
} | ||
|
||
testOptions { | ||
unitTests { | ||
includeAndroidResources = true | ||
} | ||
} | ||
} | ||
|
||
afterEvaluate { | ||
tasks.withType(org.jetbrains.dokka.gradle.DokkaTask).configureEach { | ||
outputDirectory.set(rootProject.file('docs/api')) | ||
} | ||
} | ||
|
||
dependencies { | ||
implementation Libs.AndroidX.coreAlpha | ||
implementation Libs.AndroidX.Compose.runtime | ||
implementation Libs.AndroidX.Compose.foundation | ||
|
||
implementation Libs.Kotlin.stdlib | ||
// implementation Libs.Coroutines.android | ||
|
||
// ====================== | ||
// Test dependencies | ||
// ====================== | ||
|
||
androidTestImplementation Libs.junit | ||
androidTestImplementation Libs.truth | ||
|
||
androidTestImplementation Libs.AndroidX.Compose.test | ||
androidTestImplementation Libs.AndroidX.Compose.ui | ||
androidTestImplementation Libs.AndroidX.Test.rules | ||
androidTestImplementation Libs.AndroidX.Test.runner | ||
} | ||
|
||
apply plugin: "com.vanniktech.maven.publish" |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,3 @@ | ||
POM_ARTIFACT_ID=accompanist-insets | ||
POM_NAME=Accompanist Insets library | ||
POM_PACKAGING=aar |
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,28 @@ | ||
<!-- | ||
~ Copyright 2020 The Android Open Source Project | ||
~ | ||
~ 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 | ||
~ | ||
~ https://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. | ||
--> | ||
|
||
<manifest xmlns:android="http://schemas.android.com/apk/res/android" | ||
package="dev.chrisbanes.accompanist.insets.test"> | ||
|
||
<uses-sdk android:targetSdkVersion="30" /> | ||
|
||
<application> | ||
<activity | ||
android:name="dev.chrisbanes.accompanist.insets.InsetsTestActivity" | ||
android:theme="@android:style/Theme.Material.NoActionBar" /> | ||
</application> | ||
|
||
</manifest> |
Oops, something went wrong.