What is accessibilityTextHeadingLevel supposed to do?

Question

In my iOS app I use UILabels as headings; for accessibility, I set their accessibilityTraits to .header. I thought that I could make the hierarchy of headers and subheaders clear by setting each one's attributedText to an attributed string which had an .accessibilityTextHeadingLevel applied to its entire range, but that doesn't appear to result in any difference in the accessibility experience.

What effect is .accessibilityTextHeadingLevel supposed to have? I see documentation on how to set it, but nothing saying what it actually does.

Answer 1

I see documentation on how to set it, but nothing saying what it actually does.

Unfortunately, you're right... there's no clear explanation about its purpose.

However, it's stated that this attribute is only for views that conform to the UITextInput protocol like UITextView for instance.

What effect is .accessibilityTextHeadingLevel supposed to have?

The rationale behind this key may be providing a structure identical to those in web pages for instance.

I'm not sure that's relevant but it looks like another tool that might be interesting to be used with VoiceOver even if I'm not convinced of its efficiency.

To notice the effect of this attribute, try the following code to listen to the "heading level x" when the title line is selected in the text view.

@IBOutlet weak var myTextView: UITextView!

override func viewDidAppear(_ animated: Bool) {
    
    var myString = AttributedString()
    
    for i in 0...6 {
        
        let titleStr = AttributedString("title \(i)\n\n",
                                        attributes: AttributeContainer([.accessibilityTextHeadingLevel:i]))
        myString.append(titleStr)
    }
    
    myTextView.attributedText = NSAttributedString(myString)
    super.viewDidAppear(animated)
}

The argument of this attribute's inexplicit goal is its non introduction during the WWDC series: one simple mention of it with an easy example would have been enough.

Finally, I hope that this return is satisfying to answer your initial question and to allow you for keeping on implementing VoiceOver in your apps.

I wrote a Developer Technical Support Incident (DTSI #796394403) for this problem and Apple answered that:

1. There's currently no way to reach quickly each and every element having this attribute (like the rotor item for instance).

2. Technically, the UIAccessibilityTextAttributeHeadingLevel refers to the h value similar to that of HTML tags h1,h2.

Finally, I come to the conclusion that:

• There's no point in using this attribute for a UITextField, only the UITextView may be relevant to point out the importance of some elements (only these 2 objects conform to the UITextInput protocol).
• Nothing is designed regarding the direct access to the elements having this attribute (no native rotor item).
• The effect of .accessibilityTextHeadingLevel only relies on specifying the heading level of the text in specific conditions due to the protocol to which it's mandatory to be conformed.