Extending PdfActivity with custom activities

Displaying documents using the PdfActivity is sufficient in most cases. Nonetheless, some situations need customizations beyond pure styling. For more flexibility, you can extend the PdfActivity and implement your own custom activities.

A PdfActivity and any activities deriving from it need special intent data (document sources, passwords, configuration, etc.). Create a launch Intent with the PdfActivityIntentBuilder to carry all of this information. The builder sets your activity class through its #activity method. For a comprehensive example of what is possible with customization, take a look at the CustomLayoutExample or the MainToolbarCustomizationExample inside the Catalog app.

Creating your activity

The first step for implementing a custom activity is to subclass the PdfActivity. Your custom activity doesn’t need to define or inflate a layout, because the PdfActivity parent class sets it up. To use a custom layout, pass it with PdfActivityConfiguration.Builder#layout when launching the activity. Toolbar customization goes through the items API described in customizing the main toolbar; the activity has no options menu.

class MyCustomActivity : PdfActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Custom main toolbar items; see the main toolbar guide.
        setToolbarItemsProvider { defaultItems -> defaultItems + myItem }
        setOnToolbarItemClickListener { id -> id == R.id.my_item && handleMyItem() }
    }

    override fun onDocumentLoaded(document: PdfDocument) {
        // Document is ready to use.
    }

    override fun onDocumentLoadFailed(exception: Throwable) {
        // Add your fancy error handling here.
    }
}

public class MyCustomActivity extends PdfActivity {

    @Override protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);

        // Custom main toolbar items; see the main toolbar guide.
        setToolbarItemsProvider(defaultItems -> {
            final List<ToolbarItem> items = new ArrayList<>(defaultItems);
            items.add(myItem);
            return items;
        });
        setOnToolbarItemClickListener(id -> id == R.id.my_item && handleMyItem());
    }

    @Override public void onDocumentLoaded(PdfDocument document) {
        // Document is ready to use.
    }

    @Override public void onDocumentLoadFailed(Throwable exception) {
        // Add your fancy error handling here.
    }
}

Next, you need to add this activity to your AndroidManifest.xml so you can launch it. You can also define the android:theme property to set a custom theme:

<activity
    android:name="com.pspdfkit.example.MyCustomActivity"
    android:label="@string/title_activity_custom"
    android:theme="@style/MyApp.Theme" />

To launch MyCustomActivity, first create a PdfActivityConfiguration, then create a launching intent using the PdfActivityIntentBuilder, and finally call Activity#startActivity(opens in a new tab) with the intent you created:

val config = PdfActivityConfiguration.Builder(context).build()
val intent = PdfActivityIntentBuilder.fromUri(context, uri)
    .configuration(config)
    .activity(MyCustomActivity::class.java)
    .build()

// Start the `MyCustomActivity` like any other activity.
context.startActivity(intent)

final PdfActivityConfiguration config = new PdfActivityConfiguration.Builder(context).build();
final Intent intent = PdfActivityIntentBuilder.fromUri(context, uri)
    .configuration(config)
    .activity(MyCustomActivity.class)
    .build();

// Start the `MyCustomActivity` like any other activity.
context.startActivity(intent);

Custom activity layouts

By default, PdfActivity uses the R.layout.pspdf__pdf_activity as its layout file. Have a look at that file to see all the views Nutrient uses. You can use the file as a template for your custom layout. To specify the layout, provide its ID to the PdfActivityConfiguration.Builder#layout method. Usually, it also makes sense to subclass the PdfActivity so it can make use of the custom layout and the views you may add:

val config = PdfActivityConfiguration.Builder(context)
    .layout(R.layout.my_custom_layout)
    .build()

final PdfActivityConfiguration config =
    new PdfActivityConfiguration.Builder(context)
        .layout(R.layout.my_custom_layout)
        .build();

Required views

The PdfActivity expects several views to be present in the selected layout file. If any of the following views is missing, Nutrient throws an InvalidLayoutException:

<androidx.compose.ui.platform.ComposeView
    android:id="@+id/pspdf__toolbar_compose_host"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

No toolbar View exists to reference: The main toolbar is composed inside pspdf__toolbar_compose_host, and the inline search bar is part of it. Customize its items and appearance through the main toolbar and appearance styling guides.

Optional views

In addition to the mandatory views, the layout may define several optional views. If you remove one of them from your layout, disable its feature with the PdfActivityConfiguration.Builder. Otherwise, the activity throws an InvalidLayoutException for the enabled feature:

The document title overlay is rendered inside the main toolbar and has no view of its own. The layout the SDK ships, R.layout.pspdf__pdf_activity, is the reference for the complete set; the Catalog app’s CustomLayoutExample uses a custom layout.