Find #appkit on DiscordDiscord logo

PDF Viewing

Presenting a Document

There are two fundamental ways of presenting a document to the screen. One way is to use the Default UI which includes an in-built user interface. The alternative is to load the document into a dedicated document view and provide your own Custom UI with listener methods for your document control.

Default UI

The Default UI is an App Kit UI created by Artifex which includes a user-interface for typical document features and actions. It is presented at the top of the document view and accommodates for both tablet and phone layout.

The Default UI aims to deliver a handy way of allowing for document viewing & manipulation without the need to provide your own Custom UI.

Instantiating the Default UI

An application developer should import the DefaultUIActivity and instantiate it as follows:

import com.artifex.sonui.editor.default_ui.DefaultUIActivity
...

val defaultUI = Intent(this, DefaultUIActivity::class.java).apply {
    this.action = Intent.ACTION_VIEW
    this.data = uri
}

startActivity(defaultUI)

Note

If you send null for the data uri value then the system file browser will open, whereby you can select a file to view.

Custom UI

Providing a Custom UI means that the application developer is responsible for providing their own UI and functionality. This approach involves document presentation within an instance of DocumentView.

Considering that you have a valid document Uri from a Uri File instance, an application developer should initialize the document as explained in Starting a Document View.

Note

Don’t forget to attach the DocumentView to your view hierarchy and set it’s metrics to fit the area you need for display.

Starting a Document View

A DocumentView is the central class which MuPDF uses for document display and is required to be imported and instantiated.

An application developer will typically set this up in their relevant Activity layout as follows:

<com.artifex.sonui.editor.DocumentView
    android:id="@+id/doc_view"
    android:layout_width="fill_parent"
    android:layout_height="fill_parent"
    app:layout_constraintBottom_toBottomOf="parent"
    app:layout_constraintEnd_toEndOf="parent"
    app:layout_constraintStart_toStartOf="parent"
    app:layout_constraintTop_toTopOf="parent">
</com.artifex.sonui.editor.DocumentView>

The start() method for DocumentView allows 3 parameters as follows:

  • uri: Uri The document URI.

  • page: Int The document page to start viewing from (Note: if this value is out of bounds then the document will render to the nearest available page).

  • showUI: Bool Indicates whether to render and use the :ref:`Default UI on top of the document view or not - for the :ref:`Custom UI this should always be set to false.

import com.artifex.sonui.editor.DocumentView

fun presentDocument(documentUri:Uri) {
    val documentView:DocumentView = findViewById(R.id.doc_view)
    documentView.start(documentUri, 0, false)
}

Note

Don’t forget that your Activity should also be responsible for setting up the Activity lifecycle interfaces previously explained.

You should also adhere to the document listeners which allow for feedback against document events.

Going to a Page

Once a document is loaded an application developer can view pages either by scrolling the document view or by using the App Kit API as follows:

// note: page number is zero-indexed,
// thus this would show page 8 of your document
documentView.goToPage(7)

Jump to first page:

documentView.firstPage()

Jump to last page:

documentView.lastPage()

In the code sample above documentView refers to the instance of your DocumentView. Furthermore this API should only be called after the document has initially loaded and had it’s first render (see Document Listeners - Document completed).

Viewing Full-screen

In order to view a document in full-screen, it is up to the application developer to hide any UI which has been presented, and set the frame of the document view to fill the screen. Once that’s done, calling enterFullScreen and passing a Runnable to it will invoke the full-screen mode. When the user taps to exit full-screen mode, the Runnable will be invoked, at which time the UI and frame should be restored to their previous state.

documentView?.enterFullScreen({
    // restore our UI
})

Document Page Viewer

A handy way of showing or hiding the page navigator in your Custom UI can be utilized with the following methods:

// show
documentView?.showPageList()

// hide
documentView?.hidePageList()

You can also query the presence of the page list UI with:

val isVisible:Boolean? = documentView?.isPageListVisible

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.

Discord logo