Widget a11y label from/to tooltip


I see a lot of activities around a11y in GNOME these days, that motivates me to improve my own gtk4 apps :slight_smile:

All my buttons and entries have tooltips describing them, I would like to re-use the same string for the accessibility label property, ideally without duplicating the strings everywhere in my *.ui files.

Is there an convenient way to do this?
(some kind of “labelled-by-tooltip” relation, or, the other way around, a sort of “tooltip-from-a11y” property for widgets)

As I understand it, GTK (or maybe Orca and other screenreaders) uses the tooltip for a labelled-by relation more as “everyone does it” fallback.

Someone else can probably expand on that, but in principle you “should” use a proper accessible label, while in my experience a screen reader will end up speaking something like “Refresh Push Button - Refresh” if you have both.

1 Like

That’s automatic: the tooltip text is used for the accessible description as a fallback.

On the other hand, though, remember that tooltips are for sighted users and are meant to describe the function of the UI; the accessible label and description are read by screen readers, and are meant to be used to describe the actual UI, not its function. You should not just dump the tooltip as the accessible description.

Additionally, both the accessible label and the accessible description work by accumulation: you can have a UI element being described by some text associated to the element itself, as well as provided by another UI element, through the “labelled by” and “described by” relations.

For more information and examples, GTK has a section on accessibility authoring practices.


I don’t have a real advice here but just alittle comment from the user’s perspective.
I think tooltip text is mapped to the accessible description by default at least I can remember some GTK3 and web apps that are working like this with no tweaking from the developers.
I’m currently looking at gnome-text-editor and gnome-calculator I know are GTK4 apps and I can’t quickly find controls with accessible description there so I am not sure what’s the situation like with GTK4.

1 Like


ah, OK, I see.
So I’ve better to use different strings.

Hmm… I thought the accessible description was something changing depending on the state of the control…
I’ll need to look at more real-life examples I think…

I would say this is not enforced. For example when configuring accessible name for the button that has no text and image icon of a diskette “Save” is a good accessible label. Accessible description might be slightly more verbose e.g. a single clause such as “saves the document content into existing file” or something similar. For controls that already have the text or controls where the toolkit can generate meaningfull accessible label based off of its child widgets both of these are optional. When there is no textual information either from the text of the control or the text from its children then having the label is important.
Accessible description is something that describes the control when it’s not all clear from the label.
When trying to come up with a goot accessible label or accessible description try to avoid words that describe the role of the control i.e. don’t say button, entry, list item, combobox and similar. This part is in the accessible role. And also there are states describing the control states such as focused, selected, checked, visible and similar.

If you are fine with this kind of feedback I can try out the app you are working on and comment how accessible it sounds to me with a screen reader.


Great, thanks a lot for all the tips!

Thanks! sadly that app is closed source.
I’ve other personal apps in development that I plan to publish someday, but not worth testing in their current (broken) state. Maybe when I’ve something testable I will come back for feedbacks.

This topic was automatically closed 30 days after the last reply. New replies are no longer allowed.