Alex Zhukovich

Handling Asynchronous Images in Android Screenshot Tests

Thu, 27 Aug 2026 00:00:00 GMT

This article is based on a chapter from my book, Mastering Android Screenshot Testing.

Modern applications frequently load images asynchronously, which is a common cause of unstable screenshot tests or confusion when you review newly generated screenshots. A test can pass locally and fail on CI, produce a different image on every run, or leave an empty space where the image should be placed.

This article covers two ways to make screenshot tests deterministic: injecting a fake image loader with the coil-test library, or using Compose’s inspection mode as a fallback when the first option isn’t available.

Screenshot testing frameworks wait for the UI to be idle before capturing an image, but do not wait for asynchronous image loading to complete. What happens next depends on the framework. Compose Preview Screenshot Testing and Paparazzi render through layoutlib, which has no access to the network, so the image never loads and you are left with an empty space. Other frameworks might capture a screenshot while the image request is still in progress.

The primary purpose of screenshot tests is to verify that components or screens render correctly across diverse system configurations, such as varying font scales, light and dark color modes, and different locales. In most cases, the actual image content is irrelevant—you can replace images with placeholders to verify your layouts are rendered correctly regardless of image content.

If you’re using Coil for asynchronous image loading, you can use the coil-test library to inject custom images for all image requests, ensuring predictable and consistent results.

Providing Fake Images Using the coil-test Library

The coil-test library allows you to provide custom images for all loading requests.

val imageLoaderEngine = FakeImageLoaderEngine.Builder()
    .intercept({ request -> true }, ColorImage(Color.Green.toArgb()))
    .build()

val imageLoader = ImageLoader.Builder(ApplicationProvider.getApplicationContext())
    .components { add(imageLoaderEngine) }
    .build()

To replace the default ImageLoader with a custom one, you can use SingletonImageLoader.setUnsafe(imageLoader). To revert it back to the default ImageLoader, you need to call SingletonImageLoader.reset().

Let’s look at an example that uses the Android Testify framework.

@RunWith(AndroidJUnit4::class)
class AsyncImageScreenshotTest {

    @get:Rule
    val composableScreenshotRule = ComposableScreenshotRule()

    @ScreenshotInstrumentation
    @Test
    fun asyncImage() {
        // Providing a fake image
        val imageLoaderEngine = FakeImageLoaderEngine.Builder()
            .intercept({ request -> true }, ColorImage(Color.Green.toArgb()))
            .build()
        val imageLoader = ImageLoader.Builder(ApplicationProvider.getApplicationContext())
            .components { add(imageLoaderEngine) }
            .build()
        SingletonImageLoader.setUnsafe(imageLoader)

        composableScreenshotRule
            .setCompose {
                AppTheme {
                    AsyncImage(
                        modifier = Modifier.size(200.dp),
                        uri = "content://media/external/images/media/1".toUri()
                    )
                }
            }
            .assertSame()

        // Resetting to provide real images again
        SingletonImageLoader.reset()
    }
}

You can avoid duplicating code for setting up and resetting an image loader in each test by creating a custom JUnit rule. This rule will handle the setup and reset process for you. To implement this, create a new class and extend the TestWatcher class, which serves as the base class for JUnit rules.

class FakeImageLoaderRule(
    private val contextProvider: () -> Context,
    val image: Image = ColorImage(Color.Green.toArgb())
): TestWatcher() {

    @OptIn(DelicateCoilApi::class)
    override fun starting(description: Description?) {
        super.starting(description)
        val imageLoaderEngine = FakeImageLoaderEngine.Builder()
            .intercept({ request -> true }, image)
            .build()
        val imageLoader = ImageLoader.Builder(contextProvider())
            .components { add(imageLoaderEngine) }
            .build()
        SingletonImageLoader.setUnsafe(imageLoader)
    }

    @OptIn(DelicateCoilApi::class)
    override fun finished(description: Description?) {
        super.finished(description)
        SingletonImageLoader.reset()
    }
}

The starting function runs before the test case executes, and the finished after it, including when the test fails.

Once that’s done, you can make the test class simpler.

@RunWith(AndroidJUnit4::class)
class AsyncImageScreenshotTest {

    @get:Rule(order = 0)
    val fakeImageLoaderRule = FakeImageLoaderRule(
        contextProvider = { ApplicationProvider.getApplicationContext() }
    )

    @get:Rule(order = 1)
    val composableScreenshotRule = ComposableScreenshotRule()

    @ScreenshotInstrumentation
    @Test
    fun asyncImage() {
        composableScreenshotRule
            .setCompose {
                AppTheme {
                    AsyncImage(
                        modifier = Modifier.size(200.dp),
                        uri = "content://media/external/images/media/1".toUri()
                    )
                }
            }
            .assertSame()
    }
}

The current implementation of the FakeImageLoaderRule isn’t tied to the screenshot testing framework, it depends on the coil-test library, and if you decide to use another framework instead of Coil, the implementation of it should be changed. So, the same rule can also be used with Paparazzi, Roborazzi, Dropshots and Shot.

However, you cannot use the FakeImageLoaderRule test rule for @Preview functions. Instead, you need to provide an AsyncImagePreviewHandler object through LocalAsyncImagePreviewHandler.

@Preview
@Composable
fun Preview_AsyncImage() {
    AppTheme {
        val previewHandler = AsyncImagePreviewHandler {
            ColorImage(Color.Green.toArgb())
        }
        CompositionLocalProvider(
            LocalAsyncImagePreviewHandler provides previewHandler
        ) {
            AsyncImage(
                modifier = Modifier.size(200.dp),
                model = "content://media/external/images/media/1".toUri(),
            )
        }
    }
}

Using Inspection Mode to Display Fake Images

The LocalInspectionMode.current returns a Boolean value showing whether the composable function is rendering within a preview. Let’s assume in your project, an AsyncImage component is used, which is a wrapper around the ThirdPartyAsyncImage component from the library, which doesn’t provide a way to inject fake images. To display fake images for preview functions and screenshot tests, you need to check whether inspection mode returns true. If so, use an Image component instead of the ThirdPartyAsyncImage one, with a green background and a placeholder image.

@Composable
fun AsyncImage(
    modifier: Modifier = Modifier,
    uri: Uri,
    contentDescription: String? = null,
    placeholder: ImageVector = ImagePlaceholderIcon,
    contentScale: ContentScale = ContentScale.Crop
) {
    if (LocalInspectionMode.current.not()) {
        ThirdPartyAsyncImage(
            modifier = modifier,
            model = uri,
            contentDescription = contentDescription,
            placeholder = rememberVectorPainter(placeholder),
            contentScale = contentScale
        )
    } else {
        Image(
            modifier = modifier
                .fillMaxSize()
                .background(Color.Green),
            imageVector = placeholder,
            contentDescription = null,
            colorFilter = ColorFilter.tint(Color.White)
        )
    }
}

This requires no additional configuration for Compose Preview Screenshot Testing, since preview functions already render in inspection mode. With any other framework, you need to enable it manually by providing LocalInspectionMode via CompositionLocalProvider.

@RunWith(AndroidJUnit4::class)
class AsyncImageScreenshotTest {

    @get:Rule
    val composableScreenshotRule = ComposableScreenshotRule()

    @ScreenshotInstrumentation
    @Test
    fun asyncImage_inspectionMode() {
        composableScreenshotRule
            .setCompose {
                CompositionLocalProvider(LocalInspectionMode provides true) {
                    AppTheme {
                        AsyncImage(
                            modifier = Modifier.size(200.dp),
                            uri = "content://media/external/images/media/1".toUri()
                        )
                    }
                }
            }
            .assertSame()
    }
}

Using this approach, you can achieve the same result, but I’d treat it as a last resort, for two reasons.

First, it introduces test-related code into the production codebase. Second, you need to keep the Image and ThirdPartyAsyncImage configurations in sync, as any change to parameters like contentScale or modifier must be mirrored; otherwise your screenshot tests won’t accurately reflect the real UI.

Here is an example of how the mood card component with photos looks when fake images are provided.

Asynchronous images can lead to unpredictable screenshot tests, as screenshot testing frameworks capture the screen before image loading has finished. This can result in either a blank space where the image should be, or a different image on every run. The solution is to replace all asynchronously loaded images with fake ones. You can do that by injecting a fake image loader with coil-test or a similar tool, or fall back to Compose’s inspection mode if it doesn’t. Both methods provide the same result, but a fake image loader is preferable: it keeps test-specific code out of production, and you don’t need to keep testing and production implementations in sync.

This article is based on a chapter from my book, Mastering Android Screenshot Testing. It covers the fundamental principles, frameworks, and best practices to catch visual regressions across devices and configurations before they reach production. A free sample chapter is available on Leanpub.

Originally published on alexzh.com.

My laptop died last week, and here is what it took with it

Mon, 06 Jul 2026 00:00:00 GMT

A few days ago, I accidentally spilled water on my laptop.

It restarted a few times and turned off entirely.

I did everything the internet told me to. Dried it out and didn’t touch the power button.

Every repair shop was already closed. So I waited overnight, not knowing if anything on that laptop was still alive.

The next morning, the guy at the shop checked it and said: “The chances of recovery are small. Do you want us to try?”

Until that moment, I had hope. It was just water, not coffee, not something sticky.

But now, all I could focus on was what hadn’t been backed up:

My photos
The fixes for the next release of my book
The code for one of my personal projects

Gone. Maybe forever.

Now let me ask you something.

If your laptop died right now, without any warning, what would you lose?

Do you actually back up the things you can’t replace?

If you just pictured something you wouldn’t want to lose, you’re exactly where I was a week ago. Here’s the simple system I wish I’d had back then:

Start with what you can’t replace.
Automate a backup process. A backup you have to remember is a backup you’ll forget.
Follow the 3-2-1 rule: 3 copies of your data (the original included) on 2 different types of storage with 1 copy somewhere remote.

If I’d followed step 2, the changes that I made last week for my book would be safe right now.

So here’s what I’d suggest.

Tonight, before you close your laptop, pick the one folder you wouldn’t want to lose, and copy it somewhere else: cloud, USB drive, anywhere.

That’s it. Five minutes. You can build the full 3-2-1 setup this weekend. But tonight, get your irreplaceable stuff to two places instead of one.

Take care of your data (and your drinks near your laptop),

Alex

P.S. I’m writing this from a new laptop.

The repair shop called me back a few days later. They gave me the old one and said there was nothing they could do.

I’m telling you this because “I’ll back it up later” was working fine for me too, right until the moment it wasn’t.

Originally published on alexzh.com.

How to fix the Compose preview naming problem

Thu, 22 Jan 2026 00:00:00 GMT

If you use PreviewParameterProvider to avoid duplicating preview functions, you’ve probably dealt with this frustration: index-based naming like uiState 0, uiState 1, uiState 2.

When you see these names, it’s hard to tell which one relates to the empty state or error state. When you have 20+ previews across different states, themes, and font scales, index-based naming becomes something that slows you down.

Good news: the recent stable release of ui-tooling-preview finally solves this.

Quick Context: Why PreviewParameterProvider Matters

If you’re already using PreviewParameterProvider you can skip this section. For everyone else, here’s the short version.

Instead of writing separate preview functions for each UI state (empty, loading, success, error), you create one provider that supplies multiple states to a single preview function. Let’s look at examples of testing different states of the Statistics screen. Here we want to verify empty and two states when different data are available.

Now, let’s take a look at the source code of the provider:

class StatisticsScreenUiStateProvider : PreviewParameterProvider<StatisticsScreenUiState> {
    override val values: Sequence<StatisticsScreenUiState>
        get() = sequenceOf(
            StatisticsScreenUiState(
                isLoading = false,
                selectedDateRange = SelectedDateRangeData(...)
            ),
            StatisticsScreenUiState(
                isLoading = false,
                selectedDateRange = SelectedDateRangeData(...),
                averageDailyMoodChartData = AverageDailyMoodChartData(...),
                actionImpactChartData = ActionImpactChartData(...)
            ),
            StatisticsScreenUiState(
                isLoading = false,
                selectedDateRange = SelectedDateRangeData(...),
                averageDailyMoodChartData = AverageDailyMoodChartData(...)
            )
        )
}

The main problem with this approach is the default index-based naming for the preview functions, like uiState 0, uiState 1, uiState 2.

Solution: Provide a name for every state

Starting with ui-tooling-preview:1.10.0, you can replace default index-based names with descriptive labels. The getDisplayName(index: Int): String? function gives you full control over the names of preview functions displayed in the preview panel.

class StatisticsScreenUiStateProvider : PreviewParameterProvider<StatisticsScreenUiState> {

    ...
    
    override fun getDisplayName(index: Int): String? {
        return when (index) {
            0 -> "Empty"
            1 -> "Average Daily Mood & Action Impact"
            2 -> "Average Daily Mood"
            else -> super.getDisplayName(index)
        }
    }
}

Your preview panel now shows what each state represents.

The basic approach from the previous example works, but it has a big problem: your state objects live separately from labels. If you add a new state and forget to update the name mapping, your labels will get mixed up again.

To fix this problem, we will use the Pair<String, StatisticsUiState> to connect each name with its state.

class StatisticsScreenUiStateProvider : PreviewParameterProvider<StatisticsScreenUiState> {
        val data = listOf(
            Pair(
                "Empty",
                StatisticsScreenUiState(
                    isLoading = false,
                    selectedDateRange = SelectedDateRangeData(...)
                )
            ),
            Pair(
                "Average Daily Mood & Action Impact",
                StatisticsScreenUiState(
                    isLoading = false,
                    selectedDateRange = SelectedDateRangeData(...),
                    averageDailyMoodChartData = AverageDailyMoodChartData(...),
                    actionImpactChartData = ActionImpactChartData(...)
                )
            ),
            Pair(
                "Average Daily Mood",
                StatisticsScreenUiState(
                    isLoading = false,
                    selectedDateRange = SelectedDateRangeData(...),
                    averageDailyMoodChartData = AverageDailyMoodChartData(...)
            )
        )

        override val values: Sequence<StatisticsScreenUiState>
            get() = data.map { it.second }.asSequence()

        override fun getDisplayName(index: Int): String {
            return data[index].first
        }
    }

Now, it’s impossible to add a state without naming it.

If you’re using Jetpack Compose BOM 2026.01.00 or later, you already have ui-tooling-preview:1.10.1 and this feature is ready to use.

Key Takeaways

Instead of writing multiple preview functions for different UI states, create a single provider that supplies many states to one preview function.
Starting with ui-tooling-preview:1.10.0, you can replace default index-based naming (e.g., “uiState 0”) with descriptive custom names. This naming feature requires Android Studio Narwhal 3 Feature Drop (2025.1.3) or newer.
Custom display names don’t yet work with the Compose Screenshot Testing Tool (0.0.1-alpha13), which still uses index-based naming.

Originally published on alexzh.com.

Why Visual Testing Is Critical for Mobile App Quality

Thu, 13 Mar 2025 00:00:00 GMT

Have you ever shipped an app with a broken UI?

In today’s fast-paced development environment, it is happening more often, even for teams who have manual QA and automated UI tests in place.

We often consider UI issues less important, but they can be much more important than just misalignment of a button. Many UI issues can make your application inaccessible because the text color may have not enough contrast, which leads to unreadable text. On the other side, when users see an unpolished UI, they lose trust in your brand, and bad app reviews can lead to a reduced number of downloads.

But wait… I already have UI tests.

Even if you have UI tests, this doesn’t mean that they verify pixel perfectness. Many UI tests check the behavior of components, screens, or an application, but not pixel-perfectness.

Different types of UI tests verify different aspects of the application. End-To-End and UI tests with fake data focus on user behavior, but they don’t check alignment between elements, color correctness for light and dark modes, and other visual details.

There is a solution - visual testing.

What is Visual Testing?

Visual tests focus on identifying pixel imperfections in your components and screens. In Android development, visual tests are implemented through screenshot comparison. This involves comparing the current state of the UI against a baseline screenshot (commonly called “golden screenshots”) that represents the expected state of a component or a screen.

The screenshot comparison allows you to catch the following problems:

Misaligned components and spacing inconsistencies
Incorrect colors in light mode, dark mode, and custom themes
Broken layouts for various devices (phones, tablets, foldable devices) and font sizes
Rendering errors in Right-To-Left (RTL) and Left-to-Right (LTR) layouts, often related to locale settings
Localization problems, such as text overflow when content in certain languages exceeds available space
Accessibility concerns related to displaying content, such as color contrast
Unexpected rendering problems in specific scenarios

There are multiple frameworks for screenshot testing in Android. Here are the most popular frameworks:

Framework	Local vs Instrumentation tests	Rendering engine
Shot	Instrumentation tests	Device rendering
Roborazzi	Local tests	Robolectric Native Graphics
Paparazzi	Local tests	Layoutlib
Compose Preview Screenshot Testing	Local tests	Layoutlib

Note: The “Layoutlib” renders @Previews in Android Studio.

A detailed framework comparison will be covered in one of the following articles.

These frameworks follow a similar workflow with two commands:

The “record” command generates golden screenshots for your tests.
The “verify” command compares the current UI state against the golden screenshots.

Command syntax varies between frameworks. For example, when using the Shot framework, you’ll use the -Precord parameter to generate baseline images:

./gradlew :app:debugExecuteScreenshotTests -Precord

Ok, it sounds simple, but show me the test case.

First Visual Tests with Shot Framework

Let’s explore two screenshot tests for the statistics screen for the mood tracker app using the Shot framework. The tests will focus on the UI states representing Empty and Success states (data available for chart rendering).

class StatisticsScreenScreenshotTest : ScreenshotTest {
        companion object {
        val TEST_DATE = LocalDate(2024, Month.SEPTEMBER, 15)
    }
    
    @get:Rule
    val composeTestRule = createComposeRule()

    private val dateProvider = mockk<DateProvider>()
    private val moodHistoryRepository = mockk<MoodHistoryRepository>()

    @Before
    fun setUp() {
        initDI()
    }
    
    @Test
    fun statisticsScreen_noData() {
        val startDate = TEST_DATE.atStartOfMonth().atStartOfDayIn(
            defaultTimeZone
        )
        val endDate = TEST_DATE.atEndOfMonth().atEndOfDay()

        every { dateProvider.getCurrentDate() } returns TEST_DATE

        every {
            moodHistoryRepository.getAverageDayToHappiness(startDate, endDate)
        } returns flowOf(emptyList())

        every {
            moodHistoryRepository.getActivityToHappinessByDate(startDate, endDate)
        } returns flowOf(emptyList())

        composeTestRule.setContent {
            FeelTrackerAppTheme {
                StatisticsScreen(
                    viewModel = koinViewModel(),
                    onHome = { },
                    onBreathingPatternSelection = { },
                    onSettings = { }
                )
            }
        }

        compareScreenshot(
            rule = composeTestRule,
            name = "statisticsScreen_noData"
        )
    }

    @Test
    fun statisticsScreen_hasData() {
        val startDate = TEST_DATE.atStartOfMonth().atStartOfDayIn(
            defaultTimeZone
        )
        val endDate = TEST_DATE.atEndOfMonth().atEndOfDay()
        val firstDateOfTheMonth = TEST_DATE.atStartOfMonth()

        every { dateProvider.getCurrentDate() } returns StatisticsScreenScreenshotTest.TEST_DATE

        every {
            moodHistoryRepository.getAverageDayToHappiness(startDate, endDate)
        } returns averageDayToHappinessChartData(firstDateOfTheMonth)

        every {
            moodHistoryRepository.getActivityToHappinessByDate(startDate, endDate)
        } returns activityToHappinessData()

        composeTestRule.setContent {
            FeelTrackerAppTheme {
                StatisticsScreen(
                    viewModel = koinViewModel(),
                    onHome = { },
                    onBreathingPatternSelection = { },
                    onSettings = { }
                )
            }
        }

        compareScreenshot(
            rule = composeTestRule,
            name = "statisticsScreen_hasData"
        )
    }
    
    private fun initDI() {
        stopKoin()
        startKoin {
            allowOverride(true)
            androidContext(InstrumentationRegistry.getInstrumentation().targetContext)
            modules(
                ...
                module {
                    single { dateProvider }
                    single { moodHistoryRepository }
                }
            )
        }
    }

    private fun averageDayToHappinessChartData(startDate: LocalDate): Flow<List<MoodDayToHappiness>> {
        return flowOf(listOf(...))
    }

    private fun activityToHappinessData(): Flow<List<ActivityToHappiness>> {
        return flowOf(listOf(...))
    }
}

Important notes:

Test class should implement the “ScreenshotTest” interface to screenshot comparison functionality
Fixed date is needed for reproducibility of the screenshot test
The test uses mock instances of data provider and repository to emulate different screen states. It uses the “Koin” framework.

To generate baseline (golden) screenshots, run:

./gradlew :app:debugExecuteScreenshotTests -Precord

This command saves the current state of UI as the reference point for future comparisons. Now, let’s simulate the real-world scenario by changing the title of the average daily mood chart from “AVERAGE DAILY MOOD” to “DAILY MOOD” and run the verification:

./gradlew :app:debugExecuteScreenshotTests

After execution, the Shot framework generates a report that highlights the differences:

Note: This image includes the zoom effect only for demonstration purposes.

This visual feedback is significantly more efficient than manually inspecting each component and screen.

To better understand the difference between different types of UI tests and how they complement each other, check out the “Not all UI tests are the same” article.

Conclusion

Visual testing is critical for delivering applications without visual imperfections. While UI tests focus on behavior verification, they cannot check pixel perfectness of your application.

By implementing visual testing, development teams can catch visual imperfections before releasing an application. These tests will catch component misalignments, color incorrectness across various themes, visual issues on different devices, and much more.

Unpolished UI always looks unprofessional and can damage trust in your brand. By incorporating UI tests into the development process, you’re not just checking pixel perfectness, but also protecting brand reputation.

Stay tuned for my upcoming articles where I’ll dive deeper into framework comparisons and share best practices for integrating visual testing into Android projects.

Originally published on alexzh.com.

A Visual Guide to TopAppBar Variants in Jetpack Compose

Fri, 14 Feb 2025 00:00:00 GMT

The TopAppBar is a commonly used component in Jetpack Compose as many screens use it. While developers commonly customize the TopAppBar. Material 3 library provides predefined variations to simplify development and follow Material Design guidelines.

In this article, we will explore:

The different TopAppBar components offered by the Material 3 library.
The default typography and height in each TopAppBar variant.

Let’s look at the default text styles for titles and subtitles, as well as the component height, to help choose the best TopAppBar components for your design and use case. These parameters can also be customized.

For easy comparison, I created a comprehensive table summarizing all the available options. Below, you’ll find detailed information about each TopAppBar variant, alongside with a basic example.

TopAppBar

The TopAppBar is the most widespread component.

Default values:

Property	TopAppBar
Title Text Style	TitleLarge
Height	64dp

@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun Demo_TopAppBar() {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Title") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(Icons.AutoMirrored.Default.ArrowBack, "Back")
                    }
                },
                actions = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.AttachFile, "Attach")
                    }
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.MoreVert, "More")
                    }
                }
            )
        }
    ) { innerPadding ->
        Column(
            Modifier.fillMaxWidth().padding(innerPadding).verticalScroll(rememberScrollState())
        ) {
            Text(
                modifier = Modifier.padding(16.dp),
                text = remember { LoremIpsum().values.first() },
                fontSize = 16.sp
            )
        }
    }
}

CenterAlignedTopAppBar

Similar to the standard TopAppBar, but with one key difference: the title is horizontally centered.

Default values:

Property	CenterAlignedTopAppBar
Title Text Style	TitleLarge
Height	64dp

@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun Demo_CenterAlignedTopAppBar() {
    Scaffold(
        topBar = {
            CenterAlignedTopAppBar(
                title = { Text("Title") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(Icons.AutoMirrored.Default.ArrowBack, "Back")
                    }
                },
                actions = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.AttachFile, "Attach")
                    }
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.MoreVert, "More")
                    }
                }
            )
        }
    ) { innerPadding ->
        Column(
            Modifier.fillMaxWidth().padding(innerPadding).verticalScroll(rememberScrollState())
        ) {
            Text(
                modifier = Modifier.padding(16.dp),
                text = remember { LoremIpsum().values.first() },
                fontSize = 16.sp
            )
        }
    }
}

MediumTopAppBar and LargeTopAppBar

These components introduce dynamic behavior, allowing the components to expand and collapse. They can display titles, navigation icons, and actions.

Default values:

Property	MediumTopAppBar	LargeTopAppBar
Title Text Style (Collapsed)	TitleLarge	TitleLarge
Title Text Style (Expanded)	HeadlineSmall	HeadlineMedium
Collapsed Height	64dp	64dp
Expanded Height	112dp	152dp

@OptIn(ExperimentalMaterial3Api::class)
@Preview
@Composable
fun Demo_MediumTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()

    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumTopAppBar(
                title = { Text("Title") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(Icons.AutoMirrored.Default.ArrowBack, "Back")
                    }
                },
                actions = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.AttachFile, "Attach")
                    }
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.MoreVert, "More")
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { innerPadding ->
        Column(
            Modifier.fillMaxWidth().padding(innerPadding).verticalScroll(rememberScrollState())
        ) {
            Text(
                modifier = Modifier.padding(16.dp),
                text = remember { LoremIpsum().values.first() },
                fontSize = 16.sp
            )
        }
    }
}

MediumFlexibleTopAppBar and LargeFlexibleTopAppBar

These components add the capability to display subtitle alongside with titles, navigation icons, and actions.

Default values:

Property	MediumFlexibleTopAppBar	LargeFlexibleTopAppBar
Title Text Style (Collapsed)	TitleLarge	TitleLarge
Title Text Style (Expanded)	HeadlineMedium	DisplaySmall
Subtitle Text Style (Collapsed)	LabelMedium	LabelMedium
Subtitle Text Style (Expanded)	LabelLarge	TitleMedium
Collapsed Height	64dp	64dp
Expanded Height (with subtitle)	136dp	152dp
Expanded Height (without subtitle)	112dp	120dp

@OptIn(ExperimentalMaterial3ExpressiveApi::class, ExperimentalMaterial3Api::class)
@Preview
@Composable
fun Demo_MediumFlexibleTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            MediumFlexibleTopAppBar(
                title = { Text("Title") },
                subtitle = { Text("Subtitle") },
                navigationIcon = {
                    IconButton(onClick = {}) {
                        Icon(Icons.AutoMirrored.Default.ArrowBack, "Back")
                    }
                },
                actions = {
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.AttachFile, "Attach")
                    }
                    IconButton(onClick = {}) {
                        Icon(Icons.Default.MoreVert, "More")
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { innerPadding ->
        Column(
            Modifier.fillMaxWidth().padding(innerPadding).verticalScroll(rememberScrollState())
        ) {
            Text(
                modifier = Modifier.padding(16.dp),
                text = remember { LoremIpsum().values.first() },
                fontSize = 16.sp
            )
        }
    }
}

TwoRowsTopAppBar

This component also supports expanded and collapsed states. It includes title, subtitle, navigation icons, and actions. The TwoRowsTopAppBar component simplifies the management of different text strings for expanded and collapsed states compared to MediumFlexibleTopAppBar.

Default values:

Property	TwoRowsTopAppBar
Title Text Style (Collapsed)	TitleLarge
Title Text Style (Expanded)	HeadlineMedium
Subtitle Text Style (Collapsed)	LabelMedium
Subtitle Text Style (Expanded)	LabelLarge
Collapsed Height	64dp
Expanded Height (with subtitle)	136dp
Expanded Height (without subtitle)	112dp

@OptIn(ExperimentalMaterial3Api::class, ExperimentalMaterial3ExpressiveApi::class)
@Preview
@Composable
fun Demo_TwoRowsTopAppBar() {
    val scrollBehavior = TopAppBarDefaults.exitUntilCollapsedScrollBehavior()
    Scaffold(
        modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
        topBar = {
            TwoRowsTopAppBar(
                title = { expanded ->
                    Text(
                        text = if (expanded) "Expanded Title" else "Collapsed Title",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                subtitle = { expanded ->
                    Text(
                        text = if (expanded) "Expanded Subtitle" else "Collapsed Subtitle",
                        maxLines = 1,
                        overflow = TextOverflow.Ellipsis
                    )
                },
                navigationIcon = {
                    IconButton(onClick = { /* doSomething() */ }) {
                        Icon(
                            imageVector = Icons.AutoMirrored.Filled.ArrowBack,
                            contentDescription = "Localized description"
                        )
                    }
                },
                scrollBehavior = scrollBehavior
            )
        }
    ) { innerPadding ->
        Column(
            Modifier.fillMaxWidth().padding(innerPadding).verticalScroll(rememberScrollState())
        ) {
            Text(
                modifier = Modifier.padding(16.dp),
                text = remember { LoremIpsum().values.first() },
                fontSize = 16.sp
            )
        }
    }
}

Conclusion

By exploring different TopAppBar variants, we’ve seen that Material 3 offers pre-built solutions for many common use cases.

Understanding these predefined options saves development time and effort. Instead of reinventing the wheel and customizing the basic TopAppBar for each use case, you can leverage the pre-built solutions provided by the Material 3 library.

The next time, explore the available options in the Material 3 library. It may save you time and you will already use a polished solution.

Originally published on alexzh.com.

Overcoming Comparison and Finding Joy in Writing My First Book

Fri, 31 Jan 2025 00:00:00 GMT

The past year was a roller coaster for me. In 2024, I began taking the first steps to write my first book. I started working on planning and creating the structure of my book and the writing process started pretty easily, but after the first chapter, I made a big mistake.

I started reading other technical books and compared the polished version of these books to my raw first draft. It’s a good idea to read books in your genre, but doing this made me doubt my writing skills. I forgot to remind myself that I was comparing my first iteration to a polished version that had gone through multiple iterations.

I spent weeks writing and comparing, but it made writing a book more complicated and less enjoyable. I only wrote a small number of words each writing session, pretending that I was writing a book. Then I finally admitted to myself that I wasn’t actually writing a book; I was just imitating the process and finding no enjoyment in it at all.

I decided that I had to either take writing seriously or stop it altogether. I set a goal to write 15,000 words in 3 weeks. If I couldn’t meet this goal, I knew it was time to stop lying to myself and move on. During one week of those three, I went on vacation with my family. We enjoyed the sun and went swimming, but I also made time for writing. After 19 days, I had written almost 17,000 words and after that I completely changed my approach for writing the first draft of my book.

I wrote down all my thoughts about the topic of my book, reminding myself that I could always revise my manuscript later. My focus was not on writing perfectly, but on expressing everything I wanted to say. And in the meantime, I stopped reading other books in the genre until I finished the first draft. This helped me complete the manuscript in 3 months. Writing this way made me enjoy writing again.

Of course, I found a lot of mistakes while self-reviewing my first draft, but the first draft is not a polished version of the book.

This experience taught me several valuable lessons:

Creating something great takes time and practice.
Enjoyment is an important part of the process.
Even small adjustments can bring back enjoyment and motivation.
Break down your goal into small chunks, take action, and reflect. Without this approach, progress will be slow and efficiency will suffer.

I’m still on my journey to writing my first book, and it’s already been a roller coaster ride full of unexpected twists and turns. However, it’s a journey of self-discovery. It reminded me that passion and enjoyment are crucial for creative success.

Originally published on alexzh.com.

How to add platform-specific icons to a Compose Multiplatform project

Thu, 05 Dec 2024 00:00:00 GMT

Make step towards native experience on different platforms by adopting platform-specific icons in Compose Multiplatform. This helps improve user experience by providing familiar elements on different devices, while still maintaining common code.

In this article, we will explore how to support platform-specific icons in Compose Multiplatform project.

If you like learning through videos, this is for you:

Play video: How to add platform-specific icons to a Compose Multiplatform project

Setting up a Compose Multiplatform Project

For the demo purposes, I want to have a display a separate “Back”, “Edit” and “Delete” icons for the following platforms:

Android
iOS
Web & Desktop

We will implement it using icons from the material-icons-core (which is part of compose dependency) and .svg icons. For iOS, we will use SVG icons that can be added to the composeResources/drawable folder. Icons for other platforms will come from the “material-icons” library.

Getting information about the platform

In the end, I want to have an icon object, which will contain platform-specific icons which I can reuse in Compose Multiplatform code. Kotlin Multiplatform provides a possibility to use expect/actual mechanism to use different implementation depending on the platform. Let’s use it to get information about the platform.

sealed class Platform {
    data object Android : Platform()
    data object Desktop : Platform()
    data object Ios : Platform()
    data object Web : Platform()
}

expect val platform: Platform

Here is an implementation for each platform:

// Android
actual val platform: Platform = Platform.Android

// Desktop
actual val platform: Platform = Platform.Desktop

// iOS
actual val platform: Platform = Platform.Ios

//Web
actual val platform: Platform = Platform.Web

Creating Platform-Specific Icons

The next step is to define an icon. So, we will create an ImageVector object which defines an icon base on the platform. Let’s check out the definitions for the BackIcon, EditIcon and DeleteIcon objects which provides platform-specific icons.

val BackIcon: ImageVector
    @Composable
    get() {
        return when (platform) {
            Platform.Android -> Icons.AutoMirrored.Default.ArrowBack
            Platform.Ios -> vectorResource(Res.drawable.ic_back_ios)
            else -> Icons.AutoMirrored.Default.KeyboardArrowLeft
        }
    }

val EditIcon: ImageVector
    @Composable
    get() {
        return when (platform) {
            Platform.Android -> Icons.Outlined.Edit
            Platform.Ios -> vectorResource(Res.drawable.ic_edit_ios)
            else -> Icons.Filled.Edit
        }
    }

val DeleteIcon: ImageVector
    @Composable
    get() {
        return when (platform) {
            Platform.Android -> Icons.Outlined.Delete
            Platform.Ios -> vectorResource(Res.drawable.ic_delete_ios)
            else -> Icons.Filled.Delete
        }
    }

Finally, we can use the “BackIcon” as a navigation icon of the TopAppBar, and display other icons on the screen.

@Composable
fun IconList(
    onBack: () -> Unit
) {
    Scaffold(
        topBar = {
            TopAppBar(
                title = { Text("Demo: Icons") },
                navigationIcon = {
                    IconButton(onClick = onBack) {
                        Icon(
                            imageVector = BackIcon,
                            contentDescription = "Back"
                        )
                    }
                }
            )
        },
    ) {
        Column(
            modifier = Modifier.fillMaxSize().padding(vertical = 16.dp),
            horizontalAlignment = Alignment.CenterHorizontally,
            verticalArrangement = Arrangement.spacedBy(16.dp)
        ) {
            Card(modifier = Modifier.size(100.dp)) {
                Image(
                    imageVector = EditIcon,
                    contentDescription = "Edit"
                )
            }

            Card(modifier = Modifier.size(100.dp)) {
                Image(
                    imageVector = DeleteIcon,
                    contentDescription = "Delete"
                )
            }
        }
    }
}

You can find the full source code in IconList.kt in the KotlinMultiplatformPlayground repository.

Conclusion

In a Compose Multiplatform project, we can easily leverage the expect/actual mechanism to display different icons for every platform.

If you want to use material design icons, you can use the material-icons-core library, and if you need other icons, you can use the SVG files.

Originally published on alexzh.com.

How to create a scrollable chart in Compose Multiplatform

Fri, 22 Nov 2024 00:00:00 GMT

The “koalaplot” library got an update “v0.7.0” which added zoom and pan support for all platforms for XYGraph component. These changes allow us to create scrollable charts in Compose Multiplatform which will be available for Android, iOS, Web and Desktop platforms.

In this article, we will create a “Vertical Bar Chart” which will work on all platforms.

If you like learning through videos, this is for you:

Play video: How to create a scrollable chart in Compose Multiplatform

Setting up the project

To create the “Vertical Bar Chart”, let’s start with creating the generating Compose Multiplatform project, using the Kotlin Multiplatform Wizard website.

The next step is to add the library to the project. To do so, we need to library definition and version to the gradle/libs.versions.toml file:

[versions]
...
koalaplot-core = "0.7.0"

[libraries]
...
koalaplot-core = { module = "io.github.koalaplot:koalaplot-core", version.ref = "koalaplot-core" }

...

And, we need to add dependency to the composeApp/build.gradle.kts file:

...
kotlin {
         sourceSets {
        ...
        commonMain.dependencies {
                ...
                implementation(libs.koalaplot.core)
        }
        ...
    }
}
...

Afterwards, we need to sync the project.

Creating a Chart

Let’s create a chart which has a lot of data on the “X-axis”. For example, let’s create the “Average Daily Mood” chart for a month which has 30 days. This chart will use fake data, and we will use this function to generate fake data instead of getting data from the database.

data class DemoDailyMood(
    val dayOfMonth: Int,
    val happiness: Float
)

private fun generateChartData(numDays: Int = 30) = (1..numDays).map { day ->
    DemoDailyMood(day, Random.nextFloat() * (5f - 1f) + 1f)
}

Next, we’ll create a composable function to generate a chart. This function will use a chart component that needs separate data for the X-axis and Y-axis. So, we’ll provide this data to the composable function as parameters.

@OptIn(ExperimentalKoalaPlotApi::class)
@Composable
fun DailyMoodChart(
    modifier: Modifier = Modifier,
    xData: List<Int>,
    yData: List<Float>
) {
    ChartLayout(
        modifier = modifier.padding(16.dp),
    ) {
        val xAxisModel = rememberIntLinearAxisModel(1..xData.size)
        val yAxisModel = rememberFloatLinearAxisModel(0f..5f)

        XYGraph(
            xAxisModel = xAxisModel,
            yAxisModel = yAxisModel,
            yAxisLabels = { value ->
                when (value) {
                    1.0f -> "Crying"
                    2.0f -> "Sad"
                    3.0f -> "OK"
                    4.0f -> "Good"
                    5.0f -> "Happy"
                    else -> ""
                }
            }
        ) {
            VerticalBarPlot(
                xData = xData,
                yData = yData,
                barWidth = 0.6f,
                bar = {
                    val color = when (yData[it]) {
                        in 0f..1.65f -> Color(0xFFF2554A)
                        in 1.66f..3.3f -> Color(0xFFFFB31A)
                        else -> Color(0xFF8FBF41)
                    }

                    DefaultVerticalBar(
                        brush = SolidColor(color),
                        shape = RoundedCornerShape(100)
                    )
                }
            )
        }
    }
}

When you add the DailyMoodChart to the screen, you’ll notice that there is too much data. As a result, the chart becomes almost unreadable on mobile devices.

This is how we can add it to the screen:

@Composable
fun ScrollableChartScreen(onBack: () -> Unit) {
    val data = generateChartData()
    val xValues = data.map { it.dayOfMonth }
    val yValues = data.map { it.happiness }

    Scaffold(topBar = { TopAppBar(...) }) {
        DailyMoodChart(
            xData = xValues,
            yData = yValues
        )
    }
}

We created data inside the composable function for simplicity. Ideally, it should be done outside and passed as a state to the function.

Adding Scroll Functionality

We can improve the situation by zooming in on a specific part of the chart. Instead of displaying all the data, we can show data from the first day to the 15th day of each month. This way, the user can interact with the chart and scroll horizontally.

To achieve this, we can use the setViewRange function for the “X-axis”. Additionally, we need to enable the pan gesture for both the xAxisModel and XYGraph components.

@OptIn(ExperimentalKoalaPlotApi::class)
@Composable
fun DailyMoodChart(
    modifier: Modifier = Modifier,
    xData: List<Int>,
    yData: List<Float>
) {
    ChartLayout(
        modifier = modifier.padding(16.dp),
    ) {
        val xAxisModel = rememberIntLinearAxisModel(
            range = 1..xData.size,
            allowPanning = true
        ).apply { setViewRange(1..15) }
                ...
                
        XYGraph(
            ...,
            panEnabled = true
        ) {
            ...
        }
    }
}

To have a vertically scrollable chart, you can use the same approach for yAxisModel instead of xAxisModel.

Note: To add zoom functionality to the chart, update the zoomEnabled parameter of the XYGraph component. Remember to enable it for the LinearAxisModel values as well. You can also choose to enable zoom for either the X-axis or Y-axis separately by updating the allowIndependentZoom property of the XYGraph component.

You can find the source code in ScrollableChart.kt in the KotlinMultiplatformPlayground repository.

Conclusion

The “koalaplot:0.7.0” release offers a scrollable chart option for Kotlin Multiplatform projects. This means you can create a component once and use it on Android, iOS, Desktop, and Web versions of your application.

However, the current solution only works with linear axis models. It does not work for the CategoryAxisModel.

The setViewRange function lets us zoom to a specific range. When combined with the pan gesture, you can create charts that can be scrolled.

Originally published on alexzh.com.

Date and Time Formatting in Kotlin with the DateTime Library

Fri, 01 Mar 2024 00:00:00 GMT

The “kotlinx-datetime” library got an update “v0.6.0-RC” which introduces an API for locale-invariant parsing and formatting. These changes will allow for cleaning up platform-specific date and time formatting code.

In this article, we will explore options for parsing and formatting LocalDateTime, LocalDate and LocalTime types.

Several predefined formatting options exist for different date and time types. Let’s check how they format a specific date and time: March 1, 2024, at 9:15 AM, represented in code as LocalDateTime(2024, 3, 1, 9, 15, 0, 0).

LocalDateTime
- LocalDateTime.Formats.ISO formats it as 2024-03-01T09:15:00.
LocalDate
- LocalDate.Formats.ISO formats it as 2024-03-01
- LocalDate.Formats.ISO_BASIC formats it as 20240301
LocalTime
- LocalTime.Formats.ISO formats it as 09:15:00

To use the version “0.6.0-RC” of the “kotlinx-datetime” library, you need to add a dependency to your build.gradle file or update gradle/libs.versions.toml (if you use the version catalog):

implementation "org.jetbrains.kotlinx:kotlinx-datetime:0.6.0-RC.2"

Formatting

There are 2 ways of formatting date and time by using unicode pattern or by using Kotlin DSL. Let’s explore both options.

Let’s format LocalDateTime, LocalDate and LocalTime objects using different approaches.

To format different date and time types, we need to use the format(...) function.

val currentDateTime = LocalDateTime(2024, 3, 1, 9, 15, 0, 0)
val currentDate = currentDateTime.date
val currentTime = currentDateTime.time

currentDateTime.format(LocalDateTime.Format { 
    // Use Unicode Pattern or Kotlin DSL
})

currentDate.format(LocalDate.Format { 
    // Use Unicode Pattern or Kotlin DSL
})
        
currentTime.format(LocalTime.Format { 
    // Use Unicode Pattern or Kotlin DSL
})

As you can see, if we want to format LocalDate we need to use LocalDate.Format { ... } type as a parameter for the format function.

Formatting by using Unicode pattern

Let’s take a look at examples of formatting date and times using the different unicode patterns:

val currentDateTime = LocalDateTime(2024, 3, 1, 9, 15, 0, 0)
val currentDate = currentDateTime.date
val currentTime = currentDateTime.time

// 2024 03 01 - 09:15
currentDateTime.format(LocalDateTime.Format { byUnicodePattern("yyyy MM dd - HH:mm") })

// 2024/03/01
currentDate.format(LocalDate.Format { byUnicodePattern("yyyy/MM/dd") })

// 09:15 
currentTime.format(LocalTime.Format { byUnicodePattern("HH:mm") })

Formatting by using Kotlin DSL

Let’s examine formatting dates and times using Kotlin DSL:

val currentDateTime = LocalDateTime(2024, 3, 1, 9, 15, 0, 0)
val currentDate = currentDateTime.date
val currentTime = currentDateTime.time

// Mar 01 2024 - 09:15
currentDateTime.format(
    LocalDateTime.Format {
        date(
            LocalDate.Format {
                monthName(MonthNames.ENGLISH_ABBREVIATED)
                char(' ')
                dayOfMonth()
                chars(" ")
                year()
            }
        )
        chars(" - ")
        time(
            LocalTime.Format {
                hour(); char(':'); minute()
            }
        )
    }
)

// Mar 01, 2024
currentDate.format(LocalDate.Format {
    monthName(MonthNames.ENGLISH_ABBREVIATED)
    char(' ')
    dayOfMonth()
    chars(", ")
    year()
})

// 09:15
currentTime.format(LocalTime.Format {
    hour()
    char(':')
    minute()
})

The hour() function returns the hour value between 0 and 23 hours, but if you want the hour of the day in the 12-hour clock, you need to use the amPmHour() function.

When you use the Kotlin DSL approach, you can pass the padding parameters to functions like: year(), monthNumber(), dayOfMonth(), hour(), minute() and it will change the style of padding to use when formatting a value. To understand it better, let’s take a look at an example of formatting the “09:08 (AM)” time.

val time = LocalTime(hour = 9, minute = 8)

// "9:8"
time.format(LocalTime.Format { 
    hour(padding = Padding.NONE)
    char(':')
    minute(padding = Padding.NONE) 
})

// "09:08"
time.format(LocalTime.Format { 
    hour(padding = Padding.ZERO)
    char(':')
    minute(padding = Padding.ZERO) 
})

// " 9: 8"
time.format(LocalTime.Format { 
    hour(padding = Padding.SPACE)
    char(':')
    minute(padding = Padding.SPACE) 
})

Parsing

To parse a formatted date and time into LocalDateTime, LocalDate, or LocalTime, we use the parse method on the respective type.

val formattedDateTime = "2024 03 01 - 09:15"
LocalDateTime.parse(
    input = formattedDateTime,
    format = LocalDateTime.Format { byUnicodePattern("yyyy MM dd - HH:mm") }
)

val formattedDate = "2024/03/01"
LocalDate.parse(
    input = formattedDate,
    format = LocalDate.Format { byUnicodePattern("yyyy/MM/dd") }
)

val formattedTime = "09:15"
LocalTime.parse(
    input = formattedTime,
    format = LocalTime.Formats.ISO
)

Summary

The “kotlinx-datetime:v0.6.0-RC” release provides multiple options for working with date and time independently of the platforms.

Date and time can be formatted using one of the available formatting options:

unicode pattern
Kotlin DSL

Date and time types can be parsed using the parse function on an appropriate class, like LocalTime.parse and providing the format of the value.

Remember to clean up the platform-specific code for date formatting if you decided to use the new pre-release version of the “kotlinx-datetime” library.

Originally published on alexzh.com.

Jetpack Compose: Divider

Thu, 08 Feb 2024 00:00:00 GMT

Introduction

Divider is a widespread component used to separate content.

In this article, we will explore:

What is the difference between dividers in the “Material 2” and “Material 3” libraries?
How to use horizontal and vertical dividers in Jetpack Compose?
How to customize dividers from the “Material 3” library?
How to create a custom divider?

Jetpack Compose Divider

Let’s start by exploring the differences between dividers from the “Material 2” and “Material 3” libraries.

The Divider component from the “Material 2” library uses the Box container to display a divider on the screen.

Here is the source code of the Divider component from the “Material 2” library.

@Composable
fun Divider(
    modifier: Modifier = Modifier,
    color: Color = MaterialTheme.colors.onSurface.copy(alpha = DividerAlpha),
    thickness: Dp = 1.dp,
    startIndent: Dp = 0.dp
) {
    ...
    Box(
        modifier.then(indentMod)
            .fillMaxWidth()
            .height(targetThickness)
            .background(color = color)
    )
}

The HorizontalDivider and VerticalDivider components from the “Material 3” library draw a line on a Canvas.

@Composable
fun VerticalDivider(
    modifier: Modifier = Modifier,
    thickness: Dp = DividerDefaults.Thickness,
    color: Color = DividerDefaults.color,
) = Canvas(modifier.fillMaxHeight().width(thickness)) {
    drawLine(
        color = color,
        strokeWidth = thickness.toPx(),
        start = Offset(thickness.toPx() / 2, 0f),
        end = Offset(thickness.toPx() / 2, size.height),
    )
}

All the following examples will be based on the “Material 3” implementation.

Both horizontal and vertical dividers have the modifier, thickness, and color parameters. By default, they have the following values:

thickness: 1.dp
color: MaterialTheme.colorScheme.outlineVariant

Horizontal Divider

The HorizontalDivider represents a thin horizontal line that splits different elements. By default, it uses all available width.

@Composable
fun Demo_HorizontalDivider() {
    Column(
        modifier = Modifier.padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        Text("Item 1", fontSize = 18.sp)
        HorizontalDivider()
        Text("Item 2", fontSize = 18.sp)
    }
}

Vertical Divider

The VerticalDivider represents a thin vertical line that splits different elements. By default, it uses all available height, which is why we need to specify the height of the Row container. I recommend using .height(IntrinsicSize.Min) because it will properly render all children inside the Row using the minimum possible height.

The VerticalDivider doesn’t add any space before and after the divider.

@Composable
fun Demo_VerticalDivider() {
    Row(
        modifier = Modifier.padding(16.dp)
            .height(IntrinsicSize.Min)
    ) {
        Text("Item 1", fontSize = 18.sp)
        VerticalDivider(
            modifier = Modifier.padding(horizontal = 16.dp),
            thickness = 1.dp,
            color = Color.DarkGray
        )
        Text("Item 2", fontSize = 18.sp)
    }
}

Customizing the Divider

Both HorizontalDivider and VerticalDivider have relatively limited customization options, as they have only the following parameters:

modifier: Modifier
thickness: Dp
color: Color

If we want to change the size of a divider or add padding, we need to use the modifier: Modifier parameter for it.

Adjusting Divider Colors

To set a color, we need to pass it via a parameter. We can use the Jetpack Compose Color type or pass a color from the colors.xml file using colorResource(id = R.color.myColor).

@Composable
fun Demo_HorizontalDivider() {
    Column(
        modifier = Modifier.padding(16.dp),
        verticalArrangement = Arrangement.spacedBy(8.dp)
    ) {
        Text("Item 1", fontSize = 18.sp)
        HorizontalDivider(color = Color.DarkGray)
        Text("Item 2", fontSize = 18.sp)
    }
}

Changing Divider Thickness

To specify the thickness of the horizontal and vertical dividers, we need to pass the value for the thickness: Dp parameter.

@Composable
fun Demo_HorizontalDivider_thickness() {
    Column(
        modifier = Modifier.fillMaxWidth(),
        verticalArrangement = Arrangement.spacedBy(10.dp)
    ) {
        for (thicknessValue in 1..10) {
            HorizontalDivider(
                thickness = thicknessValue.dp
            )
        }
    }
}

Creating a Custom Divider

Of course, the HorizontalDivider and VerticalDivider don’t cover all use cases. To create a custom divider, we can adopt a similar approach by drawing on a canvas to suit the specific needs of our application.

Let’s imagine we want to build a file manager application and we need to create a divider component that will separate segments of the path to the file.

So, let’s create a custom divider that helps us implement a UI similar to what we see above.

@Composable
fun SegmentPathDivider(
    modifier: Modifier = Modifier,
    width: Dp = 20.dp,
    thickness: Dp = DividerDefaults.Thickness,
    color: Color = DividerDefaults.color,
) = Canvas(modifier.fillMaxHeight().width(width)) {
    ...
}

Drawing a diagonal line requires more width than a vertical line, so we need to consider the width parameter. In our case, we will draw a line between 25% and 75% of the width. (By default, the VerticalDivider doesn’t add any additional space before and after the divider.)

@Composable
fun SegmentPathDivider(
    modifier: Modifier = Modifier,
    width: Dp = 20.dp,
    thickness: Dp = DividerDefaults.Thickness,
    color: Color = DividerDefaults.color,
) = Canvas(
    modifier
        .fillMaxHeight()
        .width(width)) {
    drawLine(
        color = color,
        strokeWidth = thickness.toPx(),
        start = Offset(thickness.toPx() / 2 + width.toPx() * 0.25f, size.height),
        end = Offset(thickness.toPx() / 2 + width.toPx() * 0.75f, 0f)
    )
}

The final step is to apply the SegmentPathDivider in the user interface of our application.

@Composable
fun Demo_SegmentPathDivider() {
    val pathSegments = listOf("Projects", "Important project", "src")
    Row(
        modifier = Modifier
            .padding(16.dp)
            .height(IntrinsicSize.Min)
    ) {
        pathSegments.forEachIndexed { index, segment ->
            Text(text = segment, fontSize = 20.sp)
            if (index < pathSegments.size - 1) {
                SegmentPathDivider(color = Color.Black)
            }
        }
    }
}

Conclusion

As you can see, the HorizontalDivider and VerticalDivider from the “Material 3” library are easy to use, but they are relatively limited in customizations.

Under the hood, this is just a Canvas with a drawn line. So, we can easily create a custom divider and reuse it in many places of our application.

Originally published on alexzh.com.

Review of 2023

Thu, 04 Jan 2024 00:00:00 GMT

The first week of 2024 is an excellent opportunity to reflect on the previous year and set goals for the upcoming one. The 2023 was pretty challenging for me in multiple areas of my life, like mental state and content creation. I’d like to share a concise recap of last year and share plans for 2024 in this article.

I want to start with activities which helped me to improve my mental state:

Morning reading
Mental walks (no music & podcasts)
Journalling
No phone first 2 hours of the day

Articles

In 2023, I published 8 articles:

The alexzh.com received over 150k page views 🎉. (Last year, the yearly result was around 112k).

Android Development and Testing Tips

In 2023, I continued to post tips about Android development and testing on X (Twitter), LinkedIn and Mastodon.

Here are 3 most popular tips:

Do you want to sort your dependencies alphabetically or variables inside the class?

Here's the simple solution:
1. Select multiple lines.
2. Click "Edit/Sort Lines".
3. Enjoy the result.#AndroidDev #AndroidStudio #IntelliJIDEATips pic.twitter.com/Sa0cU2E6zP
— Alex Zhukovich (@Alex_Zhukovich) November 8, 2023

Jetpack Compose Tip:

Make use of the "ContentAlpha" object to easily access default alpha levels for Material components. It includes:
• high (text in a selected TextField)
• medium (placeholder text)
• disabled (disabled components)#AndroidDev #JetpackCompose pic.twitter.com/NfQxC0g9o4
— Alex Zhukovich (@Alex_Zhukovich) August 25, 2023

Jetpack Compose Tip:

Did you know that you can combine multiple preview annotations and use a single annotation to generate multiple previews?#JetpackCompose #AndroidDev pic.twitter.com/X04RQY37Rh
— Alex Zhukovich (@Alex_Zhukovich) August 10, 2023

Public speaking

This year I gave workshops and talks about UI testing:

Full-day Workshop: Modern Android UI Testing @ AppDevCon (slides, project)
Common Mistakes in UI Testing @ AppDevCon (slides)
4h workshop: UI Testing of Jetpack Compose Apps @ Droidcon Italy
UI Testing of Jetpack Compose Apps @ Droidcon Italy (slides)

Plans for 2024

Previous year was pretty chaotic for me and I want to make this year much more consistent. My focus for 2024 is writing and I want to deliver more high-quality content on my blog and in social media.

Here are my main goals:

Publish a book
Release 15+ articles
Publish 10 videos

Follow my X (Twitter), LinkedIn and Mastodon accounts if you want to get more content about mobile development and testing.

Originally published on alexzh.com.

Not all UI tests are the same

Fri, 17 Nov 2023 00:00:00 GMT

Introduction

Typically, when we think of UI testing, we think of simulating user behavior, such as when a user enters their email and password and clicks the login button. However, modern UI testing can do much more than just emulate user behavior.

In this article, we will explore the following topics:

Different types of UI tests
Understanding what different UI tests CAN and CANNOT verify
What to check with each type of UI tests
How to start with UI testing

All examples will be based on the “Mood Tracker” application. Let’s explore 3 screens, as all our test cases will be based on these screens.

Different types of UI tests

End-To-End tests ensure that the application works with the production environment. This means that all application layers work correctly.

UI tests with fake data verify different states of the screen (no data, successfully loaded data, network is unavailable, and much more).

Screenshot tests ensure that a component or screen looks correct in different states.

Accessibility tests check if everyone can use a user interface, including people with disabilities.

End-To-End tests

End-to-end tests verify the interaction between the UI, back-end, database, and other application layers.

Let’s explore the main characteristics of such tests:

Entry point: This is similar to the entry point of the application (we often start such tests from the splash or home screen).
Navigation: They usually navigate through several screens starting from the entry point.
Data: We use the production or staging environment (staging environment: replica or copy of the production environment) to ensure interaction verification with the production environment.

Pros	Cons
E2E tests emulate real-world user scenarios and provide a realistic assessment of how the application will behave in a production environment.	E2E tests are slow because of interaction with the real environment and a lot of navigating is required.
We make sure that our application works well with the real environment.	They can be flaky as they have multiple dependencies (network access, network speed, VPN access, etc.).
These tests effectively detect integration issues and other complex defects that are not easily detected by unit or integration testing.	It is not possible to test all cases because it is not always possible to reproduce all types of issues within the real environment.
	E2E tests update data in the prod/staging environment and can affect other tests that use the same environment.

UI tests with fake data

UI tests with fake data verify the different states of the components or screens of the application and use the fake data to simulate all cases.

Main characteristics:

Entry point: Required screen (if the UI testing framework allows us to do it)
Navigation: Depends on the goal of the test case (they use fake data):
- Screen tests (Screen component verification): No navigation needed
- Navigation tests (Navigation verification): Navigation needed
Data: Fake data

Pros	Cons
These tests are fast and stable.	These tests use fake data and we need to synchronize fake responses with responses from a real server.
We can emulate all cases.	Testing with fake data may not fully represent the complexity and variability of real-world data.

This screen displays the time and we can verify that the time is displayed in the correct time format without updating the values in the “Settings” screen. So, let’s update our scenarios.

Note

Updated test case: Verify the different screen states

Single item on the screens with 12h time format
• [Action]: Load the screen with predefined data.
• [Assertion]: Check that the emotion item is displayed on the screen (with emotion, activity, and a specific time in 12h format).

Single item on the screens with 24h time format
• [Action]: Load the screen with predefined data.
• [Assertion]: Check that the emotion item is displayed on the screen (with emotion, activity, and a specific time in 24h format).

Multiple items on the screens with 12h time format
• [Action]: Load the screen with predefined data.
• [Assertion]: Check that emotion items are displayed on the screen (with emotion, activity, and a specific time in 12h format).

Multiple items on the screens with 24h time format
• [Action]: Load the screen with predefined data
• [Assertion]: Check that emotion items are displayed on the screen (with emotion, activity, and a specific time in 24h format).

No data
• [Action]: Load the screen with predefined data.
• [Assertion]: Check that “No data” text is displayed on the screen.

Screenshot tests

End-To-End and UI tests with fake data can find many issues in the app. However, they cannot find pixel perfectness issues because they verify that data is displayed on the screen, but they don’t check that data is displayed in the right place, that views don’t overlap each other, that text doesn’t cut off, that UI elements use the right color, font size, and much more.

If we look at this image, we can find the difference even if both screens have similar data.

So, screenshot tests verify how content is rendered on the screen. We test components and screens with static data using this type of tests. When the UI is changed, the screenshots should be updated (usually it’s done with a single command).

Pros	Cons
These tests provide a visual validation of the user interface.	The maintenance of screenshot tests can be challenging, especially if the UI changes frequently.
Visual changes are easily detected in reports after test case execution.	These tests focus on the visual aspect only and will not detect any functional issues.

So, let’s choose a few basic test scenarios which can be covered for the home screen with screenshot tests:

Often you can find a situation where a UI component or screen works with the default font size, but when the font size is large, you can see some problems in the UI. In this example, when the font size is large, some of the day abbreviations contain 2 symbols instead of 3 (e.g. “Mo” instead of “Mon”).

I highly recommend checking screens with different font sizes and scales. I saw such issues in many apps.

Accessibility tests

The application may function well and have a good design, but that doesn’t make it accessible for everyone. Often accessibility has a low priority and people with disabilities do not have the best experience when using various applications. Accessibility tests verify that our application is accessible to everyone.

Here are the common issues that can be verified with accessibility tests:

Incorrect screen structure
Missing labels for UI components
Incorrect labels for complex components
Small clickable elements, such as buttons and icons

Pros	Cons
These tests make sure the app is accessible to a broader audience, including people with disabilities.	Accessibility testing often requires specialized knowledge and skills, and it may be that not all members of the team are familiar with the best practices and guidelines.

Android recommendations:

Before creating UI tests, I recommend verifying your application with the “Accessibility Scanner” app.
Recently, the “Smart UI Check Mode” feature was added to the Android Studio Iguana, and you can verify if your composable functions are accessible without running the application.

Not sure if your composable function is accessible?

The "Smart UI Check Mode" feature of Android Studio Iguana allows you to verify your composable for common accessibility issues.#JetpackCompose #AndroidDev #AndroidStudio pic.twitter.com/C2a25yFFIZ
— Alex Zhukovich (@Alex_Zhukovich) November 1, 2023

I recommend covering all custom components (components from the design system) with accessibility tests.

How to start UI testing?

As you can see, the different types of tests have their advantages and disadvantages. If your application already has had UI tests, you will see what needs to be improved or which types of tests you can introduce to your project. However, if you are new to UI testing, you may have the question, “What is a good way to introduce UI testing to the project?”.

Here are a few recommendations:

First, we should prioritize E2E testing for the most critical use cases to ensure that the features work correctly and interact smoothly with the production/staging environment. Keep in mind that E2E testing tends to be slow and flaky. So it’s a good place to start, but I recommend focusing more on other types of tests.
Next, you can start adding UI tests with fake data and Screenshot tests, as they both check components/screens in isolation, and you can check all states and errors for your screens.
To find the important screens to test, I suggest looking at the analytics. It will show you which screens and scenarios are used more than others in your application.

Conclusion

There are several types of UI tests:

End-To-End tests ensure that your application works properly with the production/staging environment, but they are slower and less reliable than other types of test.
UI tests with fake data check various states of your screens and use fake data; this makes these tests fast, but you cannot be sure that your application works well with the real environment using only this type of test.
Screenshot tests verify that all your components and screens are rendered properly and placed correctly on the screen. You can also check your screen with different configurations like color modes, font sizes, display scales, layout directions, etc.
Accessibility tests checks that everyone can use your application using gestures, voice, or special devices.

As you can see, if we want to make sure that your application works correctly, we need to check many scenarios:

Verify that your application has no problems interacting with the production environment
Check all states and errors for components and screens
Verify that everything is correctly rendered and positioned on the screen
Make sure that your application is accessible to everyone

This requires us to combine different types of UI testing.

I would like to thank Alexey Alter-Pesotskiy, Alexey Bykov, Ekaterina Basova, Evgenii Matsiuk, Jovche Mitrejchevski, and Sergio Sastre Florez for reviewing the article.

Originally published on alexzh.com.

Jetpack Compose: Pull to Refresh

Fri, 16 Jun 2023 00:00:00 GMT

Introduction

Pull to refresh is a widespread User Interface pattern that is used to refresh data on the screen. The “Material” library for the Jetpack Compose contains the “pullRefresh” modifier and the “PullRefreshIndicator” composable function.

In this article, we will explore:

How to add pull to refresh to the Android app with Jetpack Compose?
How to customize the indicator for pull to refresh?
How to trigger pull to refresh action in UI tests?

The content of this article is based on the “material” library of the “androidx.compose:compose-bom:2023.05.01”. The pullRefresh modifier and the PullRefreshIndicator composable function are still in the experimental stage.

Box(
    modifier = Modifier
        .fillMaxSize()
        .pullRefresh(pullRefreshState)
        .verticalScroll(rememberScrollState())
) { ... }

Adding the Pull to Refresh to an app

Let’s start with creating a demo application which will emulate getting data from the network. For the sake of simplicity, we will add items to the list after a small delay instead of request to the server.

The next steps is to a add dependency:

dependencies {
    ...
    implementation "androidx.compose.material:material:$material_version"
    // Needed to get a view model reference in Jetpack Compose
    implementation "androidx.lifecycle:lifecycle-viewmodel-compose:$lifecycle_version"
}

The demo application shows the list of orders. So, let’s start with adding the Order class:

data class Order(
    val title: String,
    val price: Double
)

After it, we can create an OrderViewModel which will provide the orders and the loading state.

data class OrderScreenState(
    val isLoading: Boolean = false,
    val orders: List<Order> = emptyList()
)

class OrderViewModel : ViewModel() {
    private val _state = mutableStateOf(OrderScreenState())
    val state: State<OrderScreenState> = _state

    init {
        loadOrders()
    }

    fun loadOrders() {
        viewModelScope.launch {
            _state.value = _state.value.copy(isLoading = true)
            delay(1_000L)
            _state.value = _state.value.copy(
                isLoading = false,
                orders = _state.value.orders.toMutableList().also {
                    it.add(
                        index = 0,
                        element = Order(
                            title = "Order #${it.size + 1}",
                            price = Random.nextDouble(10.0, 100.0)
                        )
                    )
                }
            )
        }
    }
}

Finally, we can add the UI of the screen.

@OptIn(ExperimentalMaterial3Api::class, ExperimentalMaterialApi::class)
@Preview
@Composable
fun OrderScreen() {
    val viewModel = viewModel<OrderViewModel>()
    val state by viewModel.state
    val pullRefreshState = rememberPullRefreshState(
        refreshing = state.isLoading,
        onRefresh = viewModel::loadOrders
    )

    Scaffold(
        topBar = { TopAppBar(title = { Text("Items") }) }
    ) { padding ->
        Box(
            modifier = Modifier
                .fillMaxSize()
                .padding(padding)
                .pullRefresh(pullRefreshState)
        ) {
            LazyColumn {
                items(state.orders) {
                    ListItem(
                        headlineContent = { Text(text = "${it.title} (€ ${"%.2f".format(it.price)})" ) },
                    )
                }
            }

            PullRefreshIndicator(
                refreshing = viewModel.state.value.isLoading,
                state = pullRefreshState,
                modifier = Modifier.align(Alignment.TopCenter),
                backgroundColor = if (viewModel.state.value.isLoading) Color.Red else Color.Green,
            )
        }
    }
}

Pull to Refresh customization

We can customize the refresh threshold, background and content color of the pull to refresh indicator.

Customizing the Pull to Refresh state

Let’s start with exploring customization options from the rememberPullRefreshState function, which creates the instance of the PullRefreshState class.

@Composable
@ExperimentalMaterialApi
fun rememberPullRefreshState(
    refreshing: Boolean,
    onRefresh: () -> Unit,
    refreshThreshold: Dp = PullRefreshDefaults.RefreshThreshold,
    refreshingOffset: Dp = PullRefreshDefaults.RefreshingOffset,
): PullRefreshState { ... }

The refreshThreshold allows us to define the minimum values which should be achieved to trigger the onRefresh function. By default, this value to set to 80.dp (val RefreshThreshold = 80.dp).

The refreshingOffset allows us to define the offset for rendering the pull to refresh indicator. By default, this value to set to 56.dp (val RefreshingOffset = 56.dp).

Customizing the Pull to Refresh indicator

We can customize the background and content colors of the pull to refresh indicator with the backgroundColor and the contentColor parameters. If we want to combine the backgroundColor (or contentColor) with the refreshing state, we can have different colors for the refreshing and non-refreshing states of the indicator.

...
PullRefreshIndicator(
    refreshing = isLoading,
    state = pullRefreshState,
    modifier = Modifier.align(Alignment.TopCenter),
    backgroundColor = if (isLoading) Color.Red else Color.Green,
)
...

Testing Pull to Refresh state

Let’s explore how to trigger update content use pull to refresh.

We will test a screen that shows “Item 1” by default, and “Item 1” and “Item 2” after a pull to refresh action.

Here is the source code of the screen:

@OptIn(ExperimentalMaterial3Api::class, ExperimentalMaterialApi::class)
@Composable
private fun DemoPullToRefresh() {
    val coroutineScope = rememberCoroutineScope()
    val listItems = remember { mutableListOf("Item 1") }
    var isRefreshing by remember { mutableStateOf(false) }
    val pullRefreshState = rememberPullRefreshState(
        refreshing = isRefreshing,
        onRefresh = {
            isRefreshing = true
            coroutineScope.launch {
                listItems.add("Item ${listItems.size + 1}")
                isRefreshing = false
            }
        }
    )
    Scaffold(
        topBar = { TopAppBar(title = { Text("Items") }) }
    ) { padding ->
        Box(
            modifier = Modifier
                .padding(padding)
                .pullRefresh(pullRefreshState)
        ) {
            LazyColumn(Modifier.fillMaxSize()) {
                items(listItems) {
                    ListItem(headlineContent = { Text(text = it) })
                }
            }

            PullRefreshIndicator(
                refreshing = isRefreshing,
                state = pullRefreshState,
                modifier = Modifier.align(Alignment.TopCenter)
            )
        }
    }
}

To trigger pull to refresh action, we need to use the .performTouchInput { swipeDown() } action on scrollable node. We can find a scrollable node on the screen using the hasScrollToIndexAction() or hasScrollToIndexAction() semantic matcher.

Let’s create a test case for the following scenario:

Initially “Item 1” is displayed and “Item 2” is not displayed
Trigger pull to refresh action
Verify that “Item 2” is displayed on the screen

@Test
fun shouldDisplaySecondItemAfterPullToRefresh() {
    composeTestRule.apply {
        setContent {
            DemoPullToRefresh()
        }

        onNodeWithText("Item 1")
            .assertIsDisplayed()

        onNodeWithText("Item 2")
            .assertDoesNotExist()

        onNode(hasScrollToIndexAction())
            .performTouchInput { swipeDown() }

        onNodeWithText("Item 2")
            .assertIsDisplayed()
    }
}

Conclusion

The “Material” library for Jetpack Compose provides the pullRefresh modifier and the PullRefreshIndicator component. They allow us to implement the pull to refresh UI patter in a screen which is built with Jetpack Compose.

When we want to trigger pull to refresh action in UI tests, we need to find a scrollable node and execute the swipeDown() action.

Originally published on alexzh.com.

Regional Preferences in Android 14

Fri, 26 May 2023 00:00:00 GMT

Introduction

The “Regional Preferences” settings screen appeared in Android 14, and it allows users to set a few regional preferences:

First Day of Week
Temperature Unit

This feature is convenient for people who are used to one temperature unit, but live in the country where another one is used. Many applications have their own preferences, and users can set temperature units, the first day of the week, and hours cycle preferences for every app.

To find the Regional Preferences setting, go to Settings > System > Languages and press the Regional Preferences menu item.

Getting Regional Preference Values

We can use the following data by using new LocalePreferences API:

The temperature units
The first day of the week
The hour cycle
The calendar type

To use the API to get this data, we need to use the androidx.core:core-ktx dependency with version 1.12.0-alpha01 or higher.

You can find information about all versions of the “androidx.core:core-ktx” dependency on the androidx.core releases page.

dependencies {
    ...
    implementation "androidx.core:core:1.12.0-rc01"
}

Getting the temperature units

The LocalePreferences.getTemperatureUnit() returns a String value which represents a selected temperature unit:

“celsius” (°C)
“fahrenhe” (°F)

We have more functions for getting the temperature units for a specific locale:

getTemperatureUnit(Locale locale)
getTemperatureUnit(Locale locale, boolean resolved)

You can also compare these values with a specific temperature unit by using constants (LocalePreferences.TemperatureUnit.FAHRENHEIT).

You can find all the constants for the TemperatureUnit class in the LocalePreferences.TemperatureUnit reference.

Getting the first day of the week

The LocalePreferences.getFirstDayOfWeek() returns a String value which represents a selected day of the week:

“sun” - Sunday
“mon” - Monday
“tue” - Tuesday
“wed” - Wednesday
“thu” - Thursday
“fri” - Friday
“sat” - Saturday

We have more functions to for getting the first day of the week for a specific locale:

getFirstDayOfWeek(Locale locale)
getFirstDayOfWeek(Locale locale, boolean resolved)

You can also compare these values with a specific day of the week by using constants (LocalePreferences.FirstDayOfWeek.MONDAY).

You can find all the constants for the FirstDayOfWeek class in the LocalePreferences.FirstDayOfWeek reference.

Getting the hour cycle

The LocalePreferences.getHourCycle() returns a String value which represents the hour cycle for the current Locale. It returns the following values:

“h11” - 12 Hour System (0-11)
“h12” - 12 Hour System (1-12)
“h23” - 24 Hour System (0-23)
“h24” - 24 Hour System (1-24)

We have more functions to for getting the hour cycle for a specific locale:

getHourCycle(Locale locale)
getHourCycle(Locale locale, boolean resolved)

You can also compare these values with a specific hour cycle by using constants (LocalePreferences.HourCycle.H24).

You can find all the constants for the HourCycle class in the LocalePreferences.HourCycle reference.

Getting the calendar type

The LocalePreferences.getCalendarType() returns a String value which represents the calendar type for the current locale. It returns the following values:

“chinese” - Chinese Calendar
“dangi” - Dangi Calendar (Korea Calendar)
“gregorian” - Gregorian Calendar
“hebrew” - Hebrew Calendar
“indian” - Indian National Calendar
“islamic” - Islamic Calendar
“islamic-civil” - Islamic Calendar (tabular, civil epoch)
“islamic-rgsa” - Islamic Calendar (Saudi Arabia, sighting)
“islamic-tbla” - Islamic Calendar (tabular, astronomical epoch)
“islamic-umalqura” - Islamic Calendar (Umm al-Qura)
“persian” - Persian Calendar

We have more functions for getting the calendar type for a specific locale:

getCalendarType(Locale locale)
getCalendarType(Locale locale, boolean resolved)

You can also compare these values with a specific calendar type by using constants (LocalePreferences.CalendarType.CHINESE).

You can find all the constants for the CalendarType class in the LocalePreferences.CalendarType reference.

Example and Use Cases

One of the simplest ways to compare values between different locales is to create a BroadcastReceiver which logs new values for a selected locale after changing it in the Settings > System > Languages > System Languages screen.

class LocaleReceiver : BroadcastReceiver() {
    
    @RequiresApi(Build.VERSION_CODES.TIRAMISU)
    override fun onReceive(context: Context, intent: Intent) {
        val localePreferenceData = """
            getTemperatureUnit: ${LocalePreferences.getTemperatureUnit()}
            getFirstDayOfWeek: ${LocalePreferences.getFirstDayOfWeek()}
            getHourCycle: ${LocalePreferences.getHourCycle()}
            getCalendarType: ${LocalePreferences.getCalendarType()}
        """.trimIndent()

        Log.d("New locale prefs values", localePreferenceData)
    }
}

The next step is to register the LocaleReceiver receiver in the AndroidManifest.xml file:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
  ...
    <application
    ...>
    <receiver
        android:name=".LocaleReceiver"
        android:enabled="true"
        android:exported="true">
        <intent-filter>
        <action android:name="android.intent.action.LOCALE_CHANGED" />
        </intent-filter>
    </receiver>
        ...
    </application>
</manifest>

Let’s compare values for the “English (United States)” and “English (Netherlands)” locales.

Preference	English (United States)	English (Netherlands)
Temperature Unit	fahrenhe	celsius
First Day of Week	sun	mon
Hour Cycle	h12	h23
Calendar Type	gregorian	gregorian

Let’s take a look at a few use cases when this data can be helpful.

Temperature Unit

Many applications show weather data and they usually have their own settings for selecting preferred temperature units. Default data for this screen can be based on the values from the “Regional Preferences” screen.

The date in the application can be converted to a specific temperature unit based on user preferences from the “Regional Preferences” screen.

First Day of Week

The “DatePicker” component is used in many applications for selecting the date and we can decide if we want to start the week in this component from Saturday or Monday. When we get information about the first day of the week, we can make a better experience for the user.

Hour Cycle

You can find time in many applications. Usually, we see a specific time when a user creates a note, pays for a product, or checks information about delivery time. All data can have benefits from using the hour cycle preference and time will be formatted according to user preferences.

Conclusion

The “Regional Preferences” settings screens appeared in Android 14 and developers can start using API to get temperature units and the first day of the week.

We can get user preferences for temperature units and first day of week using the following functions:

LocalePreferences.getTemperatureUnit()
LocalePreferences.getFirstDayOfWeek()

In addition to that, we can get information about hour cycle and calendar type from the current locale:

LocalePreferences.getHourCycle()
LocalePreferences.getCalendarType()

I have doubts that this API will be widely used in the nearest future because many apps already have their own built-in implementation of configuring these properties in app settings and it works with all Android OS versions. However, I think that this API will be used in the future.

Originally published on alexzh.com.

Get access to string resources in UiAutomator

Fri, 24 Mar 2023 00:00:00 GMT

String resources provide multiple benefits, such as localization and accessibility support, dynamic string formatting and maintenance of the application.

When we create UI test cases, we often want to reuse strings from the app to avoid issues when a test device has different locale than the default language of the application. Unfortunately, the “UiAutomator” doesn’t allow us to get strings using the generated R class.

There are a few popular cases of using the UiAutomator framework:

We cannot verify both cases with the Espresso based framework because notifications and permission dialog are part of the OS (Operating System), not part of the application. However, when we test notifications, we use string values from resources and we want to reuse string resources to avoid failure when we update the string resource value.

Let’s take a look at part of the test cases that interact with a notification:

val expectedText = TestData.getCityById(amsterdamId).description
...

uiDevice.openNotification()
uiDevice.wait(Until.hasObject(By.text("DemoApp")), TIMEOUT)
uiDevice.findObject(By.text(expectedText))
    .click()
...

The major problem in this example is the hard-coded string. Let’s explore how we can use string resources with the UiAutomator framework.

The first option is to use the By.res(PACKAGE, RESOURCE_ID) function. Here, we need to pass package and resource ID as strings and we can easily make a typo.

Let’s explore how to get a value from a string resources by using the R class, like R.string.app_name. To get a value from the string resource, we need to have application context, which we can get from the InstrumentationRegistry.

InstrumentationRegistry.getInstrumentation().targetContext

The next step is to create a function that returns a string value from resource id.

private fun stringResource(
    @StringRes resId: Int,
    context: Context = InstrumentationRegistry.getInstrumentation().targetContext
): String {
    return context.getString(resId)
}

Now, we can use string resources in our test case:

val expectedText = TestData.getCityById(amsterdamId).description
...

uiDevice.openNotification()
uiDevice.wait(Until.hasObject(By.text(stringResource(R.string.app_name))), TIMEOUT)
uiDevice.findObject(By.textStartsWith(expectedText))
        .click()
...

When we use string resources (R.string.*) in our test case, we have a single point of truth for our strings. In addition to that, we will have a compilation error if we will update the name of the string resource. It helps us to find and fix an error faster.

Originally published on alexzh.com.