Skip to content

Commit 738b79e

Browse files
rjrjrrjrjr
authored
Merge pull request #743 from square/ray/un-dep-LR
Defers most deprecation and restores deleted kdoc
2 parents 73c2eee + e0c3fbf commit 738b79e

File tree

16 files changed

+356
-60
lines changed

16 files changed

+356
-60
lines changed

‎gradle.properties

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,7 @@ android.useAndroidX=true
88
systemProp.org.gradle.internal.publish.checksums.insecure=true
99

1010
GROUP=com.squareup.workflow1
11-
VERSION_NAME=1.8.0-uiUpdate05-SNAPSHOT
11+
VERSION_NAME=1.8.0-uiUpdate06-SNAPSHOT
1212

1313
POM_DESCRIPTION=Square Workflow
1414

‎workflow-ui/container-common/src/main/java/com/squareup/workflow1/ui/backstack/BackStackScreen.kt

Lines changed: 20 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@file:Suppress("DEPRECATION")
1+
// @file:Suppress("DEPRECATION")
22

33
package com.squareup.workflow1.ui.backstack
44

@@ -7,8 +7,26 @@ import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
77
import com.squareup.workflow1.ui.asScreen
88
import com.squareup.workflow1.ui.container.BackStackScreen as NewBackStackScreen
99

10+
/**
11+
* **This will be deprecated in favor of
12+
* [com.squareup.workflow1.ui.container.BackStackScreen] very soon.**
13+
*
14+
* Represents an active screen ([top]), and a set of previously visited screens to which we may
15+
* return ([backStack]). By rendering the entire history we allow the UI to do things like maintain
16+
* cached view state, implement drag-back gestures without waiting for the workflow, etc.
17+
*
18+
* Effectively a list that can never be empty.
19+
*
20+
* If multiple [BackStackScreen]s are used as sibling renderings within the same parent navigation
21+
* container (either the root activity or another [BackStackScreen]), then the siblings must be
22+
* distinguished by wrapping them in [Named][com.squareup.workflow1.ui.Named] renderings in order to
23+
* correctly support AndroidX `SavedStateRegistry`.
24+
*
25+
* @param bottom the bottom-most entry in the stack
26+
* @param rest the rest of the stack, empty by default
27+
*/
1028
@WorkflowUiExperimentalApi
11-
@Deprecated("Use com.squareup.workflow1.ui.container.BackStackScreen")
29+
// @Deprecated("Use com.squareup.workflow1.ui.container.BackStackScreen")
1230
public class BackStackScreen<StackedT : Any>(
1331
bottom: StackedT,
1432
rest: List<StackedT>

‎workflow-ui/container-common/src/main/java/com/squareup/workflow1/ui/modal/AlertContainerScreen.kt

Lines changed: 13 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,27 @@
1-
@file:Suppress("DEPRECATION")
1+
// @file:Suppress("DEPRECATION")
22

33
package com.squareup.workflow1.ui.modal
44

55
import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
66

77
/**
8+
* **This will be deprecated in favor of
9+
* [AlertOverlay][com.squareup.workflow1.ui.container.AlertOverlay] and
10+
* [BodyAndModalsScreen][com.squareup.workflow1.ui.container.BodyAndModalsScreen]
11+
* very soon.**
12+
*
813
* May show a stack of [AlertScreen] over a [beneathModals].
914
*
1015
* @param B the type of [beneathModals]
1116
*/
1217
@WorkflowUiExperimentalApi
13-
@Deprecated(
14-
"Use BodyAndModalsScreen and AlertOverlay",
15-
ReplaceWith(
16-
"BodyAndModalsScreen<B>(beneathModals, modals)",
17-
"com.squareup.workflow1.ui.container.BodyAndModalsScreen"
18-
)
19-
)
18+
// @Deprecated(
19+
// "Use BodyAndModalsScreen and AlertOverlay",
20+
// ReplaceWith(
21+
// "BodyAndModalsScreen<B>(beneathModals, modals)",
22+
// "com.squareup.workflow1.ui.container.BodyAndModalsScreen"
23+
// )
24+
// )
2025
public data class AlertContainerScreen<B : Any>(
2126
override val beneathModals: B,
2227
override val modals: List<AlertScreen> = emptyList()

‎workflow-ui/container-common/src/main/java/com/squareup/workflow1/ui/modal/AlertScreen.kt

Lines changed: 11 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,23 @@
1-
@file:Suppress("DEPRECATION")
1+
// @file:Suppress("DEPRECATION")
22

33
package com.squareup.workflow1.ui.modal
44

55
import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
66

77
/**
8+
* **This will be deprecated in favor of
9+
* [AlertOverlay][com.squareup.workflow1.ui.container.AlertOverlay] very soon.**
10+
*
811
* Models a typical "You sure about that?" alert box.
912
*/
1013
@WorkflowUiExperimentalApi
11-
@Deprecated(
12-
"Use AlertOverlay",
13-
ReplaceWith(
14-
"AlertOverlay(buttons, message, title, cancelable, onEvent)",
15-
"com.squareup.workflow1.ui.container.AlertOverlay"
16-
)
17-
)
14+
// @Deprecated(
15+
// "Use AlertOverlay",
16+
// ReplaceWith(
17+
// "AlertOverlay(buttons, message, title, cancelable, onEvent)",
18+
// "com.squareup.workflow1.ui.container.AlertOverlay"
19+
// )
20+
// )
1821
public data class AlertScreen(
1922
val buttons: Map<Button, String> = emptyMap(),
2023
val message: String = "",

‎workflow-ui/container-common/src/main/java/com/squareup/workflow1/ui/modal/HasModals.kt

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,14 +3,18 @@ package com.squareup.workflow1.ui.modal
33
import com.squareup.workflow1.ui.WorkflowUiExperimentalApi
44

55
/**
6+
* **This will be deprecated in favor of
7+
* [BodyAndModalsScreen][com.squareup.workflow1.ui.container.BodyAndModalsScreen]
8+
* very soon.**
9+
*
610
* Interface implemented by screen classes that represent a stack of
711
* zero or more [modal][M] screens above a [base screen][beneathModals].
812
*
913
* Use of this interface allows platform specific containers to share base classes,
1014
* like `ModalContainer` in the `workflow-ui:core-android` module.
1115
*/
1216
@WorkflowUiExperimentalApi
13-
@Deprecated("Use BodyAndModalsScreen")
17+
// @Deprecated("Use BodyAndModalsScreen")
1418
public interface HasModals<out B : Any, out M : Any> {
1519
public val beneathModals: B
1620
public val modals: List<M>

‎workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/AndroidViewRegistry.kt

Lines changed: 53 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
@file:Suppress("DEPRECATION")
1+
// @file:Suppress("DEPRECATION")
22

33
package com.squareup.workflow1.ui
44

@@ -10,7 +10,25 @@ import com.squareup.workflow1.ui.container.EnvironmentScreen
1010
import com.squareup.workflow1.ui.container.EnvironmentScreenLegacyViewFactory
1111
import kotlin.reflect.KClass
1212

13-
@Deprecated("Use ScreenViewFactoryFinder.getViewFactoryForRendering()")
13+
/**
14+
* **This will be deprecated in favor of
15+
* [ScreenViewFactoryFinder.getViewFactoryForRendering]
16+
* very soon.**
17+
*
18+
* It is usually more convenient to use [WorkflowViewStub] or [DecorativeViewFactory]
19+
* than to call this method directly.
20+
*
21+
* Returns the [ViewFactory] that builds [View] instances suitable to display the given [rendering],
22+
* via subsequent calls to [View.showRendering].
23+
*
24+
* Prefers factories found via [ViewRegistry.getFactoryFor]. If that returns null, falls
25+
* back to the factory provided by the rendering's implementation of
26+
* [AndroidViewRendering.viewFactory], if there is one. Note that this means that a
27+
* compile time [AndroidViewRendering.viewFactory] binding can be overridden at runtime.
28+
*
29+
* @throws IllegalArgumentException if no factory can be find for type [RenderingT]
30+
*/
31+
// @Deprecated("Use ScreenViewFactoryFinder.getViewFactoryForRendering()")
1432
@WorkflowUiExperimentalApi
1533
public fun <RenderingT : Any> ViewRegistry.getFactoryForRendering(
1634
rendering: RenderingT
@@ -32,18 +50,46 @@ public fun <RenderingT : Any> ViewRegistry.getFactoryForRendering(
3250
)
3351
}
3452

35-
@Deprecated(
36-
"Use getEntryFor()",
37-
ReplaceWith("getEntryFor(renderingType)")
38-
)
53+
/**
54+
* **This will be deprecated in favor of [ViewRegistry.getEntryFor] very soon.**
55+
*
56+
* This method is not for general use, use [WorkflowViewStub] instead.
57+
*
58+
* Returns the [ViewFactory] that was registered for the given [renderingType], or null
59+
* if none was found.
60+
*/
61+
// @Deprecated(
62+
// "Use getEntryFor()",
63+
// ReplaceWith("getEntryFor(renderingType)")
64+
// )
3965
@WorkflowUiExperimentalApi
4066
public fun <RenderingT : Any> ViewRegistry.getFactoryFor(
4167
renderingType: KClass<out RenderingT>
4268
): ViewFactory<RenderingT>? {
4369
return getEntryFor(renderingType) as? ViewFactory<RenderingT>
4470
}
4571

46-
@Deprecated("Use ScreenViewFactory.startShowing")
72+
/**
73+
* **This will be deprecated in favor of [ScreenViewFactory.startShowing] very soon.**
74+
*
75+
* It is usually more convenient to use [WorkflowViewStub] or [DecorativeViewFactory]
76+
* than to call this method directly.
77+
*
78+
* Finds a [ViewFactory] to create a [View] ready to display [initialRendering]. The caller
79+
* is responsible for calling [View.start] on the new [View]. After that,
80+
* [View.showRendering] can be used to update it with new renderings that
81+
* are [compatible] with [initialRendering].
82+
*
83+
* @param viewStarter An optional wrapper for the function invoked when [View.start]
84+
* is called, allowing for last second initialization of a newly built [View].
85+
* See [ViewStarter] for details.
86+
*
87+
* @throws IllegalArgumentException if no factory can be found for type [RenderingT]
88+
*
89+
* @throws IllegalStateException if the matching [ViewFactory] fails to call
90+
* [View.bindShowRendering] when constructing the view
91+
*/
92+
// @Deprecated("Use ScreenViewFactory.startShowing")
4793
@WorkflowUiExperimentalApi
4894
public fun <RenderingT : Any> ViewRegistry.buildView(
4995
initialRendering: RenderingT,

‎workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/AndroidViewRendering.kt

Lines changed: 31 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,36 @@
11
package com.squareup.workflow1.ui
22

3-
@Suppress("DEPRECATION")
4-
@Deprecated("Use AndroidScreen")
3+
/**
4+
* **This will be deprecated in favor of [AndroidScreen] very soon.**
5+
*
6+
* Interface implemented by a rendering class to allow it to drive an Android UI
7+
* via an appropriate [ViewFactory] implementation.
8+
*
9+
* You will rarely, if ever, write a [ViewFactory] yourself. Instead
10+
* use [LayoutRunner.bind] to work with XML layout resources, or
11+
* [BuilderViewFactory] to create views from code. See [LayoutRunner] for more
12+
* details.
13+
*
14+
* @OptIn(WorkflowUiExperimentalApi::class)
15+
* data class HelloView(
16+
* val message: String,
17+
* val onClick: () -> Unit
18+
* ) : AndroidViewRendering<HelloView> {
19+
* override val viewFactory: ViewFactory<HelloView> =
20+
* LayoutRunner.bind(HelloGoodbyeLayoutBinding::inflate) { r, _ ->
21+
* helloMessage.text = r.message
22+
* helloMessage.setOnClickListener { r.onClick() }
23+
* }
24+
* }
25+
*
26+
* This is the simplest way to bridge the gap between your workflows and the UI,
27+
* but using it requires your workflows code to reside in Android modules, instead
28+
* of pure Kotlin. If this is a problem, or you need more flexibility for any other
29+
* reason, you can use [ViewRegistry] to bind your renderings to [ViewFactory]
30+
* implementations at runtime.
31+
*/
32+
// @Suppress("DEPRECATION")
33+
// @Deprecated("Use AndroidScreen")
534
@WorkflowUiExperimentalApi
635
public interface AndroidViewRendering<V : AndroidViewRendering<V>> {
736
/**

‎workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/BackButtonScreen.kt

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,29 @@
11
package com.squareup.workflow1.ui
22

3-
@Suppress("DEPRECATION")
3+
/**
4+
* **This will be deprecated in favor of
5+
* [com.squareup.workflow1.ui.container.BackButtonScreen] very soon.**
6+
*
7+
* Adds optional back button handling to a [wrapped] rendering, possibly overriding that
8+
* the wrapped rendering's own back button handler.
9+
*
10+
* @param shadow If `true`, [onBackPressed] is set as the
11+
* [backPressedHandler][android.view.View.backPressedHandler] after
12+
* the [wrapped] rendering's view is built / updated, effectively overriding it.
13+
* If false (the default), [onBackPressed] is set afterward, to allow the wrapped rendering to
14+
* take precedence if it sets a `backPressedHandler` of its own -- the handler provided
15+
* here serves as a default.
16+
*
17+
* @param onBackPressed The function to fire when the device back button
18+
* is pressed, or null to set no handler -- or clear a handler that was set previously.
19+
* Defaults to `null`.
20+
*/
21+
// @Suppress("DEPRECATION")
422
@WorkflowUiExperimentalApi
5-
@Deprecated(
6-
"Use com.squareup.workflow1.ui.container.BackButtonScreen",
7-
ReplaceWith("BackButtonScreen", "com.squareup.workflow1.ui.container.BackButtonScreen")
8-
)
23+
// @Deprecated(
24+
// "Use com.squareup.workflow1.ui.container.BackButtonScreen",
25+
// ReplaceWith("BackButtonScreen", "com.squareup.workflow1.ui.container.BackButtonScreen")
26+
// )
927
public class BackButtonScreen<W : Any>(
1028
public val wrapped: W,
1129
public val shadow: Boolean = false,

‎workflow-ui/core-android/src/main/java/com/squareup/workflow1/ui/BuilderViewFactory.kt

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -5,8 +5,29 @@ import android.view.View
55
import android.view.ViewGroup
66
import kotlin.reflect.KClass
77

8-
@Suppress("DEPRECATION")
9-
@Deprecated("Use ScreenViewFactory.forBuiltView")
8+
/**
9+
* **This will be deprecated in favor of [ScreenViewFactory.fromCode] very soon.**
10+
*
11+
* A [ViewFactory] that creates [View]s that need to be generated from code.
12+
* (Use [LayoutRunner] to work with XML layout resources.)
13+
*
14+
* data class MyView(): AndroidViewRendering<MyView> {
15+
* val viewFactory = BuilderViewFactory(
16+
* type = MyScreen::class,
17+
* viewConstructor = { initialRendering, _, context, _ ->
18+
* MyFrame(context).apply {
19+
* layoutParams = ViewGroup.LayoutParams(MATCH_PARENT, MATCH_PARENT)
20+
* bindShowRendering(initialRendering, ::update)
21+
* }
22+
* )
23+
* }
24+
*
25+
* private class MyFrame(context: Context) : FrameLayout(context, attributeSet) {
26+
* private fun update(rendering: MyView) { ... }
27+
* }
28+
*/
29+
// @Suppress("DEPRECATION")
30+
// @Deprecated("Use ScreenViewFactory.fromCode")
1031
@WorkflowUiExperimentalApi
1132
public class BuilderViewFactory<RenderingT : Any>(
1233
override val type: KClass<RenderingT>,

0 commit comments

Comments
 (0)