{"id":2556,"date":"2022-06-23T16:36:09","date_gmt":"2022-06-23T23:36:09","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/surface-duo\/?p=2556"},"modified":"2022-06-23T16:36:09","modified_gmt":"2022-06-23T23:36:09","slug":"jetpack-compose-foldable-twopanelayout","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/surface-duo\/jetpack-compose-foldable-twopanelayout\/","title":{"rendered":"Jetpack Compose TwoPaneLayout update"},"content":{"rendered":"

\n Hello Jetpack Compose developers!\n<\/p>\n

\n This week, we\u2019re excited to announce some big updates to TwoPaneLayout<\/a>, our Jetpack Compose component for foldables and large screens.\n<\/p>\n

\n We\u2019ve just added a new TwoPaneLayout constructor with highly customizable navigation support, and the TwoPaneScope interface has been upgraded to provide more information while also protecting access to its fields and methods. These changes were substantial enough that we decided to bump to TwoPaneLayout version 1.0.1-xx, so now TwoPaneLayout 1.0.0 is the last version that still uses the old API.\n<\/p>\n

\n To see examples of how to use and migrate to the newest TwoPaneLayout version, check out the documentation<\/a>, library samples (TwoPaneLayout<\/a> and TwoPaneLayoutNav<\/a>), and the Surface Duo Compose samples<\/a>.\n<\/p>\n

\n \"Surface\n<\/p>\n

New TwoPaneLayoutNav constructor<\/h2>\n

\n TwoPaneLayout now offers the TwoPaneLayoutNav constructor, which is meant to be used in scenarios with complex navigation. We originally started looking into this idea after receiving some feedback on GitHub<\/a>, and we eventually decided that a new constructor would be the best solution:\n<\/p>\n

@Composable\r\nfun TwoPaneLayoutNav(\r\n    modifier: Modifier = Modifier,\r\n    navController: NavHostController,\r\n    paneMode: TwoPaneMode = TwoPaneMode.TwoPane,\r\n    destinations: Array<Destination>,\r\n    singlePaneStartDestination: String,\r\n    pane1StartDestination: String,\r\n    pane2StartDestination: String\r\n)<\/pre>\n
\n  As opposed to the original TwoPaneLayout constructor, TwoPaneLayoutNav can be used for apps that require more than two screens of content. Instead of passing in fixed composables for panes 1 and 2, you can now pass in an array of multiple app destinations via the destinations<\/code> parameter. To control which destination is shown in each pane, you can then use internal TwoPaneLayoutNav navigation methods.\n<\/p>\n
\n  If we look inside the implementation of TwoPaneLayoutNav, we can see that the code is very similar to TwoPaneLayout when only one pane is shown. We still use a NavHost in the SinglePaneContainer<\/a>, but now it contains multiple destinations instead of only two.\n<\/p>\n
@Composable\r\ninternal fun SinglePaneContainer(\r\n    navController: NavHostController,\r\n    pane1: @Composable TwoPaneScope.() -> Unit,\r\n    pane2: @Composable TwoPaneScope.() -> Unit\r\n) {\r\n    ...\r\n    NavHost(\r\n        navController = navController,\r\n        startDestination = currentSinglePane\r\n    ) {\r\n        composable(Screen.Pane1.route) {\r\n          TwoPaneScopeInstance.pane1()\r\n        }\r\n        composable(Screen.Pane2.route) {\r\n          TwoPaneScopeInstance.pane2()\r\n        }\r\n    }\r\n}<\/pre>\n
\r\n@Composable\r\ninternal fun SinglePaneContainer(\r\n    destinations: Array<Destination>,\r\n    startDestination: String,\r\n    navController: NavHostController,\r\n) {\r\n...\r\n  NavHost(\r\n        navController = navController,\r\n        startDestination = startDestination\r\n    ) {\r\n        destinations.forEach { pane ->\r\n          composable(pane.route) {\r\n              TwoPaneNavScopeInstance.(pane.content)()\r\n            }\r\n      }\r\n  }\r\n}<\/pre>\n
\n  The main difference in implementation is within the TwoPaneContainer, because now we have to keep track of the routes for the current pane 1 and 2 destinations. These routes are used to access the content that will be shown in each pane of the layout<\/a>.\n<\/p>\n
@Composable\r\ninternal fun TwoPaneContainer(\r\n    windowState: WindowState,\r\n    modifier: Modifier,\r\n    pane1: @Composable TwoPaneScope.() -> Unit,\r\n    pane2: @Composable TwoPaneScope.() -> Unit\r\n) {\r\n    ...    \r\n    Layout(\r\n        content = {\r\n          TwoPaneScopeInstance.pane1()\r\n              TwoPaneScopeInstance.pane2()\r\n          },\r\n          measurePolicy = measurePolicy,\r\n          modifier = modifier\r\n    )\r\n}<\/pre>\n
@Composable\r\ninternal fun TwoPaneContainer(\r\n    windowState: WindowState,\r\n    modifier: Modifier,\r\n    destinations: Array<Destination>,\r\n    pane1StartDestination: String,\r\n    pane2StartDestination: String\r\n) {\r\n  ...\r\n  var currentPane1 by rememberSaveable { mutableStateOf(pane1StartDestination) }\r\n  var currentPane2 by rememberSaveable { mutableStateOf(pane2StartDestination) }\r\n  \/\/ Find the destinations to display in each pane\r\n  val pane1 = findDestination(currentPane1, destinations).content\r\n  val pane2 = findDestination(currentPane2, destinations).content\r\n  Layout(\r\n        content = {\r\n          TwoPaneNavScopeInstance.pane1()\r\n          TwoPaneNavScopeInstance.pane2()\r\n        },\r\n        measurePolicy = measurePolicy,\r\n        modifier = modifier\r\n    )\r\n}<\/pre>\n
\n  To see an example of TwoPaneLayoutNav in action, you can check out our updated NavigationRail sample<\/a>. If you read the blog post announcing the release of the sample<\/a>, you may remember how complicated the original navigation hierarchy was; we had to use a combination of internal TwoPaneLayout navigation and our own NavHost\/navController combo to achieve the desired app behavior. Now, after switching to TwoPaneLayoutNav, the navigation setup for the app is much simpler because we can achieve all of the same navigation patterns with just one shared NavHost\/navController pair.\n<\/p>\n
Updated scopes and testing support<\/h2>\n
\n  The new TwoPaneLayout version also includes updates to TwoPaneScope and the addition of TwoPaneNavScope. In addition, we\u2019ve added new test scope instances to help with handling the API changes in UI tests.\n<\/p>\n
TwoPaneScope<\/h3>\n
\n  Previously, TwoPaneScope was only used to provide access to the weight modifier attribute<\/a>, while the navigateToPane1<\/code> and navigateToPane2<\/code> methods were accessible anywhere. Now, to ensure that certain methods and fields can only be accessed from within the proper scope, we\u2019ve updated the TwoPaneScope interface to the following:\n<\/p>\n
interface TwoPaneScope {\r\n    fun Modifier.weight(weight: Float): Modifier\r\n    fun navigateToPane1()\r\n    fun navigateToPane2()\r\n    val currentSinglePaneDestination: String\r\n    val isSinglePane: Boolean\r\n}<\/pre>\n
\n  So for instance, let\u2019s say your app code looked something like this:\n<\/p>\n
@Composable\r\nfun ExampleApp() {\r\n    TwoPaneLayout(\r\n        pane1 = { Pane1() },\r\n        pane2 = { Pane2() }\r\n  )\r\n}\r\n@Composable\r\nfun Pane1() {\r\n    Text(\r\n        modifier = Modifier.clickable(\r\n            onClick = { navigateToPane2() }\r\n      ),\r\n      text = \"Pane 1!\"\r\n    )\r\n}<\/pre>\n
\n  With the new TwoPaneLayout version, navigateToPane1<\/code> and navigateToPane2<\/code> can now only be called within TwoPaneScope, so you would need to update your code to this:\n<\/p>\n
@Composable\r\nfun ExampleApp() {\r\n    TwoPaneLayout<\/em>(\r\n        pane1 = { Pane1() },\r\n        pane2 = { Pane2() }\r\n    )\r\n}\r\n@Composable\r\nfun TwoPaneScope.Pane1() {\r\n    Text(\r\n        modifier = Modifier.clickable(\r\n            onClick = { navigateToPane2() }\r\n        ),\r\n        text = \"Pane 1!\"\r\n    )\r\n}<\/pre>\n
\n  Regardless of the API changes, the navigation functionality remains the same, as shown in this animation: \n<\/p>\n
\n  \"Animation\n<\/p>\n
Figure 1. Animation showing navigateToPane1<\/code> and navigateToPane2<\/code> on a single screen device<\/em>\n<\/p>\n
\n  There also are additional fields available for use in your apps:\n<\/p>\n