In the case of the contentDescription-attribute, I have spotted a few issues Android devs do this are incorrect and make apps tougher to make use of with assistive era. The very first thing I see so much is surroundings the content material description of an icon to the icon title, comparable to icon_cat_sleeping. Some other factor is suppressing the warnings Android Studio offers about lacking content material descriptions.
I determined to write down about this theme, and on this weblog publish, you’ll find out about content material descriptions: the issues and answers. And sure, you’ll perceive why the ones issues I discussed within the earlier paragraph are problematic.
Let’s get started discussing content material description, then proceed with find out how to write one, and in the end, find out how to set the content material description.
After I speak about content material description, I imply textual content selection. If in case you have any background in internet construction or, e.g., the usage of any social media platforms, you could have heard in regards to the phrase “alt textual content”. They imply the similar factor and other environments have other names for this idea.
In Android, the characteristic is known as contentDescription, and I believe that content material description is in fact an overly explanatory title for what we are looking to accomplish with it: describing the content material of a picture or a graphic.
Something that’s essential to bear in mind is who we’re describing the content material for: Customers who make the most of the accessibility APIs. This implies, as an example, display screen reader and voice get right of entry to customers. Display screen reader customers depend at the content material descriptions for visible content material (that they most often can’t see, relying on their sight degree), and voice get right of entry to customers can use those values as labels to have interaction with parts, comparable to buttons.
Content material descriptions will have to be added for significant visible parts like pictures, icons, and graphs. For one of the vital parts, it’s more uncomplicated, however for, as an example, several types of graphs, it’s extra sophisticated. This weblog publish gained’t move into main points on including content material descriptions for graphs, however I’ve written a weblog publish as one instance across the theme in case you’re : Extra Obtainable Graphs with Jetpack Compose Phase 1: Including Content material Description.
Now, in case you’ve been running with trying out gear comparable to Appium, chances are you’ll have in mind including the check identification as contentDescription. Sadly, some gear use the so-called “accessibility identification,” which maps to contentDescription on Android. On iOS, there’s a separate assets referred to as accessibilityId. It is a drawback as a result of content material description in fact overrides the textual content price for lots of parts, which means that for those parts, a display screen reader person would pay attention the price of a button being button_submit (the identification set for trying out) as an alternative of the “Put up” that is a textual content for that button.
I’ve needed to repair problems like this, and my resolution used to be to test that if a display screen reader is working, we’d set the detail’s content material as contentDescription; differently, use that trying out identification. That’s not an optimum resolution, nevertheless it used to be the most efficient lets do on the time. And this may fail with one of the vital automatic accessibility exams, although it really works for actual display screen reader customers.
The content material description is invisible to maximum customers. Because of this it’s no longer the omnipotent way to repair accessibility problems.
A commonplace false impression is that including it as a label to an icon would make it to be had to each person. However that’s no longer the case — a person who isn’t the usage of any kind of assistive era can’t see it, nor can somebody with, as an example, a keyboard. So, it’s to be had only for assistive applied sciences that make the most of the accessibility API beneath — together with, however no longer restricted to, display screen readers, transfer get right of entry to, and voice navigation.
I wish to underline this as a result of many customers most often would take pleasure in such things as textual content labels with icons, however they have a tendency to be disregarded when inquiring for them on account of the above discussed false impression. I’m certainly one of them, so I’ve skilled this firsthand.
The real content material for the contentDescription characteristic varies, relying at the goal and form of the detail. As discussed, extra complicated visualizations are outdoor the scope of this weblog publish, so we will be able to talk about significant and ornamental pictures. We’re going to additionally talk about icons as a separate, distinctive use case.
One essential factor to notice is that on every occasion you write a content material description, have in mind to localize it!
What does a “significant symbol” imply? It manner any symbol (or graphic) that has which means and provides one thing to the content material. It contains icons, and photographs that comprise directions is some other excellent instance. The textual content selection (so, content material description) will have to comprise what the picture is making an attempt to keep up a correspondence.
A picture’s content material description may be suffering from the context the place the picture is. WebAIM has an inventory of directions for writing textual content choices:
The alt characteristic will have to most often:
– be correct and an identical in representing content material and serve as.
– be succinct. Content material (if any) and serve as (if any) will have to be introduced as succinctly as imaginable, with out sacrificing accuracy. Generally, only some phrases are essential, even though infrequently a brief sentence or two is also suitable.
– no longer be redundant or give you the identical knowledge as textual content close to the picture.
– no longer come with words like “symbol of …” or “graphic of …”, and so on. This is able to be redundant since display screen readers already announce “graphic” in conjunction with the alt textual content. If the truth that a picture is a photo or representation, and so on. is essential content material, it can be helpful to incorporate this in selection textual content.
Supply and browse extra: WebAIM: Selection textual content
Within the earlier segment, we’ve mentioned significant pictures. Every so often, illustrations or pictures are there for purely ornamental functions and don’t have another which means. In those circumstances, you will have to mark the content material description as null:
Symbol(
...
contentDescription = null
)
Now, chances are you’ll surprise, why no longer go away it as an empty string? The reason being that after left empty, the accessibility API doesn’t get the data that that is ornamental and assists in keeping this symbol within the accessibility tree. This results in a state of affairs the place, when a person encounters that symbol, they might pay attention “Unnamed” as an alternative of no longer encountering it within the first position.
That “Unnamed” is redundant knowledge and will also be actually complicated. Is that symbol actually ornamental, and a developer didn’t understand how to set it as such? Or is it significant, however the developer forgot so as to add the real textual content selection?
Within the Compose global, substances like Symbol and Icon require contentDescription to be set explicitly. Then again, it used to be (or, is) imaginable to depart the characteristic out within the View global and XML-layouts.
That will result in equivalent eventualities, with “Unnamed” being introduced. This is able to additionally create a caution within the Android Studio about lacking content material descriptions. It’s imaginable to suppress that caution, and I’ve fastened a couple of cases the place the caution used to be suppressed.
So, don’t suppress that caution — set the content material description to null or supply a descriptive content material description, relying at the symbol.
As discussed, icons are a distinct case. Icons are continuously used as the one motion indicator (like an edit button with only a few icon representing modifying). I most often have issues of this on account of how I procedure knowledge. I stay inquiring for textual content labels however most often don’t get them. However this isn’t a weblog publish about textual content labels; it’s about content material descriptions, so let’s transfer on.
When an icon is the one factor inside of a button, it’s much more vital to incorporate significant content material descriptions as it’s the textual content used for the button. So, when a display screen reader person encounters a button with an icon that may be a quill, they’d pay attention one thing like “Button, Edit” as an alternative of “Button, icon underscore quill” if the content material description is ready to the icon’s title. Or, within the case I discussed within the intro, “Icon underscore cat underscore snoozing.” Understand that no matter textual content you input there might be what non-sighted display screen reader customers pay attention (or learn from braille) — they are able to’t see the icon.
So, when including a content material description for an icon, ask your self if it’s used to put across which means or if it’s purely ornamental. If it’s the latter, use null. Another way, describe the motion or which means, no longer the real icon. So, most often, an “X” icon represents one thing like “Shut,” and a chevron pointing to the left manner one thing like “Again”.
You’ll set the content material description during the contentDescription-attribute for Symbol and Icon -components. Different substances shouldn’t have this characteristic, so you’ll be able to want the assistance of semantics or clearAndSetSemantics-modifiers.
Each semantics and clearAndSetSemantics modifiers trade the detail’s semantics. The variation is that the primary builds on best of present semantics, and the latter clears all of the different semantics.
Whilst Symbol and Icon substances have the contentDescription, different parts, comparable to graphics created with Canvas, will require the usage of those modifiers. Additionally some other case is textual content with an emoji – as an example, in case your app is a talk app with reactions, and you might be the usage of Textual content-element for exhibiting the response, you would wish to set the content material description for the ones Textual content substances.
You’ll use the semantics-modifier in any detail and set the content material description inside its semantic homes lambda:
Canvas(
modifier = Modifier.semantics {
contentDescription = "Put the content material description right here"
}
) {
...
}
On this weblog publish, we’ve lined content material descriptions, what they’re, find out how to write them, and the way you’ll be able to set them.
Do you may have questions? Or feedback? Please do ask or percentage!
