Guides

Document State and Error Callbacks

When using CPDFReaderView to view PDF documents, the ComPDF SDK provides multiple callback interfaces to obtain document loading states, operation errors, or exception information. With these callbacks, developers can implement document status prompts, error handling, and logging to improve user experience.

Note This section focuses on callbacks in viewer mode. For callbacks related to annotations, content editing, and other features, refer to the corresponding sections.

---

Document Loading State Callback

IDocumentStatusCallback is used to listen for PDF document loading states, including loading, load failure, and load completion.

java

readerView.setDocumentStatusCallback(new IDocumentStatusCallback() {
    @Override
    public void onLoading() {
        // Document is loading
    }

    @Override
    public void onLoadFailed() {
        // Document failed to load
    }

    @Override
    public void onLoadComplete() {
        // Document loading completed
        // Note: This callback is also triggered when reloadPages() is called
    }
});

kotlin

readerView.setDocumentStatusCallback(object : IDocumentStatusCallback {
    override fun onLoading() {
        // Document is loading
    }

    override fun onLoadFailed() {
        // Document failed to load
    }

    override fun onLoadComplete() {
        // Document loading completed
        // Note: This callback is also triggered when reloadPages() is called
    }
})

PDF Error Callback and Messages

When opening, editing, or operating on PDF documents, various errors or exceptions may occur. The SDK provides the IPDFErrorMessageCallback interface to capture these errors and handle them in a custom way, such as displaying messages to users or recording logs. By implementing this interface, applications can gracefully handle PDF operation exceptions and enhance user experience.

Interface Definition

interface IPDFErrorMessageCallback {
    fun onError(errorId: ErrorId)
}

• errorId: An error type enum ErrorId that indicates the current error.

Common Error Types

Error Enum	Description	Applicable Scenario
NO_EMAIL_APP	No email app detected	User tries to share a PDF via email
NO_BROWSE_APP	No browser app detected	User tries to open a link in a PDF
NO_CONTENT_TO_PASTE	No content in clipboard	User uses copy or paste functionality
INVALID_LINK	Invalid link	Internal or external PDF link is unavailable
NO_TEXT_ON_PAGE	No text content on the page	User tries to select or copy text
CANNOT_EDIT	Document cannot be edited	Document is read-only or permission-restricted
CANNOT_EDIT_ANNOT	Annotation cannot be edited	Annotation is locked or permission-restricted
CANNOT_EDIT_FORM	Form cannot be edited	Form is not fillable or permission-restricted
CANNOT_ADD_ANNOT	Cannot add annotations	Adding annotations is disabled
CANNOT_ADD_FORM	Cannot add forms	Adding forms is disabled
NOT_IN_PDFEDIT_MODE	Not in PDF edit mode	Editing attempted outside edit mode

java

readerView.setPdfErrorMessageCallback(object : IPDFErrorMessageCallback {
    @Override
    public void onError(ErrorId errorId) {
        switch (errorId) {
            case NO_EMAIL_APP:
                // No available email app
                break;
            case NO_BROWSE_APP:
                // No available browser app
                break;
            case NO_CONTENT_TO_PASTE:
                // No content in clipboard
                break;
            case INVALID_LINK:
                // Invalid link
                break;
            case NO_TEXT_ON_PAGE:
                // No text content on the page
                break;
            case CANNOT_EDIT:
                // Document cannot be edited
                break;
            case CANNOT_EDIT_ANNOT:
                // Annotation cannot be edited
                break;
            case CANNOT_EDIT_FORM:
                // Form cannot be edited
                break;
            case CANNOT_ADD_ANNOT:
                // Cannot add annotations
                break;
            case CANNOT_ADD_FORM:
                // Cannot add forms
                break;
            case NOT_IN_PDFEDIT_MODE:
                // Not in PDF edit mode
                break;
        }
    }
});

kotlin

readerView.setPdfErrorMessageCallback(object : IPDFErrorMessageCallback {
    override fun onError(errorId: ErrorId) {
        val message = when (errorId) {
            ErrorId.NO_EMAIL_APP -> "No available email app detected"
            ErrorId.NO_BROWSE_APP -> "No available browser app detected"
            ErrorId.NO_CONTENT_TO_PASTE -> "No content in clipboard"
            ErrorId.INVALID_LINK -> "Invalid link"
            ErrorId.NO_TEXT_ON_PAGE -> "No text content on the page"
            ErrorId.CANNOT_EDIT -> "Document cannot be edited"
            ErrorId.CANNOT_EDIT_ANNOT -> "Annotation cannot be edited"
            ErrorId.CANNOT_EDIT_FORM -> "Form cannot be edited"
            ErrorId.CANNOT_ADD_ANNOT -> "Cannot add annotations"
            ErrorId.CANNOT_ADD_FORM -> "Cannot add forms"
            ErrorId.NOT_IN_PDFEDIT_MODE -> "Not in PDF edit mode"
        }
        Log.e("CPDFError", "PDF Error: $message")
    }
})

View Mode Change Callback

CPDFReaderView supports multiple operation modes. By setting a view mode change callback, you can receive notifications when the mode changes and perform custom operations or update the UI.

java

readerView.setOnViewModeChangedListener(new OnViewModeChangedListener() {
    @Override
    public void onViewModeChange(ViewMode viewMode) {

    }
});

kotlin

readerView.setOnViewModeChangedListener(object : OnViewModeChangedListener {
    override fun onViewModeChange(viewMode: ViewMode) {

    }
})

Touch Mode Change Callback

Users can switch between different touch modes via gestures or toolbar actions. The touch mode determines how users interact with PDF pages, such as browsing, adding annotations, or erasing ink.

The OnTouchModeChangedListener interface provides callbacks to notify developers of touch mode changes, enabling UI updates or feature control.

Touch Mode Enum

Enum Value	Description	Applicable Scenario
BROWSE	Browse mode	Default PDF viewing, scrolling and zooming
ADD_ANNOT	Add annotation mode	User adds annotations after selecting tools
EDIT	Edit mode	Edit text, forms, or images
SCREENSHOT	Screenshot mode	Capture full-page or partial screenshots
ERASE_INK	Erase ink mode	Remove handwritten notes or ink drawings

java

readerView.setOnTouchModeChangedListener(new OnTouchModeChangedListener() {
    @Override
    public void onTouchModeChanged(TouchMode touchMode) {

    }
});

kotlin

readerView.setOnTouchModeChangedListener(object : OnTouchModeChangedListener {
    override fun onTouchModeChanged(touchMode: TouchMode) {

    }
})

Reader Interaction Callback

The IReaderViewCallback interface is used to listen for user interactions within the PDF reader, such as tapping, scrolling, or page navigation. By implementing this interface, you can customize behavior or update the UI.

Method Description

Method	Description	Trigger Scenario
onTapMainDocArea()	User taps the main document area	Tap on blank or text area of a PDF page
onMoveToChild(int pageIndex)	Navigate to a child document or page index	Page jump via API or outline navigation
onEndScroll()	Scrolling ends	User stops scrolling the PDF pages
onScrolling()	Called during scrolling	Triggered continuously while scrolling
onRecordLastJumpPageNum(int pageIndex)	Record the last jumped page index	Used to restore the last reading position

java

readerView.setReaderViewCallback(new IReaderViewCallback() {
    @Override
    public void onTapMainDocArea() {
        // User taps the document area, can be used to show/hide toolbars
    }

    @Override
    public void onMoveToChild(int pageIndex) {
        // Navigate to child document or page index, can update page indicator
    }

    @Override
    public void onEndScroll() {
        // Scrolling ended, can refresh toolbars or trigger page load completion
    }

    @Override
    public void onScrolling() {
        // Scrolling in progress, can update a progress indicator
    }

    @Override
    public void onRecordLastJumpPageNum(int pageIndex) {
        // Record the last jumped page index for restoring reading position
    }
});

kotlin

readerView.setReaderViewCallback(object : IReaderViewCallback {
    override fun onTapMainDocArea() {
        // User taps the document area, can be used to show/hide toolbars
    }

    override fun onMoveToChild(pageIndex: Int) {
        // Navigate to child document or page index, can update page indicator
    }

    override fun onEndScroll() {
        // Scrolling ended, can refresh toolbars or trigger page load completion
    }

    override fun onScrolling() {
        // Scrolling in progress, can update a progress indicator
    }

    override fun onRecordLastJumpPageNum(pageIndex: Int) {
        // Record the last jumped page index for restoring reading position
    }
})