From 32485f6802bbb3c4ec6a6e00a34b573e2a1e076a Mon Sep 17 00:00:00 2001 From: Alex Vanyo Date: Thu, 11 Aug 2022 16:12:38 -0700 Subject: [PATCH] [Adaptive] Miscellaneous doc updates --- .../ISSUE_TEMPLATE/adapative-bug-report.md | 16 +++++++ .../google/accompanist/adaptive/TwoPane.kt | 18 +++----- docs/adaptive.md | 45 +++++++++++++++++++ 3 files changed, 67 insertions(+), 12 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/adapative-bug-report.md create mode 100644 docs/adaptive.md diff --git a/.github/ISSUE_TEMPLATE/adapative-bug-report.md b/.github/ISSUE_TEMPLATE/adapative-bug-report.md new file mode 100644 index 000000000..bc3e989d3 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/adapative-bug-report.md @@ -0,0 +1,16 @@ +--- +name: Adaptive bug report +about: Create a report about adaptive +title: "[Adaptive]" +labels: adaptive +assignees: alexvanyo + +--- + +**Description** + +**Steps to reproduce** + +**Expected behavior** + +**Additional context** diff --git a/adaptive/src/main/java/com/google/accompanist/adaptive/TwoPane.kt b/adaptive/src/main/java/com/google/accompanist/adaptive/TwoPane.kt index 9603566f0..ef11a0db8 100644 --- a/adaptive/src/main/java/com/google/accompanist/adaptive/TwoPane.kt +++ b/adaptive/src/main/java/com/google/accompanist/adaptive/TwoPane.kt @@ -64,6 +64,8 @@ import kotlin.math.roundToInt * and the bottom-most in a vertical split based on the [SplitResult] of * [TwoPaneStrategy.calculateSplitResult] * @param strategy strategy of the two pane that controls the arrangement of the layout + * @param displayFeatures the list of known display features to automatically avoid + * @param foldAwareConfiguration the types of display features to automatically avoid * @param modifier an optional modifier for the layout */ @Composable @@ -278,9 +280,7 @@ private fun interface ConditionalTwoPaneStrategy { /** * Returns a [TwoPaneStrategy] that will place the slots horizontally. * - * If there is a vertical fold, then the gap will be placed along the fold. - * - * Otherwise, the gap will be placed at the given [splitFraction] from start, with the given + * The gap will be placed at the given [splitFraction] from start, with the given * [gapWidth]. */ public fun HorizontalTwoPaneStrategy( @@ -294,9 +294,7 @@ public fun HorizontalTwoPaneStrategy( /** * Returns a [TwoPaneStrategy] that will place the slots horizontally. * - * If there is a vertical fold, then the gap will be placed along the fold. - * - * Otherwise, the gap will be placed at [splitOffset] either from the start or end based on + * The gap will be placed at [splitOffset] either from the start or end based on * [offsetFromStart], with the given [gapWidth]. */ public fun HorizontalTwoPaneStrategy( @@ -312,9 +310,7 @@ public fun HorizontalTwoPaneStrategy( /** * Returns a [TwoPaneStrategy] that will place the slots horizontally. * - * If there is a vertical fold, then the gap will be placed along the fold. - * - * Otherwise, the gap will be placed at the given [splitFraction] from top, with the given + * The gap will be placed at the given [splitFraction] from top, with the given * [gapHeight]. */ public fun VerticalTwoPaneStrategy( @@ -328,9 +324,7 @@ public fun VerticalTwoPaneStrategy( /** * Returns a [TwoPaneStrategy] that will place the slots horizontally. * - * If there is a vertical fold, then the gap will be placed along the fold. - * - * Otherwise, the gap will be placed at [splitOffset] either from the top or bottom based on + * The gap will be placed at [splitOffset] either from the top or bottom based on * [offsetFromTop], with the given [gapHeight]. */ public fun VerticalTwoPaneStrategy( diff --git a/docs/adaptive.md b/docs/adaptive.md new file mode 100644 index 000000000..9ce9b0d0e --- /dev/null +++ b/docs/adaptive.md @@ -0,0 +1,45 @@ +# Adaptive utilities for Jetpack Compose + +[![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-adaptive)](https://search.maven.org/search?q=g:com.google.accompanist) + +A library providing a collection of utilities for adaptive layouts. + +## calculateDisplayFeatures + +[`calculateDisplayFeatures(activity)`](../api/adaptive/com.google.accompanist.adaptive/calculate-display-features.html) returns the current list of `DisplayFeature`s, +as reported by the [Jetpack WindowManager library](https://developer.android.com/jetpack/androidx/releases/window). + +These contain the list of folds (if any), and can be used to drive components like [`TwoPane`](#TwoPane). + +## TwoPane + +[`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) is a UI component that positions exactly two slots on the screen. + +The default positioning of these two slots is driven by a [`TwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-two-pane-strategy.html), +which can decide to orient the two slots side-by-side horizontally or vertically, and also configure the gap between them. + +The built-in [`HorizontalTwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-horizontal-two-pane-strategy.html) and +[`VerticalTwoPaneStrategy`](../api/adaptive/com.google.accompanist.adaptive/-vertical-two-pane-strategy.html) allow positioning the +slots based on a fixed offset, or as some fraction of the space. + +[`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) also requires a list of display features (to be retrieved with [`calculateDisplayFeatures`](#calculateDisplayFeatures)), +and optionally a [`FoldAwareConfiguration`](../api/adaptive/com.google.accompanist.adaptive/-fold-aware-configuration.html) to determine which folds to handle automatically. + +When there is a fold that intersects with the [`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) component that is obscuring or separating, +the [`TwoPane`](../api/adaptive/com.google.accompanist.adaptive/-two-pane.html) will automatically place the slots to avoid the fold. + +When there is no fold, the default supplied strategy will be used instead. + +## Download + +[![Maven Central](https://img.shields.io/maven-central/v/com.google.accompanist/accompanist-adaptive)](https://search.maven.org/search?q=g:com.google.accompanist) + +```groovy +repositories { + mavenCentral() +} + +dependencies { + implementation "com.google.accompanist:accompanist-adaptive:" +} +``` \ No newline at end of file