Display document in fragment on Android

All actions related to the PDF viewer are handled through the PdfViewCtrlTabHostFragment2. This fragment extends androidx.fragment.app.Fragment and is responsible for showing documents in tabs.

• Integrated Apryse into your project and added the com.pdftron:tools package into your project.
• Minimum API: 16 (using AndroidX)
• Compile API: 34
• Recommended target API: 34

1. In order to support all the features in PdfViewCtrlTabHostFragment2, we will need to add the Android permissions listed in this table . However if you would like to disable certain features and customize your document viewer, you should leave out unnecessary permissions.

2. Enable largeHeap, usesClearTextTraffic, and set android:name in the <application> tag to MultiDexApplication:

<!-- Include existing attributes in application -->
<application
    android:name="androidx.multidex.MultiDexApplication"
    android:largeHeap="true"
    android:usesCleartextTraffic="true">
</application>

3. Declare your activity in the manifest file:

<!-- Include existing attributes in application -->
<application>
    <!-- Declare your activity that will use PdfViewCtrlTabHostFragment2 -->
    <!-- Include existing attributes in activity -->
    <activity
        android:theme="@style/PDFTronAppTheme"
        android:windowSoftInputMode="adjustPan" />
</application>

Note that your activity must extend AppCompatActivity.

4. If you have not done so already, add the <meta-data> tag containing a reference to your license key in the AndroidManifest.xml file. The final AndroidManifest.xml file should look something like this:

   <?xml version="1.0" encoding="utf-8"?>
   <!-- Include existing attributes in manifest -->
   <manifest>
       <!-- Required permissions are added here -->
       <uses-permission android:name="android.permission.INTERNET"/>
       <uses-permission android:name="android.permission.RECORD_AUDIO" />
   
       <!-- Add multidex support, enable largeHeap, and enable usesCleartextTraffic -->
       <!-- Include existing attributes in application -->
       <application 
           android:name="androidx.multidex.MultiDexApplication"
           android:largeHeap="true"
           android:usesCleartextTraffic="true">    
   
           <!-- Add license key in meta-data tag here. This should be inside the application tag. -->
           <meta-data
               android:name="pdftron_license_key"
               android:value="${pdftronLicenseKey}"/>
               
           <!-- Document viewer activity declaration-->
           <!-- Include existing attributes in activity -->
           <activity
               android:theme="@style/PDFTronAppTheme"
               android:windowSoftInputMode="adjustPan"/>
       </application>
   </manifest>

Use ViewerBuilder2 to create an instance of PdfViewCtrlTabHostFragment2, and add it to your activity layout. To add a document viewer fragment for a given password-protected file, call the following method in your activity:

// Add a viewer fragment to the layout container in the specified 
// activity, and returns the added fragment
public PdfViewCtrlTabHostFragment2 addViewerFragment(@IdRes int fragmentContainer, 
        @NonNull AppCompatActivity activity, @NonNull Uri fileUri, @Nullable String password) {
    
    // Create the viewer fragment
    PdfViewCtrlTabHostFragment2 fragment =
            ViewerBuilder2.withUri(fileUri, password).build(activity);

    // Add the fragment to the layout fragment container
    activity.getSupportFragmentManager().beginTransaction()
            .replace(fragmentContainer, fragment)
            .commit();

    return fragment;
}

where fragmentContainer is the resource id of a layout in your activity that will contain your fragment:

For example:

<?xml version="1.0" encoding="utf-8"?>
<!-- This FrameLayout will contain our viewer fragment-->
<FrameLayout xmlns:android="http://schemas.android.com/apk/res/android"
    android:id="@+id/fragment_container"
    android:layout_width="match_parent"
    android:layout_height="match_parent"/>

Alternatively if you have extended PdfViewCtrlTabFragment2 or PdfViewCtrlTabHostFragment2, you can specify your custom classes using the ViewerBuilder2.usingTabClass() method and the ViewerBuilder2.build() method as follows:

// Add a viewer fragment to the layout container in the specified
// activity, and returns the added fragment
public MyCustomTabHostFragment addViewerFragment(@IdRes int fragmentContainer,
        @NonNull AppCompatActivity activity, @NonNull Uri fileUri, @Nullable String password) {

    // Create the viewer fragment with a custom 
    // PdfViewCtrlTabFragment2 and PdfViewCtrlTabHostFragment2
    PdfViewCtrlTabHostFragment2 fragment =
            ViewerBuilder2.withUri(fileUri, password)
                    .usingTabClass(MyCustomTabFragment.class)
                    .build(activity, MyCustomTabHostFragment.class);

    // Add the fragment to the layout fragment container
    activity.getSupportFragmentManager().beginTransaction()
            .replace(fragmentContainer, fragment)
            .commit();

    return fragment;
}

• If you would like to customize the appearance of the viewer activity, define PDFTronAppTheme in styles.xml:

  <style name="PDFTronAppTheme" parent="PDFTronAppThemeBase">
      <item name="colorPrimary">@color/app_color_primary_day</item>
      <item name="colorPrimaryDark">@color/app_color_primary_dark_day</item>
      <item name="colorAccent">@color/app_color_accent</item>
      <!-- Action bar -->
      <item name="actionModeBackground">?attr/colorPrimary</item>
      <item name="windowActionModeOverlay">true</item>
  </style>

  You can learn more about this in the customize the viewer's theme guide .

  PdfViewCtrlTabHostFragment2 uses the AppCompat theme for material colors. Make sure that the value of android:theme in your activity tag also extends the AppCompat theme.

• If you would like to customize certain viewer settings or the UI of PdfViewCtrlTabHostFragment2, you can use ViewerConfig.Builder. For example:

  // Pass a custom ViewerConfig object to initialize your viewer fragment 
  public PdfViewCtrlTabHostFragment2 createUsingViewerConfig(@NonNull Context context,
          @NonNull Uri fileUri, @Nullable String password) {
  
      // Create a ViewerConfig object with custom settings
      ViewerConfig config = new ViewerConfig.Builder()
              .fullscreenModeEnabled(true)
              .multiTabEnabled(true)
              .documentEditingEnabled(true)
              .longPressQuickMenuEnabled(true)
              .toolbarTitle("Host Fragment")
              .showSearchView(true)
              .build();
  
      // Pass in the ViewerConfig object into the ViewerBuilder2
      return ViewerBuilder2.withUri(fileUri, password)
              .usingConfig(config)
              .build(context);
  }

The default toolbar menu consists of the following buttons on phones:

• App navigation
• Toolbar switcher
• Tab switcher
• Overflow menu

The default toolbar menu consists of the following buttons on tablets:

• App navigation
• Toolbar switcher
• Document text search
• View mode configuration
• Thumbnails browser
• List container
• Overflow menu

You can fully customize the toolbar menu and the navigation icon by calling the following in ViewerBuilder2, with custom menu resource and drawable resource files:

public PdfViewCtrlTabHostFragment2 createUsingCustomToolbar(@NonNull Context context,
        @NonNull Uri fileUri, @DrawableRes int navIcon, @MenuRes int[] menuRes) {
    return ViewerBuilder2.withUri(fileUri)
            .usingCustomToolbar(menuRes)// Specify a custom toolbar
            .usingNavIcon(navIcon)      // Specify a custom navigation component
            .build(context);
}

To change the icon color and overflow icon color, in styles.xml:

<style name="ToolbarTheme" parent="ThemeOverlay.AppCompat.Dark.ActionBar">
    <item name="colorControlNormal">@color/red</item>
    <item name="iconTint">@color/red</item>
</style>

To change the navigation icon color, in styles.xml (assume MyTheme is used as the app theme):

<style name="MyTheme" parent="PDFTronAppTheme">
    <item name="toolbarNavigationButtonStyle">@style/ToolbarButtonNavigationStyle</item>
</style>

<style name="ToolbarButtonNavigationStyle" parent="Widget.AppCompat.Toolbar.Button.Navigation">
    <item name="android:tint">@color/red</item>
</style>

If you would like to interact with the host fragment you can call addHostListener(TabHostListener) and override the methods that you are interested in. For example, you may want to override onToolbarOptionsItemSelected(MenuItem) when you add a new menu item, so when the item is clicked you can get a callback. As another example, you can get the callback when the navigation icon is clicked if you override onNavButtonPressed().

Here's an example that replaces the default navigation icon and uses a custom toolbar:

public class CustomToolbarActivity extends AppCompatActivity implements PdfViewCtrlTabHostFragment2.TabHostListener {

@Nullable
private PdfViewCtrlTabHostFragment2 mPdfViewCtrlTabHostFragment;

// Method used to initialize the viewer fragment with a custom toolbar.
public void createCustomToolbarFragment(@NonNull Uri fileUri) {
    mPdfViewCtrlTabHostFragment = ViewerBuilder2.withUri(fileUri)
            // Specify a custom toolbar
            .usingCustomToolbar(new int[] {R.menu.my_custom_toolbar})
            // Specify a custom navigation component
            .usingNavIcon(R.drawable.ic_arrow_back_white_24dp)      
            .build(this);
}

@Override
public boolean onToolbarOptionsItemSelected(MenuItem item) {
    if (item.getItemId() == R.id.action_show_toast) {
        Toast.makeText(this, "Show toast is clicked!", Toast.LENGTH_SHORT).show();
    }
    return false;
}

@Override
public void onNavButtonPressed() {
    // called when navigation button has been clicked
}

@Override
protected void onDestroy() {
    super.onDestroy();
    if (mPdfViewCtrlTabHostFragment != null) {
        mPdfViewCtrlTabHostFragment.removeHostListener(this);
    }
}

// ...

where ic_arrow_back_white_24dp.xml is a drawable resource file for a back arrow icon, and my_custom_toolbar.xml is a menu resource file that contains:

<?xml version="1.0" encoding="utf-8"?>
<menu xmlns:android="http://schemas.android.com/apk/res/android"
    xmlns:app="http://schemas.android.com/apk/res-auto">
     <item
        android:id="@+id/action_settings"
        android:icon="@drawable/ic_settings"
        android:title="@string/action_settings"
        app:showAsAction="ifRoom"/>
    <item
        android:id="@+id/action_show_toast"
        android:title="Show toast"
        app:showAsAction="never" />
</menu>

This sample replaces the navigation icon, removes all toolbar buttons except the annotation toolbar button, and adds a new Show Toast button: