Some test text!

platform
search

Show a document in a Fragment

Contents

Prerequisites
Step 1: Update AndroidManifest.xml
Step 2: Launch the viewer
Step 3: Customize the viewer
Step 4: Customize the toolbar menu
Custom toolbar menu
Custom navigation icon
Interact with the fragment
PdfViewCtrlTabHostFragment requires the full version of the PDFTron library. See PDFTron full or standard?

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

linkPrerequisites

  • Integrated PDFTron into your project and added the com.pdftron:tools package into your project.
  • A valid evaluation or commercial license key. If you do not have a license key, please contact sales for a commercial license key or click here to get an evaluation key.
  • Minimum API: 16 (using Android Support Libraries)
  • Recommended target API: 28

linkStep 1: Update AndroidManifest.xml

  1. In order to support all the features in PdfViewCtrlTabHostFragment, 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.
Storage permission
Please note that from Android 6.0 (API 23) and up, applications need to request storage permission at runtime before accessing any files on device.
  1. Enable largeHeap, usesClearTextTraffic, and set android:name in the <application> tag to MultiDexApplication:

    <application
      ...
      android:name="android.support.multidex.MultiDexApplication"
      android:largeHeap="true"
      android:usesCleartextTraffic="true">
      ...
    </application>
If your app is targeting Android SDK version 28 or higher, you will need to add the android:usesCleartextTraffic="true" attribute in your application tag.
  1. Declare your activity in the manifest file:

    <application
      ...>
      ...
      <!-- Declare your activity that will use PdfViewCtrlTabHostFragment -->
      <activity
          ...
          android:theme="@style/CustomAppTheme"
          android:windowSoftInputMode="adjustPan" />
    </application>

    Note that your activity must extend FragmentActivity.

  1. 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"?>
    <manifest ...>
        <!-- Required permissions are added here -->
        <uses-permission android:name="android.permission.INTERNET"/>
        <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
        <uses-permission android:name="android.permission.RECORD_AUDIO" />
    
        <!-- Add license key in meta-data tag here -->
        <meta-data
            android:name="pdftron_license_key"
            android:value="${pdftronLicenseKey}"/>
    
        <!-- Add multidex support, enable largeHeap, and enable usesCleartextTraffic -->
        <application 
            ...
            android:name="android.support.multidex.MultiDexApplication"
            android:largeHeap="true"
            android:usesCleartextTraffic="true">    
                
            <!-- Document viewer activity declaration-->
            <activity
                ...
                android:theme="@style/CustomAppTheme"
                android:windowSoftInputMode="adjustPan"/>
            ...
        </application>
    </manifest>

linkStep 2: Launch the viewer

Displaying the PdfViewCtrlTabHostFragment in an activity is straightforward. Like any other fragment you should make an instance of the class and attach it to the activity. To create an instance of the host fragment you need to pass in a bundle that can be created using createBasicPdfViewCtrlTabBundle. The bundle specifies the document that should be shown when the host fragment is visible. For example, to open a document in the host fragment when you know the URI of the file (and its password if the file is password protected) you can call:

Bundle args = PdfViewCtrlTabFragment.createBasicPdfViewCtrlTabBundle(context, fileUri, password);
PdfViewCtrlTabHostFragment mPdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.newInstance(args);
FragmentTransaction ft = getSupportFragmentManager().beginTransaction();
ft.replace(R.id.fragment_container, mPdfViewCtrlTabHostFragment, null);
ft.commit();

You can simply convert a file to a URI by:

File file = ...
Uri fileUri = Uri.fromFile(file);

Since PDFTron uses the Fragment class from the Support Library, your activity must extend FragmentActivity and call getSupportFragmentManager() to get the FragmentManager.

linkStep 3: (Optional) Customize the viewer

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

    <style name="CustomAppTheme" parent="Theme.AppCompat.DayNight.NoActionBar">
      <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>
    PdfViewCtrlTabHostFragment 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 the UI of PdfViewCtrlTabHostFragment, you can use ViewerConfig.Builder builder. For example:

    ViewerConfig.Builder builder = new ViewerConfig.Builder();
    ViewerConfig config = builder
      .fullscreenModeEnabled(true)
      .multiTabEnabled(true)
      .documentEditingEnabled(true)
      .longPressQuickMenuEnabled(true)
      .toolbarTitle("Host Fragment")
      .showSearchView(true)
      .build();
    
    Bundle args = PdfViewCtrlTabFragment.createBasicPdfViewCtrlTabBundle(context, fileUri, password, config);
    args.putParcelable(PdfViewCtrlTabHostFragment.BUNDLE_TAB_HOST_CONFIG, config);
    mPdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.newInstance(args);

    For details on customizing the UI and using ViewerConfig.Builder, check out the configuration tutorial.

linkStep 4: (Optional) Customize the toolbar menu

The default toolbar menu consists of the following items:

  • App navigation
  • Document text search
  • Document sharing
  • View Mode configuration
  • Showing/hiding annotation toolbar
  • Overflow menu

You can fully customize and control the toolbar menu as well as the navigation icon.

linkCustom toolbar menu

In order to change the default toolbar menu items you need to create your own menu in menu resource folder and pass it to the host fragment through bundle:

args.putInt(PdfViewCtrlTabHostFragment.BUNDLE_TAB_HOST_TOOLBAR_MENU, R.menu.fragment_viewer_simple);

linkCustom navigation icon

To change the navigation icon, similar to the toolbar menu, you need to pass the desired icon to the host fragment through the bundle:

args.putInt(PdfViewCtrlTabHostFragment.BUNDLE_TAB_HOST_NAV_ICON, R.drawable.ic_arrow_back_white_24dp);

linkInteract with the fragment

If you want to interact with the host fragment you should call addHostListener(TabHostListener) and override those 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 only keeps the annotation toolbar icon in the toolbar menu while adding a new menu item to show a toast when selected:

args.putInt(PdfViewCtrlTabHostFragment.BUNDLE_TAB_HOST_NAV_ICON, R.drawable.ic_arrow_back_white_24dp);
args.putInt(PdfViewCtrlTabHostFragment.BUNDLE_TAB_HOST_TOOLBAR_MENU, R.menu.fragment_viewer_simple);
mPdfViewCtrlTabHostFragment = PdfViewCtrlTabHostFragment.newInstance(args);
mPdfViewCtrlTabHostFragment.addHostListener(this);


@Override
public boolean onToolbarOptionsItemSelected(MenuItem item) {
    if (item.getItemId() == R.id.action_show_toast) {
        Toast.makeText(context, "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);
    }
}

The fragment_viewer_simple.xml should be placed in menu resource folder and contain:

<?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_annotation_toolbar"
        android:icon="@drawable/ic_mode_edit_white"
        android:title="@string/action_annotation_toolbar"
        app:showAsAction="ifRoom"/>
    <item
        android:id="@+id/action_show_toast"
        android:title="Show toast"
        app:showAsAction="never" />
</menu>

With this complete, you will see:

Get the anwsers you need: Support

Contents

Prerequisites
Step 1: Update AndroidManifest.xml
Step 2: Launch the viewer
Step 3: Customize the viewer
Step 4: Customize the toolbar menu
Custom toolbar menu
Custom navigation icon
Interact with the fragment