Guides

TalkBack Accessibility Support

ComPDF SDK supports Android TalkBack and hardware keyboard navigation, helping users browse PDF documents with speech or a keyboard.

Note

• Accessibility support is disabled by default.
• TalkBack can read extractable text in the PDF and announces page and zoom changes.
• For scanned PDFs or PDFs without a text layer, use OCR to create extractable text for a better reading experience.
• Before using TalkBack, enable it in the Android device's Settings > Accessibility.

Configure Accessibility Support

We recommend configuring TalkBack and keyboard navigation together with CPDFAccessibilityConfig, then applying the configuration to CPDFReaderView with setAccessibilityConfig().

import com.compdfkit.ui.reader.accessibility.CPDFAccessibilityConfig;

CPDFReaderView readerView = findViewById(R.id.readerview);

CPDFAccessibilityConfig accessibilityConfig = CPDFAccessibilityConfig.newBuilder()
        // Enable TalkBack
        .setTalkBackEnabled(true)
        // Enable hardware keyboard navigation
        .setKeyboardNavigationEnabled(true)
        // Expose extractable text in the PDF
        .setExposeText(true)
        .build();

readerView.setAccessibilityConfig(accessibilityConfig);

After applying the configuration, users can browse PDF text with TalkBack. The viewer announces the current page and zoom level when the page or zoom changes.

Use the following code to obtain the current configuration:

CPDFAccessibilityConfig currentConfig = readerView.getAccessibilityConfig();

boolean talkBackEnabled = currentConfig.isTalkBackEnabled();
boolean keyboardNavigationEnabled = currentConfig.isKeyboardNavigationEnabled();

Customize Spoken Labels

Use AccessibilityLabelProvider to customize the labels and state descriptions announced by TalkBack. For example, you can add a page number before each PDF text segment.

import com.compdfkit.ui.reader.accessibility.AccessibilityLabelContext;
import com.compdfkit.ui.reader.accessibility.AccessibilitySemanticNode;
import com.compdfkit.ui.reader.accessibility.strategy.AccessibilityLabelProvider;

readerView.setAccessibilityConfig(
        readerView.getAccessibilityConfig()
                .toBuilder()
                .setLabelProvider(new AccessibilityLabelProvider() {
                    @Override
                    public CharSequence getLabel(
                            AccessibilitySemanticNode node,
                            AccessibilityLabelContext context) {
                        CharSequence originalLabel = node.getLabel();
                        if (originalLabel == null || originalLabel.length() == 0) {
                            return null;
                        }

                        // Add the current page number before the original text.
                        return "Page " + (context.getPageIndex() + 1)
                                + ": " + originalLabel;
                    }

                    @Override
                    public CharSequence getStateDescription(
                            AccessibilitySemanticNode node,
                            AccessibilityLabelContext context) {
                        return "PDF content";
                    }
                })
                .build()
);

Use getLabel() to customize the spoken label and getStateDescription() to add a state description. Return null to retain the SDK's original spoken text.

Note Use readerView.getAccessibilityConfig().toBuilder() to add custom spoken labels while retaining the existing TalkBack, keyboard navigation, and text-exposure settings.

Quick Enable Methods

If you only need one feature, use the following convenience methods:

// Enable TalkBack only
readerView.setEnableAccessibility(true);

// Enable hardware keyboard navigation only
readerView.setKeyboardNavigationEnabled(true);

Set the parameter to false to disable the corresponding feature:

readerView.setEnableAccessibility(false);
readerView.setKeyboardNavigationEnabled(false);

Browse Documents with a Hardware Keyboard

After keyboard navigation is enabled, users can browse PDFs with the following keys:

Key	Action
Arrow keys	Scroll in continuous mode; change pages in single-page mode.
Page Up / Page Down	Go to the previous or next page.
Home / End	Go to the first or last page.
Space	Scroll down; use Shift + Space to scroll up.
Ctrl + + / Ctrl + -	Zoom in or out.
Ctrl + 0	Reset zoom to 100%.
Tab / Shift + Tab	Move focus between text content on the page.
Enter or the center D-pad button	Read the currently focused content.
Esc	Clear the current keyboard focus.

You can adjust keyboard navigation behavior for your app:

// Set the arrow-key scroll distance to 20% of the viewer width or height.
readerView.setKeyboardScrollStep(0.2f);

// Move two pages at a time with Page Up, Page Down, and page-turn actions.
readerView.setKeyboardPageStep(2);

// In double-page mode, move by a single page instead of by a spread.
readerView.setKeyboardDoublePageNavigationBySpread(false);