In this post, I would like to share the two things I learned while building this app:

Open-source doesn’t mean “do whatever you want”

The fact that software is open-sourced doesn’t mean you can do absolutely everything you want with it. Each open-source software is released under a specific license that describes how the software can be used, modified, and shared.

For example, the yt-dlp program is released under the “Unlicense license”. It’s a public domain equivalent license, which allows you to use, modify, distribute, or even sell the software without asking for permission or giving credit. This license would allow me to include yt-dlp as part of my own, paid app without any issues.

However, yt-dlp has several dependencies. All of them are optional, but two are highly recommended - ffmpeg and ffprobe, without which my app doesn’t work. They are used for merging video and audio files, converting between formats, as well as for various post-processing tasks. Most of their codebases are released under the “LGPL v2.1+” license. The license states that any “derivative” work must be distributed under the same or equivalent license terms. This effectively means that if I were to bundle ffmpeg and ffprobe executables within my app, I would have to make the app open-source as well and provide it under the same license.

Since open-sourcing the app wasn’t my intention, I had to find a different solution, and that solution would have to be aligned with the target audience for the app - potentially non-tech-savvy users. I wanted people to be able to download my app and start using it immediately without having to worry about downloading all of the necessary tools mentioned above manually. And how was I supposed to do that if I can’t include them as part of my app because of the license restrictions?

The exploration related to this question brought me to my second finding:

macOS allows apps to download and execute arbitrary executables

Firstly, let’s see what happens from the user’s perspective when they download an executable using their browser and try to run it.

On my machine (running macOS Sonoma), this is what I got after I downloaded FFmpeg, unzipped it, and either opened it by double-clicking or typed ./ffmpeg in my terminal:

The reason for this alert is the Gatekeeper mechanism. By default, it verifies that any software you intend to run for the first time is from an identified developer, is notarised by Apple to be free of known malicious content (since macOS Catalina), and hasn’t been altered.

In this case, the ffmpeg binary isn’t signed by a certified Apple Developer hence the warning that “the developer cannot be verified”. One way to work around this is to open System Settings, go to the “Privacy & Security” tab, and click on “Allow Anyway” in the section mentioning ffmpeg:

Then we can run the program again and confirm the will to open:

As you can see, a lot of steps are required - downloading the archive, unzipping it, running the executable, clicking “Allow Anyway” in the settings, running again, and finally, confirming. Given that my app requires three external dependencies, which can’t be bundled because of the license restrictions, the above steps would have to be performed three times, manually.

I considered preparing a detailed instruction for a manual installation of all of these tools for my users, but that would be way too much to ask from them, especially given that the app is paid. It should run out of the box, without any additional work.

This almost led me to abandon the app altogether, but then I realized that none of the above steps are necessary when downloading an executable using a non-browser tool, like curl or a simple Python script.

Why is that?

Firstly, it turns out that what triggers all of the Gatekeeper checks is the com.apple.quarantine extended attribute that is attached to all downloaded files.

If we run the xattr program (that’s used to work with extended attributes) on the downloaded ffmpeg executable, we can see that indeed, this attribute is present:

Secondly, Gatekeeper will only verify applications that have the quarantine flag. The problem is that this flag is added by other applications, not by the operating system itself. It’s the responsibility of app developers to make sure that this flag is added to any files downloaded by the app.

Apps like web browsers or email clients properly attach the quarantine flag to all downloaded files, but many don’t, like most BitTorrent client software. The flag is also not added if the app came from a different source, like network shares or USB drives.

To illustrate this, let’s download ffmpeg again, this time using curl. Then, when we unzip it and run xattr on the executable, we can see that there is no quarantine flag attached. Also, running doesn’t trigger any OS alerts:

We bypassed all Gatekeeper checks by simply using a program that doesn’t attach the quarantine flag (that’s one of the reasons why this mechanism received some criticism).

I used the exact same “trick” in my app. Instead of bundling yt-dlp, ffmpeg, and ffprobe within my app, which would violate their licenses, or requiring users to download them manually, I simply download the dependencies upon the first app launch and store them outside of the app in the user’s home directory, without disrespecting the licenses.

Problem solved!

One final, but very important, thing to note is that the above little experiment proves that it’s always crucial to make sure that we only open apps we trust. On the surface, the Gatekeeper mechanism sounds great and you would think it fully protects your computer against running potentially malicious executables, but, as we’ve seen, that’s unfortunately not always the case.

Let’s leave the discussion about whether that’s true aside for a moment. However, it’s worth noting that the “typing speed doesn’t matter” argument is often brought up by people who can’t type quickly. Have you ever met a fast typer who wished they hadn’t learned to type quickly because the speed was getting in their way? Similarly, it’s usually people who are happily clicking around with their mouse, repeating the same actions over and over again, day after day, who claim that learning and configuring keyboard shortcuts of the editor you’re using is a waste of time.

Not long ago, I was one of those people. Only after learning how to touch type have I noticed how effortless typing could be when you don’t have to look at the keyboard all the time and can leverage all 10 of your fingers during the process. Likewise, I started to strongly appreciate the value of having keyboard shortcuts ingrained in my muscle memory and not needing to reach for my mouse as frequently as I used to.

Two weeks ago, I finished my second marathon. At first glance, running and programming don’t have much in common. However, it was this race that has reinforced my conviction that optimizing your workflow does matter in the long run.

The race

Even though my fitness level was similar and my training plan almost identical, I managed to finish the race 10 minutes faster than my first marathon last year. It was focusing on the seemingly irrelevant details and having a much smarter strategy for the race that allowed me to arrive at the finish line earlier, feeling much better than last time.

During most officially organized races, you will encounter several aid stations. These are designated areas for runners to hydrate and refuel, usually positioned every few kilometers. At these stations, volunteers hold out cups of water to the runners so that they can grab them while still running.

Have you ever tried running and drinking from a cup simultaneously? When I first did that, I spilled almost all of it onto my face and nearly choked with little of what remained. There is always an option to stop for a moment and drink, but stopping is always risky because it might be challenging to force yourself to start running again.

It turns out that such a seemingly insignificant thing as the right technique for grabbing a cup of water can have a considerable impact on the final time. It’s enough to squeeze the top of the cup, leaving a small hole to drink from, which allows you to take frequent, small sips like this:

You might think it doesn’t make a huge difference, but remember that a marathon is a long distance. You are likely to pass at least 8-12 of those stations throughout the race. Without a proper technique for drinking, you’ll interrupt your breathing rhythm and lose much-needed focus, leaving the station frustrated and discouraged every time, all of which can contribute to a couple of additional minutes to your final time or a lack of satisfaction after finishing the race.

Back to programming

This experience made me realize how beneficial it might be for us programmers to make our tools as efficient as possible, especially when we think about programming as a lifelong career or hobby.

That keyboard shortcut for a frequently used action we’ve been diligently refining over the last weeks might seem silly to other people. Still, this very shortcut, which is now ingrained in our muscle memory, saves us from costly context switching, losing focus, reaching for our mouse, or simply wasting time. Having a bespoke workflow allows us to think purely in terms of “what” we want to do, not “what and how”.

Everyday tasks like switching between apps, running tests for our project, jumping to a specific file in the editor, or renaming a variable are performed by us dozens of times per day, so why would anyone argue that making sure these things are easily and quickly accessible is a waste of time?

Part of the reason might be that the gains are not clearly noticeable, as they are in running, for instance. When you introduce some changes, like the technique mentioned above for grabbing a cup of water or a carbon-plated pair of shoes, you can quickly tell whether it worked by simply checking your finish time. It’s more complex with programming because there is no obvious metric we can compare - it’s mostly subjective.

Therefore, drawing an analogy from other disciplines where the results are more tangible can help us visualize the importance of removing the minor pain points we encounter multiple times per day, specifically when we think about programming as a marathon, not a short park run.

The joy aspect

Another benefit of having a personal, customized environment that makes repetitive tasks easy and fun is that you will derive satisfaction from using it.

For example, when you have a keyboard that gives you joy with every keystroke, you’re more likely to come back to programming repeatedly and consistently because just the idea of being able to type on that keyboard again might be enough to motivate you to keep working on your side projects.

Similarly, having a script that puts a smile on your face every time it’s executed, potentially saving you seconds or even minutes of manual labor, is well worth it. All of this contributes to an overall joyful experience.

In contrast, having tools that work against you rather than with you might cause resentfulness to the mere idea of having to program again. A keyboard that causes pain in your wrists will make you come up with excuses to avoid typing as much as possible, and you might find yourself writing less helpful code review comments, shorter and ambiguous documentation, or confusing messages to your colleagues.

After all, wouldn’t it be a good idea to allow the mind to focus on abstract and complex problems, which supposedly are the bottleneck, instead of thinking about the distracting little details that can get in the way?

I hope you found this post useful. If you have some questions or thoughts, leave a comment here or reach out to me on X.

Very often, I know which command line tool would come in handy for a given task at hand, but I can’t recall the exact syntax I should use or the options that are available to me.

Looking into the documentation is definitely an option, but they sometimes lack practical examples. Also, usually, I’m already familiar with this tool, but I just need a quick refresher.

The solution

Meet cheat.sh. An open-source tool that gives you access to community-driven cheatsheets for programming languages, DBMSes, and command line tools through a simple interface.

Want a quick overview of the tar utility? Just type this in your terminal, no installation required:

curl cht.sh/tar

You’ll get answers from multiple cheatsheets repositories at the same time. The screenshot below shows the part of the response that comes from the https://tldr.sh/ website:

It also works for programming languages. For example, to learn about list comprehension in Python, you could use this:

curl cht.sh/python/list_comprehension

To get a list of topics available for a given language, execute curl cht.sh/python/:list. Additionally, most languages have a special :learn page that describes the basics to get you started quickly.

Command line client

If you don’t want to constantly type the curl command to access the cheatsheets, you can install the command line client according to the instructions on the GitHub page. There is also an option to activate tab completion support.

I did all of the above and created a custom bash function called c that executes the script and also pipes the result to the less program for convenience (the "$@" part refers to arguments passed to the function).

function c() {
    $HOME/.dotfiles/shell/scripts/cht.sh "$@" | less
}

After doing that, I can start typing c ff and instantly get suggestions matching the query:

If you’re interested, here’s a commit in my dotfiles repository where I added this tool (notice the #compdef c line at the top of the _cth file that was necessary to get tab completion for my custom function).

The GitHub Code Search tool was launched as a technical preview in December 2021. Almost 1.5 years later, in May 2023, it was made generally available to all GitHub users.

Fortunately, I was one of the developers who got access to the early versions of the new search engine. Months of exploration and largely positive experience led me to include this tool as an essential part of my daily workflow.

In this post, I will explain what makes this tool great not merely for searching code, but also for exploration and learning.

Overview of GitHub Code Search

You can access the new search tool by clicking on the search bar at the top of the GitHub website, by pressing the / character, or by going straight to https://github.com/search.

The documentation for code search syntax can be found under this link, but here’s a quick overview of what you can do:

• Searching for index will return files containing the term “index” in their content or path. So it would return both public/index.php, even if it doesn’t contain the term “index”, and public/sitemap.xml, if it does.
• Search supports boolean expressions. You can use AND, OR, and NOT operators. For example, the bitmap OR index query will return files containing the term “bitmap” or “index”, in any order. The bitmap index query uses an explicit AND operator, so it’s equivalent to bitmap AND index. Parenthesis can be used to compose more complex expressions, like bitmap AND (index OR header).
• To search for an exact string, including whitespace, you can surround the query with double quotes. If your query contains quotation marks, you can escape them with a backslash. For instance, to search for the "license": "MIT" string, we could use the "\"license\": \"MIT\"" query.
• It’s possible to use regular expressions. You can do that by surrounding the expression with slashes. For example, to search for Polish postal codes, we could use the /\d{2}-\d{3}/ query.
• You can narrow your search using special qualifiers, like org:github, user:ClouddJR, language:ruby, path:*.txt (notice the path: qualifier supports glob expressions), or symbol:HelloController. You can see the full list of available qualifiers with an explanation here.

Results for code search are always restricted to 100 results (5 pages). At the time of writing this post, sorting is not supported, although some heuristics are used to prioritize more meaningful results. In most cases, you can expect results from popular repositories to appear first.

There are other limitations worth keeping in mind, like the fact that large repositories might not be indexed at all. The same applies to long lines (over 1024 characters) and files (over 350 KiB). Here you can find a list of all current limitations.

Saved searches

If you find yourself typing the same query over and over again, you might want to use the mechanism for saving searches.

To do that, type saved: in the search bar and click on “Manage saved searches”. You can add your query there, which will be visible in the “Saved queries” section when you later access the search bar.

Advanced search page

This post focuses specifically on GitHub Code Search. If you want to search for non-code content, like issues, you can go to the advanced search page. This page provides a visual interface for constructing search queries so that you don’t have to remember all the available options.

However, if you prefer to type your queries manually, here’s a documentation for qualifiers that can be used when searching for non-code content.

Remember that you can use the same search bar for both code and non-code searches, although the syntax might differ.

Examples

After using the new code search for some time, I found myself using some features more frequently than others. This section will show you the most popular use cases for this tool in my workflow.

Learning a new API

When learning something new, it makes sense to see some practical examples. They can often be found in the official documentation, but that is not always the case.

Using the search engine, you can find real-life examples of the technology you’re exploring. For example, let’s say you’re learning SwiftUI and would like to see some examples of how to use the NavigationStack in practice.

You can do that with this simple query: "NavigationStack {" language:Swift.

This approach has another benefit. While searching for the code you need, you might find some interesting repositories you were unaware of.

Searching for options

Recently, I tried to extend the size of my shell’s history. I knew the options I had to modify in my .zshrc file, but I didn’t know what values are used for these options in practice.

A quick search across the GitHub repositories with the HISTFILESIZE language:Shell query showed me what values are common in many dotfiles repositories.

Inspiration for key bindings

If you want to find out how people configure their tools, like editors, using the search engine can be a great option.

For instance, to see what keymaps people use for finding files using Telescope in Neovim, you could search for builtin.find_files language:Lua.

README files

Writing good documentation is hard. Therefore, when doing this ourselves, it might make sense to get some inspiration by reading some well-written README files available on GitHub.

By using the path:/(^|\/)README\.md$/ query, we can find some README.md files from popular repositories. But obviously, the popularity of a repository doesn’t always have to correlate to the quality of its README file.

Definition of a class

The symbol: qualifier is one of the most useful ones. You could use it to find the definition of a specific class (or any other symbol, like a function) when you don’t know the repository the class is in. The query could look like this: symbol:HelloController org:github language:Ruby.

This way of searching is especially handy when your company uses a microservices architecture and the code is distributed across hundreds (or thousands) of repositories.

You can check out this link for a list of supported languages for symbol searching.

Sensitive information

Unfortunately, with the power of the new search tool, it’s now almost effortless to find repositories that contain sensitive information (like API keys for Firebase, etc.)

The "\"current_key\": " path:google-services.json query reveals a lot of unprotected repositories.

Note that even though the google-services.json file itself is considered safe to share with other people, it may contain additional information about your resources, like your database URL. If your security rules are not configured properly, an attacker could use that against you.

However, we could use this capability to find repositories in our organization that expose sensitive information and address these vulnerabilities immediately.

Additional resources

I hope you found this post useful. If you have some questions, leave a comment here or reach out to me on Twitter.

If you’d like to learn more about the technology behind the new search tool, here are some additional resources I recommend:

• https://github.blog/2023-02-06-the-technology-behind-githubs-new-code-search/ - a high-level overview of the design and architecture of the new code search.
• https://github.blog/2021-12-15-a-brief-history-of-code-search-at-github/ - a brief history of previous attempts at building a search engine suitable for GitHub’s scale and an explanation of why building from scratch was necessary despite existing open-source solutions.

As a developer, I’m always interested in different ways to improve my workflow, especially when it comes to tasks I perform frequently every single day. Switching between apps is one of those things.

I was looking for an option that would allow me to switch between apps as smoothly as possible without thinking too much about it or having to reach for my mouse.

Why weren’t existing options enough?

Using the dock

This option requires a mouse, which disqualifies it completely. Additionally, it only lets you switch between already running apps. You can’t launch an app unless you have it pinned in the dock.

CMD + Tab

This technique works fine when switching between the two most recently used apps. However, if you regularly access more than two apps, you will often find yourself examining the CMD + Tab menu looking for the app you want to switch to.

Additionally, as with the previous option, you can only switch between already running apps. Launching is not possible.

Searching with Spotlight (or alternatives)

These tools are great for launching apps but not so great for quick switching. Not only do you have to use a shortcut to trigger the search bar first (usually CMD + space), but also type at least a couple of characters to find the app you’re looking for.

Stage Manager

This feature has been introduced in macOS Ventura. Although it seems really useful at first glance, it’s still mainly a mouse/trackpad-oriented feature.

Solution: custom shortcuts

The technique that proved to be the most effective one for me was assigning a custom keyboard shortcut for every app I use frequently.

To do that, I first remapped the right command to act as the so-called hyper key (using Karabiner). This means that when I press the right command, it acts as if the CTRL+SHIFT+CMD+OPT modifiers were pressed simultaneously. This combination is pretty much guaranteed not to conflict with anything else on your computer. What kind of app would define a shortcut involving all four modifiers anyway?

Next, I defined shortcuts for some of my apps using the hyper key. I did that in the Raycast app. It was the easiest option for me because I have already been using it as a Spotlight alternative anyway. However, if you don’t use Raycast, any other tool would work just fine for that purpose, like BetterTouchTool.

After these changes, I am always a single keyboard shortcut away from apps I commonly use. This is what my workflow looks like in practice:

This approach has another benefit of being able to launch the app if it wasn’t running already and also switch focus to another monitor or space if the app is somewhere else at the time of pressing the shortcut.

Switching between spaces

Besides assigning shortcuts for apps, I assigned shortcuts for spaces. In practice, I use them less often, but they can be valuable in some situations, like when I have multiple apps’ windows arranged in a certain way in various spaces and want to switch between them quickly.

You can do that in the system settings without installing any third-party app by going to Keyboard -> Keyboard Shortcuts -> Mission Control (make sure first to open some spaces because these options won’t be visible otherwise):

I was slightly annoyed by the default transition animation when switching between spaces. Luckily, it can be minimized by turning on the Reduce motion option in the system settings (under Accessibility -> Display). Keep in mind that it won’t get rid of that animation completely. There are ways to turn it off completely, but they all require disabling the System Integrity Protection, which I’m not interested in doing (especially on a work laptop).

Summary

I hope you found this post useful. If you have some ideas about how this workflow could be improved even further, let me know here in the comments section or reach out to me on Twitter.

In this post, I will discuss potential reasons behind this behavior, offer some strategies to overcome it and talk about other serious problems that it may lead to.

Before I continue, let’s make one thing clear. By no means am I saying that there is something wrong with trying to master your tools or attempting to adjust them to suit your specific needs. It’s actually the opposite. I think it’s a great investment of your time that will make you a more efficient and productive developer in the end.

However, it’s important to recognize when constant configuration becomes an obsession and a meaningless search for perfection that’s impossible to achieve anyway. It’s time to learn to accept the “good enough” and move on to more meaningful things that will truly bring you closer to your goals.

People are obsessed with configs

If you were to go on YouTube right now and find any video related to programming, I bet some of the top comments would be one of the following:

• What’s the editor/terminal that you use?
• What’s the name of that color scheme and font in your editor?
• Do you have a link to your dotfiles repository?

Very often, it seems that people completely ignore the content of the video and simply come to the comments section to ask these questions. Why is that? Why are people so obsessed with these seemingly irrelevant details?

One potential reason is that spending time configuring the environment makes people feel productive and can provide a sense of achievement. Yes, you aren’t working on what you should be working on, but at least you are spending time with the tools you normally work with, so you don’t feel guilty. However, the harsh reality is that it’s simply a way of procrastination. It’s trickier to spot because it’s not as obvious as watching TV or playing video games, but the end result is the same - no work is being done.

Another reason is much more profound. In his excellent TED talk, called “The paradox of choice”, Barry Schwartz argues that all of the choice we have in today’s world produces paralysis rather than liberation. With so many options to choose from, people find it very difficult to choose at all. He gave an example of a study on investments in voluntary retirement plans. What was found was that for every 10 mutual funds the employer offered, the rate of participation went down 2%. You offer 50 funds, 10% fewer people participate than if you only offer 5. Why? Because with 50 different options, it’s so damn hard to decide which fund to choose that eventually, people end up not choosing at all.

We can clearly see this phenomenon at play with highly customizable editors like Neovim, where the customization options are almost endless. There are so many plugins to install, so many options to explore and so many color schemes and fonts to choose, that people feel paralyzed and simply look for someone else to make that decision for them. This perfectly explains the flood of questions we see everywhere about other people’s setups.

Another thing is that even if we manage to overcome the paralysis and finally make a choice, the fact that we had so many options to choose from makes us less satisfied with our choice than if we only had a handful of alternatives. Why? Because it’s easy to imagine that we could’ve made a different choice that would’ve been better. That imagination causes us to question the correctness of our choice. If you only had one option instead, there would be absolutely no overthinking, because there was no other choice anyway.

Once again, we can transfer that observation to our domain. The fact that we have so many customization options for our work environment makes some of us feel that what we have right now is not enough, and there awaits a perfect keymap or color scheme right around the corner that will make our setup perfect. It’s easy to imagine that if we just had a different terminal setup or a different IDE, we would become much better programmers.

Accept the good enough

Now that we know some potential reasons as to why people spend so much time on configuration, let’s talk about what we can do about it.

The first and most important step is realizing that the perfect setup doesn’t exist and will never be achieved. That realization in itself might be very liberating and free us from perfectionism, which is the enemy of progress.

As an example, learning to accept the “good enough” allowed me to setup this blog from scratch one year ago in a single evening. I used a free theme created by someone else. It was far from perfect and there were things I didn’t like. Also, I didn’t have a comments section or any other way for people to engage with my content. But I was completely fine with that since my goal was to start writing and not tinker with yet another configuration, so I resisted that urge.

However, if that little mindset shift is not enough for you, it might make sense to introduce some small rules for yourself. I suggest following ThePrimeagen’s advice on approaching your configuration. He recommends revisiting your configuration only once every couple of months, which I think is a very healthy and sustainable approach. In the meantime, take a mental note of the things that are annoying or slowing you down so that you can address them when the time to overhaul comes.

On the other hand, if your goal is to start with an editor like Neovim, don’t bother initially trying to setup everything on your own. Just copy a config from someone you follow that uses Neovim or start with this really cool project called kickstart.nvim. That will allow you to start using the editor as soon as possible so that you can see whether it’s something for you or not. And then, after some time, you will know which things need to be adjusted.

Stay away if you’re a beginner

I would argue that the consequences of perfectionism can be more severe if you’re just starting out in programming. If that’s the case, stay away from all of that for as long as possible. Your goal is to learn programming, so focus on that. Learn the fundamentals first. The time to learn and configure tools will come eventually, but this is definitely not the right time yet. If you try to do everything at once, you will be frustrated and overwhelmed. That may ultimately cause you to give up programming entirely.

The urge might be really strong because being able to engage in online discussions about editors, IDEs, and terminal setups (or understand memes) can give you a sense of belonging to the programmer’s community. But please, don’t let these shiny things distract you from your real goal, which is learning how to program.

It’s not just about configs

Honestly, it would be great if all of this was only about tinkering with our configuration. At the end of the day, who cares that some of us might spend a couple of hours every single day searching for the perfect color scheme for our Neovim setup?

Unfortunately, the problem with striving for perfectionism is that it can also manifest itself in other, much more significant, aspects of our lives. For instance, not realizing that “perfect” doesn’t exist can make you feel dissatisfied with your current partner, the place where you live, or the job you have. This could also mean that you may end up waiting for the perfect moment in your life to start chasing your goals, which will obviously never come.

If the arguments presented in previous sections weren’t convincing enough, let this motivate you to fix your obsession with configuration because, as you can see, your overall well-being is at stake.

Summary

I hope you found this post useful. I wrote it as much for you as for myself - to constantly remind myself that striking a balance between spending time on customization and actual coding is essential. And again, as I mentioned multiple times throughout this post, remember that it’s not merely about our configs in the end.

Recently, when working on an iOS app, I had to adjust the UI to work correctly with increased font size.

I had a UIStackView with its children laid horizontally - a UILabel and a UIButton. This is what the UI looked like:

And this is the code representing the stack and its elements:

private lazy var stackView: UIStackView = {
    let stackView = UIStackView()
    stackView.spacing = 16.0
    stackView.distribution = .equalSpacing
    stackView.translatesAutoresizingMaskIntoConstraints = false
    return stackView
}()

private lazy var label: UILabel = {
    let label = UILabel()
    label.text = "Lorem ipsum dolor"
    label.font = UIFont.preferredFont(forTextStyle: .body)
    label.adjustsFontForContentSizeCategory = true
    return label
}()

private lazy var button: UIButton = {
    let button = UIButton(type: .system)
    button.setTitle("Action", for: .normal)
    button.titleLabel?.font = UIFont.preferredFont(forTextStyle: .body)
    button.titleLabel?.adjustsFontForContentSizeCategory = true
    return button
}()

Right now, as we can see above, everything looks just fine. Both the label and button are fully visible. The problem appears when the user increases the font size in the system settings. We can easily emulate that using the simulator and the ⌥ ⌘ + shortcut while the app is launched:

When both elements don’t fit horizontally, they are compressed more and more as we further increase the font size. Ultimately, the button’s title disappears entirely, and we only see the three dots. Far from a good user experience, right?

Ideally, we would like to display the elements vertically when they no longer fit horizontally. Luckily, changing the axis of a UIStackView is trivial. It’s enough to modify a single property (stackView.axis = .vertical).

But the challenge, however, is to trigger that change only when we detect that the label and button can’t fit our screen horizontally without being compressed. Otherwise, we still want them to remain in the same configuration if there’s enough space. Let’s see how we can do that.

Solution

The UIView contains a function we can override to solve our problem - layoutSubviews. The documentation says that

Subclasses can override this method as needed to perform more precise layout of their subviews.

In our case, a more precise layout is exactly what we need.

Generally, this function is called on a view every time layout changes occur. It includes situations like modifying the view’s bounds, changing the interface orientation, calling setNeedsLayout or layoutIfNeeded on a view, etc.

This also implies that layoutSubviews is going to be called when the user increases the font size, which is exactly what we want.

Here’s the code that we can put inside the layoutSubviews of our stack view’s parent to solve our problem:

override func layoutSubviews() {
    super.layoutSubviews()
    
    let maxWidth = bounds.width
    let labelWidth = label.sizeThatFits(frame.size).width
    let buttonWidth = button.sizeThatFits(frame.size).width
    let spacing = stackView.spacing

    let isHorizontal = maxWidth > labelWidth + buttonWidth + spacing

    stackView.axis = isHorizontal ? .horizontal : .vertical
    stackView.alignment = isHorizontal ? .firstBaseline : .leading
    stackView.invalidateIntrinsicContentSize()
}

At first glance, the code might look complicated, so let’s break it down.

Firstly, we determine whether the stack view should be horizontal or not. We do this by summing the widths of the label and button with the stack view’s spacing.

If that sum is less than or equal to the width of the stack view’s parent, it’s safe to make the stack view horizontal because the elements would fit appropriately without being compressed. In other cases, the stack view should be vertical.

We use sizeThatFits to calculate the size of a view. The documentation mentions that this method “asks the view to calculate and return the size that best fits the specified size”. In this case, we are passing the frame size of the stack view’s parent.

Additionally, we adjust the alignment so that in vertical mode, the elements are aligned to the leading edge of the screen and by first baseline in horizontal mode. Lastly, we call the invalidateIntrinsicContentSize to announce that the intrinsic size of our stack view has changed.

With those changes, we achieved the desired result:

Initially, the elements are laid horizontally, same as before. Only when they would no longer fit entirely are they wrapped and displayed vertically.

Summary

I hope the solution presented here will make it easier for you to make your app more accessible, which I believe is crucial. If you’re interested, here’s a link to the entire source code of the application presented in this post.

In this post, I’ll show you how to setup comments on your static blog with a tool called utterances. It’s a lightweight, free, and open-source comments widget built on GitHub issues.

You can see what this tool looks like by scrolling to the bottom of the page where the comments section is.

The idea is simple. Every post on your blog will have a dedicated issue on your chosen GitHub repository. Then, every comment on your post will essentially become a comment on that issue. As a result, you won’t need dedicated storage for these comments. Everything will be stored in your repository.

The only downside is that this way of adding comments requires users to have a GitHub account. If you have a technical blog or a website, that shouldn’t be a problem since the majority of your audience is familiar with this tool. However, if that’s not the case, you might want to look for something simpler.

My blog is built with Hugo and a theme called PaperModX, and that’s what I’ll be showing here. However, given how easy the integration is, you shouldn’t have any problems with it when using different tools.

Integration

Integration with utterances is relatively simple. You have to go to their website and follow a couple of steps mentioned in the configuration section.

First, you choose a repository where you want to store your comments (and add the utterances app to it). Next, you select some options, like how you want to map your posts to issue titles or which theme you want to use on the widget. Lastly, you are given a code snippet containing a script tag that you have to add to your blog’s template and position it where you want your comments to appear.

In the case of my blog, I had to add comments: true to my config.yaml file and then create the layouts/partials/comments.html file containing the generated script tag:

<script src="https://utteranc.es/client.js"
        repo="ClouddJR/arkadiuszchmura.com"
        issue-term="pathname"
        label="comments"
        theme="github-light"
        crossorigin="anonymous"
        async>
</script>

Notice how the options you selected in the configuration step match the attributes on the script tag.

Dark mode

That’s pretty much it when it comes to the integration. If you’ve configured everything correctly, you should have a working system for adding comments to your website.

However, you might have noticed that my blog supports a dark mode that you can toggle by clicking on the icon at the top of the page. With the current configuration in the script tag, the theme used by the utterances widget will always be github-light, even when using dark mode on the website.

This definitely doesn’t provide the best user experience, so I decided to find a way to set the correct initial theme when loading the page and also change the theme every time the user toggles it on the website.

This is the code that I ultimately used (I placed it right below the script tag for the utterances widget):

<script>
    function updateUtterancesTheme(isLight) {
        const iframe = document.querySelector('.utterances-frame')
        if (iframe) {
            const message = {
                type: 'set-theme',
                theme: isLight ? 'github-light' : 'github-dark'
            }
            iframe.contentWindow.postMessage(message, 'https://utteranc.es')
        }
    }
</script>

The above is the function (credit goes to this person) for updating the theme used by the utterances widget. If the passed isLight variable is true, we’ll use the github-light theme. Otherwise, it’s going to be github-dark.

I wanted to execute this function as soon as the page loads and right before the utterances iframe makes a request. Here’s one way of doing it:

// Set correct initial utterance theme
function handleMessageEvent(event) {
    if (event.origin !== 'https://utteranc.es') return

    const isLight = !document.body.classList.contains('dark')
    updateUtterancesTheme(isLight)

    removeEventListener('message', handleMessageEvent)
}

addEventListener('message', handleMessageEvent)

After these changes, the theme is set correctly after the page loads. The only thing left to do is to update the theme after toggling it using the icon at the top of the page.

Luckily, with PaperModX, it’s quite easy to do. I just had to add the updateUtterancesTheme function to the array of callbacks that will be invoked every time the theme is changed, like this:

// Update utterances theme every time the theme is changed by a user
toggleThemeCallbacks['comments'] = updateUtterancesTheme

And that’s all! If you want to get the whole picture and see all the changes in one place, here’s the commit on my blog’s repository that introduced utterances. Also, feel free to explore the rest of the code.

Summary

In this post, I showed you how easy it is to add comments to your blog or website without much effort using a really useful tool called utterances. Additionally, I presented a way of updating the theme used by the utterances widget so that you can correctly adjust it to a dark or light theme on your website. I hope you found that post helpful!

In this post, I will show you how to make an expandable text that is controlled by a button below it using Jetpack Compose. Additionally, we’ll introduce some simple animations to make the text state changes a bit nicer and add an ellipsis at the end of the text to indicate that it has overflowed.

That’s the final result we’ll be implementing:

Solution

Let’s start with the following snippet and build on top of it:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            MyAppTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    ExpandableText(
                        modifier = Modifier.padding(16.dp)
                    )
                }
            }
        }
    }

You get that snippet after creating a new project using Android Studio’s project wizard. The only change I introduced is that I added the ExpandableText composable that we’ll be building.

First, let’s add a Text and TextButton composables (wrapped in a Column) inside our new ExpandableText composable:

@Composable
private fun ExpandableText(modifier: Modifier) {
    Column(
        modifier = modifier
    ) {
        Text(
            text = "Hello World! ".repeat(50),
            maxLines = 5,
            overflow = TextOverflow.Ellipsis
        )
        
        TextButton(
            onClick = { },
            modifier = Modifier.fillMaxWidth(),
            shape = RectangleShape
        ) {
            Text(
                text = "Expand".uppercase()
            )
        }
    }
}

I am passing a modifier as a parameter to the ExpandableText to be able to control it from the outside.

Inside, I am setting the text to “Hello World! " repeated 50 times to make sure it overflows. Also, I’m limiting the number of lines to 5 and passing TextOverflow.Ellipsis to the overflow parameter to use an ellipsis when the text overflows (by default, it just clips the text).

The TextButton below is set to fill the entire width and has a RectangleShape because it looks more appropriate in this case than the default, rounded shape.

This is what we have so far:

Next, let’s implement the onClick for our TextButton. When clicking, we want to remove the limit of 5 lines for the text (so that it expands) and change the text for the button from “Expand” to “Collapse”.

For that, we will introduce a mutable state variable called isExpanded that will be toggled inside the onClick and control the parameters mentioned above like this:

@Composable
private fun ExpandableText(modifier: Modifier) {
    var isExpanded by remember { mutableStateOf(false) }

    // ...
    Text(
        // ...
        maxLines = if (isExpanded) Int.MAX_VALUE else 5,
    )

    TextButton(
        // ...
        onClick = { isExpanded = !isExpanded },
    ) {
        Text(
            text = (if (isExpanded) "Collapse" else "Expand").uppercase()
        )
    }
}

After those changes, expanding and collapsing works properly:

But there is one problem with our implementation. What happens when the text is shorter than 5 lines?

We don’t want to show the button when the text has not overflowed. To solve this, we need to find a way to be notified when the overflow happens and store it as a state.

Luckily, with Compose, it’s easy to do. The Text composable exposes a onTextLayout parameter which is a callback that is executed when a new text layout is calculated. That callback will receive a TextLayoutResult object, from which we will be able to get all the necessary information:

@Composable
private fun ExpandableText(modifier: Modifier) {
    var textLayoutResult by remember { mutableStateOf<TextLayoutResult?>(null) }
    val isExpandable by remember { derivedStateOf { textLayoutResult?.didOverflowHeight ?: false } }

    // ...
    Text(
        // ...
        onTextLayout = { textLayoutResult = it }
    )
}

We pass a lambda to the onTextLayout parameter, which will save a new TextLayoutResult object every time it changes into our textLayoutResult state.

Additionally, we define a derived state called isExpandable that will be recalculated every time the textLayoutResult?.didOverflowHeight changes. When it returns true, it means the text occupies more than 5 lines.

We used derived state here because the isExpandable is never modified on its own. This state is always calculated based on the value of the textLayoutResult state. To learn more about derived states, check the documentation.

Now, since we know when the text overflows, we can add another derived state that will control the visibility of the button:

@Composable
private fun ExpandableText(modifier: Modifier) {
    val isButtonShown by remember { derivedStateOf { isExpandable || isExpanded } }

    // ...
    if (isButtonShown) {
        TextButton(
            // ...
        ) {
            // ...
        }
    }
}

This logic basically means that we only want to show the button when the text has overflowed (to be able to expand it) or when it’s already expanded (to be able to collapse it).

Finally, the only thing that’s missing is the animation, which we can add using a single modifier on our Text - animateContentSize():

@Composable
private fun ExpandableText(modifier: Modifier) {
    // ...
    Text(
        // ...
        modifier = Modifier.animateContentSize(),
    )
}

And with that change, we get the desired effect after running the app!

Here’s the full code:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        setContent {
            ExpandableTextTheme {
                Surface(
                    modifier = Modifier.fillMaxSize(),
                    color = MaterialTheme.colorScheme.background
                ) {
                    ExpandableText(
                        modifier = Modifier.padding(16.dp)
                    )
                }
            }
        }
    }
}

@Composable
private fun ExpandableText(modifier: Modifier) {
    var textLayoutResult by remember { mutableStateOf<TextLayoutResult?>(null) }
    val isExpandable by remember { derivedStateOf { textLayoutResult?.didOverflowHeight ?: false } }
    var isExpanded by remember { mutableStateOf(false) }
    val isButtonShown by remember { derivedStateOf { isExpandable || isExpanded } }

    Column(
        modifier = modifier
    ) {
        Text(
            text = "Hello World! ".repeat(50),
            modifier = Modifier.animateContentSize(),
            maxLines = if (isExpanded) Int.MAX_VALUE else 5,
            overflow = TextOverflow.Ellipsis,
            onTextLayout = { textLayoutResult = it }
        )

        if (isButtonShown) {
            TextButton(
                onClick = { isExpanded = !isExpanded },
                modifier = Modifier.fillMaxWidth(),
                shape = RectangleShape
            ) {
                Text(
                    text = (if (isExpanded) "Collapse" else "Expand").uppercase()
                )
            }
        }
    }
}

Summary

That’s it for this post. I hope you found it helpful and learned something from it. If you have any questions, feel free to leave a comment here or reach out to me on Twitter.

In this post, I will show you how to create factories for models that have polymorphic relationships with other models in your app.

This post assumes that you are familiar with polymorphic relationships. If that’s not true, head to the documentation to learn more.

Solution

As an example, let’s consider an app where we allow users to rate games or movies. For that, we define two Eloquent models - Game and Movie. Additionally, to avoid repetition, we use a single Rating model for both entities.

A simplified database structure for our app could look like this:

games
    id - integer
    name - string
 
movies
    id - integer
    name - string
 
ratings
    id - integer
    rating - integer
    rateable_id - integer
    rateable_type - string

Now, let’s move on to factories. For both Game and Movie, it would be a simple, regular factory. Something like this:

class GameFactory extends Factory
{
    public function definition(): array
    {
        return [
            'name' => fake()->word(),
        ];
    }
}

I’m only showing the code for the GameFactory, as the MovieFactory would look almost identical.

The factory for our Rating model is going to be a bit more complicated, and we could define it like this:

class RatingFactory extends Factory
{
    public function definition(): array
    {
        return [
            'rateable_id' => Game::factory(),
            'rateable_type' => function (array $attributes) {
                return Game::find($attributes['rateable_id'])->getMorphClass();
            }
        ];
    }
}

It’s a typical pattern to assign a new factory instance to the foreign key of the relationship (hence the 'rateable_id' => Game::factory()). Thanks to this, when we create a new Rating using the factory, a new Game instance will be automatically created for us.

The rateable_type attribute is more interesting. Potentially, we could hardcode the value to App\Models\Game, and it would work just fine because, by default, Laravel uses the fully qualified class name to store the “type” of the related model. However, I like to decouple my app internals from the database and usually change these values.

To do that, you can use the following code (placed in the boot method of one of your service providers) to store simple strings as the “type” in the database:

Relation::enforceMorphMap([
    'game' => 'App\Models\Game',
    'movie' => 'App\Models\Movie',
]);

But after that change, we must provide correct values to our RatingFactory. That’s precisely why we we used the getMorphClass() on the model instance. It allows us to get the valid morph alias at runtime.

Also, we used a closure to access other attributes defined in the factory (in particular, the rateable_id) to find the newly created Game model on which we call the getMorphClass() method.

To use the factory and create a new Rating, we can now call Rating::factory()->create().

Notice that when we use this factory, by default, it will associate the new Rating model with a new Game. What if we would like to use a Movie model instead (or any other that might be added in the future)?

To do that, we could leverage factory states. We can define a method called forMovie in our factory that will only modify the rateable_id and rateable_type attributes accordingly (leaving the remaining ones untouched):

public function forMovie(): Factory
{
    return $this->state(function (array $attributes) {
        return [
            'rateable_id' => Movie::factory(),
            'rateable_type' => function (array $attributes) {
                return Movie::find($attributes['rateable_id'])->getMorphClass();
            }
        ];
    });
}

Then, you can create a new Rating associated with a Movie by calling Rating::factory()->forMovie()->create().

Similarly, you could define a separate method for any other model related to Rating that you might add in the future.

Summary

In summary, creating factories for models with polymorphic relationships in Laravel can be a bit trickier than the standard ones. However, by following the steps outlined in this post, I hope you won’t have any problems with that.

If you have any questions, feel free to leave a comment here or reach out to me on Twitter.

In this post, I would like to explain in detail what inline functions are and what problems they address. Additionally, I will present some practical examples and tips on when it’s appropriate to use inline functions and when to avoid them.

Before we go any further, let’s first understand what inline functions do. The general idea is simple. If you mark a function with the inline modifier, the compiler will copy the body of that function and paste it at every call site.

As a result, this code:

inline fun foo() {
    print("Body of the foo() function")
}

fun main() {
    foo()
}

after compilation will be ultimately equivalent to this:

inline fun foo() {
    print("Body of the foo() function")
}

fun main() {
    print("Body of the foo() function")
}

What happened here is instead of calling foo(), the compiler copied its content and pasted it into the body of the main() function.

Now that we have a basic intuition for inline functions, we can move on to discuss their applications.

Overhead of lambdas and anonymous functions

In Kotlin, functions are first-class citizens. They can be stored in variables or data structures, used as arguments, or returned from other functions. However, this feature has an important implication. Functions in these scenarios are represented as objects, which impose certain runtime penalties.

Let’s illustrate this with an example. Suppose we write a function called takeUntil (which is surprisingly not in the standard library) that would take all the elements from an iterable until a provided predicate is satisfied.

This is what it could look like:

fun <T> Iterable<T>.takeUntil(predicate: (T) -> Boolean): List<T> {  
    val list = ArrayList<T>()  
    for (item in this) {  
        list.add(item)  
        if (predicate(item))  
            break  
    }  
    return list  
}

We define it as an extension function and specify one argument, predicate, which is a function that will control when we stop taking elements.

In Kotlin, functions that take other functions as parameters, or return a function, are called High-order functions.

Let’s see what the decompiled bytecode for this function looks like in Java:

In IntelliJ (or Android Studio), you can get the decompiled bytecode by going to Tools > Kotlin > Show Kotlin Bytecode and then clicking Decompile button to get the Java code.

public static final List takeUntil(@NotNull Iterable $this$takeUntil, @NotNull Function1 predicate)

Notice that our predicate argument has a special Function1 type (this 1 in Function1 corresponds to the number of arguments our lambda accepts), which confirms that lambdas are indeed represented as objects. We must provide an instance of the Function1 interface every time we call the takeUntil function.

Now, let’s write some code to test our new function and see how lambdas that we pass to the takeUntil function are converted to objects of the Function1 type under the hood:

fun main() {
    val numbers = listOf(1, 2, 3, 4, 5, 6, 7)  
    println(numbers.takeUntil { it >= 5 })
}

When executed, this code prints a correct result (a list of numbers from 1 to 5 included), but we’re interested in something else here. Let’s see the decompiled version of the code above:

List numbers = CollectionsKt.listOf(new Integer[]{1, 2, 3, 4, 5, 6, 7});  
List var1 = takeUntil((Iterable)numbers, (Function1)null.INSTANCE);

As you can see, the takeUntil function takes a mysterious (Function1)null.INSTANCE object as an argument. Where does it come from?

Unfortunately, the generated Function1 interface doesn’t reflect in the decompiled Java code, so we must dive deeper - into the bytecode itself.

I will skip all the irrelevant code for our discussion and present only the interesting parts.

First, we can see a class created that implements the Function1 interface.

final class MainKt$main$1 extends kotlin/jvm/internal/Lambda implements kotlin/jvm/functions/Function1

The bytecode for that class is equivalent to the lambda body that we’ve passed to the takeUntil function.

Our main() function is represented like this:

GETSTATIC MainKt$main$1.INSTANCE : LMainKt$main$1;
CHECKCAST kotlin/jvm/functions/Function1
INVOKESTATIC MainKt.takeUntil (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function1;)Ljava/util/List;

The GETSTATIC instruction gets a class’s static field value, which means we get a singleton here that is ultimately passed to the takeUntil function.

Let’s do a quick experiment to confirm that if we put our code in a loop that runs 1000 times, we still use that singleton, and we don’t create 1000 new objects:

val numbers = listOf(1, 2, 3, 4, 5, 6, 7)  
repeat(1000) {  
    println(numbers.takeUntil { it >= 5 })  
}

After getting the bytecode, we can confirm that the GETSTATIC instruction is still used, so no new objects are being created.

GETSTATIC MainKt$main$1$1.INSTANCE : LMainKt$main$1$1;
CHECKCAST kotlin/jvm/functions/Function1
INVOKESTATIC MainKt.takeUntil (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function1;)Ljava/util/List;

So far, nothing dramatic. The bytecode contains an additional class implementing the Function1 interface that represents our lambda passed to the takeUntil function. Additionally, a singleton was used, so there is only one instance of that class at runtime.

However, the situation is entirely different when we start capturing variables in lambdas.

Let’s store the value we had in the lambda in a variable called limit and use it instead:

val limit = 5
val numbers = listOf(1, 2, 3, 4, 5, 6, 7)
repeat(1000) {
    println(numbers.takeUntil { it >= limit })
}

And here’s the bytecode representation:

INVOKESPECIAL MainKt$main$1$1.<init> (I)V
CHECKCAST kotlin/jvm/functions/Function1
INVOKESTATIC MainKt.takeUntil (Ljava/lang/Iterable;Lkotlin/jvm/functions/Function1;)Ljava/util/List;

As you can see, there is no GETSTATIC instruction anymore. Instead, there is INVOKESPECIAL that calls <init>. This line means we are creating a new object of that class. Given that we run this code 1000 times, the same number of new objects will be created at this point.

It’s worth remembering that when we create lambdas that capture closures, there will always be a new object created, as the above experiment proved. However, in most cases, that won’t be a huge problem (unless you deal with a performance-critical application).

Regardless, the solution is to use inline functions. When we mark our takeUntil function as inline, this is the decompiled Java code that we get for the main() function:

List numbers = CollectionsKt.listOf(new Integer[]{1, 2, 3, 4, 5, 6, 7});  
int limit = 5;  
short var2 = 1000;  
  
for(int var3 = 0; var3 < var2; ++var3) {  
   int var5 = false;  
   Iterable $this$takeUntil$iv = (Iterable)numbers;  
   int $i$f$takeUntil = false;  
   ArrayList list$iv = new ArrayList();  
   Iterator var9 = $this$takeUntil$iv.iterator();  
  
   while(var9.hasNext()) {  
      Object item$iv = var9.next();  
      list$iv.add(item$iv);  
      int it = ((Number)item$iv).intValue();  
      int var12 = false;  
      if (it >= limit) {  
         break;  
      }   
    }
    
   List var13 = (List)list$iv;  
   System.out.println(var13);  
}

The content of the takeUntil function has been copied (inlined) here. Our lambda is no longer represented as an object, so we avoid an additional overhead. Instead, it’s been inlined into the if statement (if (it >= limit)).

Better control flow

Another benefit of using inline functions is introducing a better control flow.

Let’s consider a function that is supposed to find a user with a given id or throw an error when there is no such user:

fun getUser(users: List<User>, id: String): User {  
    users.forEach { user ->  
        print("Inspecting user: $user")  
        if (user.id == id) {  
            return user  
        }  
    }  
    error("User with id $id not found.")  
}

We iterate over the list of users and check if the current user is the one we seek. If it is, we immediately return that user from our getUser function. If we reach the end of the list, we throw an error.

Notice that we use a return statement not inside the getUsers function but in a lambda passed to the forEach. This is only possible because the forEach function has been marked with the inline modifier.

Such returns (located in a lambda, but exiting the enclosing function) are called non-local returns.

If we write our own version of forEach that is not inlined and use it instead, returning from a lambda won’t be possible:

// This is the same function as forEach, but without the inline modifier
fun <T> Iterable<T>.noInlineForEach(action: (T) -> Unit) {  
    for (element in this) action(element)  
}

fun getUser(users: List<User>, id: String): User {  
    users.noInlineForEach { user ->  
        print("Inspecting user: $user")  
        if (user.id == id) {  
            return user  
        }  
    }  
    error("User with id $id not found.")  
}

We are getting an error that says “‘return’ is not allowed here”.

The reason why returning with the regular forEach is possible is that when a lambda is inlined, it’s clear that the return statement applies to the top-level function (getUsers) because there are no other function calls made or objects created.

Noinline

If you don’t want all of the lambdas passed to an inline function to be inlined, you can use the noinline modifier.

Consider the following inline function execute that decides which API to call based on whether the user is part of an experiment or not:

inline fun execute(  
    isPartOfExperiment: (User) -> Boolean,  
    callOldApi: () -> Unit,  
    callNewApi: () -> Unit  
) {  
    // ...
    val callApi = if(isPartOfExperiment(user)) callNewApi else callOldApi  
    // ...
}

We want to store the correct lambda in a variable called callApi and call it later at some point, but that’s not possible. We get the “Illegal usage of inline-parameter” error. We can’t store inlined lambdas in variables (or pass them to other functions) because they aren’t objects anymore.

To solve this, we can add noinline modifiers to two of our lambdas, and our code compiles successfully:

inline fun execute(  
    isPartOfExperiment: (User) -> Boolean,  
    noinline callOldApi: () -> Unit,  
    noinline callNewApi: () -> Unit  
) {  
    // ...
    val callApi = if(isPartOfExperiment(user)) callNewApi else callOldApi  
    // ...
}

Crossinline

In some cases, we still want to get all the benefits of using inline functions but without giving the possibility to use a return statement inside lambdas passed as parameters.

To indicate that the lambda parameter of the inline function cannot use non-local returns, we can mark it with the crossinline modifier.

Take a look at our little helper benchmark function that allows us to measure the execution time of a lambda passed as a parameter:

inline fun benchmark(run: () -> Unit): Long {  
    val duration = measureTime {  
        run()  
    }
    return duration.inWholeMilliseconds  
}

Now, for a little experiment, let’s try to run the following code:

fun main() {
    val time = benchmark { return }  
    print(time)
}

It compiles successfully because the benchmark function is marked with the inline modifier, and using non-local returns is possible in such cases.

If we run it, the console won’t print anything. That’s because the return statement returns not from the benchmark function but immediately from the main(), thus ending the program.

If we don’t want to allow code like this, we can use the crossinline modifier, and the main() function won’t even compile. We will get the “‘return’ is not allowed here” error:

inline fun benchmark(crossinline run: () -> Unit): Long {  
    val duration = measureTime {  
        run()  
    }  
    return duration.inWholeMilliseconds  
}

Reified types

Imagine we want to write a function that will return the first item of a given type from a list. For example, we have a listOf(1, 2, "string", 3) and would like to get the first string from that list.

Here’s one approach to writing such a function:

fun <T> List<*>.firstIsInstance(clazz: Class<T>): T? {  
    @Suppress("UNCHECKED_CAST")  
    return firstOrNull { clazz.isInstance(it) } as T?  
}

And that’s what the code to use this function could look like:

val items = listOf(1, 2, "string", 3)
println(items.firstIsInstance(String::class.java))  

This code works, but it’s not pretty. We have to pass that not-so-beautiful String::class.java to the function.

Additionally, inside, we have to use a suppression mechanism and call the parameter clazz, because class is a reserved keyword. A lot of compromises.

As an alternative, we can rewrite the firstIsInstance function as an inline version and utilize reified type parameters:

inline fun <reified T> List<*>.firstIsInstance(): T? {  
    return firstOrNull { it is T } as T?  
}

Marking the type parameter with the reified modifier makes it accessible inside the function. Also, because the function is inlined, we can use normal operators like as or is, without relying on reflection.

With that change, the client code looks much more elegant:

val items = listOf(1, 2, "string", 3)   
println(items.firstIsInstance<String>())

Avoiding inline functions

So far, we’ve discussed the benefits of using inline functions. However, it’s also worth mentioning when it would be better to avoid them.

First, it doesn’t make much sense to add the inline modifier to a function that doesn’t have any lambdas as parameters because the performance gains are unlikely. The JVM already optimizes small functions and inline them automatically.

Furthermore, you can’t use inline functions when hiding implementation details (public inline functions can’t call private functions):

inline fun doSomething() {  
    doSomethingPrivately() // Won't compile.
}  
  
private fun doSomethingPrivately() {  
    print("Private function")  
}

After learning about the benefits of inline functions, it might be tempting to use them everywhere now but resist the temptation.

For example, inlining a large function could dramatically increase the size of the generated bytecode because it’s copied to every call site. For similar reasons, it’s better to avoid inlining recursive calls.

Summary

This was quite a long post, but I hope you learned a lot from it. As much as I love the Kotlin documentation, I think the section dedicated to inline functions could use some work. That was the main motivation behind the decision to cover inline functions extensively here, including some practical examples.

If you have any questions, feel free to leave a comment here or reach out to me on Twitter.

When updating your Android Studio to the newest Electric Eel version, the location of the embedded JDK is changed. In particular, it changes from:

/Applications/Android Studio.app/Contents/jre/Contents/Home

to

/Applications/Android Studio.app/Contents/jbr/Contents/Home

This might cause some problems with building your projects right after the update.

Solution

First, make sure the JDK is correctly specified for your project. Go to Preferences -> Build, Execution, Deployment -> Build Tools -> Gradle and set the Gradle JDK to the correct one (if it didn’t happen automatically):

Additionally, if your JAVA_HOME environment variable still points to the old location (as it was in my case), you will also have to update it.

You can verify it by running echo $JAVA_HOME in your terminal. If it points to a completely different location, that’s fine, you don’t have to change that. It means you are using different JDKs in Android Studio and your terminal. However, I recommend using the same JDK everywhere to avoid problems with cache or running multiple Gradle daemons.

To update it, go to your ~/.zshrc or ~/.bashrc (or any other place where you define your variables) and make sure you have this line there:

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

Summary

I hope this post helped you solve your problem. I wish the JDK location change had been signaled more clearly after the update so that we wouldn’t have to spend time investigating all the issues ourselves.

Recently, I’ve been working on a codebase where I had to write a bridging code between a data layer using Flows and a UI layer that still relied on the state exposed as LiveData.

Luckily, there is a function in the androidx.lifecycle called asLiveData() that allows you to convert a Flow to a LiveData effortlessly. However, there is one caveat to keep in mind when using a LiveData created this way. It will only emit data when it has at least one active observer. If there is an update to the upstream flow and the LiveData is inactive, it will not have the latest value.

Let me show you a potential problem we might encounter, with an example below:

Example

We have a simple activity that keeps a reference to an AAC ViewModel:

class MainActivity : AppCompatActivity() {  
    private val viewModel: MainViewModel by viewModels()  
  
    override fun onCreate(savedInstanceState: Bundle?) {  
        super.onCreate(savedInstanceState)  
        setContentView(R.layout.activity_main)    
    }  
}

The MainViewModel looks like this:

class MainViewModel : ViewModel() {  
    private val repository = Repository()  
  
    val state: LiveData<Int> = repository.state.asLiveData()  
}

We have a reference to a repository that will act as our trivial data layer. The ViewModel also exposes a state as a LiveData object converted from a StateFlow kept inside the repository using the asLiveData() function mentioned before.

Here is what the repository looks like:

class Repository {  
    private val _state = MutableStateFlow(-1)  
    val state: StateFlow<Int> = _state  
  
    suspend fun update() {  
        _state.emit(Random.nextInt(until = 1000))  
    }  
}

It’s a simple class with a StateFlow wrapping an integer (that starts with an initial value of -1) that also has a method allowing clients to update the state with a new random number between 0 and 1000.

Let’s imagine we want to schedule the update as soon as our activity is created. We could do this by creating a method inside the MainViewModel called init() that we would call inside the onCreate() of our activity:

// MainViewModel
fun init() {
    // update() is suspending, so we launch a new coroutine here
    viewModelScope.launch {  
        repository.update()
    }  
}

// MainActivity
override fun onCreate(savedInstanceState: Bundle?) {  
    super.onCreate(savedInstanceState)  
    setContentView(R.layout.activity_main)  
  
    viewModel.init()
}

Now, during the creation of our activity, a new coroutine will be launched that will eventually call update() on the repository, generating a random number and emitting it to the state.

Additionally, let’s suppose that there is a requirement to send an analytical event containing the newly generated number in our ViewModel. We could write a sendAnalyticalEvent() method in our ViewModel that we will run right after calling the update() method on the repository:

// MainViewModel
fun init() {  
    viewModelScope.launch {  
        repository.update()  
        sendAnalyticalEvent() // <-- NEW
    }  
}  
  
private fun sendAnalyticalEvent() {  
    // Typically, we would schedule a network request here  
  
    val liveDataValue = state.value  
    val flowValue = repository.state.value  
    Log.d("Current number in LiveData", "$liveDataValue")  
    Log.d("Current number in StateFlow", "$flowValue")  
}

Inside this method, we would typically schedule a network request to our backend servers but in this case, let’s see both values from the LiveData and Flow in the Logcat instead:

Now, that is quite unexpected. You could argue that the LiveData doesn’t have the newest value because there wasn’t enough time to collect it from the upstream flow, and you might be right. But in this case, not only does the LiveData contain an incorrect value, but it’s null! And remember, the initial value of the state in the repository was -1. It can only mean one thing - our LiveData didn’t collect anything from the StateFlow.

The reason is that we haven’t started observing the LiveData anywhere. Therefore, it’s considered inactive. And, according to the documentation of the asLiveData() function, in this state, LiveData won’t be collecting any values from the upstream flow:

Creates a LiveData that has values collected from the origin Flow.

The upstream flow collection starts when the returned LiveData becomes active (LiveData.onActive). If the LiveData becomes inactive (LiveData.onInactive) while the flow has not completed, the flow collection will be cancelled after timeoutInMs milliseconds unless the LiveData becomes active again before that timeout (to gracefully handle cases like Activity rotation).

Once we start observing the state in our activity (hence making the LiveData active), it will contain the correct (newest) value:

// MainActivity
override fun onCreate(savedInstanceState: Bundle?) {  
    super.onCreate(savedInstanceState)  
    setContentView(R.layout.activity_main)  
  
    viewModel.init()  
    viewModel.state.observe(this) { // <-- NEW  
        Log.d("Current number in MainActivity", "$it")  
    }  
}

And this is the output from the Logcat:

In this example, we use StateFlow, but the same rules apply to SharedFlow. Furthermore, it would be even worse because any events sent to a SharedFlow while the LiveData is inactive would be permanently lost (SharedFlow, by default, doesn’t replay any values to new subscribers).

Summary

Keep in mind that LiveData converted from a Flow using the asLiveData() function will behave slightly differently than expected. It will emit data only when there are active observers. To me, this behavior makes sense because we generally wouldn’t be interested in LiveData values if we didn’t observe it anywhere.

Regardless, there might be some use cases when you want to access the current value of your LiveData in your ViewModel before you start observing it. After reading this post, I hope you won’t be surprised when encountering seemingly incorrect values in such situations.

Imagine you spill a cup of coffee onto your laptop keyboard one day. The damage is permanent, and you desperately need a new machine.

Now, ask yourself a question. How long would it take to bring your new machine to the previous state? That includes all user settings, editors and shell configurations, installed apps, and more.

If the answer is “a couple of days”, or even worse, “a couple of weeks”, continue reading to find out what you can do about that.

This post will show you how and where I store all my configuration files (dotfiles) to make switching between many machines a breeze.

Even though it might be quite an investment of time initially to set everything up, it will undoubtedly pay off in the future.

Repository

I keep all my dotfiles and initializing scripts in a repository on GitHub. Feel free to use it as a template and adjust it to your needs and preferences. I, for example, was inspired by Freek Van der Herten’s repository.

Every time I want to set up a new machine, I clone my repository and run these simple commands:

chmod +x bootstrap
./bootstrap

Then, I follow the instructions on the screen which will do the job for me:

I usually go through all of these options sequentially when starting from scratch. Let’s explain what each of them does:

1. Bootstrap terminal

As the name suggests, this step is responsible for bootstrapping my terminal, which includes:

• Hiding the “last login” line when starting a new session.
• Installing oh-my-zsh. My terminal of choice is iTerm2. I’m using the Z shell with oh-my-zsh. It has a lot of valuable functions, plugins, helpers, and more. I highly recommend this combination.
• Creating symbolic links for .zsrhc and .vimrc. The latter contains a basic configuration for Vim. The former stores all the exports, aliases, and functions I frequently use when working on the shell. It also configures the theme (robbyrussell) and specifies used plugins (in my case: git, adb, macos, and laravel). Usually, plugins will give you auto-completion for specific commands and some useful aliases. Check out the Wiki for a complete list of plugins for oh-my-zsh. For example, here’s what the auto-completion looks like for the adb plugin. As you can see, I can also navigate between suggested options using arrows, which is very convenient:

Sometimes I want to export variables (or aliases and functions) that I wouldn’t store in a public repository for security reasons. In that case, I can create a .dotfiles-custom folder that git does not track, and the .zshrc will also load everything from there.

• Activating z.sh. If you’ve never used it before, do yourself a favor and try it. It’s a tremendously helpful and popular bash script for quick navigation between visited directories on your file system. For example, if you want to cd into a deeply nested directory (like Development/Mobile/Android/MyProject), you don’t have to specify the entire path. It’s enough to type z project to get there immediately (provided you have visited this directory before so that the script could save it in local history). It also works for sibling directories, as you can see below:

• Installing and setting up Homebrew. This package manager probably needs no introduction for macOS users. This substep also includes installing packages I use on most computers, like git, python, java, node, mysql, etc.

2. Install applications

You might be surprised that you can install regular GUI applications for macOS (those that require downloading .dmg files and running the installer) without leaving the terminal. It’s possible thanks to an extension to Homebrew called Homebrew Cask. Installing an application is as easy as running a single command (provided it’s available as a Cask):

brew install --cask firefox

This setup’s step is straightforward. It’s responsible for installing some apps (listed in the repository) using the above method.

Some apps, like IDEs, have their own configurations, which might include custom keyboard shortcuts, formatting styles, etc. I also keep them in my repository (in most cases as zip files) to easily import these configs after installation.

3. Set system defaults (macOS)

Here, the script specifies values for some system preferences, like disabling the sound effect on boot or showing all file extensions by default in Finder. There’s no shortage of things you can do. To learn more and get some inspiration, here’s a helpful website with some demos: https://macos-defaults.com.

Summary

I hope I convinced you that it’s worth setting up your dotfiles repository to have a single place where all your configurations lie. Thanks to that, switching between many machines will be a piece of cake.

If you have some tips that you would like to share with me regarding this topic, feel free to reach me on Twitter.

In this post, I would like to show you how you can draw content behind the system bars (status bar or navigation bar) when building a UI using Jetpack Compose.

A typical use case (that will be the focus of this post) is when you have an app bar or a navigation bar in your app and want to lay them out behind the system bars to achieve an effect of connectedness between system UI components and your app.

It can give your app a more compelling and modern user experience that adheres to the Material 3 guidelines.

Solution

To illustrate all the necessary steps, we will start with a basic app that has a CenterAlignedTopAppBar, NavigationBar, and a LazyColumn containing some items.

I created the project using the Empty Compose Activity template from the Android Studio’s project wizard. The generated code will make the navigation bar black by default, while the status bar will use the primary color specified in the theme.

Here’s what the app looks like:

And here’s the code (without any irrelevant parts). Firstly, MainActivity:

class MainActivity : ComponentActivity() {  
    override fun onCreate(savedInstanceState: Bundle?) {  
        super.onCreate(savedInstanceState)  
  
        setContent {  
            App()  
        }  
    }  
}

@OptIn(ExperimentalMaterial3Api::class)
@Composable
fun App() {
    AppTheme {
        val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior()

        Scaffold(
            topBar = {
                CenterAlignedTopAppBar(
                    title = { Text("Title") },
                    scrollBehavior = scrollBehavior
                )
            },
            bottomBar = {
                NavigationBar {
                    NavigationBarItem(
                        selected = true,
                        icon = { Icon(imageVector = Icons.Default.Home, contentDescription = "") },
                        label = { Text("First") },
                        onClick = { }
                    )
                    NavigationBarItem(
                        selected = false,
                        icon = { Icon(imageVector = Icons.Default.Face, contentDescription = "") },
                        label = { Text("Second") },
                        onClick = { }
                    )
                }
            }
        ) { paddingValues ->
            Surface(
                modifier = Modifier
                    .padding(paddingValues)
                    .fillMaxSize()
            ) {
                LazyColumn(
                    modifier = Modifier.nestedScroll(scrollBehavior.nestedScrollConnection),
                    contentPadding = PaddingValues(16.dp),
                    verticalArrangement = Arrangement.spacedBy(8.dp)
                ) {
                    items(count = 100) {
                        Text("Hello Android!")
                    }
                }
            }
        }
    }
}

And this is the body of the AppTheme function:

@Composable  
fun AppTheme(  
    darkTheme: Boolean = isSystemInDarkTheme(),  
    dynamicColor: Boolean = true,  
    content: @Composable () -> Unit  
) {  
    val colorScheme = when {  
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {  
            val context = LocalContext.current  
            if (darkTheme) dynamicDarkColorScheme(context) else dynamicLightColorScheme(context)  
        }  
        darkTheme -> DarkColorScheme  
        else -> LightColorScheme  
    }
      
    val view = LocalView.current  
    if (!view.isInEditMode) {  
        SideEffect {  
            val window = (view.context as Activity).window  
            window.statusBarColor = colorScheme.primary.toArgb()  
            WindowCompat.getInsetsController(window, view).isAppearanceLightStatusBars = darkTheme  
        }  
    }  
  
    MaterialTheme(  
        colorScheme = colorScheme,  
        typography = Typography,  
        content = content  
    )  
}

Notice the use of val scrollBehavior = TopAppBarDefaults.pinnedScrollBehavior() at the beginning of the App composable. Thanks to this, we get that nice visual effect of elevation on the app bar when scrolling the list.

To utilize it, we first pass the created scrollBehavior to the CenterAlignedTopAppBar. Next, we attach its nestedScrollConnection to the Modifier.nestedScroll on the LazyColumn that will keep track of scroll events and notify the app bar about them.

As you can see above, the user interface in our sample app is far from perfect. The black color of the navigation bar doesn’t play nicely with our design. Also, no matter whether the app bar is elevated or not, the status bar has always the same color.

Ideally, we would like the system navigation bar to have the same color as our app’s navigation bar. The same goes for the status bar. It should change colors based on the app bar’s current elevation.

Here’s the final effect that we would like to achieve:

Luckily, it’s not that complicated. There are only two steps we need to introduce to our code presented above:

1. Laying out our app in full screen.
2. Changing the system bar colors and transparency.

Laying out our app in full screen

A single line of code is enough to make sure our app goes edge-to-edge and is laid out using the entire width and height of the display (including the system bars). We can place it inside the onCreate method in our activity:

override fun onCreate(savedInstanceState: Bundle?) {  
    super.onCreate(savedInstanceState)  

    // This will lay out our app behind the system bars
    WindowCompat.setDecorFitsSystemWindows(window, false)  
  
    setContent {  
        App()  
    }  
}

Changing the system bar colors and transparency

After drawing our content behind the system bars we need to make sure it’s visible to the user. We can do that by setting the color of the navigation bar and the status bar to transparent.

If you are interested, I wrote an entire post about changing the system bar colors in Compose.

Here is the relevant part of the AppTheme function:

SideEffect {  
    val window = (view.context as Activity).window  
  
    window.statusBarColor = Color.Transparent.toArgb()  
    window.navigationBarColor = Color.Transparent.toArgb()  
  
    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) {  
        window.isNavigationBarContrastEnforced = false  
    }  
  
    val windowsInsetsController = WindowCompat.getInsetsController(window, view)  
  
    windowsInsetsController.isAppearanceLightStatusBars = !darkTheme  
    windowsInsetsController.isAppearanceLightNavigationBars = !darkTheme  
}

Firstly, we set the system bar colors to transparent. Next, we tell the system not to enforce the navigation bar contrast, because by default, on API >= 29, the system applies a translucent scrim behind the system bars. Lastly, we modify the icon colors to match the current theme (light or dark).

Now, after running the app, we get the desired effect and our app looks much better!

Notice that even though we draw our app bar and navigation bar behind the system bars, their content (titles, icons, etc.) doesn’t interfere with the system bars. That’s because since version 1.0.0-beta01 of the androidx.compose.material3:material3, these components handle insets automatically and apply correct padding values based on them.

If we used previous versions, we would have to do it manually. If you are interested in how it used to be done, here is the commit from the Now in Android project that removes manual insets handling after bumping the library version.

Summary

I hope this post will save you some time when you try to draw some UI components behind the system bars.

If you have any questions or comments, feel free to reach me on Twitter.

Let’s look at a simple suspending function that fetches some data from a server. Before executing a network call, it sets the isLoading variable to true. Then, after finishing successfully, it sets it back to false and returns the loaded data:

class Repository {  
    var isLoading = false  
  
    suspend fun fetchData(): String {  
        isLoading = true  
        delay(500) // Simulate a network call  
        isLoading = false  
        return "Loaded data"  
    }  
}

For simplicity, let’s ignore all the additional things we would normally take care of in a real project, like error handling, making the actual network call, parsing the result, etc. Instead, let’s focus on the aspect of testing this snippet of code.

Testing the final result of the fetchData function is relatively easy with the help of some tools from the kotlinx.coroutines.test library. This is what such a test could look like:

@Test  
fun `repository should return loaded data`() = runTest {  
    // given  
    val repository = Repository()  
  
    // when  
    val result = repository.fetchData()  
  
    // then  
    assertEquals("Loaded data", result)  
}

Notice how this test doesn’t look much different than what we would write if we were testing a regular function.

runTest is an extremely convenient function. It behaves similarly to runBlocking, with the difference that the code that it runs will skip delays. Thanks to this, we don’t have to wait 500 ms (because of the delay(500) in our fetchData function) for the test to finish.

The code above works just fine, but what if we want to have more control over this test? We would like to make sure that the fetchData function indeed sets correct values to the isLoading variable - before and after making a network call.

Solution

We can take advantage of the fact that runTest executes our test body in a new coroutine launched on a TestScope.

This scope uses a special kind of dispatcher - StandardTestDispatcher. Usually, dispatchers are used to control the thread on which our coroutines should run. This dispatcher does a bit more - it supports delay-skipping using a scheduler that operates on virtual time (TestCoroutineScheduler).

Coroutines started with the StandardTestDispatcher won’t run immediately. Instead, the dispatcher always sends them to its scheduler. Then, it’s our job to trigger their execution by controlling the virtual time. For this, we can use functions available on the TestCoroutineScheduler: advanceTimeBy, runCurrent or advanceUntilIdle.

To see this in action, look at the code below:

@Test  
fun `child coroutine`() = runTest {  
    // 1  
    launch {  
        // 3  
    }  
    // 2  
    advanceUntilIdle() // Run all the scheduled tasks
    // 4  
}

When we call launch, the coroutine is not executed immediately. Instead, as mentioned earlier, it’s sent to the scheduler. Only when we call advanceUntilIdle (or any other function controlling the virtual time), the child coroutine is executed.

Notice that we can call advanceUntilIdle directly on the TestScope. It’s because it’s defined as an extension function that internally delegates the call to the scheduler. The same is true for the remaining functions modifying the virtual time.

This behavior allows us to call the function we want to test inside a child coroutine. That coroutine will be sent to the scheduler and its execution is fully controllable by us.

We can advance the virtual time to the point where the data is about to be loaded and verify that the isLoading is properly set to true. Then we can run all the tasks scheduled at that time (remember the delay(500) that we had in our function?) by using runCurrent. Lastly, we can assert that the isLoading variable is back to false:

@Test  
fun `repository should indicate that it's loading data`() = runTest {  
    // given  
    val repository = Repository()  
    launch {  
        repository.fetchData()  
    }  
  
    // when  
    advanceTimeBy(500)  
  
    // then  
    assertTrue(repository.isLoading)  
  
    // when  
    runCurrent()  
  
    // then  
    assertFalse(repository.isLoading)  
}

Regular functions that launch coroutines

Previously, we looked at testing intermediate steps in suspending functions. But in some cases, we want to test a regular, non-suspending function that launches a new coroutine inside. It’s very common in many Android projects where you can see a code similar to this one:

class TasksViewModel(private val repository: TasksRepository) : ViewModel() {  
    private val _isLoading = MutableStateFlow(false)  
    val isLoading: StateFlow<Boolean> = _isLoading  
  
    fun getTasks() {  
        viewModelScope.launch {  
            _isLoading.emit(true)  
            repository.getTasks()  
            _isLoading.emit(false)  
        }  
    }  
}

We have a ViewModel that exposes a function called getTasks. Internally, it launches a new coroutine using a viewModelScope in which it calls a suspending function getTasks from our repository. Besides, it correctly updates the isLoading state before and after.

Here’s what the TasksRepository looks like (including the implementation that will be used in tests):

interface TasksRepository {  
    suspend fun getTasks(): List<Task>  
}  
  
class InMemoryTasksRepository : TasksRepository {  
    override suspend fun getTasks(): List<Task> {  
        delay(500) // Simulate a network call  
        return listOf(  
            Task("1", "Task 1"),  
            Task("2", "Task 2")  
        )  
    }  
}  
  
data class Task(val id: String, val name: String)

We can’t directly use the same approach as previously, because the coroutine inside getTasks is launched on the viewModelScope. This scope knows nothing about the TestScope that is running our test body. This means that viewModelScope.launch {...} would be launched immediately instead of being scheduled by the StandardTestDispatcher.

To solve this, we need to force the viewModelScope to use the StandardTestDispatcher that we could control from the outside.

Luckily, according to the source code, viewModelScope is using a Dispatchers.Main.immediate. The main dispatcher can easily be replaced during tests using Dispatchers.setMain. There, we can pass our StandardTestDispatcher.

Here’s how we could set up our test using the @Before and @After annotations:

private lateinit var testScheduler: TestCoroutineScheduler

@Before  
fun setUp() {  
    testScheduler = TestCoroutineScheduler()  
    Dispatchers.setMain(StandardTestDispatcher(testScheduler))  
}  

@After  
fun tearDown() {  
    Dispatchers.resetMain()  
}  

Before each test, we create a StandardTestDispatcher, providing our TestCoroutineScheduler, and set it as the main dispatcher (that we reset after each test).

Thanks to this, the viewModelScope will be using this dispatcher and all coroutines launched on this scope will be sent to our scheduler.

The code of our test will be almost identical to the previous one. The only difference is that we don’t launch a child coroutine anymore and we control the virtual time by calling methods on the testScheduler variable.

Here is the full code of our test, including the setup:

class ViewModelTest {  
    private lateinit var testScheduler: TestCoroutineScheduler  
  
    @Before  
    fun setUp() {  
        testScheduler = TestCoroutineScheduler()  
        Dispatchers.setMain(StandardTestDispatcher(testScheduler))  
    }  
  
    @After  
    fun tearDown() {  
        Dispatchers.resetMain()  
    }  
  
    @Test  
    fun `should indicate loading when getting the data`() {  
        // given  
        val viewModel = TasksViewModel(InMemoryTasksRepository())  
        viewModel.getTasks()  
  
        // when  
        testScheduler.advanceTimeBy(500)  
  
        // then  
        assertTrue(viewModel.isLoading.value)  
  
        // when  
        testScheduler.runCurrent()  
  
        // then  
        assertFalse(viewModel.isLoading.value)  
    }  
}

Notice that we don’t even have to run our test body inside runTest anymore. That’s because we are not calling any suspending functions here - getTasks is a regular function.

Summary

I hope this post showed you how we can easily make our tests more powerful and controllable when we write code that uses coroutines.

I first learned the trick of launching a child coroutine in a test to control it from the outside in a book I highly recommend - Kotlin Coroutines: Deep Dive by Marcin Moskala.

If you have any questions, feel free to reach me on Twitter.

If like me, you have always wondered what is the difference between viewportWidth and width (or viewportHeight and height) in vector drawables and you tend to randomly tweak these attributes until your image looks right, this post is for you.

I will show you how these attributes differ using a simple example and some visualizations.

Example

To illustrate the difference, I created a simple app with one screen that contains a centered image filling as much content as it needs. Here is the code (in Jetpack Compose):

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        setContent {
            AppTheme {
                Box(
                    modifier = Modifier.fillMaxSize(),
                    contentAlignment = Alignment.Center
                ) {
                    Image(
                        painter = painterResource(id = R.drawable.rectangle),
                        contentDescription = null
                    )
                }
            }
        }
    }
}

And this is the code for the R.drawable.rectangle drawable:

<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="256dp"
    android:height="256dp"
    android:viewportWidth="36"
    android:viewportHeight="36">

    <path
        android:fillColor="#FFEB3B"
        android:pathData="M0,0 L36,0 L36,36 L0,36 z" />

    <path
        android:fillColor="#3F51B5"
        android:pathData="M2,2 L34,2 L34,34 L2,34 z" />

</vector>

If you need a refresher on how to interpret commands like M2,2 in pathData, here is a great post on Ray Wenderlich’s blog: link. But to give you a quick overview:

• M2,0 means Move to the point at position 2,0 (x,y).
• L36,0 means draw a Line from the current point to the point at 36,0 (x,y).
• z closes the path by drawing a straight line from the current position to the starting point.

Remember that 0,0 position is in the upper left corner. Moving to the right increases the X position and moving down increases the Y position (contrary to what you might be used to).

Both paths in the drawable above define a rectangle. The first path draws a yellow rectangle that covers the entire available space, while the second path draws a slightly smaller blue rectangle on top of the first one.

This is what the rendered image looks like:

As you can see, height and width attributes were both set to “256dp” and viewportWidth, as well as viewportHeight, to “36”.

Notice that height and width values end with “dp”. It’s because they define the intrinsic size of the drawable. In simpler words, if you give this drawable to an ImageView that covers as much space as it needs, that ImageView will have the exact same size as the drawable. That’s why in the screenshot above, the rendered image has a size of 256dp x 256dp (just like height and width values).

Conversely, viewportWidth and viewportHeight define the canvas size upon which we draw our pixels. All of our commands in pathData use coordinates from this space.

Let’s take a look at the pathData for our blue rectangle:

android:pathData="M2,2 L34,2 L34,34 L2,34 z"

As you can see, all commands here use points that are contained in a space defined by viewportWidth and viewportHeight (which is 36 x 36).

Below I marked some of the relevant coordinates:

Now let’s see what happens when I change viewportWidth and viewportHeight to “48” (and modify the yellow rectangle’s pathData to still cover the entire space as in the previous example).

<?xml version="1.0" encoding="utf-8"?>
<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="256dp"
    android:height="256dp"
    android:viewportWidth="48"
    android:viewportHeight="48">

    <path
        android:fillColor="#FFEB3B"
        android:pathData="M0,0 L48,0 L48,48 L0,48 z" />

    <path
        android:fillColor="#3F51B5"
        android:pathData="M2,2 L34,2 L34,34 L2,34 z" />

</vector>

Here is the rendered result:

The image takes the same amount of space on the screen as before, but the blue rectangle is now smaller. This is because the width and height values stayed the same (“256dp”), but the coordinate space has changed affecting all of our commands responsible for drawing our paths.

This can be better seen in the below image with highlighted points:

Summary

To summarize, the difference between size and viewport size is that the former reports its values (width and height) to the outside world, whereas the latter defines an “internal” space that is the coordinate space of our pathData.

If you are given a vector drawable (or svg) from a designer, remember not to change viewportWidth and viewportHeight attributes. They define the size of the canvas and all pathData commands use this coordinate space. If you change them, your image might become distorted. Instead, if you want to manipulate the image’s size, just use width and height.

In this post, I would like to show you how you can change the status bar and navigation bar colors using Compose, without having to modify any XML files.

Before Jetpack Compose, to specify the bar colors, we would traditionally modify the themes.xml file like this:

<resources>
    <style name="Theme.BarColors" parent="android:Theme.Material.Light.NoActionBar">
        <item name="android:statusBarColor">@color/purple_700</item>
        <item name="android:navigationBarColor">@color/purple_700</item>
    </style>
</resources>

As you can guess, the android:statusBarColor and android:navigationBarColor attributes affect the status bar color and navigation bar color, respectively.

Additionally, we could specify android:windowLightStatusBar (to make the icons on the status bar dark) or android:windowLightNavigationBar (similarly for navigation bar). Unfortunately, the latter requires API level 27. It forces us to override this attribute in another themes.xml file under the values-27 folder. It can lead to quite a messy structure when we have a lot of attributes like this. It can get even worse when we decide to support a dark theme.

Luckily, with Compose, there is another way of doing this.

Solution

For this example, I created a simple screen using Compose that displays centered text on a Surface:

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
		
        setContent {
            BarColorsTheme {
                Surface {
                    Text(
                        modifier = Modifier
                            .fillMaxSize()
                            .wrapContentHeight(),
                        textAlign = TextAlign.Center,
                        style = MaterialTheme.typography.h3,
                        text = "Hello Android!",
                    )
                }
            }
        }
    }
}

The BarColorsTheme (where BarColors is the name of the app) that wraps everything is a composable function that is created for you when you use the Empty Compose Activity template from the project wizard:

This is what it looks like:

private val DarkColorPalette = darkColors(
    primary = Purple200,
    primaryVariant = Purple700,
    secondary = Teal200
)

private val LightColorPalette = lightColors(
    primary = Purple500,
    primaryVariant = Purple700,
    secondary = Teal200
)

@Composable
fun BarColorsTheme(darkTheme: Boolean = isSystemInDarkTheme(), content: @Composable () -> Unit) {
    val colors = if (darkTheme) {
        DarkColorPalette
    } else {
        LightColorPalette
    }

    MaterialTheme(
        colors = colors,
        typography = Typography,
        shapes = Shapes,
        content = content
    )
}

The BarColorsTheme serves as a root composable that specifies the proper color palette (based on whether the dark theme is enabled), typography, and shapes for the entire hierarchy.

Because it is a root composable in our app, we can use this place to specify the system bar colors. Here is how we can do that:

@Composable  
fun BarColorsTheme(darkTheme: Boolean = isSystemInDarkTheme(), content: @Composable () -> Unit) {  
    // ...
    val view = LocalView.current  
    if (!view.isInEditMode) {  
        SideEffect {  
            val window = (view.context as Activity).window  
            window.statusBarColor = colors.primary.toArgb()  
            window.navigationBarColor = colors.primary.toArgb()  
  
            WindowCompat.getInsetsController(window, view)  
                .isAppearanceLightStatusBars = darkTheme  
            WindowCompat.getInsetsController(window, view)  
                .isAppearanceLightNavigationBars = darkTheme  
        }  
    }  
    // ...
}

We use the window object associated with our activity and modify the appropriate properties - statusBarColor and navigationBarColor. We use a primary color from the current palette (in this case it’s a shade of purple).

Additionally, we use WindowCompat to make the status bar and navigation bar icons light or dark, depending on the value of the darkTheme variable. A nice benefit of using WindowCompat is that we don’t have to check the API level before executing those methods. Behind the scenes, they will have no effect on unsupported APIs.

After making those changes and running the app, we get the desired effect:

Notice the use of SideEffect here. A SideEffect runs after every recomposition. Thanks to this, the system bar colors will be automatically updated to correct values when a user enables the dark theme, without having to reopen the app:

Summary

With Jetpack Compose, specifying system bar colors that adapt to the current theme is quite simple. All of the relevant code sits in one place. We no longer have to create different themes.xml files and override specific attributes.

I hope you found this post interesting. If you have any questions, feel free to reach me on Twitter.

In this post, I would like to write about an interesting concept I learned while reading Designing Data-Intensive Applications by Martin Kleppmann. More specifically, it’s a story of how Twitter handled some of its scalability challenges related to users’ personalized timelines. If you work on an application with some sort of a personalized feed/timeline for each user, the idea introduced here might help you improve the performance or give you inspiration for your next app’s architecture.

Scaling timelines

In November 2012, at a conference in San Francisco, Raffi Krikorian published some data about two of Twitter’s main operations:

• Post tweet - a user can post a new tweet to their followers (4,6k requests/sec on average, over 12k requests/sec at peak).
• Home timeline - a user can view tweets posted by the people they follow (300k requests/sec).

With modern databases, handling 12,000 write requests is achievable fairly easily. But at Twitter, the challenge came not with the volume, but due to so-called fan-out. In transaction processing systems, this term is used to describe the number of requests to other services that need to be made to serve one incoming request. On Twitter, each user follows many people and each user is followed by many people. This means that when a new tweet is published, it needs to be delivered to all of the author’s followers. In some cases (e.g. celebrities with many followers), there might be a lot of work to do.

On a high level, there are two ways of implementing the two operations mentioned above. Let’s examine both of them.

Traditional approach with relational schema

This is probably the first approach that comes to most developers’ minds. The idea is relatively simple. We need some kind of storage for all posted tweets. When a new tweet is posted, it’s simply inserted into this global collection of tweets. When a user opens the website and requests their home timeline, all the tweets from all the people they follow are merged and served on demand. In a traditional relational database, you might have three tables to handle this scenario: users, tweets, and follows.

• users table

• tweets table

• follows table

Then, to get all the relevant tweets to assemble a user’s timeline, the SQL query could look like this:

SELECT
    tweets.*,
    users.*
FROM
    tweets
    JOIN users ON tweets.user_id = users.id
    JOIN follows ON follows.followee_id = users.id
WHERE
    follows.follower_id = CURRENT_USER

The biggest problem here is that we have to execute the above query every time we want to display a timeline for any user. It’s not hard to imagine the huge amount of work required when there are a lot of users on the platform with a substantial number of people they follow frequently accessing the website.

The first version of Twitter used this approach, but the system struggled to keep up with the load of home timeline queries. The number of users on the platform kept growing, so they had to introduce another solution.

Maintaining a cache for individual timelines

Here, the basic idea is that we prepare, or cache, each user’s home timeline ahead of time so that when it’s requested, no additional work is required. When a user posts a tweet, besides being stored in a table, it’s immediately inserted into timeline caches for all of their followers. Thanks to this, reading a timeline is very cheap, because it has already been computed - it’s enough to just read from the cache. There is no need for any other expensive database operations. This concept is visualized in the image below.

When it comes to actual tools that you could use to implement the timeline caching mechanism, a great option would be a very popular, open-source, in-memory data store called Redis.

However, while reading all relevant tweets for each user is very cheap right now, there is one downside of this approach. Posting a tweet now requires a lot of additional work. Besides storing it in a table, it has to be inserted into many other caches. The average number of followers per user is 75, which means 4,6k new tweets per second becomes 345k writes per second to the home timeline caches (4,6k * 75).

But the average is affected mainly by users with many followers (there are some with more than 30 million). The majority of users have much fewer followers. This means that the extra work required for the fan-out when posting a new tweet is only noticeable for that small number of users with a very large number of followers.

For this reason, Twitter moved to a hybrid approach to take the best of both worlds. Tweets from “regular” users continue to be fanned-out to timeline caches, as illustrated above, while tweets from celebrities are excepted from that process. When a home timeline is requested, tweets from celebrities are fetched separately from the database and merged with what’s inside the user’s cache.

Summary

If you found this story interesting, you might enjoy reading the book it was mentioned in - Designing Data-Intensive Applications. It’s a good combination of the theory behind many enterprise-level tools and practical engineering. It compares many tools and approaches, including their strengths and weaknesses, to make it easier for us to decide what’s best for our applications.

Spatie created an extremely useful library for working with any type of media in Laravel, called Laravel-medialibrary. It allows you to associate all sorts of files with Eloquent models and organize them into collections. It also has a simple fluent API that makes it effortless and pleasant to use.

Additionally, the package supports different filesystems (like Amazon S3) and can manipulate all uploaded images or pdfs according to the specified configuration. It’s possible to resize, reformat, apply special effects, and much more. Check out the documentation to learn about everything it can do for you.

However, the feature I like most about this library is that it can automatically create responsive variants of images. The moment you upload an image, the media library will create resized versions of the original image suitable for different screen sizes, as well as a tiny blurred one used for progressive loading (which will be displayed before the full image is ready).

What’s even better, the package has support for generating a necessary HTML markup, automatically creating an img tag and specifying src, srcset, and sizes attributes for you.

To display your image in a Blade file, all you have to do is output the Media object:

<h1>My blog post</h1>

{{ $post->getFirstMedia() }}

It’s very convenient, isn’t it? But what about Vue? In a component’s template, we can’t just output the object like in a Blade file.

Luckily, there is a way to make responsive images work in Vue.

Solution

The Media object implements the Htmlable interface, defined as follows:

interface Htmlable
{
    /**
     * Get content as a string of HTML.
     *
     * @return string
     */
    public function toHtml();
}

Internally, the Blade compiler will use the toHtml() method when it encounters a Media object while rendering the view.

This method is public, so nothing stops us from using it ourselves.

In a controller that’s responsible for providing data used by your Vue component, simply return the result of the toHtml() method:

namespace App\Http\Controllers;

use App\Http\Controllers\Controller;

class PostController extends Controller
{
    public function show(Post $post)
    {
        return [
            'title' => $post->title,
            'content' => $post->content,
            'img' => $post->getFirstMedia()->toHtml()
        ];
    }
}

Then, inside your Vue component, output the image using the v-html directive by providing the data received from the controller:

<template>
    <div v-html="img"></div>
</template>

And that’s it! Now, your image should be correctly displayed based on the screen size.

Summary

If you’ve been trying to take advantage of the simplicity of responsive images provided by the media library inside a Vue component, I hope this post saved you some time. If you have some questions, feel free to reach me on Twitter.

At Google I/O 2017, the Android Framework team introduced Architecture Components - a set of tools that significantly changed how many Android developers write and structure their apps. This post will focus on the internals of one of them - the ViewModel.

The ViewModel class is designed to store and manage UI-related data in a lifecycle conscious way. The ViewModel class allows data to survive configuration changes such as screen rotations.

Usually, one of the first things we find out when learning Android development is that activities get re-created after configuration changes. When it happens, we lose all initialized variables and the view gets re-rendered. We get a completely new activity instance.

So when I first heard about the ViewModel class and what it can do, some questions immediately popped up in my head:

1. How is it possible that ViewModels survive configuration changes given that the activities that hold them get destroyed and created again?
2. How does the newly created activity instance access a reference to the same ViewModel used by the previous activity instance?

Recently I decided to find answers to those questions. I chose to dive into the Android’s source code and explore the ViewModel’s implementation details.

Creating a ViewModel

Let’s start from the beginning. The recommended approach (at the time of writing this post) to create an instance of a ViewModel class inside an activity is to use the following code:

private val viewModel: MyViewModel by viewModels()

where by viewModels() is a syntax representing Kotlin delegated properties.

The viewModels() function returns a Lazy<T> instance, which serves as a lazy property delegate. This basically means that a MyViewModel instance is going to be obtained on first access to the viewModel variable (not when this variable is declared).

Here is what the viewModels() function looks like:

public inline fun <reified VM : ViewModel> ComponentActivity.viewModels(  
    noinline factoryProducer: (() -> Factory)? = null  
): Lazy<VM> {  
    val factoryPromise = factoryProducer ?: {
        defaultViewModelProviderFactory  
    }  
  
    return ViewModelLazy(VM::class, { viewModelStore }, factoryPromise)  
}

It accepts a single parameter - a factoryProducer. If it’s specified, the ViewModelProvider.Factory returned by this lambda will be used to create a ViewModel instance. If not, the default one will be used.

The function returns an instance of the ViewModelLazy class which is an implementation of the Lazy interface that I mentioned earlier.

The ViewModelLazy’s constructor takes three parameters. The first one represents a class of the ViewModel we want to create an instance of. The third one is a lambda that returns a ViewModelProvider.Factory. It’s the same one as the one passed to the viewModels() function (or a default one).

The second parameter is interesting. It’s a lambda that returns a ViewModelStore. Here, a lambda is passed that returns a viewModelStore variable. Where is this variable coming from?

As you can see, the viewModels() function is an extension function on the ComponentActivity class. So when we call viewModelStore in Kotlin, we effectively invoke the getViewModelStore() method from the ComponentActivity (written in Java) that returns its member variable called mViewModelStore:

public ViewModelStore getViewModelStore() {
    if (getApplication() == null) {
        throw new IllegalStateException("Your activity is not yet attached to the "
                + "Application instance. You can't request ViewModel before onCreate call.");
    }
    ensureViewModelStore();
    return mViewModelStore;
}

The reason why the ComponentActivity has this method is that it implements the ViewModelStoreOwner interface. This is its declaration:

/**
 * A scope that owns {@link ViewModelStore}.
 * <p>
 * A responsibility of an implementation of this interface is to retain owned ViewModelStore
 * during the configuration changes and call {@link ViewModelStore#clear()}, when this scope is
 * going to be destroyed.
 *
 * @see ViewTreeViewModelStoreOwner
 */
@SuppressWarnings("WeakerAccess")
public interface ViewModelStoreOwner {
    /**
     * Returns owned {@link ViewModelStore}
     *
     * @return a {@code ViewModelStore}
     */
    @NonNull
    ViewModelStore getViewModelStore();
}

Now you may ask: “What is ViewModelStore?”

As the name suggests, the ViewModelStore class is responsible for storing instances of ViewModels. This is what this class looks like:

public class ViewModelStore {

    private final HashMap<String, ViewModel> mMap = new HashMap<>();

    final void put(String key, ViewModel viewModel) {
        ViewModel oldViewModel = mMap.put(key, viewModel);
        if (oldViewModel != null) {
            oldViewModel.onCleared();
        }
    }

    final ViewModel get(String key) {
        return mMap.get(key);
    }

    Set<String> keys() {
        return new HashSet<>(mMap.keySet());
    }

    public final void clear() {
        for (ViewModel vm : mMap.values()) {
            vm.clear();
        }
        mMap.clear();
    }
}

This relatively simple class serves as a wrapper around HashMap<String, ViewModel>. This is the ultimate place where all ViewModels associated with an activity or a fragment are stored.

Now, since we know what the ViewModelStore is, it’s clear what the ViewModelStoreOwner interface is used for. A class that implements it indicates to the outside world that it owns an instance of the ViewModelStore.

This is a list of all classes in the Android framework that implement the getViewModelStore() method from the ViewModelStoreOwner interface. Basically, it’s only activities and fragments.

Let’s look at the documentation from the ViewModelStoreOwner interface, particularly this fragment:

A responsibility of an implementation of this interface is to retain owned ViewModelStore during the configuration changes and call ViewModelStore#clear(), when this scope is going to be destroyed.

This gives us a valuable hint. It means that it’s the activity’s (or fragment’s) responsibility to make sure that its ViewModelStore (along with all ViewModels) is preserved across configuration changes.

How do activities handle that? We will come back to this question in the next section.

For now, let’s go back again to the viewModels() function and see what the newly constructed ViewModelLazy class looks like:

public class ViewModelLazy<VM : ViewModel> (
    private val viewModelClass: KClass<VM>,
    private val storeProducer: () -> ViewModelStore,
    private val factoryProducer: () -> ViewModelProvider.Factory
) : Lazy<VM> {
    private var cached: VM? = null

    override val value: VM
        get() {
            val viewModel = cached
            return if (viewModel == null) {
                val factory = factoryProducer()
                val store = storeProducer()
                ViewModelProvider(store, factory).get(viewModelClass.java).also {
                    cached = it
                }
            } else {
                viewModel
            }
        }

    override fun isInitialized(): Boolean = cached != null
}

Most of the code in this class just deals with caching the object and making sure that the same instance is returned on subsequent calls.

The most relevant fragment is this one:

ViewModelProvider(store, factory).get(viewModelClass.java)

It creates an instance of the ViewModelProvider class by passing the required parameters (that were created by executing the lambdas passed to the constructor) and calls get() to obtain our ViewModel.

Here’s the get() method:

public open operator fun <T : ViewModel> get(modelClass: Class<T>): T {
    val canonicalName = modelClass.canonicalName
        ?: throw IllegalArgumentException("Local and anonymous classes can not be ViewModels")
    return get("$DEFAULT_KEY:$canonicalName", modelClass)
}

This methods call another get() method that additionally accepts a key as a parameter. In this case, the key is a concatenated string consisting of two parts separated by a colon:

• A DEFAULT_KEY value (which is "androidx.lifecycle.ViewModelProvider.DefaultKey").
• A canonical name of our ViewModel class.

This key will be used to identify our ViewModel object in the HashMap<String, ViewModel> that we saw earlier in the ViewModelStore class.

Here’s the second get() method:

public open operator fun <T : ViewModel> get(key: String, modelClass: Class<T>): T {
    var viewModel = store[key]
    if (modelClass.isInstance(viewModel)) {
        (factory as? OnRequeryFactory)?.onRequery(viewModel)
        return viewModel as T
    } else {
        @Suppress("ControlFlowWithEmptyBody")
        if (viewModel != null) {
            // TODO: log a warning.
        }
    }
    viewModel = if (factory is KeyedFactory) {
        factory.create(key, modelClass)
    } else {
        factory.create(modelClass)
    }
    store.put(key, viewModel)
    return viewModel
}