Extending PdfActivity with custom activities

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

Since a PdfActivity and any activities deriving from it need special intent data (document sources, passwords, configuration, etc.) you need to create a special launch Intent using the PdfActivityIntentBuilder that will carry all of this information. The builder allows you to set your activity class using its #activity method. For a comprehensive example of what is possible with customization, take a look at the CustomLayoutExample or the CustomActionsExample inside the Catalog app.

Creating your activity

The first step for implementing a custom activity is to subclass the PdfActivity. Note that your custom activity does not need to override #onCreate, and it does not need to define or inflate a layout. The layout will be set up by the PdfActivity parent class and can be using the PdfActivityConfiguration.Builder#layout when launching the activity:

class MyCustomActivity : PdfActivity() {

    override fun onPrepareOptionsMenu(menu: Menu): Boolean {
        var handled = super.onPrepareOptionsMenu(menu)

        // Custom action bar menu creation.

        return handled
    }

    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 public boolean onPrepareOptionsMenu(Menu menu) {
        boolean handled = super.onPrepareOptionsMenu(menu);

        // Custom action bar menu creation.

        return handled;
    }

    @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 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 will throw an InvalidLayoutException:

Optional views

In addition to the mandatory views, the layout may define several optional views. These views may be removed from the original layout. However, if this is done, they need to be deactivated explicitly using the PdfActivityConfiguration.Builder: