DEV Community: Zarah Dominguez

Seeing What Talkback Sees 🔍

Zarah Dominguez — Mon, 13 Sep 2021 00:00:00 +0000

One of the things we should be doing as Android developers is to ensure that our apps are as accessible as possible. There are a bunch of talks and articles that discuss the motivations behind current MDC a11y support, the basic steps to support a11y, testing overviews, even creating your own a11y service!

There’s a lot of resources that tell me what I should do, but what I found sorely lacking is information on helping me figure out what to do when something goes wrong (and knowing me, something is always bound to go wrong).

For example, this is the upper part of my app’s homepage.

Talkback says "2 items in cart"

When the cart action menu item is focused, we expect Talkback to announce how many items are currently in the cart. However I noticed that sometimes Talkback just out of the blue says the number (and just the number) after announcing “2 items in cart”. Weird!

If only I could dive into what Talkback “sees” so I could figure out how to fix the problem and make our Talkback announcements less confusing. I haven’t found any mention of how to do this in the official Android docs, and it is by sheer luck that I stumbled upon this ✨ amazing ✨ article by Midori Bowen from 2018(!).

Wait, what! 😻

It turns out that deep in the bowels of Talkback’s developer settings is an option to “Enable node tree debugging”. Midori links to the Android documentation on enabling this setting but that page has since been deleted. 😿

Turn it on! (While you're there, turn on "Display speech output" as well if you prefer. This will put up a Toast of the Talkback announcements)

The “node tree” being referred to here is basically how Talkback interprets your view hierarchy. Having visibility on this would surely give us a lot of insight into what is going on under the hood.

Follow the steps outlined in the OG post to enable node tree debugging. Some things have changed in Android and in Talkback since Midori’s post, but in general the steps in there should give you an idea of how to enable logging. For instance, instead of looking for “Unassigned”, assignable gestures are now subtitled “Tap to assign”. On some devices, Talkback allows multi-finger gestures, so there’s a lot of options to use to trigger node tree log dumps. If a gesture already has an action, you can still overwrite it if you wish to do so.

I settled on "Tap with 3 fingers"

What do we have here? 🤔

We can now trigger a dump of the node tree on any screen by using the gesture we have set in Talkback.

Talkback will tell you it has been done

At this point I want to reiterate to please do not be like me and spend an hour looking for where the logs actually are (I forgot that I have Logcat filters on 🤦‍♀️). They are in Logcat, with the tag TreeDebug.

Here’s the partial output of the node tree (timestamps remove for verbosity):

The first few lines (lines 2-9) pertain to the status bar stuff, so let’s just ignore that. Our application’s contents start at line 10 (type=TYPE_APPLICATION) with all the views on the screen in the following lines. Each ViewGroup is tabbed which is really helpful in figuring out how each node maps to the view hierarchy. There’s a lot of information here and some things have changed since Midori’s post, so I thought it would be good to review what we can see in the logs. Let’s take line 18 for example:

(1100966)652.Switch:(668, 225 - 800, 357):CONTENT{See only Specials}:STATE{OFF}:not checked(action:FOCUS/A11Y_FOCUS/CLICK):focusable:clickable

Content	Notes
`(1100966)`	The node’s hashcode (which the Talkback source code refers to as a “poor man’s ID”)
`652`	The window ID
`Switch`	The node’s class name (usually type of widget)
`invisible`	This is not shown in this particular line – it is appended only if the view is invisible
`(668, 225 - 800, 357)`	Coordinates of the view on the screen, `(Left, Top - Right, Bottom)`
`TEXT{xxx}`	Text that’s visible to the user (this `Switch` is unlabeled so this does not appear in this line)
`CONTENT{See only Specials}`	The content description provided by the widget
`STATE{OFF}`	If a widget is stateful, such as this `Switch`, the current state
`(action:FOCUS/A11Y_FOCUS/CLICK)`	Actions available on the node, as defined by `AccessibilityNodeInfoCompat`
`:focusable:clickable`	All other properties of the widget follow, delimited by `:`. Possible values, in the order that they may appear are `focusable`, `screenReaderfocusable`, `focused`, `selected`, `scrollable`, `clickable`, `longClickable`, `accessibilityFocused`, `supportsTextLocation`, `disabled`
“Collection” information	If things are in a `RecyclerView`

The screen is actually a RecyclerView, so let’s also take a look at what information we receive:

At the end of:

Line	Notes
1	The `RecyclerView` node itself, we see `:collection:R10C2`. This indicates that this is a collection of views consisting of 10 rows, with two columns in each row. Talkback will announce the collection information the first time an item in the collection is selected. For example, if we tap on the Caramello Koala tile, Talkback will announce all the product information (based on the content description of the `ViewGroup`) plus the location of the tile and the collection information (“Row 1, Column 2, In grid, 10 rows, 2 columns”).
2	The item on the top right, we see `:item#r0c0`. This is the row- and column-index (starting at 0) of the item relative to the list.
5	The item on the top left, we see `:item#r0c1`. Talkback will announce this item’s location as “Column 2”.
9, 10	The `Button` is marked as `:invisible` because it’s there, but not visible on the screen.

I was able to glean all this information from the LogTree file in Talkback’s repo.

Note that aside from logging the node tree, Talkback also logs the traversal order which may be useful when trying to figure out the order in which elements on the screen gets focus.

Fixing our issue… maybe 👀

Going back to our original issue, the node tree gives us a clue (the cart menu item is in most screens of my app):

(1094239)652.ViewGroup:(948, 77 - 1080, 209):CONTENT{Cart: 2 items in Cart}(action:FOCUS/A11Y_FOCUS/CLICK):focusable:clickable
  (1095200)652.TextView:(1008, 107 - 1023, 140):TEXT{2}(action:A11Y_FOCUS):supportsTextLocation

AHA! It looks like both the ViewGroup as a whole and the TextView itself can have focus (it looks like the TextView itself does not have a value for CONTENT, which is what Talkback announces though), which may explain why I sometimes hear just the number?

I guess I still don’t have a definitive answer, but setting android:importantForAccessibility="no" on the TextView should not present a problem since enough context is already given to the user when the ViewGroup gets focus.

I hope that as more and more people become a11y allies that we also get more attention on a11y tooling, and more technical articles focused on supporting a11y beyond the basics. For instance, did you know that we can change what Talkback says to provide more context on actionable content? For example, when selecting this ViewGroup:

Double-tapping will bring the user to the edit store or delivery address screen

Talkback will announce “Double-tap to change” instead of the default “Double-tap to activate”. The former gives the user more context about what is expected to happen when they interact with the element. Come to think of it, that’s a good idea for our next a11y post! See you then! 👌

Enforcing Team Rules with Lint: Tests 🧐

Zarah Dominguez — Fri, 20 Nov 2020 00:00:00 +0000

A few months ago, my team came upon an agreement that when leaving a TODO anywhere in our code, we need to always provide several things:

the person who is expected to address the TODO
date when the TODO was left
a comment or explanation on what needs to be done

I created a live template to support adherence to this rule, but why not go one step further and integrate the rule into our daily workflow?

We have previously seen:

Having tests for our custom Lint rule is really important. We do not want Lint to flag errors, uhm, erroneously. It results in frustration and users might just turn off our rule.

Serving up files 💁

Lint checks run on files, so for each of our test cases we need to provide mock files.

Lint provides a TestFile API that allows us to create these mock files inline.

TestFiles.java(
    """
        package test.pkg;
        public class TestClass1 {
            // In a comment, mentioning "lint" has no effect
         }
    """
)


TestFiles.kotlin(
     """
        package test.pkg
        class TestClass {
            // In a comment, mentioning "lint" has no effect
        }
    """

I am using raw strings so that I do not have to worry about escaping special characters.

It also gives us very nice syntax highlighting!

Furthermore, if you choose “Edit Kotlin Fragment” from the hint, Android Studio will open up a file editor. Any changes you make in this editor will immediately reflect in your TestFile. Pretty cool!

Let’s get testing 🔬

The gateway to our test cases is TestLintTask. We need to provide it the following:

files we want to run our checks on
the issue we are testing against
expected result

@Test
fun testKotlinFileNormalComment() {
    TestLintTask.lint()
        .files(
            TestFiles.kotlin(
                """
                    package test.pkg

                    class TestClass {
                        // In a comment, mentioning "lint" has no effect
                    }
                """
            )
        )
        .issues(TodoDetector.ISSUE)
        .run()
        .expect("No warnings.")
}

Note that we have the option here of using expect("No warnings.") or expectClean().

For the test cases where we expect an error to occur, we need to put in the text that Lint spits out (i.e. similar to what you see in the console when running .gradlew :app:lintDebug). The trickiest thing about this is that the string has to match exactly, including where the squiggly lines are.

The easiest way to do this is to pass an empty string to expect() and let the test fail. You can then copy-paste the error message into your test.

Retrieving the message for an error scenario

I wrote a few tests for the detector covering Java and Kotlin files, incorrect date formats, and “TODO” casing. You can find them all here.

Bringing it all together 🤝

Now that we have written our tests, it’s finally time to integrate our Lint rule into our app!

First we need to create our IssueRegistry to let Lint know about our custom rule. We also need to provide an API value; for custom rules we can use the constant defined by the Lint API.

@Suppress("UnstableApiUsage")
class IssueRegistry : IssueRegistry() {
    override val issues: List<Issue> = listOf(
        TodoDetector.ISSUE
    )

    override val api = CURRENT_API
}

We then register our IssueRegistry by creating a file with the fully qualified name of our file under a META-INF/services/ folder:

src/main/resources/META-INF/services/dev.zarah.lint.checks.IssueRegistry

🙋 Most posts mention that adding this registry is enough, and I am probably doing something wrong but I found out that for my project, I still have to include my IssueRegistry in the Manifest by adding this to my build.gradle.kts file:

tasks {
  jar {
    manifest {
      attributes(
          "Lint-Registry-v2" to "dev.zarah.lint.checks.IssueRegistry"
      )
    }
  }
}

We have set up everything and now it’s time to consume our custom lint rule! In the modules where you want the rules applied, add a lintChecks entry in the dependencies closure, build your project, and everything should be good to go! 🏃‍♀️

dependencies {
    lintChecks project(':checks')
}

Seeing it in action 📽️

Finally! We have come to the end of our journey! Here’s our detector in action:

Custom lint rule with quickfix

The source code for this Lint series is available on Github (diff).

🙇‍♀️ I have learned so many things whilst I was doing this task.

As I mentioned on Twitter, there’s barely any public documentation at all. The talks I’ve seen are way too advanced for me (for example, I needed to understand what PSI and UAST were before it clicked and most talks barely even define them).

There was a lot of trial and error, and so. much. guesswork. It was incredibly frustrating. Major props to Mike Evans who patiently guided me through the hours and hours of pair programming that we did. If he didn’t help, I wouldn’t even know where to start. Sure I can copy-paste from samples but I want to understand why things are done the way they are – that’s how I learn.

I probably have made wrong assumptions whilst writing these posts 🤷‍♀️ but again, no documentation so this is the best I could do. 😅

Anyway, what I want to say is, I usually only see the final output of other people’s work and sometimes I cannot help but feel jealous – how come they find it super easy whilst I’m out here crying because I don’t understand anything? I needed to remind myself that it’s okay to be frustrated, it’s okay to take your time to learn, and it’s okay to ask for help.

Enforcing Team Rules with Lint: Detectors 🕵️

Zarah Dominguez — Thu, 19 Nov 2020 00:00:00 +0000

A few months ago, my team came upon an agreement that when leaving a TODO anywhere in our code, we need to always provide several things:

the person who is expected to address the TODO
date when the TODO was left
a comment or explanation on what needs to be done

I created a live template to support adherence to this rule, but why not go one step further and integrate the rule into our daily workflow?

In this post, we build upon the foundations we have started.

Now that we have our module set up, we can start writing our detector.

As mentioned previously, detectors do the heavy lifting for our custom rule. To do so, it has to fulfil several roles:

Look for the relevant locations
Find issues, if any, in those locations
Report back any found issues to the user
Suggest fixes for issues, if possible

We will look at each of these roles in turn.

Coming to terms with Lint 🏛️

Before we dive into detectors, it is useful to understand a bit of Lint lingo. This took me a really long time to understand and it was really frustrating. To say that there is no documentation at all is not a lie, there is no one place I can link to. A lot of the information here I sort of cobbled together from all the talks, posts, and hours and hours of research on Lint.

When dealing with detectors, most things refer to something called UAST or PSI. For illustration purposes, let’s take this sample file from Florina Muntenescu’s gist:

package com.zdominguez.sdksandbox

/*
 * Copyright (C) 2018 The Android Open Source Project
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import android.graphics.Typeface
import android.text.TextPaint
import android.text.style.MetricAffectingSpan

/**
 * Span that changes the typeface of the text used to the one provided. The style set before will
 * be kept.
 */
open class CustomTypefaceSpan(private val font: Typeface?) : MetricAffectingSpan() {

    override fun updateMeasureState(textPaint: TextPaint) = update(textPaint)

    override fun updateDrawState(textPaint: TextPaint) = update(textPaint)

    private fun update(textPaint: TextPaint) {
        textPaint.apply {
            val old = typeface
            val oldStyle = old?.style ?: 0

            // keep the style set before
            val font = Typeface.create(font, oldStyle)
            typeface = font
        }
    }
}

PSI

PSI, or P rogram S tructure I nterface, is traditionally used by IntelliJ to model source files via elements. The PsiViewer plugin is really useful in helping you visualise what this means.

I like to think of PSI as the blueprint of the file. It shows each and every single element, including whitespaces and braces (it can even tell you if it’s a left brace or a right brace!)

PSI for the CustomTypefaceSpan Kotlin file

PSI for an XML file

UAST

UAST, or U niversal A bstract S yntax T ree, was created by Jetbrains to describe Java and Kotlin syntax trees. A syntax tree shows the hierarchical structure of our code, illustrating all the rules and constructs that the code will follow via nodes.

Partial UAST for the CustomTypefaceSpan Kotlin file

When dealing with UAST, we do not really care if we are looking at a Java file or a Kotlin file. Instead we see the logical branches in our code.

PSI vs UAST

It took a while for me to wrap my head around these concepts, and I finally sort of understood it with with an IKEA analogy. UAST is like the photos you see on the catalogue. It describes what the furniture is – a chest of drawers with white knobs, a shelf, it has a specific kind of door. PSI, on the other hand, is like the assembly instructions for that furniture. Get this plank, put a screw in here, a bolt there.

Just get on with it, Zarah

Let’s go ahead and make our detector:

import com.android.tools.lint.detector.api.Detector

@Suppress("UnstableApiUsage")
class TodoDetector : Detector() {
}

Detector is the base class of all detectors. It is marked as @Beta, so I added the @Suppress annotation there to confirm that yes, I know this might break.

Detector is pretty generic (except for ResourceXmlDetector), and we can get much more out of Lint if we can indicate what specific detector we need. There are a few specialised interfaces we can use depending on what type of thing we need to run our rule on:

Type	Note
BinaryResourceScanner	For scanning binaries like images, and resources inside `res/raw`
ClassScanner	For `.class` files
GradleScanner	For `.gradle` files
OtherFileScanner	Uhm, others
ResourceFolderScanner	For looking at resource folders (not the contents, just the folder!)
SourceCodeScanner	For scanning source code like Java or Kotlin files
XmlScanner	For XML files

For the purposes of our TODO detector, we will need to implement the SourceCodeScanner interface since we want to look at Java and Kotlin files:

@Suppress("UnstableApiUsage")
class TodoDetector : Detector(), SourceCodeScanner {

}

Being specific

There is another term that most talks on Lint mention a lot, and that is “visit”. I haven’t seen an exact accurate definition of the term, but from what I gather this is what we call the act of Lint getting to a particular UAST node or PSI element.

This means if we want to look at usages of a method for example, we need to “visit” methods and figure out if the issue exists there. If we want to write a rule that checks constraints in a layout file, then we probably need to “visit” XML attributes and values.

There is, indeed, a proper way to be specific in Lint about what locations we want to be visited. The Detector povides several methods for this. Note that MOST of them start with get but not all of them do. 😅

Available getApplicable* methods

All of these methods are available to you regardless of what kind of *Scanner interface our detector implements as they are all in the base Detector() class. We need to make sure to implement at least one of these methods to signal to Lint that we care about those locations.

Since we want to look at comments, the best fit for our usecase is getApplicableUastTypes().

Next we need to specify what specific kind of UAST node we are looking for. There is a UComment UAST type which sounds like exactly the type we need.

There is one caveat though – if we look at the generated UAST for our sample file, UComment does not make an appearance at all! However, we do see via PsiViewer that a PsiComment is present.

If we traverse the UAST backwards (upwards?), we eventually get to UFile which encompasses all the possible places that a comment can reside in. Perfect, let’s go ahead and use that as the UAST type we care about.

@Suppress("UnstableApiUsage")
class TodoDetector : Detector(), SourceCodeScanner {
    override fun getApplicableUastTypes(): List<Class<out UElement>> {
        return listOf(UFile::class.java)
    }
}

Receiving callbacks

Now that we have told Lint what kind of location we care about, we need to tell it to let us know if it encounters that location.

Again, there are numerous options available to us. Note that MOST of them of them start with visit, but not all of them do. 😅 😅

Available visit*** methods

In fact, judging by the names, none of these match what we need. Since we have selected that we care about UAST types, what we need is actually called createUastHandler(). Our next task is to create this handler:

override fun createUastHandler(context: JavaContext): UElementHandler {
    return TodoScanner(context)
}

A very important side note 🛑

It is important to remember that each of the getApplicable* methods map to a corresponding visit* method.

Let’s take this example from the ADS 2019 talk on Lint. We want to create a rule that prevents users from calling Log.wtf() anywhere in an app. In it, they are overriding getApplicableMethodNames() so the corresponding callback method to override is visitMethodCall().

Similarly, if we want to look at XML attributes we would override getApplicableAttributes() and the corresponding visitAttribute() callback. Alex Lockwood demonstrates this in this sample project.

It is extremely important to double check that you are using the correct combination because Lint will not tell you if are doing it incorrectly (i.e. everything will still compile). I haven’t found any documentation on the mapping of getApplicable* against visit* but this what I gather from my experiments:

`get*`	`visit*`	Framework examples
`applicableAnnotations`	`visitAnnotationUsage`	BanKeepAnnotation
`applicableSuperClasses`	`visitClass`	OnClickDetector
`getApplicableAsmNodeTypes`	`checkInstruction`	FieldGetterDetector
`getApplicableAttributes`	`visitAttribute`	DuplicateIdDetector
`getApplicableCallNames`	`checkCall`	LocaleDetector
`getApplicableCallOwners`	`getApplicableCallNames`	SecureRandomGeneratorDetector
`getApplicableConstructorTypes`	`visitConstructor`	DateFormatDetector
`getApplicableElements`	`visitElement`	InstantAppDetector
`getApplicableMethodNames`	`visitMethodCall`	ReadParcelableDetector
`getApplicablePsiTypes`	`createPsiVisitor`
`getApplicableReferenceNames`	`visitReference`	AlwaysShowActionDetector
`getApplicableUastTypes`	`createUastHandler`	OverdrawDetector

Implementing the scanner

I felt it worth the effor of understanding the relationship between get* and visit* methods because that same principle applies when implementing our handler.

When we defined our detector, we told Lint that we want to watch for UAST type of UFile and thus we must implement the appropriate callback in our scanner:

class TodoScanner(private val context: JavaContext) : UElementHandler() {

    override fun visitFile(node: UFile) {

    }
}

For each UAST type we provide in getApplicableUastTypes(), we should also have the corresponding the visit* implementations. I will not enumerate them here because ✨ there are a LOT ✨ but this time Lint actually helps you out!

For example, if we say:

override fun getApplicableUastTypes(): List<Class<out UElement>> {
    return listOf(UMethod::class.java, UClass::class.java, UFile::class.java)
}

We would need to implement visitMethod, visitClass, and visitFile in our scanner. Lint will tell you at runtime if it encounters a particular UAST type but cannot find the appropriate callback.

If like me you have no idea what the possible U-values are or how a file’s UAST would look like, it is quite challenging to figure out what to do at this point. Unfortunately there is no UastViewer that I know of, and the only way to explore this realm is through good old-fashioned println.

override fun visitFile(node: UFile) {
    val nodesString = node.asRecursiveLogString()
    println(nodesString)
}

This gives you a string with the full UAST structure of the file being analysed.

Finding fault

Now that we have a better understanding of what is going on, let’s go ahead and implement the soul of our scanner:

override fun visitFile(node: UFile) {

    val allComments = node.allCommentsInFile
    allComments.forEach { comment ->
        val commentText = comment.text

        // Ignore regular comments that are not TODOs
        // If we find a TODO that does not follow the convention, show an error
        if (commentText.contains("TODO", ignoreCase = true) && !isValidComment(
                commentText)) {
            reportUsage(context, comment)
        }
    }
}

The isValid method checks if the comment follows our team rules:

private fun isValidComment(commentText: String): Boolean {
    val regex = Regex("//\\s+TODO-\\w*\\s+\\(\\d{8}\\):.*")
    return commentText.matches(regex)
}

And if it does not, report this as an issue.

Responsible reporting 📢

When we find a comment that violates the contract, we want to give our users a clear definition of what went wrong and how to fix the issue.

Remember the anatomy of an issue we talked about in the previous post? Let’s use that knowledge to define our issue:

val ISSUE: Issue = Issue.create(
    id = "UnassignedTodo",
    briefDescription = "TODO with no assignee",
    explanation =
    """
        This check makes sure that each TODO is assigned to somebody.
    """.trimIndent(),
    category = Category.CORRECTNESS,
    priority = 3,
    severity = Severity.ERROR,
    implementation = IMPLEMENTATION
)

The last parameter required by Issue.create() is an Implementation that maps the issue being reported with the detector responsible for finding that issue.

An Implementation requires a Scope – which tells Lint what kind of files our implementation is interested in.

private val IMPLEMENTATION = Implementation(
    TodoDetector::class.java,
    Scope.JAVA_FILE_SCOPE
)

The naming is indeed misleading but JAVA_FILE_SCOPE means both Java and Kotlin files will be considered for our rule when running Lint.

This means at this point in our implementation it is absolutely critical that these information need to be compatible:

✅ the interface we are implementing for our detector

✅ the overridden getApplicable* method

✅ the overridden visit* method

✅ (since we using UAST type) the overridden visit* methods in our UElementHandler

✅ the Scope of the issue’s implementation

A little help from my friends

We can help our users get more value out of our custom Lint rule by helping them fix the issue. Lint allows us to provide a quickfix option and users can press SHIFT+ALT+ENTER (or ALT+ENTER then ENTER) and apply the changes we have proposed.

For our detector, we want to format the comment properly.

// TODO This is an improperly formatted comment

A comment like the one above would be flagged by our detector as improperly formatted (remember we look for the TODO string). To fix it, we would need to add the user’s name and today’s date. Luckily LintFix allows us to do it pretty easily:

// Look for the instance of the "TODO" literal
val oldPattern = Regex("TODO|todo")

// Our proposed fix concatenates the user's name
// and today's date in the correct format
val replacementText = "TODO-${System.getProperty("user.name")} " +
    "(${
        LocalDate.now()
            .format(DateTimeFormatter.ofPattern("yyyyMMdd"))
    }):"

val quickfixData = LintFix.create()
    .name("Assign this TODO")
    .replace()
    .pattern(oldPattern.pattern)
    .with(replacementText)
    .robot(true) // Can be applied automatically.
    .independent(true) // Does not conflict with other auto-fixes.
    .build()

Now that we have the issue, implementation, and quickfix created, the only thing remaining is to tell Lint where to indicate that an issue was encountered. It is important to provide an accurate location because this tells the IDE where to show the error:

And where to put the red squiggly lines in the Lint report:

For this rule, it’s good enough for me to highlight the full comment. We can now finish up our reportUsage method:

private fun reportUsage(
    context: JavaContext,
    comment: UComment
) {
    context.report(
        issue = Companion.ISSUE,
        location = context.getLocation(comment),
        message = "Please make sure to assign the TODO, include today's date in YYYYMMDD format, and the comment is properly formatted.",
        quickfixData = quickfixData
    )
}

We have finally finished our detector! 💪 This has been an honest-to-goodness brain dump. Writing my first Lint rule has truly been a challenge and there are stretches of time where I was literally staring at the screen periodically yelling WHAT at no one in particular. Good thing we’ve all been working from home. 😅

In the next post in this series, we get to write some tests and if everything goes well, we get to actually use our detector! Stay tuned!

Enforcing Team Rules with Lint 👩‍🔧

Zarah Dominguez — Wed, 18 Nov 2020 00:00:00 +0000

A few months ago, my team came upon an agreement that when leaving a TODO anywhere in our code, we need to always provide several things:

the person who is expected to address the TODO
date when the TODO was left
a comment or explanation on what needs to be done

But memories fade and sometimes people forget. So I made a live template to make it easier for everyone to adhere to the rule. A simple ALT+ENTER and tada, there’s the TODO template for you to fill in:

Custom template in action

If you’re curious to know more about how this was done, I wrote about implementing a live template here.

Everything seemed fine and dandy, but after a few months I noticed that even though we have the template, people occasionally ✨ forget ✨ to fill it in.

We can keep on reminding people to use the template, but I don’t want to be that annoying person saying things over and over. Wouldn’t it be better if we incorporate this team rule into the developer workflow? So it got me thinking, why not write a custom Lint rule to remove the human intervention and let the tool do its job?

A great idea

Lint is a static analyser and the built-in rules are great! They help identify common problems (forgetting to call super()), possible bugs (forgetting to constrain a view), or potential optimisations (detecting overdraw) in our code and gives us the chance to correct them immediately.

These rules are flexible. We can pick and choose which ones we want to exclude from running, we can choose to fail the build if something goes wrong, we can even identify a specific issue to be ignored.

There are a lot of great talks out there that give an overview of Lint’s history, philosophy, and features especially this one by Tor Norbye from KotlinConf 2017.

Lint has been around for a while, and support for writing our own Lint checks has also been around for a while, so surely there are references out there right? There’s this good overview by John Rodriguez from Droidcon NYC 2017 and this very informational talk by Alan Viverette and Rahul Ravikumar from Android Dev Summit 2019.

They make it look easy enough. Surely I can do this. 💃

The worst idea

Turns out that it is easy enough… if you know what you’re doing. And ooooh mama I DO NOT know what I was doing.

The Android tools site looks abandoned 🙈. The sample rules are a bit basic but aside from helping me figure out how to set things up, it doesn’t really tell me anything.

But Zarah, you say, why not just copy off of the ones in the platform? I did, and there are HUNDREDS of them. It is overwhelming to figure out which one to look at first.

I guarantee you that if someone asks me to do this again in about three months, I would have totally forgotten what I did or how I made it work (to be honest I still do not understand how it actually works 🤷‍♀️). Fair warning: I will constantly be calling out things that I do not understand or was just guessing at.

Let’s get to it. 🙇‍♀️

Getting cosy with it

There are some key concepts we need to understand before diving into the code. Lint is fueled by issues and detectors.

Issues identify implementations that we want to highlight as incorrect or potential sources of bugs. Take this excerpt from a report and let us look at the anatomy of an issue from this perspective:

An issue has:

Ref		Note
1	Brief description	A summary of what went wrong
2	Explanation	Provides details of why this is considered an issue. You can also suggest possible fixes, or provide links to relevant documentation.
3	ID	A unique identifier for the issue. This is what developers use to suppress reporting of this issue, i.e. what goes into `@Supress`
4	Category	Identifies an area where this issue can be bucketed. There is a wide variety of available categories, covering areas from `A11Y` (accessibility) to `INTEROPERABILITY_JAVA` (issues when calling Kotlin from Java) to `TYPOGRAPHY`.
5	Severity	This influences how this issue is treated and can be one of several options, with `FATAL` being the most severe (the build is aborted and nopes out). Users can force the build to fail if an `ERROR` is encountered with `lintOptions.isAbortOnError = true` in their `build.gradle` file.
6	Priority	A number from 1 to 10, with 10 indicating the highest priority

Detectors do the heavy lifting and figure out where the issues are. They can look in virtually any sort of file – Manifest? ✅, resource file? ✅ Gradle files? ✅

A single detector can identify any number of related issues, and can report each of those issues individually.

Note that Lint calls all existing detectors in a pre-defined order. This means that if a Lint rule needs to check something in both Kotlin and XML files (like resource usages, for example) the order in which checks are executed matters.

Setting up

Our custom rules need a home; and their home is a new module. Right click on your project and select New > Module then choose Java or Kotlin Library

In the freshly-created build.gradle file, add the dependencies for Lint. (Note: I use the Kotlin DSL)

// The Lint version is strongly tied to the Android Gradle Plugin (AGP) version
// Add 23 to the major version number of AGP (x in x.y.z)
// The project is currently dependent on AGP v4.1.1
val lintVersion = "27.1.1"

// Lint
compileOnly("com.android.tools.lint:lint-api:${lintVersion}")
compileOnly("com.android.tools.lint:lint-checks:${lintVersion}")

// Lint testing
testImplementation("com.android.tools.lint:lint:${lintVersion}")
testImplementation("com.android.tools.lint:lint-tests:${lintVersion}")
testImplementation("junit:junit:4.13.1")

The next part of our Lint journey is going to be long and treacherous. So let’s take a quick break here, make sure to watch the talks linked above and ⏸️ stay tuned for the next post in this series where we finally get to write our very own detector!

On-Device Debugging Part V: Strut Your Stuff

Zarah Dominguez — Sat, 20 Jul 2019 00:00:00 +0000

Over the past year, my team have been steadily building a Developer Options screen for our app. It is a simple PreferenceScreen available on debug builds that help us:

figure out what’s going on without needing to be attached to a computer
test various configurations without re-installing
have a host for various experimentations we are trying to explore

In this series of posts, I will share what these various options are and how we made them.

Read the other posts in this series:

(If you are not familiar with PreferenceFragmentCompat, I highly suggest to read about that first before proceeding. You can start with this AndroidX guide on Settings.)

Working on an app means we are constantly tweaking how things look. Change this shade of green, use this widget instead of that, move this thing to there.

In the last part of our on-device debugging series, we look at some of the ways we showcase how things should look in our app.

Design Playground and Shortcuts

Design Playground

A few weeks ago, we went all in and switched our whole app to use the new Material Design Components theme. (Nick Rout has an awesome article showing you more details on how to do this for your app.)

Zarah Dominguez 🦉

@zarahjutz

My team is SMASHING IT. 💪

06:26 AM - 03 Jun 2019

0 16

We fully expected that some widgets might look strange and we might have to tweak some things a bit. Taking inspiration from the MDC Catalog app, we came up with a Theme Showcase page.

This page has all the widgets as well as the custom components we use throughout the app.

Widget showcase

This has been really useful in helping us figure out how things look as we go through adapting MDC. This page has also been handy when we are tweaking something with our design team, and as a reference page for when we are visually testing a new feature.

Since we also have multiple themes in the app, we included a theme switcher that allows us to see how everything looks in each of the themes.

Dynamically switch themes

This switcher is accessed through the overflow menu. When the user chooses a theme, we save the value to a SharedPreferences file.

For simplicity, we only save the position of the chosen theme:

We then need to make sure that we get back the chosen theme:

And set it on our Activity’s onCreate via setTheme().

Shortcuts

Some parts of the app are a bit cumbersome to get to.

When we were building our app’s order confirmation page, it was getting annoying having to complete an order each time to see how it looks whenever we change something in the layout.

As we saw in my previous post about app shortcuts, we can put in a targetPackage and a targetClass in our Intents:

Having these shortcuts available helped us skip having to navigate through multiple steps to get to a particular screen.

And with that, we wrap up this series on on-device debugging options. We have seen how we can make feature toggles more user-friendly, how we can surface stacktraces for quicker debugging, and how we can retrieve Logcat traces out of our testers’ devices.

Thank you for sticking with the series, and massive thanks to everyone who has given me their time helping get these posts through! 💚

On-Device Debugging Part IV: Log All The Things!

Zarah Dominguez — Mon, 08 Jul 2019 00:00:00 +0000

Over the past year, my team have been steadily building a Developer Options screen for our app. It is a simple PreferenceScreen available on debug builds that help us:

figure out what’s going on without needing to be attached to a computer
test various configurations without re-installing
have a host for various experimentations we are trying to explore

In this series of posts, I will share what these various options are and how we made them.

Read the other posts in this series:

(If you are not familiar with PreferenceFragmentCompat, I highly suggest to read about that first before proceeding. You can start with this AndroidX guide on Settings.)

As I mentioned in part II, we leverage Timber a lot. Those stacktrace log screens have been really useful when the app misbehaves, but what about those times when we just want to have checkpoints whilst using the app?

Enter our next set of developer options:

More debugging!

Show Debug Toasts

Toasts are a great way of setting visual checkpoints in an app. They are relatively unobtrusive and easy to create.

Enabling “Show debug Toasts” in our developer settings allows us to surface these checkpoints when we are testing something unpredictable:

I previously talked about a geofencing feature we had to implement, and we have that feature to thank for spurning the idea for this debugging feature.

In this feature, we want the app to notify the user when they enter a geofence. Testing geofences in the middle of the city can be tricky, and having visual cues that let us know if we have entered or exited a geofence has been super helpful for us.

This function lives in our DebugExtensions class:

(In this case, SettingsInteractor takes care of exposing some of the debug options that our main source set needs access to.)

Having a developer option toggle to control this means we can turn the Toasts off when it gets too annoying, and we lower the risk of leaving a debugging Toast when we release to production as well.

Enable Leak Canary

We have some really old Activities in the app that drive Leak Canary crazy. Until we get around to cleaning them up, it also drives our QAs crazy. This toggle gives them the power to turn the tool off so they can test in peace.

As a rule, developers keep this toggle on during active development. As for those old Activities, we are in the process of reworking them to make them perform better.

Show Debug Notification

When enabled, the app shows a persistent notification that serves as the shortcut to this Developer Settings screen (we also provided an entry to this screen in our app’s junk drawer aka the “More” menu for debug builds). Pretty straightforward.

Logs

When connected to our development computers, we have a wide array of debugging tools at our disposal. We can use Timber, or System.out, or Toasts, or breakpoints, etc.

But going back to our geofencing feature, all of these options are not really viable to us during testing. Sure we can walk around Surry Hills with a laptop and keep an eye on Logcat whilst debugging. But we really can’t expect everyone who is testing the app to do this.

When this option is turned on, we send all the Logcat information from our app into a text file:

Getting those logs out of a particular device can be fiddly, dealing with multiple OEMs and USB variations. And those logs are pretty useless just sitting there, so we put in the option to send those files to us:

Using ACTION_SEND_MULTIPLE with the Intent allows us to automatically attach all the log files we can find in the user’s debug file storage.

Gimme those logs!

Depending on the email client they choose to send the files with, they can remove or add more files as they please.

To be good citizens, we have also provided the option to clear all existing logs so that users can reclaim their precious storage space.

Out of all the debugging features that we have, this one is probably my favourite. 💚

(Massive thanks go out to @ataul for all his patience reviewing my crazy ramblings 😆 )

In the next post, we will look at how our developer settings help us work better with the designers in our team. Stay tuned! 📻

On-Device Debugging Part III: Inspect, Reset, Repeat

Zarah Dominguez — Mon, 01 Jul 2019 00:00:00 +0000

Over the past year, my team have been steadily building a Developer Options screen for our app. It is a simple PreferenceScreen available on debug builds that help us:

figure out what’s going on without needing to be attached to a computer
test various configurations without re-installing
have a host for various experimentations we are trying to explore

In this series of posts, I will share what these various options are and how we made them.

Read the other posts in this series:

(If you are not familiar with PreferenceFragmentCompat, I highly suggest to read about that first before proceeding. You can start with this AndroidX guide on Settings.)

A lot of things affect how the Woolworths app behaves. Sometimes databases get out of sync between production and development environments, there are one-shot screens and tooltips, the UI may look different based on device qualities, or even changes to available options to users based on the type of account they have.

To manage and keep track of all these things, we included a set of actions in our developer options.

Additional actions

Environment Switcher

We have a few different environments that the apps can use. Having a switcher built into the app means we can easily test our app’s behaviour on any of the available environments.

Switcher confirmation

For us, switching environments mean revoking access tokens and everything else that come with that. Since this is a destructive action (they would need to log back in), we opted to present a confirmation dialog before proceeding.

Your testers are users too, so UX is important. 😉

Inspect and Reset Preferences

Last year, Woolworths have completely removed single-use plastic bags from all stores nationwide. To help with the transition to reusable bags, we built a feature into the app that allows users to enable bag reminders for their chosen store. We also included a “nudge” feature to assist with discovery – the app would nudge you three times to set up your reminders, after which it assumes you do not want to set it up.

This is one of the many use cases where we leveraged SharedPreferences. This whole feature is based on geofencing around a store, which can be a little finicky. We decided to include a SharedPreference inspector so that we can easily answer questions from our testers like “I did not get any set up notifications, I’m pretty sure I have only gotten two?”.

Being able to see what current values have been saved in the app allows us to quickly triage issues in the wild.

Remember that override Firebase kill switch?

I have already written about resetting SharedPreferences here, and the “inspect” bit follows the same principle as that. Mainly:

This function assumes that the SharedPreferences files your app owns follow this naming convention: MY.APPLICATION.ID_my_preference_file.

But we do need some modifications to the gist quoted in that post. For one, we can extract out the bit that reads the files:

We need to do a bit of processing because we want to have readable names (again, UX!) as well as the name that Android would need to retrieve the SharedPreference. As an example:

File location	`/data/user/0/com.woolworths.debug/shared_prefs/com.woolworths.debug_prefs.xml`
Android-readable name	`com.woolworths.debug_prefs`
Nice name	`debug_prefs`

To keep things simple, we only display a dialog with all the existing values in the SharedPreference:

This option has helped us a lot debugging our nudges out in the wild. It eliminated the need to be connected to a computer, or to fiddle with file viewers, etc.

Show Device Info

Sometimes we want the UI to change based on some device qualifications like say the smallest available width. Using the emulator makes it super easy for us to test these visual breakpoints. But for someone who does not have access to the emulator, it can be quite hard to verify the UI changes we expect.

This screen shows some basic information that might affect how our app displays something to the user:

Minimum information to debug device-dependent UI

Everything under the “Build Information” header is retrieved from Android’s Build.VERSION API or the BuildConfig. And for the “Device Information” section, we utilised windowManager.defaultDisplay.getMetrics(DisplayMetrics()).

The “Account Information” section contains some basic information about the user that might affect the UI. For example, if “Is legal adult” is false, the user will not be able to see any liquor products in the app.

Show Diagnostic Info

There is a lot more information that affects a user’s experience with the Woolworths app other than if they are logged in or not. Inventory is different store-to-store, Rewards and offers may be targetted, legal requirements are different based on the state, among other things.

All of these things may affect the app one way or another, and we use a Diagnostics screen to display all those information.

And with that we wrap up this post on our developer options for UI-affecting variables. In the next post, we will talk about logging, Toasts, and more fun stuff! 🎊

On-Device Debugging Part II: Timbeeeeeeer!

Zarah Dominguez — Mon, 24 Jun 2019 00:00:00 +0000

Over the past year, my team have been steadily building a Developer Options screen for our app. It is a simple PreferenceScreen available on debug builds that aims to help us:

figure out what’s going on without needing to be attached to a computer
test various configurations without re-installing
have a host for various experimentations we are trying to explore

In this series of posts, I will share what these various options are and how we made them.

(If you are not familiar with PreferenceFragmentCompat, I highly suggest to read about that first before proceeding. You can start with this AndroidX guide on Settings.)

Read Part I (Now It’s On, Now It’s Off) here.

One of the tools we utilise a lot at Woolworths is Timber. We use it not just to help us with debugging during development, but also to figure out problems early during testing as well as to keep an eye on things in production.

Before, when we have a build for testing and things don’t go to plan, we get sent a screenshot pretty much like this:

Uh 🙀

We try to figure out what they were trying to do before the app crashed, replicate the exact conditions they had prior, and try and try and try. More often than not, we hit the “that shouldn’t have happened” wall – even though it obviously just did. 🤦‍♀️

To help in these situations, we turned to Timber. We log those “We should never get here!!!” scenarios using Timber.e. In production, those logs get sent to Fabric via Crashlytics.log(). In debug builds, those logs get sent to a crash log screen.

This screen shows the stacktrace, if there’s any, and some basic information about the build and the device. We also decided to use this screen to log any uncaught exceptions. At the bottom of the screen is a button to send the crash log through via an Intent Chooser.

Crash log screen variations

To bring this to life, we override Timber’s e:

class LoggingTree(private val app: Application) : Timber.DebugTree() {

    override fun e(message: String, vararg args: Any) {
        super.e(message, *args)
        printStackTrace(null, message, *args)
    }

    override fun e(t: Throwable, message: String?, vararg args: Any) {
        super.e(t, message, *args)
        printStackTrace(t, message, *args)
    }

And printStackTrace simply passes on the information to a dedicated Activity that would display the error.

We provide the kind of error as an Intent extra with a CrashType:

enum class LogType(val additionalMessage: String, @ColorRes val background: Int) {
    UNCAUGHT_EXCEPTION("!!! DO NOT IGNORE! THIS WILL CAUSE A CRASH IN PRODUCTION !!!", R.color.error_color),

    LOG("We are monitoring an issue. You may still send this log if you want.", R.color.white);
}

The crash screen implementation is pretty straightforward, we retrieve the extras and use data binding to display the message and style the header. (For the curious, I previously wrote about using resource references in databinding)

Since we use the crash log screen for uncaught exceptions as well, we directly call the Activity when something goes wrong. This means that it skips the Timber processing but sometimes it’s still useful to see the logs in Logcat, so we log the stacktrace there as well:

@SuppressLint("LogNotTimber")
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    // ...

    // We still want to display the stack trace in Logcat for uncaught exceptions
    // but are not using Timber.e here lest we get into an infinite loop
    Log.e("FIXME", Log.getStackTraceString(stackTrace))

}

The “Send crash” button at the bottom of the screen sends out an ACTION_SEND Intent so that users can send the information via email, Slack, or whatever other app they choose (I also wrote about that here!).

This may seem like a simple thing, but time and again it has helped us quickly figure out issues in a more meaningful way. Even if those helping us test choose to send a screenshot, there is more relevant information rather than the generic crash dialog. 💞

On-Device Debugging Part I: Now It’s On, Now It’s Off

Zarah Dominguez — Sat, 22 Jun 2019 00:00:00 +0000

Over the past year, my team have been steadily building a Developer Options screen for our app. It is a simple PreferenceScreen available on debug builds that aims to help us:

figure out what’s going on without needing to be attached to a computer
test various configurations without re-installing
have a host for various experimentations we are trying to explore

In this series of posts, I will share what these various options are and how we made them.

(If you are not familiar with PreferenceFragmentCompat, I highly suggest to read about that first before proceeding. You can start with this AndroidX guide on Settings.)

At Woolworths, we use feature flags a lot. It helps us merge our code to master quicker, allows our QA team to provide feedback faster, and helps manage the risks when doing an important release.

We use Firebase Remote Config to manage our existing feature flags, which enable us and our product owners to control these flags very easily.

Although it is very convenient to have these flags configurable remotely, it also makes it difficult to do a quick test on something behind a feature flag for someone who doesn’t have access to the console. It might also disrupt someone’s work if somebody else changes the flags’ values remotely without them knowing it.

It is for this reason that we introduced local feature toggles. This gives anyone on a debug build the ability to turn as many features on or off as many times as they want without affecting anyone else’s builds.

Names changed to protect individuals 😅

On a fresh install, the app would use the in-app default values we have set and the override switch is OFF. The app would keep using the values provided by Firebase until the override switch is flipped.

And when it gets confusing and we want a do-over, the “Reset local to Firebase” button would turn the flags back to what is provided by Firebase.

All the features in this list are added dynamically from an enum that holds all our feature flags:

There a few things at work to make all of this come together. First off, if the override button is OFF, we want everything related to feature flags to be disabled. This gives better clarity on what settings the app is using, and prevents the user from unwittingly changing a value.

To do this, we define the switch’s behaviour in our XML file:

The attribute disableDependentsState means that if this switch is OFF, any other value that depends on this preference gets disabled.

Next, we want to create a new category that will contain all of our feature toggles and belong to the same category as our override switch.

We can then add each of our features into this featureTogglesCategory:

For simplicity, we use the Feature enum’s name as the SharedPreference key for each feature toggle, as well as the label that appears beside the Switch.

What the function isFeatureEnabled() does is simply return Firebase-provided values for production builds, and figure out what the our preferences are for debug builds:

Now that we have prepared our feature flags PreferenceCategory, we can route our dependency on our override switch:

It may seem turned the other way around, but that is correct. ✅ To set this new category as dependent ON another preference, we need to call setDependency() and give it the name of that control preference.

As for our “Revert…” button, we also want it to be disabled if the override switch is off (because it doesn’t serve any real purpose in this case):

And to handle user clicks on this button, we set up a callback in our PreferenceFragment:

And that’s it! We have dynamically added a set of switches to our PreferenceScreen that would hopefully make testing our app much easier.

In the next post in the series, we will talk about more on-device debugging tools such as managing our SharedPreferences, and showing device information, among others.

Tintable Toolbar Things

Zarah Dominguez — Fri, 21 Jun 2019 00:00:00 +0000

A few weeks ago, I merged a pull request that updates our app’s theme to Material Components from the Bridge version.

// Detect dark theme var iframe = document.getElementById('tweet-1135432513688465408-366'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1135432513688465408&theme=dark" }

I have been referencing the MDC Catalog app a lot during this exercise; and I thought it would be a good idea to pattern how we organise and apply our theming and styling based on that app. (Hey they must know what they’re doing, right?)

We have two kinds of Toolbars in our app – the first one with our standard primary colour, and a “clean” variant.

When we initially set up our theming, we made this theme overlay (read about theme overlays here) to style our toolbar and give it that green arrow:

<style name="ThemeOverlay.Toolbar.Inverse" parent="ThemeOverlay.AppCompat.Light">
    <item name="colorControlNormal">?colorAccent</item>
    <item name="android:background">@color/white</item>
</style>

We then set this in our Toolbars as android:theme:

<androidx.appcompat.widget.Toolbar 
    ...
    android:theme="@style/ThemeOverlay.Toolbar.Inverse" />

The MDC Catalog app uses styles instead of themes , so I set about copying their technique. (Side note: Anita Singh has an amazing talk on styles, themes, and material design)

We immediately run into one problem: in our theme-based approach, we can set the colorControlNormal attribute in our theme overlay, but we cannot do that anymore with our style-based approach.

We definitely want our green arrow though, and we can look at the MDC source code to get some clues. It’s always a good idea to start off with what we want to be our parent style:

<style name="Widget.MaterialComponents.Toolbar.Surface">
    <item name="android:background">?attr/colorSurface</item>
    <item name="titleTextColor">?attr/colorOnSurfaceEmphasisHighType</item>
    <item name="subtitleTextColor">?attr/colorOnSurfaceEmphasisMedium</item>
    <!-- Note: this theme overlay will only work if the style is applied directly to a Toolbar. -->
    <item name="android:theme">@style/ThemeOverlay.MaterialComponents.Toolbar.Surface</item>
</style>

🤔 Interesting note there, we should totally remember that.

Taking a peek at the referenced theme overlay, we see the attribute we want 🎉 :

<style name="ThemeOverlay.MaterialComponents.Toolbar.Surface" parent="">
    <item name="colorControlNormal">?attr/colorOnSurfaceEmphasisMedium</item>
    <item name="actionMenuTextColor">?attr/colorOnSurfaceEmphasisMedium</item>
  </style>

Adapting this to our code, we now have:

<style name="Widget.Toolbar.Inverse" parent="Widget.MaterialComponents.Toolbar.Surface">
    <item name="android:background">@color/white</item>
    <item name="android:theme">@style/ThemeOverlay.ToolbarTint</item>
</style>

<style name="ThemeOverlay.ToolbarTint" parent="ThemeOverlay.MaterialComponents.Toolbar.Surface">
    <item name="colorControlNormal">?colorSecondary</item>
</style>

And applying this to our Toolbar (remember it is now a style!):

 <androidx.appcompat.widget.Toolbar
    ...
    style="@style/Widget.Toolbar.Inverse"
    app:navigationIcon="?homeAsUpIndicator" />

And this works really well, until….

The close button is now invisible 😱

The only difference between this screen and the others is that we provide a vector drawable for the navigation icon:

<androidx.appcompat.widget.Toolbar
    ...
    style="@style/Widget.Toolbar.Inverse"
    app:navigationContentDescription="@string/close"
    app:navigationIcon="@drawable/ic_close" />

So it should work, right? MDC Catalog has a style with a close button like we have, the vector they use also has a fillColor hardcoded in it (I even tried making their fill colour red 😂), but it is always always getting tinted correctly.

I always find theming and styling really hard to debug, so I gave up on this for a while and conceded my defeat. The next day, I decided to timebox myself to a couple of hours – if I can’t figure it out by then I will just stick to how it was before. I re-read all the blog posts, re-reviewed the source code, and gave StackOverflow another shot.

And there… in one random comment exchange:

What’s the difference between using ?attr/colorControlNormal at android:tint vs android:fillColor attributes? Thanks! – Thomas Vos Jun 20 ‘17 at 15:46 @SuperThomasLab The example is from Chris Banes’s blog where it illustrates replacing a tinted image with a tinted vector. Note that the fillColor was effectively hard-coded in the source image. I do not know if other color representations are now supported in AppCompat. – Joe Bowbeer Jun 22 ‘17 at 20:06

And sure enough, our vector didn’t have android:tint defined in it! 🤦‍♀️ Adding it into our vector makes everything work perfectly 👌

<vector xmlns:android="http://schemas.android.com/apk/res/android"
    android:width="24dp"
    android:height="24dp"
    android:viewportWidth="24"
    android:viewportHeight="24"
    android:tint="?colorControlNormal">
  <path
      android:fillColor="#FFFFFFFF"
      android:pathData="M19,6.41L17.59,5 12,10.59 6.41,5 5,6.41 10.59,12 5,17.59 6.41,19 12,13.41 17.59,19 19,17.59 13.41,12z"/>
</vector>

I know it may be obvious to some people (of course you need a tint to tint something, duh???), but it wasn’t super obvious to me.

So, TL;DR: Make sure your vectors actually support tinting before trying to tint it. 🌈

Shortcuts to Shortcuts

Zarah Dominguez — Sat, 08 Jun 2019 00:00:00 +0000

It has been a few years since I last looked at implementing app shortcuts, and lately I have been looking at them again. I remember implementing them the first time they were released for Android N, but as with life, things have changed a bit.

In this post I want to share some interesting learnings I had whilst implementing static app shortcuts. (Note: This post assumes the reader is familiar with the basic requirements of implementing app shortcuts). As always, all the code for this post is in my Sandbox App.

Android Studio support is… limited.

☝️ For this exercise, I am using Android Studio 3.5 Beta 4.

And by limited I mean resource references do not autocomplete at all. This becomes tricky as some of the required attributes can use resource references. The table below shows what those are:

Allowed	Not allowed
`shortcutShortLabel`	`shortcutId`
`shortcutLongLabel`	`Intent` attributes (`targetPackage`, `targetClass`)
`icon`

⚠️ My non-scientific test shows that on Pixel launchers, shortcutShortLabel is used unless shortcutLongLabel is 17 characters or less.

There are changes in design guidelines between APIs 25 and 26

Android O introduced adaptive icons and if we take into consideration that users can pin shortcuts onto their homescreens, we need to support this format if we want to provide the best possible user experience.

Nick Butcher talked about this in detail in his post on implementing adaptive icons.

⚠️ Using a VectorDrawable for the icon foreground as Nick showed, it didn’t seem to like using theme references for the fill colour. Using a resource reference is okay.

Read this post to learn more about designing adaptive icons, and this document for designing app shortcut icons.

Mo’ package names, mo’ files

For each app shortcut we want to support, there needs to be an Intent associated with it; with each Intent needing a targetPackage and a targetClass. To wit:

<intent
    android:action="android.intent.action.VIEW"
    android:targetPackage="com.zdominguez.sdksandbox"
    android:targetClass="com.zdominguez.sdksandbox.MainActivity" />

This might present a problem if your app have different package names for each build type. Someone has written a function to support variables but unfortunately it does not work on more modern versions of the Gradle Plugin.

This means that we would need multiple shortcuts.xml files for all build variants that we want to support:

Passing intent extras is possible, but sometimes a trampoline activity comes in handy

If we need to pass some extras to the Activity we are targetting, we can do so via the XML file:

<intent ...>
    <extra android:name="target_tab" android:value="settings" />
</intent>

One important statement that is a bit buried in the documentation for app shortcuts is:

[W]hen the app is already running, all the existing activities in your app are destroyed when a static shortcut is launched.

This is when a trampoline Activity becomes useful so we can prepare our back stack or even get a handle on some requirements the receiving activity would need (for example, a value to be read from the database). You can read more about trampoline activities here. ➰

Handling up navigation

Similar to how we should handle navigation when starting an Activity from a notification, we need to consider how the app would behave when the user navigates away from our target Activity.

Thus, we need to provide multiple Intents to the shortcut and the last one in the list would be what the user initially sees.

<shortcut ...>
    <intent
        android:action="android.intent.action.VIEW"
        android:targetPackage="com.zdominguez.sdksandbox"
        android:targetClass="com.zdominguez.sdksandbox.MainActivity">
        <extra android:name="target_tab" android:value="settings" />
    </intent>
    <intent
        android:action="android.intent.action.VIEW"
        android:targetPackage="com.zdominguez.sdksandbox"
        android:targetClass="com.zdominguez.sdksandbox.DemoActivity">
    </intent>
</shortcut>

It took me a bit longer than I liked to figure out all of this 😩, so I’m writing it down to have a reference for future me.

👯 Make sure to read the rest of the best practices document to learn more.

Moving On Up (Or Down)

Zarah Dominguez — Wed, 03 Apr 2019 00:00:00 +0000

Zarah Dominguez 🦉

@zarahjutz

Using CMD+SHIFT+UP/DOWN when reordering element in an enum respects the semicolon. 😍 It's the small things!

00:52 AM - 03 Apr 2019

17 129

I tweeted that this morning after rediscovering CMD+SHIFT+UP. I have known about this shortcut for a while, but I guess I haven’t had reason to use it until lately.

And then I remembered a variation of this shortcut that would literally “move things don’t care”.

Zarah Dominguez 🦉

@zarahjutz

EDIT: (versus SHIFT+ALT+UP/DOWN which just moves the line regardless of context)

04:32 AM - 03 Apr 2019

0 9

This being IntelliJ, these actions work on more than just properties. They work for basically anything in your code that has a scope – individual lines, functions, classes even!

There are two main movement actions, move statement and move line. Depending on what you want to do, each of these have their own benefits.

Moving a statement means that the IDE will respect the context within which that particular element exists. In the case of a single line of code, this means maintaining its current scope. What this means exactly is – if a line is inside a function, using CMD+SHIFT+UP/DOWN will never move it out of the function.

To wit:

But this line wants to move to another function! It says so itself! This is when CMD+ALT+UP/DOWN comes in handy:

This shortcut is really handy when reordering or refactoring functions:

I leave it as an exercise for the reader to see how the shortcut behaves with classes. Get moving and stop copy-pasting! 👯

DEV Community: Zarah Dominguez

Seeing What Talkback Sees 🔍

Wait, what! 😻

What do we have here? 🤔

Fixing our issue… maybe 👀

Enforcing Team Rules with Lint: Tests 🧐

Serving up files 💁

Let’s get testing 🔬

Bringing it all together 🤝

Seeing it in action 📽️

Further reading (and/or watching) 📖

Enforcing Team Rules with Lint: Detectors 🕵️

Coming to terms with Lint 🏛️

PSI

UAST

PSI vs UAST

Just get on with it, Zarah

Being specific

Receiving callbacks

A very important side note 🛑

Implementing the scanner

Finding fault

Responsible reporting 📢

A little help from my friends

Enforcing Team Rules with Lint 👩‍🔧

A great idea

The worst idea

Getting cosy with it

Setting up

On-Device Debugging Part V: Strut Your Stuff

Design Playground

Shortcuts

On-Device Debugging Part IV: Log All The Things!

Show Debug Toasts

Enable Leak Canary

Show Debug Notification

Logs

On-Device Debugging Part III: Inspect, Reset, Repeat

Environment Switcher

Inspect and Reset Preferences

Show Device Info

Show Diagnostic Info

On-Device Debugging Part II: Timbeeeeeeer!

On-Device Debugging Part I: Now It’s On, Now It’s Off

Tintable Toolbar Things

Shortcuts to Shortcuts

Android Studio support is… limited.

There are changes in design guidelines between APIs 25 and 26

Mo’ package names, mo’ files

Passing intent extras is possible, but sometimes a trampoline activity comes in handy

Handling up navigation

Moving On Up (Or Down)