Guides

Event Callbacks

ComPDFKit_Tools provides a unified event dispatch mechanism via CPDFCustomEventCallbackHelper for listening to custom button clicks, annotation interaction interceptions, and other events.

CPDFCustomEventCallbackHelper

Register Callback

java

CPDFCustomEventCallbackHelper.getInstance().addCustomEventCallback(extraMap -> {
    String eventType = extraMap.get(
        CPDFCustomEventField.CUSTOM_EVENT_TYPE).toString();
    // Handle based on event type
});

kotlin

CPDFCustomEventCallbackHelper.getInstance().addCustomEventCallback { extraMap ->
    val eventType = extraMap[CPDFCustomEventField.CUSTOM_EVENT_TYPE].toString()
    // Handle based on event type
}

Remove Callback

java

@Override
protected void onDestroy() {
    super.onDestroy();
    CPDFCustomEventCallbackHelper.getInstance().removeCustomEventCallback(this);
}

kotlin

override fun onDestroy() {
    super.onDestroy()
    CPDFCustomEventCallbackHelper.getInstance().removeCustomEventCallback(this)
}

Event Types

Toolbar Button Tap

Triggered when a custom toolbar button is tapped.

Field	Value / Description
CUSTOM_EVENT_TYPE	CPDFCustomEventType.TOOLBAR_ITEM_TAPPED
identifier	Unique identifier of the button

java

if (CPDFCustomEventType.TOOLBAR_ITEM_TAPPED.equals(eventType)) {
    String identifier = extraMap.get("identifier").toString();
    switch (identifier) {
        case "custom_download":
            // Handle download button tap
            break;
    }
}

kotlin

if (CPDFCustomEventType.TOOLBAR_ITEM_TAPPED == eventType) {
    when (extraMap["identifier"].toString()) {
        "custom_download" -> {
            // Handle download button tap
        }
    }
}

See Custom Toolbar Items for details.

Context Menu Item Tap

Triggered when a custom context menu item is tapped.

Field	Value / Description
CUSTOM_EVENT_TYPE	CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED
IDENTIFIER	Unique identifier of the menu item
ANNOTATION	Associated annotation object (may be null)

java

if (CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED.equals(eventType)) {
    String identifier = extraMap.get(CPDFCustomEventField.IDENTIFIER).toString();
    CPDFAnnotation annotation = (CPDFAnnotation) extraMap.get(
        CPDFCustomEventField.ANNOTATION);
    // Handle based on identifier
}

kotlin

if (CPDFCustomEventType.CONTEXT_MENU_ITEM_TAPPED == eventType) {
    val identifier = extraMap[CPDFCustomEventField.IDENTIFIER].toString()
    val annotation = extraMap[CPDFCustomEventField.ANNOTATION] as? CPDFAnnotation
    // Handle based on identifier
}

See Context Menu for details.

Annotation Interaction Interception

When the corresponding intercept*Action in annotationsConfig is set to true, tapping an annotation triggers an event instead of executing the default behavior.

Intercept Config	Event Description
interceptNoteAction: true	Intercept note annotation tap
interceptLinkAction: true	Intercept link annotation tap

Form Interaction Interception

When the corresponding intercept*Action in formsConfig is set to true, tapping a form control triggers an event (only supported for ListBox, ComboBox, and PushButton).

Intercept Config	Event Description
interceptListBoxAction: true	Intercept list box tap
interceptComboBoxAction: true	Intercept combo box tap
interceptPushButtonAction: true	Intercept push button tap

CPDFCustomEventField Constants

Constant	Description
CUSTOM_EVENT_TYPE	Event type identifier
IDENTIFIER	Unique identifier of custom button/menu
ANNOTATION	Associated annotation object

CPDFCustomEventType Constants

Constant	Description
TOOLBAR_ITEM_TAPPED	Toolbar button tap event
CONTEXT_MENU_ITEM_TAPPED	Context menu item tap event

Best Practices

1. Remove callbacks promptly: Remove callbacks in onDestroy() to avoid memory leaks
2. Check event type: Always check CUSTOM_EVENT_TYPE in callbacks, as different events may share the same callback
3. Null safety: Perform null checks when retrieving values from extraMap
4. Thread safety: Callbacks execute on the main thread; time-consuming operations should be moved to a background thread