How can I modify the TalkBack usage hint for a clickable View on Android? – Stack Overflow

Being “polite”

We gave our accessibilityLiveRegion a value of “polite”. This simply means that TalkBack won’t interrupt anything it may already be announcing when it processes the event generated by a live region. An alternate to “polite” is “assertive”, which instructs TalkBack to move announcements related to a live region up the event queue and interrupt ongoing announcements. You should use live regions sparingly, and nearly always avoid “assertive” live regions.

Download the code

You can clone the repo that contains the code for this codelab:

Fixing the decorative image

Go back to Android Studio and from res/layout, open content_labeling.xml.

Place your cursor over the first <ImageView>. Android Studio’s lint checks warn about a missing contentDescription.

Let’s fix this. Since the musical note is purely decorative, we should set the contentDescription to “@null”:

Fixing the play/pause button

The Play/Pause toggle is managed dynamically through the code. Look at the code in the ContentLabelingFragment class:

private void updateImageButton() {
    if (mPlaying) {
       mPlayPauseToggleImageView.setImageResource(R.drawable.ic_pause);
    } else {
       mPlayPauseToggleImageView.setImageResource(R.drawable.ic_play_arrow);
    }
}

We toggle the image, but we don’t add a contentDescription to describe the current state of the view. Add calls to setContentDescription() so the code looks like this:

private void updateImageButton() {
    if (mPlaying) {
       mPlayPauseToggleImageView.setImageResource(R.drawable.ic_pause);
       mPlayPauseToggleImageView.setContentDescription(getString(R.string.pause));

    } else {
       mPlayPauseToggleImageView.setImageResource(R.drawable.ic_play_arrow);
       mPlayPauseToggleImageView.setContentDescription(getString(R.string.play));
    }
}

Press the green Play icon

1. Tap on the Play icon. TalkBack announces “Play button”.
2. Double-tap to toggle the icon.
3. Tap on the Pause icon. TalkBack announce “Pause button”.

Fixing the share image button

TalkBack simply reads the Share image button as “Button, Unlabelled”, and Android Studio generates a lint warning about a missing contentDescription. Add a contentDescription, using “@string/share” as the value (this is defined in res/values/strings.xml with a value of “Share”):

Grouping content for accessibility

There are several ways to fix this. Since the song data is made up of only six short strings, we could have TalkBack group all six items into a single announcement. Let’s experiment with this approach.

It is a common best practice to group non-focusable items (e.g. TextView elements) in a focusable container to have them read as a single item.

Open content_grouping.xml and locate the RelativeLayout that contains the six TextView elements that we wish to consolidate.

Add the focusable attribute to the <RelativeLayout> element:

Press the green Play icon Content Grouping Screen with TalkBack.

What do you notice now? TalkBack announces the title (“Song Details”), and then it announces the song details as a single announcement ( “Name, Hey Jude, Artists, The Beatles, Cost, $1.45”).

How live regions work

Using an accessibilityLiveRegion with a view means that when that view updates, it generates an extra AccessibilityEvent in the event stream that an AccessibilityService like TalkBack can pay attention to.

Incorrectly grouped content

To see an example for this, navigate to the Content Grouping Screen.

Click on the title, and swipe right repeatedly to move down to the other views. What do you notice?

TalkBack announces the title (“Song Details”), and then it announces the views in the following order:

1. “Name”
2. “Hey Jude”
3. “Artists”
4. “The Beatles”
5. “Cost”
6. “$1.45”.

Launching the demo application

Make sure a device is connected to your workstation. Press the green Play icon Basic Android Accessibility Codelab app. The landing page for that app looks something like this:

Don’t close the app. We’ll return to it soon.

Linear navigation

To explore your screen one item at a time, swipe-left or swipe-right to move through the items in sequence. Swipe-left takes you to the item previous from the one you’re on. Swipe-right takes you to the next item.

Execute the following steps:

1. Click on the “Basic Android Accessibility Codelab” title in the toolbar at the top of the screen. TalkBack focuses on this view.
2. Swipe-right. The focus moves to “CONTENT LABELING SCREEN“.
3. Swipe-right again. The focus now moves to “CONTENT GROUPING SCREEN”.
4. Swipe-left. The focus moves back to “CONTENT LABELING SCREEN“.

TalkBack offers a rich option of gestures (learn more about TalkBack gestures), but in this codelab we’ll restrict ourselves to the gestures covered in this step.

For help with TalkBack, visit Get Started on Android with TalkBack.

Objectives

In this codelab, you will:

The codelab is structured in small, discrete steps, and each step focuses on a specific accessibility issue.

Setting up android studio

Launch Android Studio by clicking the Studio icon:

Talkback settings

We’ll use TalkBack with a developer-mode option that will show the text from the auditory feedback on the screen.

Follow these steps to set up TalkBack. These instructions assume a Pixel device; the location of TalkBack settings can vary on other Android devices.

Talkback tutorial

At this point, TalkBack may launch its Tutorial, which goes over TalkBack fundamentals. You are welcome to work through the tutorial, but you can skip it for now if you prefer.

We use only a subset of Talkback’s functionality in this codelab, and the next step provides enough help to get you started with Talkback.

Tooling and layout bounds

Enable developer options by going to Settings > System > Developer Options. Under the Drawing category, find “Show layout bounds” and turn it on. Your screen should now show the clip bounds, margins, etc. of every visible view.

Go back to the Expand Touch Area Screen, and notice the small layout bounds for the button.

In Android Studio, open content_expand_touch_area.xml, and look at the XML for the image button:

Add a minimum width and height to the ImageButton:

Press the green Play icon

The layout bounds have expanded, making the touchable area 48dp X 48dp, our recommended minimum target.

Try rapidly clicking on the button to toggle between the play and cancel icons, and you’ll find that the expanded touch target makes it easier to avoid missing the button.

Go back to developer options (Settings > Developer Options). In the Drawing category, find “Show layout bounds” and set it to “off”.

Unlabeled content

Navigate to Content Labeling Screen (remember this is a two-step process when using TalkBack). The screen looks like this:

The screen contains a title, an EditText for entering text, a “Go” button, a Share button, and Play button. When the play button is clicked, it toggles to a Pause button.

Discover the content on the screen using TalkBack:

1. Tap on the title. TalkBack announces “Content labeling screen”.
2. Swipe right to get to the next view. TalkBack announces “Jukebox”.
3. Swipe right again. TalkBack skips over the purely decorative musical note image (we’ll discuss that shortly), focuses on the EditText, and announces “Enter favorite song. Edit box. ” TalkBack knows to announce “Enter favorite song” because the EditText has an android:hint attribute that is set to "Enter favorite song" in the layout XML.

Using accessibilitools

Novoda has a utility library to help with accessibility on Android. This includes some tools to help set usage hints:

UsageHintsAccessibilityDelegate delegate = new UsageHintsAccessibilityDelegate(resources);  
delegate.setClickLabel("play video");

ViewCompat.setAccesibilityDelegate(playButton, delegate);

I wrote a blogpost which is an overview of accessibilitools (I am also a contributor to the library).

Using an accessibilitydelegate instead

It’s very similar – you can override the equivalent method in a custom AccessibilityDelegate that you extend:

public static class PlayVideoAccessibilityDelegate extends AccessibilityDelegateCompat {

    @Override
    public void onInitializeAccessibilityNodeInfo(View host, AccessibilityNodeInfoCompat info) {
        super.onInitializeAccessibilityNodeInfo(host, info);
        info.addAction(
                new AccessibilityNodeInfoCompat.AccessibilityActionCompat(
                        AccessibilityNodeInfoCompat.ACTION_CLICK,
                        "play video"
                )
        );
    }
}

then to use it, you set the delegate with ViewCompat:

ViewCompat.setAccessibilityDelegate(playButton, new PlayVideoAccessibilityDelegate());

Using natural groupings

In the example we’re considering, having a single TalkBack announcement is better than having six; but this solution has its limits:

Overriding the oninitializeaccessibilitynodeinfo method

If you have a custom View, you can override the onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) method and add an action with the ACTION_CLICK ID, to override the label:

@Override
public void onInitializeAccessibilityNodeInfo(AccessibilityNodeInfo info) {
    super.onInitializeAccessibilityNodeInfo(info);
    info.addAction(
            new AccessibilityNodeInfo.AccessibilityAction(
                    AccessibilityNodeInfo.ACTION_CLICK,
                    "play video"
            )
    );
}

If that View has a click listener, then by adding this new Action, you’ll have overridden the default label so TalkBack will say “Double tap to ” instead.

This is only available on API 21 – what if you wanted something that worked on a lower API version or wanted to set a custom usage hint on a non-custom View? You can use ViewCompat and AccessibilityDelegateCompat!