{"id":2138,"date":"2022-01-20T12:13:30","date_gmt":"2022-01-20T20:13:30","guid":{"rendered":"https:\/\/devblogs.microsoft.com\/surface-duo\/?p=2138"},"modified":"2022-01-20T12:13:30","modified_gmt":"2022-01-20T20:13:30","slug":"jetpack-compose-windowstate-preview","status":"publish","type":"post","link":"https:\/\/devblogs.microsoft.com\/surface-duo\/jetpack-compose-windowstate-preview\/","title":{"rendered":"Jetpack Compose WindowState preview"},"content":{"rendered":"

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

\n This week, we\u2019d like to announce the release of WindowState<\/a>, a new utility library that\u2019s part of our Compose SDK<\/a>. Our goal was to provide easy access to all the window information provided by the Jetpack Window Manager library<\/a> and to simplify the logic required to enhance your apps for large screens and foldables. \n<\/p>\n

Library overview<\/h2>\n

\n The main features of the library are the WindowState data class, which contains three categories of information, and the rememberWindowState()<\/code> helper function.\n<\/p>\n

data class WindowState(\r\n   val hasFold: Boolean = false,\r\n   val isFoldHorizontal: Boolean = false,\r\n   val foldBounds: Rect = Rect(),\r\n   val foldState: FoldState = FoldState.FLAT,\r\n   val foldSeparates: Boolean = false,\r\n   val foldOccludes: Boolean = false,\r\n   val windowWidth: Dp = 0.dp,\r\n   val windowHeight: Dp = 0.dp,\r\n)\r\n@Composable\r\nfun Activity.rememberWindowState(): WindowState<\/pre>\n
Figure 1. Constructor for the WindowState data class and function signature for rememberWindowState().<\/em>\n<\/p>\n
Fold properties<\/h3>\n
\n  The WindowState class encapsulates all of the fold data that can be extracted from Jetpack Window Manager\u2019s WindowLayoutInfo<\/a> and FoldingFeature<\/a> classes. As shown above, the properties passed into the WindowState constructor are all publicly accessible values, and we also added a few other properties that might be helpful in your app\u2019s logic:\n<\/p>\n
val foldablePaneWidth: Int<\/pre>\n
\n  The foldablePaneWidth<\/code> property returns the width (in pixels) of a single pane of a dual-screen or foldable device when the device is in dual-screen mode. If the device is in single-screen mode, or the device is a regular single-screen device, the return value will be 0. (Note: the return value is based on the assumption that the developer wants two panes of equal width)\n<\/p>\n
val foldSize: Int<\/pre>\n
\n  The foldSize<\/code> property returns the width (in pixels) of the hinge of dual-screen device or the folding line of foldable device when the device is in dual-screen mode. If the device is in single-screen mode, or the device is a regular single-screen device, the return value will be 0.\n<\/p>\n
Window size<\/h3>\n
\n  The WindowState class also contains properties related to large screens. As you can see in constructor, the class accepts the height and width of the current window, then uses this information to calculate the corresponding WindowSizeClass<\/code> for both window dimensions. Our implementation follows the official Android guidance<\/a> for how to partition windows into the three size classes.\n<\/p>\n
\n  The window dimensions passed into the constructor are public, so these can be accessed at any time. In addition, the calculated size classes for the window can be accessed via the following getters:\n<\/p>\n
fun widthSizeClass(): WindowSizeClass\r\nfun heightSizeClass(): WindowSizeClass<\/pre>\n
Figure 2. Getter methods for window width and height size classes<\/em>\n<\/p>\n
Window mode<\/h3>\n
\n  Lastly, WindowState makes it simple to calculate the current window mode, which is helpful when making decisions about your app\u2019s layout. We\u2019ve provided several properties and getters that help you determine which of the four window modes<\/a> is currently in use:\n<\/p>\n
val windowMode: WindowMode\r\nfun isDualScreen(): Boolean\r\nfun isDualPortrait(): Boolean\r\nfun isDualLandscape(): Boolean\r\nfun isSinglePortrait(): Boolean\r\nfun isSingleLandscape(): Boolean<\/pre>\n
Figure 3. Public properties and getter methods for window mode information<\/em>\n<\/p>\n
\n  To make the library as flexible as possible, we\u2019ve given you the option to access the windowMode<\/code> directly, which is useful for choosing between different layouts in a when<\/code> block, or to simply ask whether the current window is in a specific mode, which is useful as a state to pass to composables.\n<\/p>\n
Get started<\/h2>\n
Add to your project<\/h3>\n
\n  To start using the WindowState library, follow these steps:\n<\/p>\n
    \n
  1. \n  Add the following dependency to your build.gradle<\/b> file:<\/p>\n
    implementation \"com.microsoft.device.dualscreen:windowstate:1.0.0-alpha1\"<\/pre>\n<\/li>\n
  2. \n  Call the rememberWindowState()<\/code> function from your MainActivity and pass the result into your top-level composable<\/p>\n
    class MainActivity : ComponentActivity() {\r\n    override fun onCreate(savedInstanceState: Bundle?) {\r\n        super.onCreate(savedInstanceState)\r\n        \r\n        setContent {\r\n            ExampleAppTheme {\r\n                ExampleApp(rememberWindowState())\r\n            }\r\n        }\r\n    }\r\n}<\/pre>\n<\/li>\n
  3. \n  Access the WindowState properties within your composables and use them to make layout decisions<\/p>\n
    \r\nfun ExampleApp(windowState: WindowState) {\r\n    if (windowState.isDualScreen())\r\n        DualScreenAppContent(windowState.foldSize)\r\n    else\r\n        SingleScreenAppContent()\r\n}<\/pre>\n<\/li>\n<\/ol>\n
    \n  For more detailed instructions and API reference information, please refer to the WindowState README<\/a>.\n<\/p>\n
    Example usage<\/h3>\n
    \n  To see some of examples of how to use the library, you can check out a few different samples. \n<\/p>\n
    \n  In the SDK repo, we created a small sample<\/a> to showcase all of the properties that can be accessed via WindowState.\n<\/p>\n
    \n  \n  \n<\/p>\n
    Figure 4. Screenshots of the library sample in single portrait mode and dual landscape mode on the Surface Duo emulator.<\/em>\n<\/p>\n
    \"WindowState<\/a><\/p>\n
    Figure 5. Screenshots of the library sample on other large screen and foldable emulators (clockwise from the top: 6.7 Horizontal Fold-in, 7.6 Fold-in with outer display, Pixel C).<\/em>\n<\/p>\n
    \n  We\u2019ve also updated each of our Compose samples<\/a> to use WindowState. For an example of how foldable properties can be used, check out the updated TwoPage sample<\/a>. To see how you can use windowMode<\/code> inside a when<\/code> block, check out the updated CompanionPane sample<\/a>. If you would prefer to check whether the window is in a specific mode, you can refer to the ListDetail sample<\/a> to see how isDualPortrait()<\/code> is used.\n<\/p>\n
    \n  In our samples, we definitely noticed that using WindowState helped simplify our app logic, and we hope it does the same for you! Since this is the first version of the library, please don\u2019t hesitate to send us feedback on how you think future versions could be improved \ud83d\ude0a\n<\/p>\n
    Resources and Feedback<\/h2>\n
    \n  Check out the Surface Duo Jetpack Compose developer documentation<\/a> and past blog posts<\/a> for links and details on all our samples. You can find our Jetpack Compose samples<\/a> on GitHub.\n<\/p>\n
    \n  If you have any questions, or would like to tell us about your apps, use the feedback forum<\/a> or message us on Twitter @surfaceduodev<\/a>.\n<\/p>\n
    \n  Finally, join us live on Twitch<\/a> at 11am PST to discuss the WindowState library, Jetpack Window Manager, and any other Surface Duo developer questions you might have.<\/p>\n","protected":false},"excerpt":{"rendered":"
    Hello Jetpack Compose developers! This week, we\u2019d like to announce the release of WindowState, a new utility library that\u2019s part of our Compose SDK. Our goal was to provide easy access to all the window information provided by the Jetpack Window Manager library and to simplify the logic required to enhance your apps for large […]<\/p>\n","protected":false},"author":72597,"featured_media":2139,"comment_status":"open","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"footnotes":""},"categories":[1],"tags":[692,706,46],"class_list":["post-2138","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-surface-duo-sdk","tag-jetpack-compose","tag-jetpack-window-manager","tag-surface-duo"],"acf":[],"blog_post_summary":"
    Hello Jetpack Compose developers! This week, we\u2019d like to announce the release of WindowState, a new utility library that\u2019s part of our Compose SDK. Our goal was to provide easy access to all the window information provided by the Jetpack Window Manager library and to simplify the logic required to enhance your apps for large […]<\/p>\n","_links":{"self":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts\/2138","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/users\/72597"}],"replies":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/comments?post=2138"}],"version-history":[{"count":0,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/posts\/2138\/revisions"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/media\/2139"}],"wp:attachment":[{"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/media?parent=2138"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/categories?post=2138"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/devblogs.microsoft.com\/surface-duo\/wp-json\/wp\/v2\/tags?post=2138"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}